wesandClaude Fable 5
9a5ee30db9
The campsite HAOS Pi now runs the ESPHome CAN node natively ("OneControl
CAN", *.onecontrol_can_*); the BLE integration is fully torn out (config
entry, custom_components on the Pi, stale MQTT registry orphans) and the
camper dashboard rewritten — water-pump tile dropped on purpose (pump is
panel-only), awning + fault sensors added.
New canbus/ha/mqtt_bridge_onecontrol.yaml (deployed to the Pi as
packages/mqtt_bridge.yaml) bridges the CAN entities to the home broker
via MQTT Discovery, same pattern as the gazebo bridge. Kept the old
unique_ids so home entity ids and recorder history carried over; added
an availability topic and explicit command-topic allowlists (3 switches
+ awning — a future debug entity must not become remotely controllable
for free). Round-trip verified from home HA.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
166 lines
10 KiB
Markdown
166 lines
10 KiB
Markdown
# Handoff — finish & flash the OneControl IDS-CAN node
|
||
|
||
**Goal:** complete and flash an ESP32 firmware that puts our RV's Lippert
|
||
OneControl system (tanks, lights, switches) into Home Assistant as native
|
||
entities, talking directly to the OneControl CAN network. This replaces the
|
||
slower Bluetooth integration in `../src/` + `../custom_components/`.
|
||
|
||
Read `README.md` first — it has the full message-format documentation, the node
|
||
map for this coach, and the wiring procedure. This file is just the current
|
||
state + what's left.
|
||
|
||
## FLASHED & READ-VERIFIED (2026-06-12, afternoon)
|
||
|
||
The node is built, flashed over USB, on the bus, and on WiFi
|
||
(`192.168.69.18`, hostname `onecontrol-canbus`, adoptable via the API key in
|
||
`secrets.yaml`). **All 11 read entities verified live over the native API**:
|
||
battery 13.27 V, tanks fresh 0 / black 33 / grey1 33 / grey2 100 %, interior
|
||
lights on, exterior/heater off, both fault flags clear, awning idle.
|
||
|
||
What changed this session:
|
||
- `secrets.yaml` filled (WiFi + fallback AP from the shared gazebo proxy creds).
|
||
- **Battery voltage decode finished** (remaining-work item 4): matches the
|
||
page-`0x11` `00 2B …` telemetry frame, `b2..b3` BE / 256 — reads 13.27 V.
|
||
- **Toolchain fixes** (ESPHome moved since the last build; it no longer compiled):
|
||
the `g_node_type` array global's bare `{}` initializer was ambiguous (named the
|
||
type), and the awning cover enum is `COVER_OPERATION_OPENING/CLOSING` (no `IS_`).
|
||
- **Dual `on_frame` trigger** — this build filters `on_frame` by frame type, so a
|
||
single `use_extended_id: true` trigger only saw the 29-bit frames; the 11-bit
|
||
read broadcasts (tanks/lights/heater/awning) were silently dropped. Added a
|
||
second `use_extended_id: false` trigger sharing the same lambda via a YAML
|
||
anchor. (This was the exact risk the bus-config note called out.)
|
||
- **Logger** — raised the `canbus` component to INFO and silenced the per-frame
|
||
dump; at DEBUG it logged ~50 frames/s and saturated the 115200 serial link.
|
||
|
||
Still TODO (needs the operator in the loop — see "Remaining work" items 5–6):
|
||
command-path verification (toggle a light) and the attended awning test.
|
||
|
||
## Current status (2026-06-12)
|
||
|
||
- **Message format documented and confirmed against live captures.** The bus is
|
||
Lippert **IDS-CAN** (250 kbit/s, 11-bit IDs), not RV-C. Every tank, light,
|
||
pump, heater, the awning, and battery voltage is decoded — see the node map in
|
||
`README.md`.
|
||
- **Read path:** modules broadcast their state continuously, no authentication.
|
||
- **Command path:** each command is preceded by a short challenge/response
|
||
authentication exchange (the same one the OEM app uses). Implemented in
|
||
`ids_can_auth.py` (reference) and `esphome/ids_can_auth.h` (the firmware copy,
|
||
verified **bit-exact** against the Python and against captured/live values).
|
||
- **Proven working end to end.** `idscan_cmd.py` ran the full exchange over a USB
|
||
CAN adapter and operated the interior lights (node `F8`) on/off/on, each
|
||
answering a distinct fresh challenge, with the module's own status broadcast
|
||
confirming the result. A bare command with no exchange is ignored.
|
||
- **Firmware compiled successfully** last night (`esphome/.esphome/build/…`).
|
||
|
||
## Hardware (assembly-ready)
|
||
|
||
- ESP32 WROOM devboard (`esp32dev`) + Waveshare **SN65HVD230** transceiver
|
||
(3.3 V logic, onboard 120 Ω terminator → this node is the bus-END node).
|
||
- **Power:** buck converter dialed to **5 V**, tapped from the panel's 12 V
|
||
supply (common ground with the bus — good). Feed the ESP32 5 V pin.
|
||
- **Connection:** Molex Mini-Fit Jr. pigtail into the panel's CAN **data** port
|
||
(the one with the terminator), per `README.md` → "Physical connection".
|
||
⚠️ Meter the port first: data idles ~2.5 V, power reads ~12 V; 12 V on CAN-H/L
|
||
destroys the transceiver.
|
||
- **Pigtail wiring (as crimped):** green = CAN-L, blue = CAN-H.
|
||
- **GPIO:** transceiver `CTX/D` ← ESP32 `GPIO5` (tx_pin), `CRX/R` → `GPIO4`
|
||
(rx_pin). Adjust `substitutions:` in the YAML if you wire differently.
|
||
|
||
## Remaining work (in order)
|
||
|
||
1. ~~**`secrets.yaml`**~~ — DONE. WiFi + fallback-AP creds filled from the shared
|
||
gazebo proxy; the `api_key` was already set.
|
||
2. ~~**First flash over USB**~~ — DONE (`/dev/ttyUSB0`). OTA from here on.
|
||
Note: this laptop's user isn't in the `uucp` group, so the serial node needed
|
||
`chmod 666 /dev/ttyUSB0` (resets on replug) — irrelevant for OTA.
|
||
3. ~~**Confirm the read entities populate**~~ — DONE. All 11 verified live over the
|
||
native API (see status block above). NB: ESPHome 2026.5 doesn't echo
|
||
`publish_state` at DEBUG over serial, so a quiet serial log is normal — read the
|
||
states over the API, not the console.
|
||
4. **Open read items in the YAML lambda:**
|
||
- ~~**Battery voltage**~~ — DONE; reads 13.27 V.
|
||
- Optionally add **water pump (`61`)** and **water heater (`95`)** — both are
|
||
ordinary switched loads, same decode + command path as the lights. (Heater is
|
||
already exposed; pump stays command-blocked.)
|
||
5. ~~**Verify the command path**~~ — DONE (Interior + Exterior lights, on & off,
|
||
each a confirmed challenge→response→opcode exchange on the serial log, with the
|
||
read-back flipping to match). Switches are now `optimistic:false` so HA shows
|
||
ground truth. **Confirmed module behaviour:** after a successful session the
|
||
module enforces a **~2 s cooldown** — a second command to the same load sooner
|
||
gets no challenge and is dropped (opcode-independent, module-side, not a bug).
|
||
The arm retry was widened to 8×150 ms to absorb the odd dropped frame on the
|
||
busy bus. Heater is wired the same way but wasn't actuated (avoid cycling gas
|
||
ignition casually); it should behave identically.
|
||
6. **Attended awning test (motor — watch it move).** The Awning `cover` is wired
|
||
(open/close/stop). On the first run, confirm: (a) which direction open/close
|
||
actually go, (b) whether one command runs to the travel limit or only moves
|
||
while commands stream. If it under-travels, change `send_load_command` to
|
||
stream the opcode (repeat until Stop) — only after watching it. The single-shot
|
||
default can't run the motor away.
|
||
7. ~~**Surface at the campsite HA**~~ — DONE (2026-06-12). Added to the campsite
|
||
HAOS Pi (`192.168.69.10`) as ESPHome config entry "OneControl CAN"; all 11
|
||
entities (`*.onecontrol_can_*`) live. The old BLE integration is **fully torn
|
||
out**: config entry deleted, `custom_components/lippert_onecontrol` removed
|
||
from the Pi, 11 stale `campsite_onecontrol_*` MQTT registry orphans purged
|
||
(home broker had no retained discovery topics — they were registry-only). The
|
||
camper dashboard (`lovelace.dashboard_camper`) was rewritten to the new
|
||
entities; the water-pump tile was dropped (pump is panel-only by design) and
|
||
awning + both fault sensors added.
|
||
8. ~~**Bridge home via MQTT**~~ — DONE (2026-06-12 evening). The Pi package
|
||
`/config/packages/mqtt_bridge.yaml` was rewritten against the CAN entities
|
||
(repo copy: `canbus/ha/mqtt_bridge_onecontrol.yaml`); it publishes MQTT
|
||
Discovery + state to cyrion's Mosquitto (192.168.88.69) and relays commands
|
||
back, same pattern as the gazebo bridge. Same `unique_id`s kept for surviving
|
||
loads, so home HA entity ids + history carried over (`*.campsite_onecontrol_*`);
|
||
water pump / cover_2 / cover_3 retained topics cleared (entities auto-removed
|
||
on home); awning + both fault sensors added, plus an availability topic
|
||
(`campsite/onecontrol/availability`) the old bridge lacked. Home Overview
|
||
"Camper" view updated to match. Command round-trip verified from home HA.
|
||
|
||
The DSI fault is already decoded and wired in (see below) — no capture needed.
|
||
|
||
## File map
|
||
|
||
| File | What it is |
|
||
|------|-----------|
|
||
| `esphome/onecontrol-canbus.yaml` | the ESP32 firmware (read dispatch + command path) — the thing to finish & flash |
|
||
| `esphome/ids_can_auth.h` | command-authentication response, used by the YAML lambda |
|
||
| `esphome/secrets.yaml.example` | template for the git-ignored secrets |
|
||
| `ids_can_auth.py` | Python reference for the same authentication + 51/51 self-test |
|
||
| `idscan_cmd.py` | desktop tool that proved the command path over a USB CAN adapter |
|
||
| `captures/` | raw bus logs + the challenge/response pairs + `analyze_auth.py` |
|
||
| `captures/log-can.sh` | bring up the USB CAN adapter and log frames |
|
||
| `README.md` | full message-format documentation + node map + wiring |
|
||
|
||
## Safety notes
|
||
|
||
- **SLIDES, JACKS, and the WATER PUMP ARE PANEL/APP ONLY — never over CAN. This
|
||
is a hard rule, do not weaken it.** `esphome/command_guard.h`
|
||
(`command_blocked()`) is the single source of truth: it refuses the slide/jack
|
||
nodes (6A/7F/9C, effective even before a node's identity is heard), the water
|
||
pump (61, winterizing-only), and — generally — any motor-class (0x21) node other
|
||
than the awning. It's enforced in two independent places (the command-entry
|
||
script and the actual transmit point), so loosening one does not open the other.
|
||
Wiring a switch for a blocked node cannot actuate it; the gate drops the command
|
||
before any frame goes out.
|
||
- **Exposed (controllable) loads:** exterior lights (2A), interior lights (F8),
|
||
water heater (95) as `switch`es, and the awning (75) as a `cover`. To expose
|
||
another *permitted* switched load, add its node to the layer-2 allowlist in
|
||
`send_load_command` and add a `switch` entity; never add a slide/jack/pump.
|
||
- **The awning is a motor — its first actuation must be attended** (see
|
||
remaining-work item 6). The wired commands are single-shot, which can't run the
|
||
motor away, but direction and latch-vs-stream behavior need a live check.
|
||
- The physical connection is fully reversible: unplug, re-seat the terminator.
|
||
- One transceiver = one bus-end terminator. Never add a terminated node in the
|
||
middle of the bus (would make three terminators).
|
||
|
||
## DSI fault — DECODED (2026-06-12)
|
||
|
||
Forced a real lockout and captured it (`captures/dsi-fault-*.log`). Already wired
|
||
into the YAML as two `binary_sensor`s; nothing left to do here.
|
||
|
||
- **Water Heater DSI Fault** = node `95` page-3 `b0` bit5 (`0x20`). Healthy heater
|
||
= `0x80` off / `0x81` running; lockout = `0xA0`.
|
||
- **OneControl System Fault** = page-0 `b0` bit0 (`0x01`), a bus-wide
|
||
"fault exists somewhere" flag (read from node `95`'s page 0 in the lambda).
|