docs: add e-golf integration guidance

AGENTS.md

@@ -0,0 +1,33 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+`VWBMSV2/` holds the active Teensy 3.2 firmware: `VWBMSV2.ino` bootstraps the system, `BMSModule*` manage CMU data, `SerialConsole.*` handles CLI diagnostics, and `Logger.*` persists pack state. Support sketches live in `Teensy_can/` and `VWbms/` for quick experiments, while `VW GTE E-Golf Can/` stores reference DBC files and capture logs. Hardware-specific defaults and EEPROM mirrors are centralized in `VWBMSV2/CONFIG.H`; keep board profiles and pin maps there. Generated HEX files land in `VWBMSV2/build/`.
+
+## Build, Test, and Development Commands
+Use the Teensy/Arduino toolchain locally; install the Teensy core once via `arduino-cli core install teensy:avr`. Common commands:
+```
+arduino-cli compile --fqbn teensy:avr:teensy31 VWBMSV2        # build for Teensy 3.2
+arduino-cli upload --fqbn teensy:avr:teensy31 -p /dev/ttyACM0 VWBMSV2
+teensy_loader_cli --mcu=TEENSY32 -w VWBMSV2/build/VWBMSV2.ino.hex
+arduino-cli monitor -p /dev/ttyACM0 -c baudrate=115200        # watch SerialConsole output
+```
+Rebuild whenever `CONFIG.H` or any module changes; cached artifacts will otherwise keep stale calibrations.
+
+## Coding Style & Naming Conventions
+Match the existing two-space indentation, braces on the same line as declarations, and `UpperCamelCase` for classes (`BMSModuleManager`) with lower camelCase for methods/variables (`decodecan`, `lowpassFilter`). Keep constants `ALL_CAPS` and prefer `constexpr` over macros where possible. When adding files, route includes through project-relative headers, and update `CONFIG.H` for any new pin, CAN ID, or threshold so downstream agents can audit changes quickly.
+
+## Testing Guidelines
+There is no automated unit test harness yet; rely on bench validation. Before flashing, enable verbose logging by toggling the relevant `DEBUG_LEVEL` flags in `Logger.cpp`, then exercise charge, drive, and balance modes via `SerialConsole` commands. Capture CAN traffic with the `Teensy_can` sketch to confirm frame layouts whenever you touch `decodecan`/`decodebal` logic. Document measured pack voltages and temperatures in your PR if they vary from configured values.
+
+## Commit & Pull Request Guidelines
+Commits follow short, imperative subjects (`Update balancing check`, `SOH to reflect cell gap`). Reference the touched subsystem (`BMSModuleManager`, `SerialConsole`, `CONFIG`). For PRs, include: problem statement, summary of firmware behavior changes, hardware/firmware versions used for validation, console logs or CAN captures that prove success, and any remaining risks. Link related issues and call out EEPROM layout changes so other contributors can plan migrations.
+
+## Configuration & Safety Tips
+Treat `CONFIG.H`, EEPROM schema, and `EEPROMSettings` structures as the single source of truth for pack geometry, sensor type, and charger profiles. Validate over-current/over-temp thresholds against the real pack before merging. Never commit customer-specific CAN keys or VIN data; store those in local `*.local.h` files ignored by Git if you must keep templates.
+
+## E-Golf Integration Checklist
+- Safety: e-Golf packs stay above 350 V and hide a DC-link capacitor inside the contactor box; discharge it with a resistor before loosening any HV hardware.
+- Harness: half-modules expose connector TE 1-1670990-1 (alias 6R0 972 930). Wire pin 1=GND, 3=Enable 12 V, 5=+12 V, 6=CAN-H, 7=CAN-L, then daisy-chain CAN to the Teensy.
+- CAN protocol: firmware already transmits the required `0x0BA` poll (`VWBMSV2.ino:190`) and listens for module replies on `0x1CC–0x1D4` inside `BMSModuleManager::decodecan`. Verify IDs against `VW GTE E-Golf Can/VWtest.dbc` when sniffing traffic.
+- Configuration: set the pack series count, charger thresholds, and sensor options in `VWBMSV2/CONFIG.H`, then document your measured volt/temperature limits in PRs.
+- More detail lives in `e-golf-notes.md`; keep it updated with wiring changes, contactor control expectations, and EEPROM migration steps.

README.md

@@ -1,2 +1,56 @@
 # VW-bms
-Can based decoding of VW bms data
+A Teensy 3.2 firmware and set of helper sketches for decoding, monitoring, and controlling VW e-Golf battery modules over CAN. The active firmware (`VWBMSV2`) polls the OEM CMUs, enforces pack safety limits, drives contactors/chargers, and exposes a serial console for diagnostics and configuration.
+
+## Firmware highlights
+- `VWBMSV2/VWBMSV2.ino` bootstraps the hardware (GPIO, ADC, PWM, CAN, EEPROM), tracks pack state (SOC, charge/discharge modes, charger coordination), and mediates Victron VE.Direct/VE.Can messaging.
+- `BMSModule.*` models an individual CMU: it decodes cell voltages, temperatures, alert/fault bits, and balancing status directly from VW frames.
+- `BMSModuleManager.*` owns a fleet of modules, providing helpers to sum pack voltage, aggregate temperature extremes, balance cells, and produce CSV/console summaries used by the logger and CLI.
+- `SerialConsole.*` implements the USB menu (`h`, `p`, `d`, `B`, etc.) so you can wake boards, clear faults, trigger balancing, and stream pack details every few seconds while tuning parameters.
+- `Logger.*` delivers timestamped log output with adjustable verbosity (`LOGLEVEL` in the console) and is the backbone for bench validation.
+- `CONFIG.H` and the `EEPROMSettings` struct centralize hardware defaults: pack geometry, charger profiles, current-sensor selection, CAN IDs, trip timers, and hysteresis thresholds. Rebuild whenever you touch this file so the Teensy EEPROM stays synchronized.
+
+## Repository layout
+- `VWBMSV2/` – Active Teensy 3.2 sketch plus supporting modules, logger, CLI, config header, and generated HEX/build artifacts.
+- `Teensy_can/` – Minimal FlexCAN sketch for sniffing bus traffic or validating charger/module IDs before flashing the full firmware.
+- `VWbms/` – Quick prototype sketch used for experiments outside the main firmware loop.
+- `VW GTE E-Golf Can/` – Reference DBC, INI, and spreadsheet captures of VW IDs (`0x0BA` poll, `0x1CC–0x1D4` replies) for verifying decoder changes.
+- `e-golf-notes.md` – Wiring, contactor, and EEPROM migration details specific to the e-Golf integration checklist.
+- `AGENTS.md` – Maintainer guidance on coding style, safety practices, and PR expectations (summarized here).
+
+## Build and flash
+Install the Teensy core once:
+
+```bash
+arduino-cli core install teensy:avr
+```
+
+Compile, upload, and monitor via USB:
+
+```bash
+arduino-cli compile --fqbn teensy:avr:teensy31 VWBMSV2
+arduino-cli upload --fqbn teensy:avr:teensy31 -p /dev/ttyACM0 VWBMSV2
+teensy_loader_cli --mcu=TEENSY32 -w VWBMSV2/build/VWBMSV2.ino.hex
+arduino-cli monitor -p /dev/ttyACM0 -c baudrate=115200
+```
+
+Rebuild any time you modify `CONFIG.H`, `EEPROMSettings`, or module code so cached artifacts do not carry stale calibrations.
+
+## Configuration workflow
+1. **Pack geometry & thresholds** – Edit `VWBMSV2/CONFIG.H` to set `Scells`, `Pstrings`, voltage/temperature limits, charger types, current-sensor selection (`Analoguedual`, `Canbus`, etc.), and CAN IDs (`controlid` `0x0BA`, module response base `0x1CC` by default).
+2. **EEPROM schema** – Keep the `EEPROMSettings` layout in sync with your changes and bump `EEPROM_VERSION` whenever fields move; this prevents mismatched flash/EEPROM data.
+3. **Board profiles** – Map pins (inputs, contactor outputs, PWM current display) directly in `VWBMSV2.ino` or extend `CONFIG.H` if you bring up new hardware.
+4. **Victron / charger integration** – Adjust VE.Direct strings, charger CAN IDs, and current limits inside `VWBMSV2.ino` to match your hardware, then document the measured voltage and temperature behavior in your PR.
+5. **Balancing & ignore windows** – Tune `balanceVoltage`, `balanceHyst`, `IgnoreVolt`, and `DeltaVolt` via `CONFIG.H` so `BMSModuleManager::balanceCells` keeps the pack within safe deltas.
+
+## Diagnostics and testing
+- **Serial Console** – Connect at 115200 baud, toggle pack summaries (`p`) or detailed dumps (`d`), run `B` to pulse balancing, `F/R/W` to discover and renumber CMUs, and set `LOGLEVEL` interactively.
+- **Logger** – For bench work, raise the log level in `Logger.cpp` or through the console so you capture charge/drive/balance transitions alongside CAN measurements.
+- **CAN sniffing** – Use `Teensy_can/Teensy_can.ino` or an external tool with `VW GTE E-Golf Can/VWtest.dbc` to confirm decoder changes (`decodecan`, `decodebalVW`, `decodetemp`) before committing.
+- **Bench validation** – Exercise charge, drive, and balance modes while capturing Victron/charger interactions; there is no automated unit test harness yet, so console logs and CAN captures prove behavior.
+
+## Safety and integration notes
+- Follow the e-Golf checklist in `e-golf-notes.md`: discharge the DC-link capacitor before service, wire TE 1-1670990-1 pins (1=GND, 3=Enable 12 V, 5=+12 V, 6/7=CAN) correctly, and set pack series count plus charger thresholds in `CONFIG.H`.
+- Document EEPROM layout or migration changes in PRs so other boards can be upgraded safely.
+- Never commit customer-specific CAN keys or VINs; keep any local overrides in ignored `*.local.h` files.
+
+With this layout and tooling, you can iterate on VW e-Golf battery support, extend sensor/charger integrations, and capture the evidence needed for safe firmware updates.

e-golf-notes.md

@@ -0,0 +1,24 @@
+# E-Golf Integration Notes
+
+## Safety
+- Pack >350VDC; discharge the DC link capacitor inside the contactor box before touching bus bars.
+- No factory service disconnect; isolate mechanically and electrically before splitting modules.
+
+## Module Harness
+- Connector: TE 1-1670990-1 (aka 6R0 972 930).
+- Pinout: 1=GND, 3=Enable 12V, 5=+12V, 6=CAN-H, 7=CAN-L.
+- Each half-module needs the enable pin held high and 12V supply to wake the CMU.
+
+## CAN Protocol
+- CMUs expect a periodic 0x0BA poll frame (either all zeros or 0x45 0x01 0x28 0x00 0x00 0x00 0x00 0x30).
+- Modules reply on 0x1CC–0x1D4; matches `BMSModuleManager::decodecan` mappings.
+- `VWBMSV2.ino` already sets `controlid = 0x0BA`, so firmware is aligned with wiki docs.
+
+## Firmware Touchpoints
+- Update `VWBMSV2/CONFIG.H` with e-Golf series counts, current sensor choice, and charger thresholds.
+- Use `SerialConsole` commands to toggle drive/charge modes and inspect module summaries while commissioning.
+- `VW GTE E-Golf Can/VWtest.dbc` mirrors the published DBC for logging via SavvyCAN/Teensy_can.
+
+## Outstanding Questions
+- Document contactor/charger wiring and expected GPIO mapping for the pack harness.
+- Confirm EEPROM layout migrations before flashing new configs into production packs.