Yatnc

YetAnotherTNC

Zephyr firmware (and, eventually, a companion PCB) for a nRF52840 Pro Micro board that turns a phone's Bluetooth connection into a packet radio TNC. Depending on how three GPIO pins are strapped at boot, the board acts as a transparent UART↔BLE bridge, a real AX.25/KISS TNC driving 1200 baud Bell 202 AFSK audio (with optional FX.25 FEC), an AX.25 digipeater, or a standalone GPS APRS tracker that beacons its position with no phone attached.

Early stage. This has not been widely field-tested — one unit rides in the author's car and works there, but it hasn't been validated across different radios, conditions, or by other users. Treat it as a hobby project that works, not a hardened product.

No app or phone-side code lives in this repo — this is the board (and PCB) side only. Anything that speaks BLE Nordic UART Service (NUS) and either raw KISS or TNC2 monitor lines can talk to it; see Phone app below.

Contents

• Why
• Hardware
  • PCB
  • Pinout
  • Transceiver connector (JST 10-pin)
  • Bill of Materials (BOM)
• Operating modes
• Runtime configuration
• Known limitations
• Phone app
• Building
  • Releases
• Testing
• Hardware-in-the-loop (HIL) test plan
• Repo layout
• License

Why

Cheap handheld radios generally don't have a KISS/TNC mode, and dedicated TNC hardware is either bulky or costs more than the radio. This is a ~$10 nRF52840 board wired to a radio's mic/speaker/PTT lines, doing the AFSK modem and AX.25 framing in software, with a phone or laptop over BLE instead of a serial cable.

Hardware

Primary target: Yaesu FTM510. The board's connector is designed to match the FTM510's mic/data jack. The FTM400 works out of the box — same connector, same signals. Any other radio that can be driven by its mic/speaker/PTT lines can work too, via a custom audio interface cable (not covered by this repo — just the pins on the nRF52840 side).

Board: Pro Micro nRF52840 (or any nice!nano-bootloader-compatible clone, promicro_nrf52840 in Zephyr).

PCB

PCB design files and bill of materials live under pcb/ (yatnc.kicad_sch, yatnc.kicad_pcb, yatnc.csv).

PCB 3D Render	PCB Editor

Pinout

Transceiver connector (JST 10-pin)

[!IMPORTANT]

• RS-232 voltage levels (±12V): The serial lines on the 10-pin JST connector (TO TRCV) are true RS-232 (±12V) driven by the onboard MAX3232 transceiver, not 3.3V or 5V TTL. Do not connect them directly to logic-level UART pins!
• RX / TX crossover: The RS-232 RX and TX lines must be crossed between the board's 10-pin JST connector and the radio (Board TX → Radio RX, Board RX → Radio TX).

Bill of Materials (BOM)

Generated from KiCad BOM (pcb/yatnc.csv):

Transceiver connector (JST 10-pin)

[!IMPORTANT]

• RS-232 voltage levels (±12V): The serial lines on the 10-pin JST connector (TO TRCV) are true RS-232 (±12V) driven by the onboard MAX3232 transceiver, not 3.3V or 5V TTL. Do not connect them directly to logic-level UART pins!
• RX / TX crossover: The RS-232 RX and TX lines must be crossed between the board's 10-pin JST connector and the radio (Board TX → Radio RX, Board RX → Radio TX).

Bill of Materials (BOM)

Generated from KiCad BOM (pcb/yatnc.csv):

Operating modes

The firmware selects one of four modes at boot (and re-checks live on every packet) by reading the mode-select, digipeater-select and standalone-select pins above. There is no software switch — the mode is purely hardware-strapped, and the pins are read fresh on every packet, so mode can in principle change at runtime by re-wiring the straps (no latching).

Resolution order (mode_select_get_current() in src/mode_select.c):

1. standalone_pin grounded → STANDALONE
2. else digi_pin grounded → DIGIPEATER
3. else mode_pin grounded → PACKET_TNC
4. else (all floating/high, the default) → BRIDGE

1. BRIDGE (default — all pins open)

A transparent, byte-for-byte serial bridge between the radio's RS232 (UART0) and the phone app over BLE (NUS). No AX.25/KISS parsing, no AFSK, no PTT — just raw bytes both directions.

This is primarily for FTM510/FTM400 radios in their own native APRS mode: the radio decodes AFSK itself and emits packets over RS232, and this mode just relays that (and any outgoing data) to/from the phone app. It also works with any other radio/modem that expects to speak its own native serial protocol (AT commands, firmware passthrough, etc.) rather than doing AX.25 packet radio in this firmware.

• Radio → App: uart_isr (main.c) collects UART0 RX bytes into a ring buffer; 50ms after the line goes idle, process_uart_to_ble() sends whatever accumulated straight out over BLE notify.
• App → Radio: nus_received() queues whatever the app wrote straight to the TX queue; the TX thread writes it byte-by-byte to UART0 via uart_poll_out().

2. PACKET_TNC (mode_pin grounded)

A real AX.25 KISS TNC. The app talks AX.25/KISS over BLE; the radio side is driven as 1200 baud Bell 202 AFSK audio (with optional FX.25 forward error correction), not raw serial.

App → Radio (TX), in tnc_process_ble_bytes():

1. Bytes from BLE are fed into a persistent KISS decoder. A full KISS frame (FEND ... FEND) is only acted on once its closing FEND has actually arrived — a frame split across several BLE writes (common: phones write in ~20-byte ATT chunks before MTU negotiation) is reassembled correctly before anything is sent.
2. Most phone APRS apps don't actually KISS-frame anything — they write a human-readable TNC2 monitor line instead, e.g. SP3LSN-9>APVEC0,WIDE1-1,WIDE2-1:!5227.76N/01654.03E>comment. If nothing KISS-decodes within 250ms of the app going idle, tnc_send_raw_frame() tries ax25_parse_monitor() on the accumulated bytes; on success it builds a real binary AX.25 UI frame (proper shifted-ASCII addresses, control/PID, FCS) instead of transmitting the raw text. If it doesn't parse either way, the bytes are assumed to already be a raw AX.25 frame and sent as-is.
3. If a stray FEND byte appears in non-KISS app data (e.g. a Latin-1 accented character in an APRS comment happens to be 0xC0) and never gets a matching closing FEND, the KISS decoder used to wedge itself in-frame forever, silently swallowing everything after it. It now self-resets after the same 250ms idle window instead.
4. Every queued frame is picked up by the TX thread: PTT keys (pin 22, active-high), the frame is modulated to AFSK PCM (AFSKModulator, with FX.25 RS(255,239) wrapping if enabled via audio_tx_set_fx25(true) — off by default, no live control path wired to it yet), the waveform is played out on pin 20 via the nRF52840's hardware PWM, then PTT unkeys.

Radio → App (RX), two independent sources feed the same BLE output:

• Audio demodulation: a dedicated thread samples pin 31 (ADC, AIN7) at 9600Hz through AFSKDemodulator (bandpass filter → frequency discriminator → DPLL bit recovery → HDLC flag/destuff, with an FX.25 correlation-tag correlator running in parallel that transparently Reed-Solomon-corrects a frame if the sender wrapped it in FX.25). A decoded frame is KISS-wrapped and sent over BLE.
• UART0: if the radio/modem itself emits KISS bytes over serial rather than raw audio, tnc_process_radio_bytes() decodes and forwards those the same way.

3. DIGIPEATER (digi_pin grounded, overrides mode_pin)

Everything PACKET_TNC does, plus: every frame heard on the radio is checked for an un-repeated WIDEn-N/DIGI hop in its path (digipeat_process_frame()). If found, the hop's SSID is decremented (H-bit set once it reaches 0, marking it used) and the frame is re-encoded and re-transmitted back out over radio — a standard WIDEn-N digipeater. The frame is forwarded to the BLE app either way, repeated or not, so the app sees everything heard on the channel.

4. STANDALONE (standalone_pin grounded, overrides the other two)

A GPS APRS tracker. The board beacons its position over the radio on a timer, with no phone needed. Otherwise it behaves like PACKET_TNC (the BLE app can still connect, send frames, and change settings).

• Live GPS (default): at boot the firmware powers the GPS module (gps_enable_pin) and reads NMEA from uart1. $GPGGA/$GNGGA sentences are parsed for fix state and position. The first fix starts the beacon; it then repeats every BEACON seconds while the fix is held, using the most recent position. No fix (or fix lost) → nothing is transmitted.
• Fixed position: with SET FIXEDPOS=ON (and both LAT/LON set) the GPS module is never powered or touched. The stored coordinates are beaconed on the same interval, starting once the TX pipeline is up. Handy indoors or with no GPS fitted. Until both coordinates are set, nothing is sent.
• Beacon format: an uncompressed APRS position report (!DDMM.hhN/DDDMM.hhE> + comment) from your callsign to APRS, primary-table car symbol (/>), sent through the normal TX path (PTT → AFSK → PWM).

Runtime configuration

Callsign, beacon interval, comment and fixed position are set at runtime with single-line ASCII commands sent as KISS command 0x06 (KISS_CMD_SETHARDWARE) over BLE. Each command is applied immediately, saved to flash, and answered with a KISS 0x06 frame carrying the reply text. Errors are reported in the reply (ERR ...), never as a dropped connection. Settings survive reboots.

The settings live in a 32 KiB NVS partition at 0x90000 (see app.overlay), deliberately clear of the UF2 bootloader. The BLE device name is YATNC.

Known limitations

• AFSK decode is functional but not polished. It works, but weak-signal / low-level decode robustness needs more work — expect some missed frames on marginal audio until the demodulator gets more tuning.
• Not widely field-tested. Verified on the bench and in one car; not yet validated across multiple radios, RF conditions, or users.
• FX.25 TX wrapping has no live control path yet (audio_tx_set_fx25, code only).
• STANDALONE mode parses GGA sentences only, with no altitude, speed/course or compressed positions in the beacon. The symbol is fixed to the car icon.
• The SET/GET config commands are not yet exposed in any phone app; send them yourself as KISS 0x06 frames.

Phone app

Developed and tested against aprsvector (also by the author) — that's the reference app for this firmware and the one to reach for first.

More generally, anything that speaks BLE Nordic UART Service (NUS) and either raw KISS or TNC2 monitor lines should work (most Android APRS apps fit this description), but only aprsvector has actually been tested against this firmware.

Building

./build.sh

First run creates a .venv, pulls a Zephyr workspace into zephyrproject/ (via west), and builds for promicro_nrf52840. Later runs reuse both, so they're much faster. Pass anything after the script name straight through to west build if you need non-default args:

./build.sh -b promicro_nrf52840 --pristine

If no usable Zephyr SDK is found (it looks in .zephyr-sdk/, ~/zephyr-sdk-*, /opt/zephyr-sdk-*, etc, and checks that CMake and the ARM compiler are actually present), the script downloads a minimal one into .zephyr-sdk/ and sets up the arm-zephyr-eabi toolchain. Set ZEPHYR_SDK_INSTALL_DIR to use your own instead.

Output is build/zephyr/zephyr.uf2. To flash: double-tap the board's reset button to drop into the UF2 bootloader (it'll show up as a USB drive), then copy the file over. Boards need the nice!nano / Adafruit UF2 bootloader already installed.

Releases

Pushing a version tag (1.2.3 or v1.2.3) triggers .github/workflows/release.yml, which runs the host tests, builds the firmware, and publishes a GitHub release with yatnc-<tag>.uf2 attached, so you can flash without building.

git tag 1.2.3 && git push origin 1.2.3

Testing

./run_tests.sh

Builds and runs the host-side unit tests for everything that doesn't touch Zephyr or real hardware — AX.25, KISS, FX.25, GPS/NMEA formatting, and the AFSK modem DSP — and fails if line coverage on any of those drops below 80%. tnc.c, main.c, ptt.c, mode_select.c, gps.c, tnc_config.c, and the audio drivers aren't covered here; they need a board, see HIL test plan.

There's also a Python reference model of the AFSK modem (tools/afsk_dsp.py, tested by tools/test_afsk.py/pytest) used to sanity-check the C++ implementation and to generate/analyze WAV captures independent of the firmware.

Hardware-in-the-loop (HIL) test plan

run_tests.sh covers the Zephyr-free pure-logic modules (AX.25, KISS, FX.25, GPS formatting, AFSK modem DSP) at ≥80% line coverage on host. It cannot touch anything that only exists on real silicon: GPIO strapping, hardware PWM audio out, ADC audio in, UART timing, or BLE NUS. Those need the actual promicro_nrf52840 board. This is a plan, not a runnable suite yet — no board rig is set up for automated HIL runs.

What each untestable-on-host module needs:

1. mode_select.c — ground/float P0.02, P0.29 and P1.15 in each combination, reboot, confirm mode_select_get_current()/boot log report BRIDGE / PACKET_TNC / DIGIPEATER / STANDALONE correctly, and that re-strapping is picked up live (no latching).
2. ptt.c — scope P0.22 across a TX; confirm it goes active-high only for the duration audio_tx_pwm is actually playing samples, and idles low the rest of the time (a PTT stuck high keys the radio permanently).
3. audio_tx_pwm.cpp — scope P0.20; confirm the PWM carrier frequency and the external low-pass filter actually pass 1200/2200 Hz clean and knock the PWM carrier down enough that an external TNC (or this board's own RX path, looped back) decodes it.
4. audio_rx_adc.cpp — feed a known AFSK signal into P0.31 (from a signal generator, or TX pin of a second unit looped back through the filter) and confirm frames make it out over BLE.
5. RS232 bridge (BRIDGE mode, main.c) — with a real FTM510/FTM400 (or other serial device) on P0.09/P0.10 through the onboard MAX3232, confirm byte-for-byte passthrough both directions and the 50ms idle-flush timing.
6. BLE NUS end-to-end — a phone/PC BLE client sends a KISS frame or TNC2 monitor line; confirm it comes out the radio side per the routing already unit-tested at the ax25.c/kiss.c level, and vice versa.
7. gps.c — in STANDALONE mode with a GPS module on P0.11/P1.00, confirm P1.04 goes high at boot, NMEA shows in the log, and a beacon goes out after the first fix and again every BEACON seconds. With FIXEDPOS=ON, confirm P1.04 stays low and the stored position beacons.
8. tnc_config.c — send each SET/GET command over BLE, confirm the reply, power-cycle, and confirm values persist. Confirm the UF2 bootloader still works afterwards (NVS must not touch it).
9. Full loop: two boards, one PACKET_TNC and one DIGIPEATER, over actual RF or a dummy-load/attenuator link — confirms the whole AFSK+FX.25+KISS stack end to end, not just each half in isolation on host.

Implementing an automated HIL rig (e.g. Zephyr twister --hardware-map) is a follow-up once there's dedicated bench hardware for it; for now these are run by hand.

Repo layout

src/            firmware source (Zephyr app)
tools/          host-side Python tooling (AFSK reference model, WAV decoder, log capture)
app.overlay     devicetree overlay: GPIO straps, GPS UART/enable, ADC channel, PWM pin, NVS partition
prj.conf        Zephyr/Kconfig options
CMakeLists.txt  build target sources
build.sh        one-shot Zephyr workspace + SDK + build
run_tests.sh    host-side unit tests + coverage
.github/        CI: tag-triggered release workflow
gerber/         PCB fabrication files
pcb/            KiCad board design files and BOM (yatnc.kicad_sch, yatnc.kicad_pcb, yatnc.csv)
images/         PCB 3D render and layout editor screenshots

Other tools in tools/:

• decode_aprs.py — decodes AX.25/APRS frames out of a captured WAV file, for checking a TX recording without a second TNC.
• capture_log.ps1 — tails the board's USB serial console to a timestamped log file, reconnecting automatically across board resets (handy for catching a crash dump).

License

src/main.c carries an SPDX-License-Identifier: Apache-2.0 header; treat the rest of the firmware the same way unless noted otherwise.