OCPP CP Simulator

OCPP 1.6J charge point simulator for AI agent testing, CI automation, and CSMS development. Comes with a browser UI, a headless CLI, and a Socket.IO control API that any agent or script can drive. Also speaks OCPP 2.0.1 / 2.1 (WebSocket) and OCPP 1.2 / 1.5 / 1.6S (SOAP).

| Interface | Description | Docs | | ----------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | Browser | Web console at / / Tauri desktop app | Web console · Desktop app | | CLI | Headless mode for scripting, CI, and AI integration | CLI | | Server | Long-running Socket.IO server, multi-CP per process | Daemon · Control plane | | Docker | Pre-built image (daemon + web console) on GHCR | Docker image | | MCP | POST /mcp tools for Claude Code and other MCP clients | MCP endpoint |

See the web console tour for each feature in action, with videos.

Quick Start

# Install dependencies
npm install

# Browser UI (dev server)
npm run dev

# CLI / Server mode (requires Bun)
ocpp-cp-sim --ws-url ws://localhost:9000/ocpp --cp-id CP001

Install as a global command (ocpp-cp-sim; ocpsim and cp-sim are aliases)

# From the npm registry (Bun is needed at run time: the bin runs under a `bun` shebang)
pnpm install -g ocpp-cp-simulator     # or: bun install -g / npm install -g ocpp-cp-simulator

# Without installing
bunx ocpp-cp-simulator --help         # or: npx ocpp-cp-simulator --help

# Prebuilt release tarball (same package, from GitHub)
pnpm install -g https://github.com/shiv3/ocpp-cp-simulator/releases/download/cli-latest/ocpp-cp-simulator.tgz
bun install -g https://github.com/shiv3/ocpp-cp-simulator/releases/download/cli-latest/ocpp-cp-simulator.tgz

# From a local checkout
bun link              # in this repo
bun link ocpp-cp-simulator   # in any other project

The package installs four commands for the same entry point: ocpp-cp-sim, ocpsim, cp-sim and ocpp-cp-simulator (what npx / bunx run).

Every install URL above is fetched by CI, so a URL printed here resolves. Do not use GitHub's releases/latest/download/… — releases made before the trains were unified carry no .tgz, so "latest" can land on one. Use the cli-latest URL below.

releases/download/cli-latest/ocpp-cp-simulator.tgz is a rolling pre-release the Release CLI workflow moves onto every stable CLI release (a SemVer prerelease such as v1.0.0-rc.1 is skipped), so the commands above always install the newest stable CLI. To pin a version, use that release's own asset instead, e.g. releases/download/v0.10.0/ocpp-cp-simulator-0.10.0.tgz. See docs/entities/cli.md.

The release tarballs are produced by the Release CLI workflow on v* tags (the same tag that builds the desktop app, so the CLI and the app share one version). A bare bun install -g github:shiv3/ocpp-cp-simulator does not work — dist/ is built at release time, not committed, and bun doesn't install devDependencies for global packages so the on-install vite build can't run.

Then run from anywhere:

# Interactive REPL against a CSMS
ocpp-cp-sim --ws-url ws://localhost:9000/ocpp --cp-id CP001

# Headless daemon (Socket.IO control API only)
ocpp-cp-sim --daemon --http-port 9700

# Daemon + bundled browser UI on the same origin
#   open http://127.0.0.1:5172 to drive the daemon from the web console
ocpp-cp-sim --http-port 5172 --web-console \
            --cp-id CP001 --connectors 2 \
            --ws-url wss://csms.example.com/ocpp/

# Full kitchen-sink: persistent SQLite, JSON-line logs, demo scenario auto-loaded
ocpp-cp-sim --http-port 5172 --web-console \
            --cp-id CP001 --connectors 5 \
            --ws-url wss://csms.example.com/ocpp/ \
            --scenario-template-file docs/examples/scenarios/demo-charging.json \
            --scenario-connector all \
            --state-db ./state.db --log-format json

--web-console serves the browser UI (built into dist/ and shipped inside the release tarball) from the same HTTP port as the Socket.IO control plane, so a single port is all you need to expose. See CLI for the full flag reference and Control plane for the Socket.IO protocol.

Behind a reverse proxy? Bound to a non-loopback host the daemon applies a safe same-origin CORS policy, so the web console served at a public URL will 403 its own assets until you name that origin with --cors-origin https://your.url (or, behind a trusted proxy, --trust-forwarded-headers). See Access control → Behind a reverse proxy for details and an nginx + Authelia example compose.

Documentation

docs/ is organized as an LLM Wiki: an interlinked knowledge base maintained by an LLM agent under the schema in CLAUDE.md.

• Start here: Overview · Index of all pages · Choosing an interface
• Entities — CLI, analyze, Daemon, Web console, Desktop app, Docker image, MCP endpoint, Scenario templates, CSMS peers, Open EV Directory
• Concepts — Control plane, Scenario format, Trace format, State persistence, Log format, Network simulation, Access control, OCPP versions & transports, Security profiles, Local vs Remote mode, Vehicle profiles
• Analyses — Driving from an AI agent, REST → Socket.IO migration, Testing strategy
• Sources — summaries of the raw inputs (JSON schemas, example files, sibling READMEs, issues): docs/sources/

Also browsable at https://deepwiki.com/shiv3/ocpp-cp-simulator.

Highlights

• AI agent & automation testing — structured JSON logs, one Socket.IO rpc/event contract, an MCP endpoint, runtime-injected scenario templates with machine-readable verdicts, an unauthenticated health probe, and SQLite persistence. Minimal recipe and client options: Driving from an AI agent.
• SOAP versions (1.2, 1.5, 1.6S) — full bidirectional OCPP-S in CLI / server mode, send-only in the browser: OCPP versions & transports.
• OCPP 1.6 security profiles 1–3 — Basic Auth with AuthorizationKey, server-certificate verification, mutual TLS: Security profiles.
• Network simulation — seeded latency / jitter, forced and periodic disconnects, delayed reconnect, configured at runtime: Network simulation.
• Certification scenarios — 47 cert16-* templates covering the OCPP 1.6 test cases, verified against SteVe: Scenario templates.
• Diagnostics — versioned OCPP trace files and DebugKit reports via ocpp-cp-sim analyze: analyze.
• Persistence — the browser (sql.js + IndexedDB) and the daemon (--state-db) share one SQLite schema: State persistence.
• Local vs Remote mode — the browser decides once per load by probing /v1/healthz: Local vs Remote mode.

Contributing

See CONTRIBUTING.md: the checks to run before pushing, the wiki update rule, the contribution terms, and how issues and pull requests are labelled and assigned to milestones. Everyone taking part follows the code of conduct.