OCPP WS IO

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)

client.ts
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)

server.ts
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

ComponentImportDescription
OCPPClientocpp-ws-ioNode.js client with TLS, security profiles, ping/pong
OCPPServerocpp-ws-ioWebSocket server with auth, clustering, strict mode
BrowserOCPPClientocpp-ws-io/browserLightweight browser client for testing & simulation
RedisAdapterocpp-ws-io/adapters/redisMulti-instance clustering via Redis pub/sub

OCPP Version Support

FeatureOCPP 1.6OCPP 2.0.1OCPP 2.1
Type-safe call()
Type-safe handle()
JSON Schema Validation
Auto-generated Types

What's Next?

On this page