46 lines
1.7 KiB
Plaintext
46 lines
1.7 KiB
Plaintext
---
|
|
description: DigiRadio core non-negotiables (always on)
|
|
alwaysApply: true
|
|
---
|
|
|
|
# DigiRadio — core rules
|
|
|
|
Firmware for ESP32-S3 on ESP-IDF v5.5.x. C++23 (-std=gnu++23),
|
|
strongly typed, class-based. C++ exceptions disabled. Companion chips:
|
|
Si4684 (DAB+/FM), ADAU1701 (SigmaDSP), FSC-BT1035 (Bluetooth).
|
|
Full spec: @AGENTS.md
|
|
|
|
## Behaviour
|
|
- Blockers first: state what breaks the build or the hardware before the
|
|
solution.
|
|
- Never invent a register address, opcode, bit field, or boot sequence.
|
|
If it is not in the datasheet, say so and stop. Cite the doc section.
|
|
- No silent failure: every fallible op returns a typed error.
|
|
- Ask when a hardware invariant is unclear — don't assume.
|
|
|
|
## Code That Fits in Your Head (hard limits)
|
|
- Cyclomatic complexity <= 7 per method; at 8, decompose.
|
|
- Method fits an 80x24 box: <= 80 cols wide, <= 24 lines tall.
|
|
- One method does one thing at one level of abstraction.
|
|
- Name for intent (`tuneTo`), not mechanism (`writeReg0x30`).
|
|
- Delete before you add.
|
|
|
|
## Errors
|
|
- Typed result `std::expected<T, Error>` (native under C++23), never a
|
|
bare int code. Every timeout is an explicit error value. No C++
|
|
exceptions (disabled in ESP-IDF).
|
|
|
|
## Embedded
|
|
- No dynamic allocation in audio or ISR paths, ever.
|
|
- No virtual calls in IRAM-safe ISRs (vtables live in flash).
|
|
- Every wait has a timeout and a defined failure path.
|
|
|
|
## Version control
|
|
- Small commits, each compiles and keeps tests green.
|
|
- Commit messages: 50/72 (summary <= 50 chars, body wrapped at 72).
|
|
|
|
## Definition of Done (summary — full list in @AGENTS.md §10)
|
|
Compiles warnings-as-errors; clang-tidy clean; Apache header on every
|
|
file; doc block on every class/method; `doxygen Doxyfile` exits 0;
|
|
typed errors; host tests green; no plaintext secrets.
|