Skip to content

Building from source

The firmware is a PlatformIO project for the Arduino core on the STM32F103CB, in the Spectral BLDC Firmware folder of the firmware repository on the Bootloader_main branch.

Building

  1. Install Visual Studio Code and the PlatformIO extension.
  2. Clone the repository and check out Bootloader_main.
  3. Open the Spectral BLDC Firmware folder in VS Code; PlatformIO fetches the platform (ststm32@15.4.1) and builds with the PlatformIO Build button or pio run. The image is .pio/build/genericSTM32F103CB/firmware.bin.

The project is linked for the bootloader: VECT_TAB_OFFSET=0x3000, the linker script ldscript_bootloader.ld, the upload offset 0x08003000 and a maximum size of 118784 bytes, in platformio.ini. A build that exceeds the size fails to link.

Check

PlatformIO ends the build with SUCCESS, and .pio/build/genericSTM32F103CB/firmware.bin is there. If it fails, the first error above the summary names the cause.

Uploading

PlatformIO runs on Windows, Linux and macOS alike. On Linux, an upload with the programming adapter also needs PlatformIO's udev rules (99-platformio-udev.rules, in the PlatformIO documentation), and a serial port the dialout group.

  • Through the bootloader: flash the built firmware.bin with bl_flash.py or Motor GUI as in Updating through the bootloader. This is how a release is installed, and works on any driver with the bootloader.
  • With the programming adapter: Upload in PlatformIO uses ST-LINK and writes the image at 0x08003000. The bootloader must already be on the board; the upload does not touch it. The serial monitor (the plug icon) opens the UART at 256000 with send_on_enter, so you can type commands to the driver from the same window.
Build, upload and the serial monitor in PlatformIO's status bar.
Figure 7.2: Build, upload and the serial monitor in PlatformIO's status bar.

Where things are
src/constants.h FIRMWARE_VERSION, the CAN command IDs, the EEPROM map, the loop and PWM frequencies
src/common.h the controller and PID structures with their defaults
src/communication.cpp the UART command handlers
src/communication_CAN.cpp the CAN receive switch and the transmit functions
src/SerialPacketParser.cpp the UART parser and the list of names it accepts
src/motor_control.cpp the control loops, the calibration routine, the gripper state machine
src/bootloader_config.cpp the vector table offset and the reset into the bootloader
release_guide.md how a release is cut: version bump, build, tag, GitHub release with firmware.json

Making a release

release_guide.md in the repository is the procedure: bump FIRMWARE_VERSION, build, commit the source change with the rebuilt Binaries/firmware.bin, tag V<number>, create the GitHub release with the image and firmware.json and the release notes. This site's tools/sync_firmware.py reads a release by its tag; the version box names the release.

A firmware for a board without a bootloader

The main branch builds a firmware linked at 0x08000000 for boards that have no bootloader. Its last tagged release is 101; it is not maintained. Install the bootloader instead: Installing the bootloader on an older board.

Comments

Found a mistake on this page? Edit it on GitHub · Report it · Get help · This page as Markdown · llms.txt · The whole manual as PDF