Ferrite

Developers

Building and flashing Ferrite

The workspace, the tests, the images and their build features, and flashing a radio.

Ferrite is Rust, no_std, for the RT-950 Pro's AT32F403A (Cortex-M4F). Everything below runs from the ferrite/ checkout.

What you need

  • Rust with the thumbv7em-none-eabihf target (the toolchain is pinned in rust-toolchain.toml).
  • Python 3 for the tools in tools/ (pyserial for the cable).
  • The programming cable (a CH340 USB serial adapter; it shows as /dev/cu.usbserial-* on a Mac).

The workspace

  • firmware/: the radio's binary: the HAL, the tasks (src/tasks/radio/ is the Radio task) and the board.
  • crates/ferrite-core: pure logic, tested on the host (frequencies, the link's wire format, the SPI layout, satellites, the parts).
  • crates/ferrite-ui: drawing (canvas, fonts, widgets).
  • crates/ferrite-app: the screens, the terminal (src/term/) and the link session (src/link.rs).
  • crates/ferrite-store: the SPI flash store.
  • crates/ferrite-radio: the chips' register recipes.
  • drivers/: BK4829, SI4732, ST7789, W25Q, keypad, NMEA.
  • digimodes/: the AFSK, FX.25, POCSAG and DSC decoders.
  • sim/, sim-web/: the simulator (a window, headless for tests, and the browser build).

Tests

cargo test                                   # every host test
cargo test -p ferrite-app --no-default-features
cargo clippy --all-targets -- -D warnings
cargo fw-clippy -- -D warnings               # the firmware target

The UI tests drive the simulator through the link, as Console does: python3 tools/uitest.py --sim auto -j 20.

Images

tools/mkbtf.sh tx          # the user build: target/ferrite-tx.btf and target/ferrite-tx.ffw
tools/mkbtf.sh tx-bench    # tx with the bench commands, the cable log and the line commands; Dry TX on at power-on
tools/mkbtf.sh tx no-vt100 # without the terminal's full-screen pages

Each build also packs the update file, .ffw (the update file): the .btf plus the SPI parts. tools/slowcheck.py runs with every build and must say ok (what has to stay in zero-wait flash).

Build features worth knowing:

Feature In What it holds
tx tx, tx-bench Transmit. Without it the image has no transmit code at all.
bench tx-bench, bring-up Raw chip and memory access, test tones, the cable log, the line commands.
vt100 default The terminal's full-screen pages (an interpreter; the pages are an SPI part).
line-cmds bench The terminal's command line and CMD over the link. A user build has none: Console uses the binary records.
cable-log bench The plain log on the cable at power-on. A user build prints only a fault's report.
sat-predict default Satellite pass prediction on the radio.

Flashing

python3 tools/flash.py /dev/cu.usbserial-XXXX target/ferrite-tx.ffw --backup FLASH.BIN --dev-unsigned
  • --backup is the radio's own SPI flash backup (calibration included), made before the first install. The tool refuses without it.
  • A local build is unsigned; releases are signed in CI, and only a signed file installs without --dev-unsigned.
  • The MCU image goes in through the stock bootloader; then the SPI parts go over the link's raw writes, each read back by CRC; then the radio restarts with them.
  • Never written, whatever any file says: the factory calibration (0x00F000-0x00FFFF), the bootloader's update area (0x300000 up) and the MCU's option bytes.

Talking to the radio

  • tools/ferrite_link.py PORT hello | ui | heard | log | slot ... speaks the link protocol.
  • tools/term.py opens the cable terminal (the full-screen pages).
  • Ferrite Console is the programming app: channels, settings, backups, updates (the same link).

Made from docs/dev/building.md by docs/tools/mkdev.py.