The STM32 board firmware

Overview

The firmware is the real-time half of drDRO — it reads the encoders, drives the axis, keeps the persistent settings, and speaks the protocol the host app talks to.

• Reads 4 quadrature scales (TIM1–TIM4 in encoder mode).
• Drives a step/dir servo with trapezoidal accel/decel ramps — jog, indexing and scale-synchronised motion — from a TIM9 interrupt relocated to RAM, so it keeps stepping even during a flash write.
• Speaks the RS-485 line protocol on USART1 @ 115200 8N1 (auto-direction).
• Stores rarely-changed settings (scale ratios, servo config, boot mode, active bank) in flash, power-fail-safe.
• Field-updatable over RS-485 via a two-bank A/B bootloader — keep two versions, switch or roll back.

Flash map & project layout

The 512 KB flash is partitioned for a dual-bank bootloader. The app is linked once for the Exec region; the bootloader copies the active bank into Exec and jumps to it (copy-on-activate). Switching banks or rolling back just changes the active-bank byte in settings.

Repository layout

app/          # the application (linked at Exec 0x08020000)
  src/        # app + frozen CubeMX glue (hand-maintained; NOT regenerated)
  include/    # app + config headers (FreeRTOSConfig.h, hal_conf.h)
  lib/FreeRTOS# vendored middleware
  test/       # native unit tests + HAL/RTOS mocks
bootloader/   # IAP bootloader (sector 0, 0x08000000)
shared/       # Bootloader.h, Settings.h, BlinkCode.h (app<->bl contract)
tools/        # dro_update.py, make_factory.py, build-release.sh
docs/         # protocol_design, dualbank_design, HARDWARE.md, trackers

Toolchain setup

The project builds with PlatformIO (platform ststm32@~19.4.0, framework = stm32cube, board genericSTM32F411CE). The ARM toolchain and framework are fetched automatically on the first build.

# PlatformIO Core (official installer, or: pipx install platformio)
python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py)"

git clone https://github.com/bartei/drdro-firmware-f4.git
cd drdro-firmware-f4

nix-shell -p platformio --run 'pio run -d app'

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/master/platformio/assets/system/99-platformio-udev.rules \
  | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo udevadm control --reload && sudo udevadm trigger

Build & test

The app and bootloader are two sibling PlatformIO projects; pass -d <dir> to target one.

pio run  -d app                  # build the application  -> firmware.{elf,bin,hex}
pio run  -d bootloader           # build the bootloader
pio test -d app -e native        # host-side protocol/settings unit tests (no hardware)
pio run  -d app -t clean         # linker-script changes need a clean relink

Artifacts: app/.pio/build/drdro_f411ce/firmware.{elf,bin,hex} and bootloader/.pio/build/bootloader/firmware.{elf,bin,hex}. The native tests link only Protocol.c and mock the HAL/RTOS — they run anywhere, no board required.

Flashing the board

First-time flash — combined factory image

A brand-new board needs both the bootloader and an app in Exec. Merge them into one image and write it with ST-Link:

pio run -d app && pio run -d bootloader          # build both first
python tools/make_factory.py factory.hex \
    bootloader/.pio/build/bootloader/firmware.hex \
    app/.pio/build/drdro_f411ce/firmware.hex
st-flash --format ihex write factory.hex

Iterating — flash a single project over ST-Link

pio run -d app        -t upload   # flash the app to Exec (0x08020000)
pio run -d bootloader -t upload   # flash the bootloader (sector 0)

Field update — over RS-485, no probe

For bring-up/debug you can drive the whole dual-bank update cycle from a host PC over the serial link (self-contained YMODEM sender, baud 115200):

# auto-pick the inactive bank, flash, select, boot, verify:
python tools/dro_update.py /dev/ttyACM0 app/.pio/build/drdro_f411ce/firmware.bin
python tools/dro_update.py /dev/ttyACM0 firmware.bin --bank 1        # force a bank
python tools/dro_update.py /dev/ttyACM0 firmware.bin --no-boot       # flash+select only

Configure (persistent settings)

The board keeps its rarely-changed configuration in flash (ping-pong A/B sectors, magic + CRC32, power-fail safe). You rarely touch these directly — the host app reads them on connect and writes them when you change a value — but you can configure them over the CLI too:

settings              # dump the current persisted settings
set servo.max 3000    # change a value in RAM
save                  # persist RAM settings to flash
load                  # reload settings from flash (discard RAM changes)

Persisted fields include the scale sync ratios, servo config (max speed, acceleration, jog, index feedrate), the boot mode and the active bank. See Board vs host settings for what lives where and why.

CLI reference

Both CLIs share the wire format: key=value lines, a crc=HH line, then a blank line; requests may carry an optional *HH XOR-8 checksum.

Diagnostics

The USR_LED (PB12) blinks a repeating ~1 Hz, active-low heartbeat so you can tell what's running at a glance:

• 1 blink — the application is running.
• 2 blinks — the bootloader is running.
• Longer counts are reserved for app error codes.

Over serial, version confirms the app is alive and reports the firmware version; sta streams live scale + servo state.

Develop

• Native unit tests exercise the transport-independent protocol logic (parser, dispatch, registry, checksum) with the HAL/CMSIS-RTOS mocked — pio test -d app -e native. Add tests under app/test/.
• Don't regenerate CubeMX. The CubeMX glue in app/src/ is frozen and hand-maintained; the HAL comes from the pinned framework — don't add Drivers/, system_stm32f4xx.c, or a startup .s.
• Board specifics baked into the build: Cortex-M4F hard-float, HSE_VALUE=8000000 (the board crystal is 8 MHz; the framework default of 25 MHz would give the wrong USART1 baud), and -Ofast to match the timing-sensitive motion ISR.
• The register image is the rampsHandler_t.shared struct — its field layout is the host contract; changes must stay in sync with the app.
• Peripheral/pin map and full architecture detail live in docs/migration_todo.md.

CI & releases

.github/workflows/ci.yml builds both projects and runs the native tests on every push. release.yml uses python-semantic-release: pushes to dev cut vX.Y.Z-beta.N prereleases, pushes to main cut stable releases. Each release publishes drdro-app.*, drdro-bootloader.* and drdro-factory.hex.

Links