xcore.boot

A bootloader for xCore microcontroller boards, consisting of a microcontroller-side firmware written in C and a host-side utility written in Python for uploading images over the network.

Introduction

xcore.boot is a network-based bootloader designed for xCore microcontroller boards. It allows users to upload firmware images to the microcontroller over TCP/IP, facilitating easy updates and deployment.

The bootloader is split into two components:

• Microcontroller Firmware (C): Runs on the STM32 microcontroller and handles network communication, image verification, and programming.
• Host Utility (Python): A command-line tool that runs on a host PC to discover devices on the network and upload firmware images.

Features

• Network Discovery: Automatically discovers xCore devices on the local network.
• Secure Image Transfer: Uses SHA256 checksums to verify the integrity of the uploaded image.
• Progress Feedback: Displays upload progress with a progress bar.
• Flexible Interface Selection: Allows specifying a network interface for communication.

Usage

Docker

The host software is provided as docker image, so uploading a firmware file is as easy as running:

docker run --rm -it --network=host -v/path/to/your/firmware:/workdir ghcr.io/clemenselflein/xcore.boot:main upload /workdir/firmware.bin

Without Docker

To upload a firmware image without Docker, use the upload command followed by the path to the image file:

./xcore-boot.py upload path/to/your/image.bin

Prerequisites

• Python 3.x: The host utility requires Python 3.
• Python Packages:
  • tqdm: For displaying progress bars.
• Operating System: Unix/Linux (due to the use of specific system calls like fcntl.ioctl).

Script Options

• -i, --interface: Specify the network interface to use for communication.

  ./xcore-boot.py -i eth0 upload firmware.bin

• --target-ip: Specify the IP address of the target board to skip service discovery.

  ./xcore-boot.py --target-ip 192.168.1.100 upload firmware.bin

How It Works

1. Service Discovery:

   • The host utility sends a broadcast message (DISCOVER_REQUEST) over the network.
   • The microcontroller responds with its IP address.

2. Establishing Connection:

   • The host connects to the microcontroller using TCP on port 8007.

3. Handshake Protocol:

   • The microcontroller sends variable pairs (if any) and requests the SHA256 checksum.
   • The host computes the SHA256 checksum of the image and sends it.
   • Upon verification, the microcontroller requests the file length.
   • The host sends the file length.
   • The microcontroller acknowledges and requests the data.
   • The host uploads the image data while displaying a progress bar.

4. Completion:

   • After successful upload, the connection is closed.

Manual Installation

If you want to run the host-software without docker, follow these steps:

1. Clone the Repository:

   git clone https://github.com/ClemensElflein/xcore.boot.git
   cd xcore.boot/host-software

2. Install Required Python Packages:

   pip install tqdm

3. Make the Host Utility Executable:

   chmod +x xcore-boot.py

License

This project is licensed under the MIT License. This project uses ChibiOS (GPL version), so the final executable is also licensed under the GPL license. When purchasing a commercial version of ChibiOS it is possible to use the sources according to ChibiOS commerical license terms.