Core architecture layers
CAN ingestion
Telemetry state
Lock calculations
Frame shaping
HTTP API
UI client
Layer responsibilities
can_rx.cpp: reads chassis/haldex buses, decodes mapped and fallback telemetry.state.cpp: shared runtime state, persistent tuning arrays, input mappings, gates.calcs.cpp: computes lock request from mode plus curves/maps and safety gates.frames.cpp: applies lock request to generation-specific output frame payloads.api.cpp: exposes control/status/map/curve/log/ota/network endpoints.storage.cpp: stores and restores settings from non-volatile preferences.filelog.cpp: log routing, retention, read/delete/clear file operations.data/ui-dev/*: browser UI that drives everything through HTTP API.
Design principle
UI is replaceable. Firmware control path is authoritative. Any custom UI should obey firmware state and endpoint
contracts rather than duplicating mode and calculation logic in-browser.
State ownership model
| Domain |
Owner |
Persistence |
Notes |
| Current mode |
state.mode |
Runtime + storage |
Set by /api/mode, constrained when debug capture profile is active. |
| Input mappings |
mapped_input_* |
Storage via /api/settings |
Keys resolved at runtime into DBC bindings. |
| Curves/maps |
state.cpp arrays |
Storage + map files |
Used by dynamic modes; UI edits data, firmware runs interpolation. |
| Live telemetry |
received_* values |
Runtime only |
Updated by mapped decode first, then fallback decode when stale/missing. |
| Logs |
filelog.cpp |
LittleFS |
Scoped logs (all, can, error) with rotation. |
Safety boundaries
- Controller can be globally disabled without deleting tuning artifacts.
- Dynamic mode low-speed disengage is mode-specific and can be set independently.
- Global gates (
disableThrottle, disableSpeed) are firmware-enforced.
- Debug capture profile forces stock/controller-off behavior under high diagnostic load.
- Mapped telemetry has timeout fallback so stale source keys do not freeze values permanently.
Try the OpenHaldex Firmware Demo
Preview the real OpenHaldex firmware UI in your browser with simulated live CAN traffic and interactive pages for tuning, diagnostics, logs, setup, and OTA workflows.
Open firmware demo