firmware

name

firmware

description

Use when working on the silken_net STM32 firmware — Soldier (sense→TinyML→Lorenz→encrypt→TX, STOP2 loop) and Queen (LoRa RX→CIFO dedup→CoAP flush, OTA) in firmware/{soldier,queen}/main.c, the mruby bio_contract.rb, and the header-only One-Home libs in firmware/common/ (silken_sha256, lorenz_seed, lora_ccm, silken_crc, queen_attest). Knows the non-obvious gotchas — ECB-restore after CBC, Load_AES_Key before MX_CRYP_Init, RTC DR0..DR19 budget (DR7 freed by FW.54), post-FW.29 StatusByte bit-layout, Lorenz continuation vs cold-start, HAL_GetTick frozen in STOP2 (wall-time via wall_time.h), vcap = VDDA-mV not EDLC-Vcap, gated CCM vs live ECB — and the host-test parity discipline (make -C firmware/test). Routes to CLAUDE.md §3 + the 03_01..03_06 canon, does not restate. Examples: "add a sensor field", "change Lorenz params", "modify AES / CRYP init", "touch RTC-persisted state", "why do LoRa decrypts fail after a flush", "edit the seed / cold-start crypto".

Firmware (Soldier + Queen)

Navigation aid + non-obvious gotchas. The SSOT is the docs + code below — this skill points, it does not restate (so it can't drift). Verify a fact at its home before trusting a summary.

SSOT Documents — Read These First

Document	What it covers
CLAUDE.md §3	High-level architecture, AES table, OTA, Lorenz (summary — for exact packet/Status-byte bit-layout trust the canon docs below, not the summary)
docs/03_01_Firmware_Lifecycle_and_DMA.md	Soldier/Queen lifecycle, STOP2 phases, ISR map, RTC Backup Register Map §2 (canonical DR0..DR19 + magic markers), binary packet format §8, mesh-relay + rendezvous ladder §1.9 (CCM-era star-only; single-Queen scale ceiling §1.9.1)
docs/03_02_Queen_Gateway_Firmware.md	Queen: LoRa RX → CIFO dedup → CoAP flush, OTA broadcast, AES mode transitions
docs/03_03_TinyML_Acoustic_Inference.md	Audio DMA, TinyML INT8 forward-pass (NOT CMSIS-NN), decision logic, confidence thresholds (DR13/DR14)
docs/03_04_mruby_Lorenz_Attractor.md	Lorenz constants (§1.2; Z-thresholds §4.1), Float-not-BigDecimal parity, RTC continuation vs cold-start (§2.1), Status-byte packing (§4.4)
docs/03_05_Hardware_Symmetric_Crypto_and_Security.md	AES modes, key rotation (FW.17), SE05x secure element (baseline SE051C2; SEC.6 + SEC.14 provisioning-only — KEYL stays in Protected Flash; ATECC608B = banner-legacy pattern), IV, QATT wire (§2.2), PQC roadmap
docs/03_06_Factory_Flashing_and_Key_Provisioning.md	Factory home (split from 03_05 §3.4): HKDF per-device derivation, K_seed, K_ota (FW.23 §4), flashing pipeline + ops-security (SEC.3 §5)
docs/00_07_Action_Plan_Tracker.md	FW./SEC. task status, open items (canonical home of blockers)

Source Files

File	Role
firmware/soldier/main.c	Sensor node: sense → TinyML → Lorenz → encrypt → TX (multi-phase STOP2 loop)
firmware/queen/main.c	Gateway: RX → decrypt → CIFO cache → batch flush via CoAP (CCM-ера gated: blind courier — air-кадр (30B rev2.1) НЕ розшифровується, запис air+1 via rx_route.h)
firmware/queen/*.h	Queen-only pure headers (host-tested): at_engine/coap_pdu/sim7070_coap (FW.3/FW.56 модем-труба + Sim7070_Read_Csq), sim7070_udp (FW.60 сира CA*-розмова poll-тракту: Sim7070_Udp_Fetch, CARECV-заголовок посимвольно; механіка poll'а = Queen_Poll_Downlink main.c — канон 03_02 §4а), uart_rx_ring, ota_window (FW.52б), rx_route (FW.2 роутер 16/air + запис air+1), soldier_cmd_queue (FW.20-Q2), coap_iv (SEC.12), helium_sos (ARCH.34: 12B SOS-wire byte-parity з HeliumSosWorker + тригер + бюджет сліпоти; MAC-шов Helium_Mac_SendSos = adapter у lorawan_glue/helium_mac.c)
firmware/bio_contracts/bio_contract.rb	mruby Lorenz attractor (runs on MCU); calculate_state is the sole entry-point
firmware/common/*.h	Shared header-only One-Home libs (compile into BOTH firmware + host tests — kill the mirror-drift pattern): silken_sha256.h (SHA-256/HMAC, FIPS/RFC KAT), lorenz_seed.h (FW.30 cold-start deriv), silken_crc.h (CRC16-CCITT, OTA), lora_ccm.h (CCM packet), tx_defer.h (FW.10 Cold-TX: Should_Defer_TX — freeze-contract на < −15°C/4000mV, host-gated One-Home; раніше тест-локальний дубль = false-green), adc_convert.h (FW.50 VREFINT-cal ADC→mV; wired: vcap_voltage = Adc_Vdda_Mv(...) — VDDA-mV, not EDLC-Vcap), queen_attest.h (L1 QATT v2 signed-batch envelope + 8B health-блок пульсу — ARCH.54; wire home 03_05 §2.2; residue 1, ct=0 heartbeat легальний), flash_kv.h+fc_hiwater.h+ota_antirollback.h (journal Flash-KV база + FC/OTA-version high-water — SEC.20 anti-rollback ключ 0x15, строго >; база вимкнена з фіч-фліп-гейтів через SEC20_OTA_ANTIROLLBACK_ENABLED — вкл. декл/mount/compact (Put32 НЕ auto-компактить)), fw_report.h (SEC.20 wire-звіт contract-стану `[semantic:1
firmware/test/	x86 host-based tests — make -C firmware/test (host gate; not gcov-instrumented — per-line coverage gaps → best-TU трюк [[reference_firmware_coverage_gcov_gotcha]]). make -C firmware/test asan = ASan+UBSan dynamic memory-safety lane (TEST.5, CI-gating in firmware_test — keep it green; canon 04_06 §B.1.1). New crypto in common/ ⇒ add a parity test vs OpenSSL, don't re-copy logic into the test file.
firmware/extern/subghz-phy	Vendored stm32-mw-subghz-phy @v1.5.0 (FW.46 Шлях A): radio_driver/radio.h = THE Semtech API both main.c compile against (owned stub deleted; both register a static RadioEvents_t — driver keeps the pointer). radio.c NOT compiled until radio_conf.h exists (.ioc board-freeze); ⚠️ its lorawan/ dir is the LBM radio layer (SWL2001 support: smtc_ral/ralf, radio_planner, SPI chip drivers) — NOT a MAC stack; the ARCH.34 LoRaMac-node = separate submodule firmware/extern/stm32-mw-lorawan @v2.6.2; its Conf/*_template.h are CubeMX-fill templates → owned copies live in queen/lorawan_glue/ (EU868-only profile, soft_timer/systime pure-cores, helium_mac.c adapter — episode = fresh OTAA join, DevNonce = the ONLY cross-join persist via MIB_NVM_CTXS→flash_kv 0x30). Host-smoke of the REAL MAC on a stub radio: make -C firmware/test helium_mac_smoke — full OTAA join+uplink cycle vs an in-test mock-LNS (crypto-valid JoinAccept on the zero-key se-identity; server-side MIC + FRM parity with LNS-derived session keys; deadline = the real 20s blind budget at SF12-TOA) + a crypto-valid 23B JoinRequest + DevNonce monotonicity/KV-reboot. The mock needs -DAES_DEC_PREKEYED (smoke-target-only — the server ENCRYPTS JoinAccept with AES-decrypt; mirrored in firmware/.clangd). ⚠️ Helium_Mac_Bind_Nvm keeps the pointer forever — bind only a static/file-scope FlashKv (ASan stack-use-after-scope class). ⚠️ The recipe links -lm: RegionCommon.c calls floor(), and the coverage lane's -O0 (make coverage) does NOT inline it as a builtin the way -O1 (asan) / -O2 (normal) do → a green local helium_mac_smoke + asan still red-CIs on coverage without it (the class: a vendored-math TU needs explicit -lm; make coverage is the only lane that catches it). ARM lanes: lorawan_mac_check (glue+MAC) + hal_check_ccm compiles the gated Queen KV-mount block (ARCH34_HELIUM_ENABLED=1). The submodule is OUR FORK Alexey-Lukin/stm32-mw-lorawan @v2.6.2-silken.1 — v2.6.2 + one fix: RegionCommonComputeSymbolTimeLoRa SF11/SF12 signed-overflow (upstream Semtech master has the same hole; UBSan found it, upstream-PR = 00_07 ARCH.34 👤). Bumping the submodule → re-check that fix survives. Include-path lives in CMake hal-lane + firmware/.clangd (change one → sync the other)

Line counts drift every commit — don't hardcode them (see [[feedback_no_volatile_counts]]); wc -l if you need a number.

Gotchas Not Obvious From Docs

1. ECB restore after CBC flush — Queen MUST call Restore_ECB_Mode() after every CBC operation. Without it, subsequent LoRa decrypts silently fail (wrong KeySize + wrong key loaded in CRYP peripheral). 1b. Queen CDNSGIP re-resolve on flush-fail — FW.58 host-half SHIPPED (vilize 07-11) — coap_server_ip is cached for the boot, but Coap_Reresolve_Due(coap_consec_fail) (sim7070_coap.h) now invalidates it after N≥3 consecutive flush-fails → next flush re-resolves (an A-record flip = the zero-infra failover is picked up без IWDG-reboot). coap_consec_fail streak resets on any send_success; g_coap_fail_count stays a lifetime health-odometer (never reset). DNS-fail path already clears the IP (return before the streak logic — no double-count). Silicon-confirm = RUNBOOK §5.5 (👤 bench). CMD_SET_BACKEND never existed — the doc-phantom is purged.
2. RTC registers are nearly all spoken-for — but allocated ≠ optimally packed — DR0..DR19 allocated except DR7, freed by FW.54 (DID is now deterministic f(UID) recomputed on boot via did_derive.h — 03_01 §7; spend DR7 only via the 03_01 §2.2 procedure). After the FW.2 freeze-contract even DR15 is reserved (CCM Frame Counter, dormant until FW2_CCM_ENABLED flips at bench). For new persisted state: first check 03_01 §2.3.2 reclamation (under-utilized DRs → freeable without Flash: DR2 holds a 1-bit flag, DR14/DR19 pack) before paying Flash-KV (03_01 §2.3) wear. RAM-state inventory + key→field map = 03_01 §2.3.1. Canonical register map (bit-fields + magic markers) = 03_01 §2 — never restate the allocation in code comments, reference it.
3. Load_AES_Key() BEFORE MX_CRYP_Init() — reversing the order means CRYP uses a zeroed key. Both files follow this order but it's easy to break during refactoring.
4. Cold-TX deferral — at low temp + low Vcap (FW.10 winter ESR guard), Soldier skips TX entirely to avoid brownout. Don't assume every wake cycle emits a packet.
5. StatusByte layout is post-FW.29 — packet byte 10 = [PanicFlag:1 (bit7) | Status:2 (bits6..5) | GrowthPoints:5 (bits4..0)]; firmware packs (status << 5) | growth_points, backend unpacks (byte & 0x1F) * 2. Status now has 4 values (0 homeostasis / 1 stress / 2 anomaly / 3 vm_error — [SLASH-1 P0, 2026-07-05] status=3 is written ONLY by BIO_STATUS_VM_ERROR; mruby pack_status_byte returns 0..2; physical tamper rides PANIC_FLAG, NOT the status bits — backend decodes 3 as vm_error → firmware_fault alert, never vandalism_breach). Normal frames force bit7=0 (lora_payload[10] &= ~PANIC_FLAG_BIT); panic frames set it. Canon: 03_04 §4.4 Status-byte + 03_01 §8.
6. Lorenz state: continuation vs cold-start — on boot, DR19 == LORENZ_STATE_MAGIC (0x4C5A5354 "LZST") && isfinite(x,y,z) → restore (x,y,z) from DR16/17/18 (warm continuation, >99% of cycles); else cold-start derives (x₀,y₀,z₀) from K_seed (Flash) via common/lorenz_seed.h (pure-C HMAC-SHA256 — byte-parity with backend SeedDerivation, FW.30 closed; mbedTLS no longer needed). epoch_day prefers beacon UTC (soldier_unix_ts, FW.20) over the RTC calendar; RTC-default after VBAT loss = 10957 (2000-01-01) = backend's FIRMWARE_RTC_DEFAULT_EPOCH_DAY. After each cycle the C side MUST write DR16-18 + set DR19. Canon: 03_04 §2.1; layout 03_01 §2.
7. CCM is gated, ECB is live — WL CCM API is TWO-PHASE, and the CCM era is TWO-KEY — the FW.2 AES-128-CCM path (30B wire-rev2.1, 8B MIC, DR15 FC) is fully integrated behind FW2_CCM_ENABLED 0 (Soldier Phase-4 + panic TX; Queen = blind courier — cleartext-DID demux, NO decrypt, air+1 records via queen/rx_route.h). The shipping build is AES-128-ECB transitional. Traps: (1) HAL_CRYPEx_AESCCM_Encrypt/Decrypt DO NOT EXIST in WL-HAL (F4/F7/L4 API) — the real flow is Init.B0 (Build_CCM_B0) + HAL_CRYP_Encrypt/Decrypt (Size in BYTES) + HAL_CRYPEx_AESCCM_GenerateAuthTAG + caller-side Fw2_Ccm_Tag_Equal; after CCM restore width-units to WORD (MX_CRYP_Restore_From_CCM). (2) In the 14B CCM plaintext (rev2.1) status_byte is offset 6, offset 10 is diag, offsets 12..13 are ema_delta_t_s («wire = GP input» contract, E.63 (г)) — never read CCM payload through legacy 16B offsets. (3) Key-scoping (FW.2 (в), 2026-07-03): Soldier's ambient hcryp = KEYB cluster control-plane (bcast_key, page 125, Load_Broadcast_Key fail-open fallback→KEYL); session aes_key (KEYL) lives ONLY inside the CCM scope — MX_CRYP_Init_CCM sets pKey EXPLICITLY, Restore returns KEYB (a sticky session key would MIC-fail every frame on Rails). Queen's single LoRa key = the KEYB value (her code unchanged). FW.17 ratchet rotates session only. Mesh Scenario Б is gated OUT of the CCM build (star-only; mesh return = wire-rev3 addressing → 00_07 ARCH.43, scale ceiling 03_01 §1.9.1). (4) Gated-branch code compiles NOWHERE locally — host tests mirror, clangd can't see past the gate; a call before its static definition needs an explicit prototype or only hal_check_ccm (CI) catches it. All flip-gates DECIDED (founder 2026-07-03) — flip day = bench attestation only; 03_05 §2.1 flip-checklist + §3.1 two-key model + 00_07 FW.2.
8. HAL_GetTick() is frozen in STOP2 — SysTick stops during EnterSTOP2Mode, so a tick delta measures only active-time, NOT wall-time. Host mocks have a monotonic tick → they hide this. FW.49 S1 host-half is shipped: delta_t_seconds (the primary bio-signal) runs on wall-seconds via common/wall_time.h (Wall_Seconds_Now, RTC-calendar timebase, cold-start/backwards/epoch-jump guards → baseline; wire dT:2 saturates @0xFFFF). ⚠️ On silicon Wall_Seconds_Now returns 0 (honest refusal → baseline) until the LSE/RTC clock-tree bench bring-up (MX_RTC_Init absent from repo) — 00_07 FW.49; FW.27-B re-request counts silent wakeups instead of ticks (STOP2-immune by design). Still: never trust a raw tick delta as wall-seconds. Canon 03_01 §1.4/§1.10.
9. vcap_voltage is honest mV of VDDA, NOT the EDLC Vcap — post-FW.50 the raw-counts-as-mV bug is fixed: vcap_voltage = Adc_Vdda_Mv(...) (factory VREFINT-cal, common/adc_convert.h, host-tested) → ≈3300 mV while the buck lives, so the RX-listen window (2800) is open. But VREFINT sees VDDA behind the buck, not the supercap: the fauna gate (FAUNA_VCAP_MIN_MV=4500) is deliberately fail-CLOSED above the VDDA ceiling (tripwire-tested) until a real Vcap divider + separate ADC channel lands (hardware residual, 00_07 FW.50). Don't "fix" the 4500 threshold down — it's the honesty guard. Canon 03_01 §1.4.
10. BIO_STATUS_VM_ERROR = 0x60 (not 0xFF) — must survive the & ~PANIC_FLAG_BIT mask as status=3+gp=0. Backend decodes status=3 as vm_error (honest software-fault → firmware_fault ops-alert, [SLASH-1 P0] — NOT tamper/vandalism); emission_eligible_growth_points zeroes gp for anomaly/vm_error (defense-in-depth). A wire byte with status=anomaly/vm_error must NEVER mint.
11. OTA wire has two layers — LoRa Queen→Soldier: [0x99][idx:2][total:2][bytecode:11] (5B header). CoAP Rails→Queen: [0x99][idx:2][total:2][len:2][bytecode:len][crc16:2] — explicit len (NOT length-guessing from CBC padding — that bug truncated every chunk) + CRC16 verified via common/silken_crc.h. The assembled stream Soldier CRC32-checks = bytecode + zero-pad + CRC32, LoRa-MTU(11)-aligned. Built by OtaPackagerService. Canon 03_01 §4.6 / 03_02 §5.
12. cppcheck version-skew: a green local lint proves NOTHING about CI — CI runs cppcheck 2.13, the local silken_lint conda env has 2.21; the two classify diagnostics differently (2.13 gated constParameterCallback that 2.21 let pass → false-green local, red CI). Related trap: suppress-ids MIGRATE with usage — taking a callback's address flips constParameterPointer→constParameterCallback, silently unmatching an existing inline suppress. Also: deleting a header cppcheck couldn't resolve OPENS a deeper analysis path — expect previously-hidden pre-existing findings (2 shadowVariable surfaced when the radio.h stub died); fix them properly (rename), don't suppress.
13. Enabling compile-coverage of a gated block = wire ALL its board-freeze deps FIRST; CI-only verify means each miss is a separate red-push you can't catch locally (gotcha 7.4 — no ARM toolchain locally). THREE parts, miss any → red main: (a) the in-file #define GATE 0 MUST be #ifndef-wrapped so CMake's -DGATE=1 sticks — a bare #define clobbers the -D (macro-redefined = warning-not-error, in-file wins → block stays dead = a silent no-op guard; the exact ARCH.34 bug, re-hit on ARCH.35); (b) board pin-macros stubbed in queen_hal_check.c before its #include "../queen/main.c" (macros must precede use); (c) every HAL module the block calls enabled in hal_glue/stm32wlxx_hal_conf.h — ARCH.35 W25Q32 SPI → uncomment HAL_SPI_MODULE_ENABLED (mirror of how ARCH.34's block needs the already-enabled HAL_FLASH; compile-only OBJECT lib = header decl suffices, no link). Grep the block's FULL external-symbol set (sed -n 'A,Bp' main.c | grep -oE 'HAL_[A-Za-z]+|[A-Z][a-zA-Z]+_HandleTypeDef|<pin-macros>') and wire each BEFORE the first push — a review that flags one missing dep can miss a second (it flagged W25Q32_CS, not the SPI-HAL module). The macro-redefinition + gate arithmetic ARE host-verifiable (cc -DGATE=1 -E), even though the block itself isn't.

Common Tasks

• Add sensor field: Soldier Phase 1 ADC → pack in lora_payload[] → Queen Process_And_Cache_Data → Flush_Cache_To_Rails → Rails TelemetryUnpackerService unpack string → host tests. Check the RTC budget first (03_01 §2; DR7 is free post-FW.54 — spend via §2.2 procedure; §2.3.2 reclamation frees more before reaching for Flash).
• Change Lorenz params / bio_contract.rb: edit bio_contract.rb AND app/services/silken_net/attractor.rb → run parity tests (must stay bitwise-identical, Float IEEE-754 both sides). Two hidden gates a subset-run misses (both tripped in E.63 + E.64): (1) regenerate lorenz_bytecode.h (tools/firmware/gen_bytecode.sh) — the FW.46 sha256 stamp-gate goes red if it's stale; (2) a signature change → grep spec/ too (not just app/lib — once missed 6 integration-spec callers) + run the FULL bin/rspec, never a subset, before pushing a contract/DCI change.
• Change seed/cold-start crypto: edit common/lorenz_seed.h / silken_sha256.h ONCE (shared) → make -C firmware/test seed_derivation re-proves parity vs OpenSSL + backend SeedDerivation. Never fork the math into the test file.
• Modify AES: touch MX_CRYP_Init() in BOTH files, update Load_AES_Key()/Load_Broadcast_Key(), Restore_ECB_Mode(), host tests — and preserve the two-key scoping contract (gotcha 7.3; guarded by test_ccm.c::test_two_key_scoping_contract + KEYB-load tests in test_soldier_logic.c). On a bench, make -C firmware/test selftest sym_selftest (CCM + ECB/CBC KAT) attests silicon==OpenSSL — catches the CRYP_DATATYPE_32B word-swap class invisible to passthrough host mocks. New factory key slot? Mirror it in FactoryFlashing::CommandBuilder + 03_06 §2 (page 124 = per-device identity, page 125 = cluster membership KOTA/KEYB).
• Touch RTC-persisted state: update the 03_01 §2 canonical table FIRST (SSOT), add isfinite()/magic/range restore guards, then ≥3 host tests (cold-boot / warm-roundtrip / corruption-fallback).