Firmware + Integration Documentation
This technical hub is the canonical reference for OpenHaldex-S3 engineering work: firmware architecture, CAN decoding, torque-request calculations, diagnostics behavior, endpoint contracts, and release validation. If you are building tooling, extending firmware logic, or publishing integration guides, start here.
Firmware developers, CAN reverse engineers, and frontend/tooling integrators.
src/functions/* controls runtime behavior. UI clients consume API state.
Control logic, CAN decode mapping, diagnostics/logging, network/OTA, API contracts.
ESP32-S3 with Gen1/Gen2/Gen4 Haldex generation-aware frame shaping.
can_rx.cpp: signal ingestion and mapped/fallback telemetry updates.calcs.cpp: mode output, gates, interpolation, and lock release shaping.frames.cpp: generation-specific output-byte mutation before TX.api.cpp: endpoint contracts and mutator validation logic.storage.cpp + filelog.cpp: persistence and operational logs.Mapped inputs use bus|frameId|signalName|unit keys with mux checks and 1000 ms freshness windows.
mapped decode -> freshness check -> fallback decode (if stale)
-> received_vehicle_speed / received_pedal_value / received_vehicle_rpmDo not mirror control calculations in frontend code. Write through mutators, then read firmware truth.
GET /api/status
POST /api/settings (or map/curve endpoint)
GET /api/status
GET /api/canview or /api/logs when validating behavior409 canview capture mode active) are handled cleanly.| Need | Go to |
|---|---|
| CAN decoding + mappings | Core: Mapping |
| Mode/gate/interpolation behavior | Core: Control Logic |
| Frame output by generation | Core: Frame Shaping |
| Payload schema by endpoint | Integration: Payloads |
| OTA/network integration | Integration: OTA |
| Release verification checklist | Integration: Checklist |
OpenHaldex firmware is authoritative for drivetrain control and safety boundaries.
UI/API clients should present, mutate, and verify state. They should not redefine lock-request logic.
| Area | Primary file(s) | What changes there |
|---|---|---|
| Control request model | src/functions/core/calcs.cpp |
Mode targets, speed gates, interpolation, release smoothing. |
| CAN receive/decode | src/functions/can/can_rx.cpp |
Mapped inputs, freshness timeout, fallback decode semantics. |
| Output frame shaping | src/functions/can/frames.cpp |
Generation-specific lock-byte mutation on Haldex TX path. |
| HTTP API surface | src/functions/api/api.cpp |
Route registration, payload validation, mutator behavior. |
| Persistence + logs | src/functions/storage/storage.cpp, src/functions/storage/filelog.cpp |
NVS/LittleFS state, maps/curves, file-based diagnostics logs. |
| Network + OTA backend | src/functions/net/update.cpp, wifi.cpp |
Manifest check, staged install, AP/STA + internet status behavior. |
Use this hub as the reference URL when publishing code reviews, integration PRs, or external articles about OpenHaldex firmware behavior.