OCPP DebugKit

Scenarios

Scenarios are predefined trace fixtures that test the analysis engine. Each scenario pairs a trace with the failures it is expected to produce, so the detection engine can be checked against known-good and known-bad sessions.

Built-in Scenarios

The toolkit ships 15 scenarios:

  • normal-session — a complete session (boot, authorize, start, meter values, stop) with no failures expected.
  • failed-auth — the idTag is rejected by the CSMS; StartTransaction is not attempted. FAILED_AUTHORIZATION
  • connector-fault — the connector faults mid-charging and the transaction stops with a fault reason. CONNECTOR_FAULT
  • station-offline — a StartTransaction with no StopTransaction to follow. STATION_OFFLINE_DURING_SESSION
  • meter-value-gap — an active transaction with no MeterValues between start and stop. METER_VALUE_GAP
  • invalid-stop-reason — a StopTransaction reason not in the OCPP 1.6 specification. INVALID_STOP_REASON
  • unexpected-start — a StartTransaction with no preceding BootNotification or Authorize. UNEXPECTED_START
  • status-transition-violation — an invalid OCPP 1.6 connector status transition (Available directly to Finishing). STATUS_TRANSITION_VIOLATION
  • diagnostics-failure — a DiagnosticsStatusNotification reporting DiagnosisFailed. DIAGNOSTICS_FAILURE
  • slow-csms-response — the CSMS takes 15s to answer a BootNotification. SLOW_RESPONSE
  • meter-anomaly — meter values decrease during a transaction (non-monotonic). METER_VALUE_ANOMALY
  • short-session — a session lasting only ~10 seconds. SUSPICIOUS_SESSION_DURATION
  • heartbeat-irregular — heartbeats at irregular intervals (300s expected, 600s observed). HEARTBEAT_INTERVAL_VIOLATION
  • unresponsive-csms — a Call is sent but the CSMS never answers. UNRESPONSIVE_CSMS
  • unexpected-stop-reason — a parser/timeline-only fixture (no detection rule matches) that validates handling of stop events with error payloads.

Failure Detection Rules

The detection engine implements 16 rules covering the OCPP 1.6J failure taxonomy, ranked by severity:

  • FAILED_AUTHORIZATION — Authorize rejected by the CSMS
  • CONNECTOR_FAULT — connector reports Faulted during an active session
  • STATION_OFFLINE_DURING_SESSION — station drops offline mid-transaction, or a transaction never stops
  • UNRESPONSIVE_CSMS — a Call is sent but never answered (no CallResult or CallError)
  • SLOW_RESPONSE — a response exceeds the expected latency budget
  • TIMEOUT_NO_HEARTBEAT — no heartbeat within the expected window
  • HEARTBEAT_INTERVAL_VIOLATION — heartbeats arrive outside the configured interval
  • REPEATED_BOOT_NOTIFICATION — repeated boots suggest a reboot loop
  • METER_VALUE_GAP — an active transaction with no MeterValues
  • METER_VALUE_ANOMALY — meter values decrease during a transaction
  • STATUS_TRANSITION_VIOLATION — an invalid connector status transition
  • UNEXPECTED_START — a StartTransaction without a preceding boot or authorize
  • INVALID_STOP_REASON — a StopTransaction reason outside the OCPP 1.6 spec
  • SUSPICIOUS_SESSION_DURATION — a session ends suspiciously quickly
  • DIAGNOSTICS_FAILURE — a diagnostics upload reports failure
  • FIRMWARE_UPDATE_FAILURE — a firmware update reports failure

Running Scenarios

# List all scenarios
ocpp-debugkit scenario list

# Run a specific scenario
ocpp-debugkit scenario run connector-fault

The CLI reports detected vs expected failures and shows a pass/fail result.

Synthetic Data

All scenario data is fully synthetic. No real station identifiers, transaction IDs, idTag values, or personal data are used.