BMW_E8x_EPS/eps-comms

EPS communication notes

Findings about what the Electric Power Steering (EPS) unit needs on the bus, built up from gateway sessions between the car's PT-CAN bus and the EPS's (isolated) bus via the CAN-IO board.

• EPS_PROTOCOL.md — the consolidated result: how to power up, control and monitor the EPS standalone (e.g. in a custom EV). Start here.
• findings.md — chronological working log: what was tested, what broke, and why.

Headline result: the EPS needs only two CAN messages (0x130 terminal status, 0x1A0 road speed) plus a 12V enable wire — not the 69 messages the car puts on the bus. Total required rate: 60 frames/s.

Setup

car PT-CAN --[CANdapter]-- gateway (this repo) --[CAN-IO board USB bridge]-- EPS bus -- EPS unit

• Car side: CANdapter, port varies (/dev/cu.usbserial-DNBJV4F5 as of writing).
• EPS side: CAN-IO board (XIAO ESP32-S3, can-io/), port varies (/dev/cu.usbmodemXXXX - changes on replug, always re-check with ls /dev/cu.*).
• Both sides run at 500 kbit/s.
• Tool: gateway/gateway_app.py (live relay + per-ID filter + IO test) or gateway/replay_to_bus.py (replay a capture onto one side, no car needed).
• Every gateway session logs every frame seen (relayed or not) to captures/gateway_<timestamp>.csv - columns: t, direction, arbitration_id, is_extended, dlc, data_hex, relayed.

Workflow

1. Transparent relay (current stage): everything allowed both ways, confirm EPS + car both still behave normally through the gateway.
2. Filter down: block IDs one at a time (or in groups) via the "Allow" checkboxes in gateway_app.py, re-test after each cut, to find the minimal set of car-bus messages the EPS actually needs.
3. Replay-only: once step 2 gives a candidate minimal set, use gateway/replay_to_bus.py to feed just those messages to the EPS with the car fully disconnected, to confirm it's really enough to bring the EPS up on its own.
4. Synthesize: once replay works, write a generator that produces those messages from scratch (no capture needed) - not started yet.

Tools

• gateway/gateway_app.py - live relay + per-ID filter + IO test (Streamlit).
• gateway/replay_to_bus.py - replay a capture CSV onto one adapter, with the same FilterRules filtering, --dry-run needs no hardware.
• tools/gateway_log_to_capture.py - turns a gateway session log (which has both directions + relay/block status) into a plain capture CSV for replay_to_bus.py, e.g. to replay exactly what a working live session sent, filtered to one direction and optionally only the frames that were actually relayed.
• tools/extract_dio_timeline.py - pulls the CAN-IO board's own digital IN1-4/OUT1-2 timeline out of a gateway log (decoded from its 0x100 status frames) - answers "when was the 12V signal high/low", and feeds replay_to_bus.py --dio-log so a replay reproduces the digital signal (e.g. the 12V repeat to the EPS) in sync with the CAN traffic, not just the CAN frames alone. Resolution is limited to whenever the board sent a status frame (on change, plus a 1s heartbeat) - a change undone within a couple of scheduling ticks might not show up as its own sample.
• gateway/rules.suggested.json / rules.suggested_car_to_eps.json - current best-guess filter (see findings.md for what's blocked and why): the combined form loads in gateway_app.py's sidebar, the plain form loads via replay_to_bus.py --rules.

Synthesis plan (not started)

Once a minimal, replay-confirmed message set is known:

1. For each required ID, write an encoder (the mirror image of files/decode_ptcan.py's SIGNALS decoders) that produces the raw bytes from a target value (angle, speed, rpm, terminal state, ...), including the alive-counter and checksum schemes already documented in files/PTCAN_protocol.md.
2. Start with static/slowly-changing values (terminal state, a fixed "engine running" RPM, zero speed) to prove the EPS accepts synthetic frames at all, before worrying about realistic dynamic values.
3. Time the generator against gateway/replay_to_bus.py's measured periods per ID (10ms for steering angle, 20ms for road speed, etc.) - this is also where the jitter hypothesis from findings.md gets tested: a dedicated generator (ideally on the CAN-IO board itself, not the PC) can hit those periods far more precisely than the PC-mediated relay.
4. Longer term: move the generator onto the CAN-IO board's firmware itself, so the final setup needs no PC in the loop at all.

Known pitfalls (see findings.md for detail)

• TX-echo feedback loop (fixed 2026-08-29): the CAN-IO board's firmware used to mirror every frame it successfully transmitted back over USB, including frames the gateway had just asked it to relay from the car bus - not just its own status/heartbeat. This made every relayed ID falsely reappear as "new EPS-bus traffic" a moment later, which is what session gateway_20260829_162235.csv shows (64 of 69 "eps->car" IDs were things just relayed car->eps seconds earlier). Fixed in can_bus.cpp/usb_bridge.cpp by only mirroring board-originated transmits, not bridge-injected ones. Any gateway log captured before this fix should be treated as unreliable for "what does the EPS bus actually carry" purposes.