feat(ocpp-cp): emit v201 TransactionEvent(ChargingStateChanged) on suspend/resume (M7)

[duyhuynh-vn]

Summary

Teaches the OCPP 2.0.1 simulator to report interim charging-state transitions during a live transaction — the EV pausing draw (SuspendedEV), the EVSE/CSMS pausing delivery (SuspendedEVSE), or charging resuming (Charging) — each as one TransactionEvent(Updated, triggerReason = ChargingStateChanged). Advances M7 — OCPP 2.0.1.

Closes #577

Real use case

A driver is charging when the utility sends a load-management signal that drops the connector to 0 A: the EV stops drawing, the session is now suspended, not charging. Minutes later the constraint lifts and charging resumes. On a real OCPP 2.0.1 station each of those moments emits an interim TransactionEvent(Updated) with triggerReason = ChargingStateChanged carrying the new chargingState, so the CSMS's billing/CDR and the operator's dashboard show a session that paused and resumed rather than one that was "always charging" until it abruptly ended. Until this change the simulator reported only Charging (Started/Updated) and Idle (Ended), so a CSMS integration test could never exercise the suspend semantics that smart-charging conformance depends on. This hook lets a test drive Charging → SuspendedEVSE → Charging deterministically and assert exactly what reached the wire.

What changed

crates/ocpp-cp/src/v201_transaction.rs and crates/ocpp-cp/src/lib.rs only.

• v201_transaction::transaction_event_charging_state_changed(session, seq_no, new_state, timestamp) — a pure, schema-validated builder emitting a TransactionEvent(Updated) with triggerReason = ChargingStateChanged and transactionInfo.chargingState = new_state. A pure state-change event carries no meterValue (readings stay on the MeterValuePeriodic path — meterValue is optional in the 2.0.1 schema) and no idToken (the session is already authorized). Mirrors the existing transaction_event_* builder idiom.
• ChargePoint::transition_charging_state(evse_id, new_state) — a V201-only driver hook that drives a live transaction across the interim Charging ↔ SuspendedEV ↔ SuspendedEVSE transitions, returning a typed ChargingStateChangeOutcome.
• V201Session.charging_state — the session's current chargingState, tracked behind a per-session Mutex (opens Charging, matching the Started event).

Design / failure modes / trust boundary:

• Deterministic injection — a pure simulator has no real EV to pause draw, so the transition is injected by the caller, the same opt-in behavior-injection seam as trip_variable_monitor / request_notify_charging_limit. Inputs are strongly typed (i32, ChargingStateEnumType); the CSMS .conf is discarded, so no untrusted wire data is parsed.
• Hysteresis — a redundant transition (already in the target state) is a silent no-op: no event, no seqNo burned.
• Inert on no context — no active transaction on the EVSE (including a non-positive / out-of-range evse_id, which matches nothing) returns NoTransaction with no CALL; never a panic.
• Scope guard — Idle (terminal, reported by Ended) and EVConnected (the pre-authorization plug-in state, follow-up port(m7): CP simulator 2.0.1 — emit the pre-authorization EVConnected state + TransactionEvent(triggerReason=CablePluggedIn) when the cable is plugged before Started #579) are rejected with OcppError::ValidationError before any wire I/O; every accepted arm is handled explicitly (no panic).
• seqNo is drawn from the transaction's shared monotonic counter (V201Session::next_seq_no), so a transition interleaves cleanly with the periodic sampler's Updated events and stays strictly between Started and Ended.
• Locking — the compare-and-emit runs under the per-session charging_state Mutex, never the v201_sessions map lock, so the map lock is not held across the outbound send and a failed send leaves the modeled state unchanged (the seqNo is spent, as on any emitted event).
• V201-only — a 1.6J station is refused with OcppError::NotSupported.

What was ported

mobilityhouse/ocpp is protocol-only and models each message independently (no state-transition driver), so the wire semantics are ported and the interim-transition reporting is written idiomatically as the simulator's own responsibility.

• ocpp/v201/enums.py — ChargingStateEnumType (Charging / SuspendedEV / SuspendedEVSE), TriggerReasonEnumType.charging_state_changed.
• ocpp/v201/call.py — class TransactionEvent; ocpp/v201/datatypes.py TransactionType.charging_state.

Test plan

• cargo fmt --all --check ✅
• cargo clippy --all-targets -- -D warnings ✅
• cargo test --workspace ✅ (804 ocpp-cp lib tests + all crates green)

New tests:

• Builder — transition shape (Updated / ChargingStateChanged / chargingState, no meterValue, no idToken); SuspendedEV / SuspendedEVSE / Charging serialize as the exact PascalCase wire tokens; each of the three satisfies the bundled 2.0.1 TransactionEvent JSON Schema.
• Driver hook (via the capturing mock CSMS, asserting what reached the wire and in what order):
  • Charging → SuspendedEV → one event, chargingState = SuspendedEV, seqNo next, no meterValue/idToken.
  • Charging → SuspendedEVSE → Charging → two events, correct states in order, seqNo 1 then 2.
  • Redundant transition → Redundant, no event, no seqNo burned (the next real transition still claims seqNo 1).
  • No active transaction (and out-of-range evse_id) → NoTransaction, inert.
  • Idle / EVConnected target → ValidationError.
  • 1.6J station → NotSupported.

Acceptance criteria

• A V201-only driver hook drives a connector Charging ↔ SuspendedEV ↔ SuspendedEVSE and originates one schema-valid TransactionEvent(Updated, triggerReason=ChargingStateChanged) per real transition, carrying the transitioned chargingState.
• Pure builder with a schema-validity test for each of SuspendedEV, SuspendedEVSE, and the Charging resume.
• Redundant / no-transition and no-active-transaction cases are inert (no event, no seqNo burned, no panic).
• seqNo continues the transaction's monotonic stream; Ended still closes with Idle.
• A 1.6J charge point refuses the hook with OcppError::NotSupported.
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test --workspace all green.

Known gaps / notes

• The pre-authorization EVConnected state + triggerReason = CablePluggedIn before Started is the explicit companion follow-up, tracked in port(m7): CP simulator 2.0.1 — emit the pre-authorization EVConnected state + TransactionEvent(triggerReason=CablePluggedIn) when the cable is plugged before Started #579 (this hook rejects EVConnected for now and reuses the same plumbing when port(m7): CP simulator 2.0.1 — emit the pre-authorization EVConnected state + TransactionEvent(triggerReason=CablePluggedIn) when the cable is plugged before Started #579 lands).
• A Sample.Periodic reading emitted while suspended is out of scope (noted on the issue).
• No new dependencies.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AaEcbYKZPx1xbT6tTMx6Mp

---

Generated by Claude Code

[duyhuynh-vn]

🌙 Nightly dev — 2026-09-27

This PR had gone un-mergeable (dirty): #578 merged into main and added EvChargingNegotiationOutcome at the same spot in crates/ocpp-cp/src/lib.rs where this branch adds ChargingStateChangeOutcome.

Resolved by merging latest main into the branch (merge commit 3f52a88, no history rewrite). The conflict was a clean "both added" — the two outcome enums are independent additions, so I kept both.

Re-validated on the merged tree:

• cargo fmt --all --check ✅
• cargo clippy --all-targets -- -D warnings ✅
• cargo test --workspace ✅ (810 ocpp-cp lib tests + all crates green)

mergeable_state is now clean. No code behavior changed — this was purely a conflict resolution. Ready for your review whenever you'd like; I won't merge it myself.

---

Generated by Claude Code