+ OCPP DebugKit is a modular monorepo with independent packages. Each package can be used + standalone or together. +
+ +
+ {`ocpp-debugkit/
+├── packages/
+│ ├── core/ # Data model, parser, normalizer, timeline, failure detection
+│ ├── scenarios/ # Predefined trace scenarios for testing
+│ ├── reporter/ # Report generators (Markdown)
+│ ├── cli/ # Command-line interface
+│ ├── replay/ # Replay engine (v0.2+)
+│ └── react/ # Reusable React components (v0.2+)
+├── apps/
+│ └── web/ # Single Next.js app (landing, inspector, docs)
+└── turbo.json # Turborepo task pipeline`}
+
+
+
+ {` core ← everything depends on this
+ / | \\
+ scenarios | reporter
+ \\ | /
+ cli
+ |
+ apps/web`}
+
+
+ Packages must be built in dependency order: core → scenarios/reporter → cli → app
+ +The analysis pipeline processes traces in three stages:
+parseTrace() accepts JSON Object, JSONL, or bare
+ array input, validates with Zod schemas, and produces normalized Event{' '}
+ objects.
+ buildSessionTimeline() groups events into
+ sessions, then detectFailures() checks for known failure patterns (failed
+ auth, connector fault, station offline).
+ generateMarkdownReport() produces a human-readable
+ Markdown report with session overview, timeline, failures, and suggested steps.
+ + All trace processing in the web inspector happens client-side. No trace data is uploaded to + any server. The CSMS/CLI process traces locally. +
+ +
+ The ocpp-debugkit CLI provides commands for inspecting traces, generating
+ reports, and running scenarios.
+
+ {`npm install -g @ocpp-debugkit/cli`}
+
+
+ + Parse and analyze an OCPP trace file. Outputs a summary with events, sessions, failures, and + warnings. +
+
+ {`ocpp-debugkit inspect `}
+
+ Example:
+
+ {`ocpp-debugkit inspect trace.json`}
+
+
+ Generate a Markdown report from an OCPP trace file.
+
+ {`ocpp-debugkit report [options]`}
+
+ -f, --format <format> — Report format (default: markdown)
+ -o, --output <file> — Write report to file (default: stdout)
+ Example:
+
+ {`ocpp-debugkit report trace.json --output report.md`}
+
+
+ List all available built-in scenarios.
+
+ {`ocpp-debugkit scenario list`}
+
+
+ + Run a built-in scenario through the analysis engine. Compares detected failures against + expected failures and reports pass/fail. +
+
+ {`ocpp-debugkit scenario run `}
+
+ Example:
+
+ {`ocpp-debugkit scenario run failed-auth`}
+
+
+ Note: scenario run runs static fixtures through the local
+ analysis engine only. It is not active endpoint testing, WebSocket simulation, or live
+ station/CSMS testing.
+
-V, --version — output the version number
+ -h, --help — display help for any command
+ Key OCPP and EV charging terms used throughout this project.
+ ++ Open Charge Point Protocol — the communication protocol between EV charging stations (Charge + Points) and charging station management systems (CSMS). OCPP 1.6 JSON is the primary + protocol supported by DebugKit. +
+ ++ The physical EV charging station. Also referred to as a "station". Communicates + with the CSMS via OCPP. +
+ ++ Charging Station Management System — the central server that manages charging stations. Also + referred to as "the backend". +
+ ++ A physical charging outlet on a charging station. A station may have multiple connectors + (e.g., connector 0 is typically the whole-station connector, connector 1+ are individual + charging outlets). +
+ ++ A single charging session, initiated by a StartTransaction request and terminated by a + StopTransaction request. Each transaction has a unique transactionId assigned by the CSMS. +
+ +
+ An OCPP message type (MessageTypeId = 2) representing a request from one side to the other.
+ Format: [2, UniqueId, Action, Payload]
+
+ An OCPP message type (MessageTypeId = 3) representing a successful response to a Call.
+ Format: [3, UniqueId, Payload]
+
+ An OCPP message type (MessageTypeId = 4) representing an error response to a Call. Format:{' '}
+ [4, UniqueId, ErrorCode, ErrorDescription, ErrorDetails]
+
+ An identifier (typically an RFID card or app token) used to authorize a charging session. + The CSMS validates the idTag and returns an authorization status (Accepted, Invalid, etc.). +
+ ++ A capture of OCPP messages exchanged between a Charge Point and CSMS over a period of time. + Traces are the primary input to DebugKit. +
+ +
+ The direction of an OCPP message: CS_TO_CSMS (station to backend),{' '}
+ CSMS_TO_CS (backend to station), or
+ UNKNOWN.
+
- Documentation is under construction. -
-+ Get started with OCPP DebugKit — open-source DevTools for debugging OCPP charging sessions. +
+
+ {`npm install -g @ocpp-debugkit/cli`}
+
+
+ Parse and analyze an OCPP 1.6 JSON trace file:
+
+ {`ocpp-debugkit inspect trace.json`}
+
+ This outputs a summary with event count, sessions, and detected failures.
+ +Generate a Markdown report from a trace:
+
+ {`ocpp-debugkit report trace.json --output report.md`}
+
+
+ Run a predefined scenario through the analysis engine:
+
+ {`# List available scenarios
+ocpp-debugkit scenario list
+
+# Run a scenario
+ocpp-debugkit scenario run failed-auth`}
+
+
+ + No installation required — visit the inspector and paste a trace, + upload a file, or select a sample scenario. +
+ +For programmatic use in your own TypeScript/JavaScript project:
+
+ {`import { parseTrace, buildSessionTimeline, detectFailures } from '@ocpp-debugkit/core';
+
+const result = parseTrace(traceString);
+const sessions = buildSessionTimeline(result.events);
+const failures = detectFailures(result.events, sessions);
+
+console.log(\`Found \${failures.length} failures\`);`}
+
+ + Scenarios are predefined trace fixtures that test the analysis engine. Each scenario has a + trace and a list of expected failures. +
+ +DebugKit v0.1 includes 5 scenarios:
+ ++ A complete charging session: boot, authorize, start transaction, meter values, stop + transaction. No failures expected. +
+expectedFailures: []
+ + Failed authorization: the idTag is rejected by the CSMS. StartTransaction is not attempted. + The connector transitions to Faulted. +
+expectedFailures: ["FAILED_AUTHORIZATION"]
+ + Connector fault during an active session: the connector reports a Faulted status + mid-charging, and the transaction stops with a fault reason. +
+expectedFailures: ["CONNECTOR_FAULT"]
+ + Station goes offline during an active session: a StartTransaction is sent but no + StopTransaction follows. +
+expectedFailures: ["STATION_OFFLINE_DURING_SESSION"]
+ + A stop transaction with an unexpected stop reason. This is a parser/timeline-only fixture — + no v0.1 detection rule matches it. +
+expectedFailures: []
+ Three detection rules are available in v0.1:
+idTagInfo.status = "Invalid"
+ status = "Faulted" during an active session
+
+ {`# 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.
+ ++ All scenario data is fully synthetic. No real station identifiers, transaction IDs, idTag + values, or personal data are used. +
++ DebugKit accepts three trace formats. All formats use the OCPP 1.6 JSON message structure. +
+ +The primary format — a structured file with metadata and events:
+
+ {`{
+ "traceId": "trace-001",
+ "metadata": {
+ "stationId": "CS-SYNTHETIC-001",
+ "ocppVersion": "1.6",
+ "source": "csms-log"
+ },
+ "events": [
+ {
+ "timestamp": "2024-01-15T10:30:00.000Z",
+ "direction": "CS_TO_CSMS",
+ "message": [2, "msg-001", "BootNotification", {
+ "chargePointVendor": "SyntheticVendor",
+ "chargePointModel": "SM-100"
+ }]
+ },
+ {
+ "timestamp": "2024-01-15T10:30:00.500Z",
+ "direction": "CSMS_TO_CS",
+ "message": [3, "msg-001", {
+ "currentTime": "2024-01-15T10:30:00.500Z",
+ "status": "Accepted"
+ }]
+ }
+ ]
+}`}
+
+
+ One event per line — useful for CSMS logs and streaming captures:
+
+ {`{"timestamp":"2024-01-15T10:30:00.000Z","direction":"CS_TO_CSMS","message":[2,"msg-001","BootNotification",{}]}
+{"timestamp":"2024-01-15T10:30:00.500Z","direction":"CSMS_TO_CS","message":[3,"msg-001",{"status":"Accepted"}]}`}
+
+ Blank lines are ignored. Malformed lines produce parse warnings but don't fail.
+ +A JSON array of raw OCPP messages — convenience for quick testing:
+
+ {`[
+ [2, "msg-001", "BootNotification", {}],
+ [3, "msg-001", {"status": "Accepted"}]
+]`}
+
+ Direction is inferred; timestamps are null.
+ +Three message types are supported:
+[2, UniqueId, Action, Payload]
+ [3, UniqueId, Payload]
+ [4, UniqueId, ErrorCode, ErrorDescription, ErrorDetails]
+ Accepted formats:
+2024-01-15T10:30:00.000Z
+ 2024-01-15T12:00:00+02:00
+ 1705312200000
+ 1705312200
+ null
+ | Limit | +Value | +
|---|---|
| Maximum input size | +10 MB | +
| Maximum event count | +10,000 | +
When direction is not specified, it is inferred from the action name:
+CS_TO_CSMS — BootNotification, Authorize, StartTransaction, StopTransaction,
+ StatusNotification, MeterValues, Heartbeat, etc.
+ CSMS_TO_CS — Reset, RemoteStartTransaction, GetConfiguration,
+ ChangeConfiguration, etc.
+ UNKNOWN — unrecognized actions
+ For CallResult/CallError, direction is inferred from the matching Call.
+