Bored Systems logo Bored Systems shield Bored Systems logo dark Bored Systems shield dark
  1. Home
  2. OpenHaldex
  3. Legacy S3 Developer Reference

Legacy S3 Developer Reference

Legacy OpenHaldex-S3 archive

Legacy OpenHaldex-S3 developer reference

This reference describes the earlier MIT-licensed S3 edition. Its firmware paths, APIs and wiring assumptions do not describe the current SS application. For SS v1.1, use current SS documentation, the SS installation guide and openhaldex.dev.

This archived technical hub covers OpenHaldex-S3 engineering work: firmware architecture, CAN decoding, torque-request calculations, diagnostics behavior, endpoint contracts, and release validation. Use it alongside the legacy S3 source for that edition.

Firmware C++ Core Integration + API GitHub Source

Primary Audience

Firmware developers, CAN reverse engineers, and frontend/tooling integrators.

Source of Truth

src/functions/* controls runtime behavior. UI clients consume API state.

Core Domains

Control logic, CAN decode mapping, diagnostics/logging, network/OTA, API contracts.

Target Platform

ESP32-S3 with Gen1/Gen2/Gen4 Haldex generation-aware frame shaping.

Developer Workflow (Start-to-Finish)

  • 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.
Open file ownership map

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_rpm
Read mapping internals

Do 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 behavior
Open integration patterns

  • Confirm capture mode lockouts (409 canview capture mode active) are handled cleanly.
  • Verify curve/map payload bounds and strict ascending point rules.
  • Check OTA stage/progress fields and failure paths under weak network conditions.
  • Retest logs list/read/delete/clear behavior after persistence changes.

Quick Navigation Matrix

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

Runtime Ownership Rule

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.

Source Tree Entry Points

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.

Developer Deliverable Standard

  • Document the affected runtime path and endpoint contract changes.
  • Provide before/after behavior notes with realistic CAN or status evidence.
  • Keep user-facing docs and technical docs updated in the same release cycle.
  • Avoid multi-variable tuning changes without intermediate validation checkpoints.

Identify the legacy S3 edition when citing this archive in code reviews, integration work or articles about firmware behavior.

© Bored Systems
Theme Settings
Color Scheme
Light
Dark
Layout Mode
Fluid
Boxed
Topbar Color
Light
Dark
Menu Color
Light
Dark
Layout Position
Buy Now