API Reference
Detailed API reference for OCPPClient and OCPPServer.
OCPPClient
import { OCPPClient } from "ocpp-ws-io";Constructor
const client = new OCPPClient(options: ClientOptions);ClientOptions
| Option | Type | Default | Description |
|---|---|---|---|
identity | string | required | Charging station ID |
endpoint | string | required | WebSocket URL (ws:// or wss://) |
protocols | string[] | [] | OCPP subprotocols to negotiate |
securityProfile | SecurityProfile | NONE | Security profile (0–3) |
password | string | Buffer | — | Password for Basic Auth (Profile 1 & 2) |
tls | TLSOptions | — | TLS/SSL options (Profile 2 & 3) |
headers | Record<string, string> | — | Additional WebSocket headers |
query | Record<string, string> | — | Additional URL query parameters |
reconnect | boolean | true | Auto-reconnect on disconnect |
maxReconnects | number | Infinity | Max reconnection attempts |
strictMode | boolean | string[] | false | Enable/restrict schema validation |
Methods
connect()
Connect to the OCPP server.
await client.connect();call(protocol?, method, params, options?)
Make an RPC call.
protocol: Optional. e.g., "ocpp1.6". If omitted, generic type inference is used.method: The OCPP method name (e.g., "BootNotification").params: The request payload.options:{ timeoutMs?: number }
const result = await client.call("ocpp1.6", "BootNotification", { ... });handle(protocol?, method, handler)
Register an RPC handler.
protocol: Optional. If provided, handler only triggers for this protocol version.method: The OCPP method name.handler:(context) => Response | Promise<Response>
// Version specific
client.handle("ocpp1.6", "Reset", ({ params }) => { ... });
// Generic
client.handle("Reset", ({ params }) => { ... });
// Catch-all
client.handle((method, { params }) => { ... });close(code?, reason?)
Close the connection.
OCPPServer
import { OCPPServer } from "ocpp-ws-io";Constructor
const server = new OCPPServer(options?: ServerOptions);Methods
listen(port, host?, options?)
Start listening on a port. Returns the http.Server instance.
auth(handler)
Attach authentication logic.
server.auth((accept, reject, handshake) => {
// handshake has .identity, .password, .headers, etc.
accept({ session: { ... } }); // Attach session data to client
});on("client", handler)
Listen for new connections.
server.on("client", (client) => {
// client is an OCPPServerClient (extends OCPPClient)
console.log(client.session); // Access session data
});Protocol Constants
NOREPLY
Return NOREPLY from a handler to suppress the automatic response. This is useful for asynchronous processing where you might send a response later manually, or for specific OCPP flows.
import { NOREPLY } from "ocpp-ws-io";
client.handle("StatusNotification", ({ params }) => {
// Process the notification but don't send a response immediately
return NOREPLY;
});BrowserOCPPClient
import { BrowserOCPPClient } from "ocpp-ws-io/browser";A browser-compatible OCPP client with the same typed API as OCPPClient. Uses the native browser WebSocket API — no Node.js dependencies.
See Browser Client for the full guide with examples.
Constructor
const client = new BrowserOCPPClient(options: BrowserClientOptions);BrowserClientOptions
| Option | Type | Default | Description |
|---|---|---|---|
identity | string | required | Charging station ID |
endpoint | string | required | WebSocket URL (ws:// or wss://) |
protocols | string[] | [] | OCPP subprotocols to negotiate |
query | Record<string, string> | — | Additional URL query parameters |
reconnect | boolean | true | Auto-reconnect on disconnect |
maxReconnects | number | Infinity | Max reconnection attempts |
backoffMin | number | 1000 | Initial reconnect delay (ms) |
backoffMax | number | 30000 | Maximum reconnect delay (ms) |
callTimeoutMs | number | 30000 | Default RPC call timeout (ms) |
callConcurrency | number | 1 | Max concurrent outbound calls |
maxBadMessages | number | Infinity | Close after N bad messages |
respondWithDetailedErrors | boolean | false | Include error details in responses |
Methods
All methods match OCPPClient:
await client.connect();
// Version-aware typed call
const result = await client.call("ocpp1.6", "BootNotification", { ... });
// Register handlers (version-specific, generic, wildcard)
client.handle("ocpp1.6", "Reset", ({ params }) => { ... });
client.handle("Reset", ({ params }) => { ... });
client.handle((method, { params }) => { ... });
// Close
await client.close();
await client.close({ force: true });
await client.close({ awaitPending: true });
// Runtime reconfiguration
client.reconfigure({ callTimeoutMs: 10000 });
// Handler removal
client.removeHandler("Reset");
client.removeHandler("ocpp1.6", "Reset");
client.removeAllHandlers();
// Raw message
client.sendRaw(JSON.stringify([2, "uuid", "Heartbeat", {}]));Events
client.on("open", (event) => {
/* connected */
});
client.on("close", ({ code, reason }) => {
/* disconnected */
});
client.on("error", (error) => {
/* error */
});
client.on("connecting", ({ url }) => {
/* attempting */
});
client.on("reconnect", ({ attempt, delay }) => {
/* reconnecting */
});
client.on("message", (message) => {
/* OCPP message */
});
client.on("call", (call) => {
/* incoming call */
});
client.on("callResult", (result) => {
/* result received */
});
client.on("callError", (error) => {
/* error received */
});
client.on("badMessage", ({ message, error }) => {
/* malformed */
});Error Classes
All error classes are exported for instanceof checks:
import {
// Base errors
TimeoutError, // Call timeout
UnexpectedHttpResponse, // Non-101 upgrade response
WebsocketUpgradeError, // WebSocket upgrade failure
// RPC errors (OCPP-J spec Section 4.3)
RPCGenericError,
RPCNotImplementedError,
RPCNotSupportedError,
RPCInternalError,
RPCProtocolError,
RPCSecurityError,
RPCFormationViolationError,
RPCPropertyConstraintViolationError,
RPCOccurrenceConstraintViolationError,
RPCTypeConstraintViolationError,
RPCGenericTransportError,
} from "ocpp-ws-io";