micheleandCursor
425b3f98cf
Add ch-api.tex for REST endpoints and boot flow, update ch-firmware, ch-build, and ch-intro. Extend CONTRIBUTING, instructions, and README with manual sync checks and API reference. Co-authored-by: Cursor <cursoragent@cursor.com>
100 lines
4.6 KiB
TeX
100 lines
4.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{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}, and
|
|
\texttt{POST /api/wifi} for provisioning. JSON parsing and serialisation
|
|
delegate to the pure core; credentials persist via \texttt{ISecureStore}.
|
|
|
|
\section{NetBootstrap}\label{cls:NetBootstrap}
|
|
Owns network resources for setup or STA mode. \texttt{start(store)}
|
|
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.
|
|
|
|
% ------------------------------------------------------------------
|
|
% Future slices (drivers, services)
|
|
% ------------------------------------------------------------------
|
|
% \section{Si4684Driver}\label{cls:Si4684Driver}
|
|
% \section{TunerService}\label{cls:TunerService}
|
|
% ...
|