159 lines
7.6 KiB
TeX
159 lines
7.6 KiB
TeX
\chapter{Class Reference}
|
||
\label{ch:classes}
|
||
|
||
This chapter documents the firmware's public classes at the design level:
|
||
what each class is responsible for, which collaborators it depends on, its
|
||
key invariants, and how it fits the system. It complements --- and does
|
||
not duplicate --- the generated API documentation, which carries the exact
|
||
method signatures. The HTTP JSON endpoints are documented separately in
|
||
Chapter~\ref{ch:api}.
|
||
|
||
\begin{drnote}[How this chapter grows]
|
||
Per the development rules, every public, architecturally-significant class
|
||
(the drivers, the application services, and the public domain-core types)
|
||
gets a section here, tagged \texttt{\textbackslash label\{cls:ClassName\}},
|
||
added in the same change that introduces the class. A tooling check keeps
|
||
this chapter in step with the code, so it is always current.
|
||
\end{drnote}
|
||
|
||
The firmware is under active development. As each public class lands, its
|
||
section appears below, grouped by layer: domain core, application
|
||
services, and hardware drivers.
|
||
|
||
% ------------------------------------------------------------------
|
||
% Domain core (Slice 1)
|
||
% ------------------------------------------------------------------
|
||
|
||
\section{FirmwareVersion}\label{cls:FirmwareVersion}
|
||
Strong type wrapping the firmware release identifier (e.g.\ \texttt{0.1.0}).
|
||
Used by \texttt{HealthStatus} and the \texttt{/api/health} endpoint so
|
||
version strings are never passed as bare \texttt{char*} across module
|
||
boundaries. Invariant: non-empty at construction.
|
||
|
||
\section{FrequencyKHz}\label{cls:FrequencyKHz}
|
||
Validated FM centre frequency in kilohertz (64\,000–108\,000). Parsed once
|
||
from JSON at the HTTP boundary via \texttt{FrequencyKHz::tryFromKhz()};
|
||
trusted downstream by \texttt{ITuner}, \texttt{Si4684Driver}, and status DTOs.
|
||
|
||
\section{HealthStatus}\label{cls:HealthStatus}
|
||
Immutable health-check DTO returned by \texttt{GET /api/health}. Built via
|
||
\texttt{HealthStatus::ok(FirmwareVersion)} in the pure core; JSON
|
||
serialisation lives in \texttt{serializeHealthStatusJson()}. No ESP-IDF
|
||
headers.
|
||
|
||
% ------------------------------------------------------------------
|
||
% Network shell (Slice 1)
|
||
% ------------------------------------------------------------------
|
||
|
||
\section{SoftApConfig}\label{cls:SoftApConfig}
|
||
Immutable value type holding SoftAP parameters (SSID, channel, station
|
||
limit). Factory \texttt{setupDefault()} yields SSID \texttt{DigiRadio-setup}
|
||
for first-time provisioning.
|
||
|
||
\section{SoftApHost}\label{cls:SoftApHost}
|
||
RAII wrapper around the ESP-IDF Wi-Fi stack that starts and stops the
|
||
configured SoftAP. Imperative shell; no business logic.
|
||
|
||
\section{SetupWebServer}\label{cls:SetupWebServer}
|
||
Minimal HTTP server: gzipped setup UI, \texttt{GET /api/health},
|
||
\texttt{POST /api/wifi}, and tuner routes (\texttt{/api/tuner/*}).
|
||
JSON parsing and serialisation delegate to the pure core; credentials
|
||
persist via \texttt{ISecureStore}; tuner operations via
|
||
\texttt{tuner::TunerService}.
|
||
|
||
\section{NetBootstrap}\label{cls:NetBootstrap}
|
||
Owns network resources for setup or STA mode.
|
||
\texttt{start(store, tuner)} initialises the platform, joins stored Wi-Fi
|
||
when credentials exist, or falls back to the \texttt{DigiRadio-setup}
|
||
SoftAP. Must outlive \texttt{app\_main} for the process lifetime.
|
||
|
||
% ------------------------------------------------------------------
|
||
% Domain core + secure store (Slice 2)
|
||
% ------------------------------------------------------------------
|
||
|
||
\section{Secret}\label{cls:Secret}
|
||
Opaque wrapper for sensitive strings. Buffer is zeroised on destruction;
|
||
no \texttt{operator<<} and no plaintext serialisation. Shell code uses
|
||
\texttt{usePlaintext()} transiently for driver APIs only.
|
||
|
||
\section{WifiSsid}\label{cls:WifiSsid}
|
||
Validated Wi-Fi SSID (1--32 bytes). Parsed once from untrusted JSON at
|
||
the HTTP boundary before persistence or driver calls.
|
||
|
||
\section{WifiCredentials}\label{cls:WifiCredentials}
|
||
Domain value pairing \texttt{WifiSsid} with a \texttt{Secret} password.
|
||
Open networks use an empty password; WPA-PSK requires 8--63 characters.
|
||
|
||
\section{ISecureStore}\label{cls:ISecureStore}
|
||
Abstract persistence boundary for credentials at rest. Slice~2 implements
|
||
Wi-Fi credential save/load/clear; station list and user credentials arrive
|
||
in later slices. Host tests use fakes; the shell uses \texttt{NvsSecureStore}.
|
||
|
||
\section{StaClient}\label{cls:StaClient}
|
||
RAII STA join helper with an explicit connect timeout. Assumes
|
||
\texttt{esp\_wifi\_init()} was already called by \texttt{NetBootstrap}.
|
||
|
||
\section{NvsSecureStore}\label{cls:NvsSecureStore}
|
||
\texttt{ISecureStore} implementation backed by an NVS namespace. Passwords
|
||
are stored as NVS strings and never logged. Production should enable NVS
|
||
encryption using the reserved \texttt{nvs\_keys} partition.
|
||
|
||
% ------------------------------------------------------------------
|
||
% Hardware drivers (Slice 3)
|
||
% ------------------------------------------------------------------
|
||
|
||
\section{IFirmwareBlobReader}\label{cls:IFirmwareBlobReader}
|
||
Abstract streaming reader for firmware blobs embedded in flash. The Si4684
|
||
driver uses it to HOST\_LOAD patch and application images in bounded SPI
|
||
chunks without allocating the full image on the heap. Host tests use the
|
||
same interface over in-memory buffers.
|
||
|
||
\section{EmbeddedBlobReader}\label{cls:EmbeddedBlobReader}
|
||
Non-owning \texttt{IFirmwareBlobReader} over a contiguous byte range (linker
|
||
symbols from \texttt{EMBED\_FILES} or test data). Implements offset-based
|
||
\texttt{read()} with truncation at end-of-blob.
|
||
|
||
\section{Si4684EmbeddedImages}\label{cls:Si4684EmbeddedImages}
|
||
Owns \texttt{EmbeddedBlobReader} views over \texttt{rom\_patch\_016.bin},
|
||
\texttt{dab\_firmware.bin}, and \texttt{fm\_firmware.bin}. Constructed once;
|
||
passed to \texttt{Si4684Driver}. \texttt{applicationImage(Si4684Band)} selects
|
||
DAB or FM.
|
||
|
||
\section{Si4684Driver}\label{cls:Si4684Driver}
|
||
Full SPI driver for the Si4684 DAB+/FM tuner (Chapter~\ref{ch:si4684}).
|
||
|
||
\texttt{boot(Si4684Band)} runs AN649 HOST\_LOAD, configures I\textsuperscript{2}S
|
||
and band-specific properties, and records \texttt{loadedBand()}. After boot the
|
||
driver exposes FM tuning/seek/RSQ/RDS, DAB ensemble tuning, digital service list
|
||
fetch, and \texttt{startDabService}. Property access (\texttt{setProperty},
|
||
\texttt{setVolume}) and diagnostics (\texttt{getPartInfo}, \texttt{getSysState})
|
||
are included. Wrong-band calls return \texttt{Si4684Error::WrongBand}.
|
||
Register-level opcodes remain private; see \texttt{Si4684Types.hpp} for status
|
||
DTOs.
|
||
|
||
\section{Adau1701Driver}\label{cls:Adau1701Driver}
|
||
RAII I2C driver for the ADAU1701 SigmaDSP. \texttt{boot()} asserts RESET\#,
|
||
initialises the shared I2C bus, and replays the SigmaStudio export from
|
||
\texttt{Firmware/ADAU1701-Firmware/} on every power-up (no EEPROM self-boot
|
||
on DigiRadio).
|
||
|
||
% ------------------------------------------------------------------
|
||
% Application services (Slice 4)
|
||
% ------------------------------------------------------------------
|
||
|
||
\section{ITuner}\label{cls:ITuner}
|
||
Abstract tuner boundary in the pure core. Defines boot, band selection,
|
||
status readout, FM/DAB tuning, service list, playback, and volume without
|
||
ESP-IDF types. \texttt{si4684::Si4684Tuner} implements it on device; host
|
||
tests can use fakes.
|
||
|
||
\section{TunerService}\label{cls:TunerService}
|
||
Application service exposing intent-level tuner operations to HTTP and
|
||
future UI. Holds a reference to \texttt{core::ITuner}, tracks last tune
|
||
target and volume, and maps driver failures to \texttt{core::TunerError}.
|
||
|
||
\section{Si4684Tuner}\label{cls:Si4684Tuner}
|
||
\texttt{ITuner} adapter over \texttt{Si4684Driver}. Translates domain calls
|
||
into SPI commands and maps \texttt{Si4684Error} to \texttt{TunerError}.
|
||
Constructed once in \texttt{HardwareBootstrap} alongside the driver.
|