Esta página aún no está traducida; se muestra en inglés.
Architecture
One radio-independent core runs on every radio. Each radio adds a board directory that describes it and drives its
chips. The core never includes a board or platform header and never tests a radio define: what differs by radio
reaches it at run time through the board descriptor, board_t in hal/board.h.
Layers
core/ DMR stack, radio core, UI, codeplug, settings, storage, hotspot, host link, CPS, debug link,
APRS, IP services (TCP, HTTP, mDNS, TFTP, SNMP)
| calls only hal/*.h and board.<field>
hal/ interfaces: board_t, radio, DMR modem, audio, vocoder, display, input, flash, power, stream, netif,
system, AFSK, broadcast receiver
| implemented by
boards/<b>/ the radio: board_t, pins, key map, how its build differs from the platform's, codec hosting, chip glue;
radios of one board design share it in a family directory (adding-a-radio.md)
| uses
drivers/ chips shared by several radios: AT1846S, BK4819, FD6818, SKY72310, HR_C6000, HR_C7000, ST7735, ST7789,
RDA5807M, SPI NOR, key matrix, encoder, NMEA GPS, USB; and the math they share (mic level, battery)
platform/<p>/ the SoC: start-up, clocks, interrupts, time base, FreeRTOS port glue, and the build defaults its
boards share (stm32f4, hrc7000)
third_party/ FreeRTOS, TinyUSB, ST HAL and CMSIS (submodules, permissive licenses)
| Layer | Rule |
|---|---|
core/ |
Portable C. Tests every radio difference through board (bands, power levels, display geometry and insets, key map, optional hooks that may be NULL). Host tests compile it unchanged |
hal/ |
Headers only: structs of function pointers and the data types between core and board |
drivers/ |
One chip each, no knowledge of the radio it sits in beyond what its init call is given. Also header-only helpers the boards share, such as audio/miclevel (the VOX level) and power/battery (the battery average and charge estimate) |
boards/ |
The only place that knows the radio. Fills in board_t; maps physical keys to logical actions |
platform/ |
The SoC, shared by every radio on it (the STM32F405 radios share platform/stm32f4), and in subdirectories the glue for a chip on that SoC that several radios share (platform/stm32f4/hrc, gps_uart, spi_flash, fsmc_keypad), built for the boards that list it in BOARD_DIRS. Also the build defaults: platform.mk (compiler, part defines, HAL modules), config.mk (feature defaults), common.ld (the memory layout), FreeRTOSConfig.h. A board's files list only how it differs |
Besides board_t, every board provides three functions (hal/board.h): board_early_init (pins and clocks before
the RTOS), board_init (from the first task) and board_rf_safe (transmitter off with register writes only). The
platform calls board_rf_safe first in main(), in its fault handlers and before every software reset or jump out
of the application; the crash capture in core/crash calls it too. It must work with interrupts off, without the
RTOS and before the clocks are set up (crash-log.md 8).
RF chip drivers share three interfaces in drivers/rf:
| Interface | What it is |
|---|---|
rfbus |
A chip's register bus: write, read, a millisecond wait and a write count. rfbus_3w_t is the bit-banged 3-wire bus; a board fills its pin functions. A driver takes an rfbus_t * and never touches pins |
subaudio |
The CTCSS, tone and DCS words every chip family uses, rounded or truncated as the caller needs |
superhet |
The two roles of a superheterodyne: main transceiver and LO, as tables of ops. A driver that can fill a role exports its ops; the board detects its chips, binds each to its ops and calls only those. Steps that depend on the board (band pins, calibration lookups) stay in the board |
Tasks
FreeRTOS tasks, created by core/app/app.c (its header comment has the priorities and stack sizes):
| Task | Owner | Does |
|---|---|---|
| start / housekeeping | core/app |
Start-up, then the power switch poll, settings saves and codeplug writes (storage jobs) |
| radio | core/radio |
The radio state machine: requests, status poll, squelch, PTT, time-out, the DMR call stack tick, the data service |
| dmr | board | Modem events to the DMR call stack or the hotspot |
| audio | board | PCM blocks; the vocoder runs here |
| input | core/input |
Key scan, gestures; PTT and monitor go straight to the radio core |
| host | core/hostlink |
The host port: MMDVM hotspot, CPS shim, debug link; in network mode the IP gateway and the radio's own services (core/net, core/snmp) |
| usb | drivers/usb |
TinyUSB device stack |
| ui | core/ui |
Frame pacing, drawing, the UI's behavior |
| gps | board | NMEA from the GPS module, on radios that have one |
Other tasks talk to the radio core through requests (radio_req_*, queued, never waiting) and read a copy of its
state (radio_view_t). The UI never calls the RTOS from its behavior code, so the host simulator runs it unchanged.
The core, by directory
| Directory | Spec | Contents |
|---|---|---|
core/radio |
radio-features, dmr-roaming, airband-and-broadcast | The radio state machine (radio_sm.c), its task, scan, beeps, battery, Morse, roaming, air band and broadcast receive |
core/dmr/call |
dmr-voice, dmr-modem | The DMR call stack: talk targets, filters, late entry, talker alias |
core/dmr/fec, core/dmr/ambe |
dmr-modem | ETSI FEC, AMBE frame FEC and the voice path around the codec |
core/dmr/*.c |
dmr-data, dmr-emergency, sfr, usb-network | Data service (SMS, CSBK signaling, ARS, LRRP, confirmed data, SAP 3 compression), emergency, privacy, SFR, IP gateway |
core/hotspot |
mmdvm-protocol, split-duplex | MMDVM modem protocol, the hotspot, MMDVM SFR and the split duplex repeater |
core/net |
tcp-services, mdns, tftp | The minimal TCP and the radio's services on the USB network link: KISS, HTTP, rigctld, APRS-IS, mDNS, TFTP |
core/snmp |
snmp | SNMPv2c agent, the RadioFoundry MIB, notifications |
core/aprs |
aprs | AX.25 / AFSK, beacons, messages, KISS TNC, iGate rules |
core/usbaudio |
usb-audio | USRP and the jitter buffer (host tested, not in an image yet) |
core/hostlink |
cps-protocol 1 | Dispatch of the host port by first byte; the USB network side |
core/cps |
cps-protocol | The open-firmware CPS shim |
core/codeplug |
open-firmware-cps, codeplug-native | Codeplug reading and editing, the DMR ID database |
core/settings, core/storage |
settings-store | The settings ring, the sector journal, the foreign region guard |
core/ui |
ui, docs/ux | Drawing, screens, navigation, Find, the services the UI calls |
core/input |
ui 3 | Gesture engine (press, long, repeat), injected keys |
core/debuglink |
debuglink | The debug protocol and its view sections |
core/app |
Start-up and housekeeping |
The UI's seams
The UI asks for data other packages own through core/ui/ui_svc.h. Each call has a weak "not in this build" stub in
ui_svc_stub.c; the owning package's strong definition replaces it at link time. A screen whose feature is missing is
dimmed and says why. See ui.md section 4.
Build switches
Features that cost flash sit behind CONFIG_ switches (config/features.mk, core/config.h). Code tests them with
#if CONFIG_X; whole directories drop out in the Makefile. See Building.
Gotchas
docs/spec/gotchas.md collects the lessons from earlier firmware work, by subsystem: modem timing, hotspot buffering, data retries, storage. Read the section for the subsystem you touch.