Introduction
Type-safe OCPP WebSocket RPC client & server for Node.js — with browser support.
ocpp-ws-io
Type-safe OCPP WebSocket RPC client & server for Node.js.
Built with TypeScript from the ground up — supports OCPP 1.6, 2.0.1, and 2.1 with full JSON schema validation, all three OCPP security profiles, optional Redis-based clustering, and a zero-dependency browser client for testing.
Looking for browser usage? Check out the Browser Client — a lightweight charge point simulator client that runs directly in the browser.
Key Features
⚡ Full OCPP-J RPC
Call, CallResult, CallError message framing per OCPP-J specification. Handles all RPC lifecycle management automatically.
🎯 Type-Safe
Auto-generated TypeScript types for every OCPP 1.6, 2.0.1, and 2.1 method. Full request/response inference — catch errors at compile time.
🔒 Security Profiles 0–3
Plain WS, Basic Auth, TLS + Basic Auth, and Mutual TLS. All OCPP security profiles supported out of the box.
📐 Strict Mode
Optional JSON schema validation for all inbound and outbound messages. Catch malformed payloads before they cause issues.
🔁 Auto-Reconnect
Exponential backoff with configurable min/max delays, max retries, and runtime reconfiguration.
🧩 Framework Agnostic
Use standalone, or attach to Express, Fastify, NestJS, or any Node.js HTTP server.
📡 Redis Clustering
Optional Redis adapter for multi-instance deployments. Supports both ioredis and node-redis.
🔀 Version-Aware Handlers
Register handlers per OCPP version with typed params, or use generic handlers with protocol context.
🌐 Browser Client
Zero-dependency browser WebSocket client for building charge point simulators and testing dashboards.
Quick Start
Install
bash npm install ocpp-ws-io bash pnpm add ocpp-ws-io bash yarn add ocpp-ws-io bash bun add ocpp-ws-io Create a Client (Charging Station)
import { OCPPClient, SecurityProfile } from "ocpp-ws-io";
const client = new OCPPClient({
endpoint: "ws://localhost:3000",
identity: "CP001",
protocols: ["ocpp1.6"],
securityProfile: SecurityProfile.NONE,
});
// Register a typed handler
client.handle("Reset", ({ params }) => {
console.log("Reset type:", params.type); // typed: "Hard" | "Soft"
return { status: "Accepted" };
});
await client.connect();
// Version-aware call — fully typed
const response = await client.call("ocpp1.6", "BootNotification", {
chargePointVendor: "VendorX",
chargePointModel: "ModelY",
});
console.log("Status:", response.status); // "Accepted" | "Pending" | "Rejected"Create a Server (Central System)
import { OCPPServer } from "ocpp-ws-io";
const server = new OCPPServer({
protocols: ["ocpp1.6", "ocpp2.0.1"],
});
server.auth((accept, reject, handshake) => {
console.log(`Connection from ${handshake.identity}`);
accept({ session: { authorized: true } });
});
server.on("client", (client) => {
console.log(`${client.identity} connected (${client.protocol})`);
client.handle("ocpp1.6", "BootNotification", ({ params }) => {
return {
status: "Accepted",
currentTime: new Date().toISOString(),
interval: 300,
};
});
});
await server.listen(3000);Architecture Overview
| Component | Import | Description |
|---|---|---|
OCPPClient | ocpp-ws-io | Node.js client with TLS, security profiles, ping/pong |
OCPPServer | ocpp-ws-io | WebSocket server with auth, clustering, strict mode |
BrowserOCPPClient | ocpp-ws-io/browser | Lightweight browser client for testing & simulation |
RedisAdapter | ocpp-ws-io/adapters/redis | Multi-instance clustering via Redis pub/sub |
OCPP Version Support
| Feature | OCPP 1.6 | OCPP 2.0.1 | OCPP 2.1 |
|---|---|---|---|
Type-safe call() | ✅ | ✅ | ✅ |
Type-safe handle() | ✅ | ✅ | ✅ |
| JSON Schema Validation | ✅ | ✅ | ✅ |
| Auto-generated Types | ✅ | ✅ | ✅ |
What's Next?
Quick Start Guide
Set up your first OCPP client and server in under 5 minutes.
Browser Client
Build charge point simulators that run directly in the browser.
Framework Integration
Use with Express, Fastify, NestJS, Next.js, and more.
Security Profiles
Configure TLS, Basic Auth, and Mutual TLS for production.
Type Safety
Leverage auto-generated types for compile-time safety.
API Reference
Complete API documentation for all classes and methods.