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-eabihftarget (the toolchain is pinned inrust-toolchain.toml). - Python 3 for the tools in
tools/(pyserialfor 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
--backupis 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.pyopens 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.