Skip to content

v0.3.0 — Session boundary redesign (plug-anchored multi-window)

Choose a tag to compare

View all tags
@cryptotomte cryptotomte released this 19 May 19:03
v0.3.0
02ee428
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Major redesign of the session model

This release replaces the heuristic gate/H1/H2/balancing-skip mechanism with a plug-anchored multi-window session model for the go-e Gemini profile. Sessions are now anchored on cable insertion/removal rather than the car's status signal, producing exactly one session per physical plug cycle regardless of BMS pulsing, lock/unlock events, or app toggles.

Verified against 3 days of production data from two vehicles (Peugeot 3008 PHEV with heavy BMS pulsing; Mercedes GLB 350 with clean charging + post-completion cell balancing).

What's new

  • One session per cable insertion — phantom sessions caused by BMS pulse cycling are gone. Up to 11% of delivered energy that was previously lost between phantom sessions is now correctly attributed.
  • Multi-window inside one session — bulk charge + post-completion cell balancing (Mercedes pattern) or scheduled top-ups are captured as multiple charging windows within the same session. charging_window_count reflects how many bursts occurred.
  • Two distinct durations — connection_duration_s (plug-in to plug-out) and charging_duration_s (sum of active-charging time). avg_power_w is now correctly computed from charging duration, matching the convention used by the go-e charger's own app.
  • Status sensor lifecycle — Idle → Waiting → Charging → Charged → Idle. The sensor does not flap during BMS pulse pauses below the configured idle threshold.
  • Unmapped-RFID notification — when an RFID tag is detected by the charger but not mapped in the integration, a persistent HA notification appears with a clear warning that the energy is being attributed to the 'Unknown' user bucket. Auto-dismisses when you add the mapping. Opt-out: notify_unmapped_rfid advanced option.
  • New duration sensors — last_session_charging_duration and last_session_connection_duration expose the two times distinctly.
  • New debug log categories — CHARGING_WINDOW_OPEN/CLOSE, DISCONNECT_DETECTED/RESOLVED, CHARGER_OFFLINE/BACK_ONLINE, RFID_UNMAPPED_NOTIFIED, RECOVERY_TIMEOUT, and several more for diagnostic clarity.

Resilience improvements

  • HA restart mid-session now resumes correctly (including spot-pricing hourly tracker re-arm).
  • 60-minute deferred-recovery timeout with user notification if the plug entity never becomes available after restart.
  • Disk I/O failure during session save no longer leaves the engine stuck; event still fires, state still resets.
  • Transient go-e disconnects (cable_lock != Unlocked) no longer split sessions.
  • Charger-outage detection (all entities unavailable) is distinct from cable-out and does not trigger the disconnect grace timer.

Configuration

Three new advanced options in the integration settings:

  • charging_idle_timeout_min (default 5 minutes, range 3–30) — how long sustained zero-power before the current charging window closes
  • disconnect_grace_min (default 10 minutes, range 5–30) — safety net for transient cable_lock states
  • notify_unmapped_rfid (default true) — controls the unmapped-RFID notification

Storage migration

Schema bumped from v1.1 to v1.2. Migration runs automatically and is idempotent. Existing sessions get new fields backfilled with sensible defaults; existing duration attribute now maps to charging_duration_s (the more meaningful value). All existing data is preserved.

Scope

This release affects only the goe_gemini charger profile. The generic profile keeps the previous session engine unchanged. The new model is architected for modular extensibility — future charger profiles can opt in by exposing equivalent HA entities (plug, cable_lock, car_status, power, energy counter, trx).

Documentation

A new user-facing document docs/SESSION-MODEL.md explains the session model in non-technical terms. Recommended reading after upgrade.

Compatibility

  • Existing automations subscribing to ev_charging_manager_session_completed continue to work (backward-compat field aliases preserved).
  • New events ev_charging_charged (per window close) and ev_charging_manager_unknown_rfid_detected are additive.
  • Status sensor adds new states (Waiting, Charged) — automations checking for Charging/Idle are unaffected.

Test coverage

495 unit tests pass, including 27 explicit test cases covering every Decision in the spec, plus production log replay regression tests against captured Peugeot and Mercedes data.

Full changelog: v0.2.4...v0.3.0

Assets 2
Loading