Micro-FT8

A headless FT8 station for the QRP Labs QMX that keeps working when you put your phone away.

Micro-FT8 is firmware for two small ESP32 boards that sit beside the radio. The main board decodes, calls CQ, works the stations that answer and keeps the log. A sidekick runs its own WiFi network and serves a web app, so any phone, tablet or laptop browser is the remote. There is nothing to install, and nothing in the field needs internet.

Operating a station? The site is for you: what it does, screenshots, getting started and downloads are at micro-ft8.kalikstein.com. This README is for people who want to build, change or contribute to it.

Status

Pre-alpha. It has completed real FT8 QSOs on the air, and it changes fast. Anything can change or break between commits, and nothing is carried forward from an older state. What has and has not been checked on hardware is in docs/TEST_PLAN.md.

Hardware

Part	Role
M5Stack Unit PoE-P4 (ESP32-P4)	Main board: USB host to the radio, decode, transmit, sequencing, log
M5Stack AtomS3 Lite (ESP32-S3)	Sidekick: WiFi access point, web server, the app
Grove cable (ships with the PoE-P4)	The link between the two boards
QRP Labs QMX	The radio, over one USB-C cable (audio and CAT)

A QDX backend exists but has never run against a real QDX. Testing it is a good first contribution if you own one.

How it works

The phone is the only screen, the sidekick is a peripheral, and the main board is the station. The main board talks to the radio over USB (audio in and out, CAT control) and runs everything that keys the transmitter. The sidekick talks to the main board over a serial link on the Grove cable, and serves the web app and its API to the browser over its own access point or your home WiFi. The browser reaches the internet for optional extras (QRZ lookups, space weather, POTA/SOTA spots, PSKReporter) and the station never needs it.

flowchart LR
    phone["Phone browser<br/>the web app"] -- WiFi --> sk["Sidekick<br/>AtomS3 Lite"]
    sk -- "Grove serial (Port A)" --> p4["Main board<br/>PoE-P4"]
    p4 -- "USB: audio + CAT" --> radio["QMX"]

The full picture, and the rules about who may key the transmitter: docs/architecture/system.md.

Repository layout

Path	What is there
poe_p4/	Main board firmware (ESP-IDF, target esp32p4)
sidekick/	Sidekick firmware (ESP-IDF, target esp32s3)
components/	Shared, mostly host-testable logic: sequencing, decode pipeline, logging, radio control, the board-to-board protocol. ft8_lib is a submodule
webapp/	The browser app (webapp/app/) and the public site
host_mock/, tests/	Host tests that run the firmware's logic without hardware
tools/	check.sh and the checks it runs, release and flashing helpers
docs/	Architecture, roadmap, RFCs, style guide, test plan

Build and test

git clone --recurse-submodules https://github.com/kb2slo/micro-ft8.git
cd micro-ft8
tools/check.sh

tools/check.sh runs every check CI runs: the host tests, the web app's build and tests, decode recall and the docs. tools/check.sh --changed runs only the checks your change can affect. The firmware needs ESP-IDF v5.5.5; without idf.py on the PATH the two firmware builds report SKIP. Building and flashing each board: poe_p4/README.md and sidekick/README.md.

Prebuilt images of the tip of main are on the continuous release, and are flashed at 0x0. How releases are made: docs/RELEASE_PROCESS.md.

Contributing

Contributions are welcome, and you do not need the hardware to make a useful one: much of the logic in components/ and the web app is covered by host tests. CONTRIBUTING.md is the whole path from setup to a merged pull request. In short:

• Bug fixes can go straight to a pull request.
• Features and behaviour changes start as an issue, so we can agree on what and why before you build. docs/ROADMAP.md is the plan.
• Field reports are as valuable as code. If you own a PoE-P4, an AtomS3 Lite and a QMX (or a QDX), the Pending checks in docs/TEST_PLAN.md are written to be run step by step.
• AI coding agents are welcome. AGENTS.md is the working agreement, and most agents read it on their own.

Everyone taking part follows the code of conduct. C and C++ follow docs/STYLE.md. How things work, area by area: docs/architecture/.

Acknowledgements

• Mini-FT8, by Wei Cheng AG6AQ, with Zhenxing N6HAN. Micro-FT8 began as a fork of Mini-FT8, which ran on the M5Stack Cardputer ADV. The sequencer, ADIF logging and ft8_lib integration here grew from that code. Mini-FT8 was itself inspired by DX FT8 (Barb WB2CBA, Charley W5BAA and Paul G8KIG).
• ft8_lib, by Karlis Goba, encodes and decodes every message, with non-standard callsign support from Shawn Rutledge.
• WSJT-X, by Joe Taylor K1JT and the WSJT Development Group, is the on-air standard Micro-FT8 follows. Its source was the reference for message sequencing and the signal-report scale.
• esp-usb, by Espressif Systems, is the P4's USB host stack. Its usb component is vendored in components/usb (Apache-2.0) with one patch.
• qmx-panadapter, by SteffenLav, showed that an ESP32-P4 can run FT8 with a live QMX, and was the working reference for driving the QMX over USB audio and CAT.

WSJT-X and qmx-panadapter are GPL-3.0 projects that were read as references. No code from either is in this repository.

License

MIT: see LICENSE. The ft8_lib submodule carries its own license.