@blokcert/node-red-contrib-ocpp 1.0.0

package/README.md

@@ -0,0 +1,188 @@
+# node-red-contrib-ocpp
+
+Node-RED nodes for OCPP (Open Charge Point Protocol) message handling via Redis Streams.
+
+## Features
+
+- **OCPP 1.6 & 2.0.1 Support** - Handle both protocol versions with unified message format
+- **Redis Streams Integration** - Consumer groups for scalable message processing
+- **Automatic Normalization** - Convert between OCPP versions transparently
+- **CSMS Commands** - Send remote commands to charging stations
+
+## Installation
+
+```bash
+cd ~/.node-red
+npm install /path/to/node-red-contrib-ocpp
+```
+
+Or from npm (when published):
+```bash
+npm install node-red-contrib-ocpp
+```
+
+## Nodes
+
+### ocpp-config
+
+Configuration node for Redis connection settings. Shared by other OCPP nodes.
+
+### ocpp in
+
+Receives OCPP messages from charging stations via Redis Streams.
+
+**Features:**
+- Consumer group support for load balancing
+- Optional payload normalization (OCPP 1.6/2.0.1 → unified format)
+- Filter by action type
+- Auto-acknowledge messages
+
+**Output:**
+```javascript
+{
+  payload: { /* OCPP message payload */ },
+  ocpp: {
+    messageId: "abc123",
+    action: "BootNotification",
+    version: "1.6",
+    tenant: "operator1",
+    deviceId: "charger001",
+    identity: "operator1:charger001",
+    timestamp: 1699999999999,
+    streamId: "1699999999999-0"
+  }
+}
+```
+
+### ocpp out
+
+Sends OCPP responses back to charging stations.
+
+**Features:**
+- Automatic denormalization (unified → OCPP version)
+- Error response support
+- Auto-acknowledge inbound message
+
+**Input:**
+```javascript
+// Normal response
+msg.payload = {
+  status: "Accepted",
+  currentTime: new Date().toISOString(),
+  interval: 300
+};
+
+// Error response
+msg.ocpp.error = true;
+msg.ocpp.errorCode = "NotImplemented";
+msg.ocpp.errorDescription = "Action not supported";
+```
+
+### ocpp command
+
+Sends CSMS-initiated commands to charging stations.
+
+**Supported Commands:**
+- Reset
+- RemoteStartTransaction / RequestStartTransaction
+- RemoteStopTransaction / RequestStopTransaction
+- UnlockConnector
+- TriggerMessage
+- ChangeAvailability
+- GetConfiguration / GetVariables
+- SetVariables
+- ClearCache
+- And more...
+
+**Example:**
+```javascript
+msg.ocpp = {
+  tenant: "operator1",
+  deviceId: "charger001",
+  command: "Reset"
+};
+msg.payload = {
+  type: "Soft"
+};
+return msg;
+```
+
+## Example Flow
+
+```
+[ocpp in] → [switch] → [BootNotification handler] → [ocpp out]
+                   └→ [Heartbeat handler] → [ocpp out]
+                   └→ [StatusNotification handler] → [ocpp out]
+```
+
+### Simple BootNotification Handler
+
+```javascript
+// Function node
+msg.payload = {
+  status: "Accepted",
+  currentTime: new Date().toISOString(),
+  interval: 300
+};
+return msg;
+```
+
+### Remote Start Command
+
+```javascript
+// Inject node → Function node → ocpp command
+msg.ocpp = {
+  tenant: "operator1",
+  deviceId: "charger001",
+  command: "RemoteStartTransaction"
+};
+msg.payload = {
+  connectorId: 1,
+  idTag: "RFID12345"
+};
+return msg;
+```
+
+## Message Normalization
+
+The nodes automatically normalize OCPP messages to a unified format, allowing you to handle both OCPP 1.6 and 2.0.1 with the same logic.
+
+### BootNotification
+
+| OCPP 1.6 | OCPP 2.0.1 | Unified |
+|----------|------------|---------|
+| chargePointVendor | chargingStation.vendorName | vendor |
+| chargePointModel | chargingStation.model | model |
+| chargePointSerialNumber | chargingStation.serialNumber | serialNumber |
+| firmwareVersion | chargingStation.firmwareVersion | firmwareVersion |
+
+### StatusNotification
+
+| OCPP 1.6 | OCPP 2.0.1 | Unified |
+|----------|------------|---------|
+| connectorId | evseId + connectorId | evseId, connectorId |
+| status | connectorStatus | status |
+| errorCode | (not in 2.0.1) | errorCode |
+
+## Redis Data Structures
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `ws:inbound` | Stream | Messages from devices (consumer group: biz-workers) |
+| `ws:out:{tenant}:{deviceId}` | Stream | Messages to specific device |
+| `ws:conn:{tenant}:{deviceId}` | Hash | Connection registry |
+| `ws:pending:{tenant}:{deviceId}` | Hash | Pending command tracking |
+
+## Requirements
+
+- Node-RED >= 2.0.0
+- Node.js >= 18.0.0
+- Redis >= 6.0 (for Streams support)
+
+## License
+
+MIT
+
+## Related
+
+- [OCPP WebSocket Server](https://github.com/your-org/ocpp-ws-server) - The WebSocket server that works with these nodes

package/icons/ocpp.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="20" height="20">
+  <path fill="#4CAF50" d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/>
+  <path fill="#2196F3" d="M7 10h2v7H7zm4-3h2v10h-2zm4 6h2v4h-2z"/>
+</svg>

package/lib/ocpp-normalizer.js

@@ -0,0 +1,368 @@
+/**
+ * OCPP Message Normalizer
+ * Converts between OCPP 1.6 and 2.0.1 formats to a unified internal format
+ *
+ * Reference: docs/NODE-RED-ABSTRACTION.md
+ */
+
+/**
+ * OCPP Message Types
+ */
+const MessageType = {
+    CALL: 2,
+    CALLRESULT: 3,
+    CALLERROR: 4,
+};
+
+/**
+ * Parse raw OCPP message from Redis Stream
+ * @param {object} streamData - Data from Redis XREADGROUP
+ * @returns {object} Parsed message with metadata
+ */
+function parseStreamMessage(streamData) {
+    const { messageId, tenant, deviceId, action, payload, protocol, timestamp } = streamData;
+
+    // Determine OCPP version from protocol
+    const version = protocol === 'ocpp2.0.1' ? '2.0.1' : '1.6';
+
+    // Parse payload if it's a string
+    let parsedPayload = payload;
+    if (typeof payload === 'string') {
+        try {
+            parsedPayload = JSON.parse(payload);
+        } catch (e) {
+            // Keep as string if not valid JSON
+        }
+    }
+
+    return {
+        messageId,
+        tenant,
+        deviceId,
+        action,
+        payload: parsedPayload,
+        version,
+        protocol,
+        timestamp: timestamp || Date.now(),
+        // Identity string for routing
+        identity: `${tenant}:${deviceId}`,
+    };
+}
+
+/**
+ * Normalize OCPP message to unified format
+ * @param {object} msg - Parsed message
+ * @returns {object} Normalized message
+ */
+function normalize(msg) {
+    const { action, payload, version } = msg;
+
+    // Apply action-specific normalization
+    const normalizer = normalizers[action];
+    const normalizedPayload = normalizer
+        ? normalizer(payload, version)
+        : payload;
+
+    return {
+        ...msg,
+        payload: normalizedPayload,
+        _original: payload, // Keep original for reference
+    };
+}
+
+/**
+ * Denormalize unified format back to OCPP version-specific format
+ * @param {object} msg - Normalized message with response
+ * @param {string} targetVersion - Target OCPP version ('1.6' or '2.0.1')
+ * @returns {object} Version-specific message
+ */
+function denormalize(msg, targetVersion) {
+    const { action, payload } = msg;
+    const version = targetVersion || msg.version;
+
+    const denormalizer = denormalizers[action];
+    const denormalizedPayload = denormalizer
+        ? denormalizer(payload, version)
+        : payload;
+
+    return {
+        ...msg,
+        payload: denormalizedPayload,
+        version,
+    };
+}
+
+// ============================================================================
+// Action-specific Normalizers (OCPP 1.6/2.0.1 -> Unified)
+// ============================================================================
+
+const normalizers = {
+    /**
+     * BootNotification normalizer
+     * 1.6: { chargePointVendor, chargePointModel, ... }
+     * 2.0.1: { chargingStation: { vendorName, model, ... }, reason }
+     * Unified: { vendor, model, serialNumber, firmwareVersion, reason }
+     */
+    BootNotification: (payload, version) => {
+        if (version === '2.0.1') {
+            const cs = payload.chargingStation || {};
+            return {
+                vendor: cs.vendorName,
+                model: cs.model,
+                serialNumber: cs.serialNumber,
+                firmwareVersion: cs.firmwareVersion,
+                reason: payload.reason,
+                // Keep modem info if present
+                modem: cs.modem,
+            };
+        }
+        // OCPP 1.6
+        return {
+            vendor: payload.chargePointVendor,
+            model: payload.chargePointModel,
+            serialNumber: payload.chargePointSerialNumber || payload.chargeBoxSerialNumber,
+            firmwareVersion: payload.firmwareVersion,
+            reason: 'PowerUp', // 1.6 doesn't have reason field
+        };
+    },
+
+    /**
+     * StatusNotification normalizer
+     * 1.6: { connectorId, status, errorCode, timestamp }
+     * 2.0.1: { evseId, connectorId, connectorStatus, timestamp }
+     * Unified: { evseId, connectorId, status, errorCode, timestamp }
+     */
+    StatusNotification: (payload, version) => {
+        if (version === '2.0.1') {
+            return {
+                evseId: payload.evseId,
+                connectorId: payload.connectorId,
+                status: payload.connectorStatus,
+                errorCode: 'NoError', // 2.0.1 doesn't have errorCode in StatusNotification
+                timestamp: payload.timestamp,
+            };
+        }
+        // OCPP 1.6
+        return {
+            evseId: payload.connectorId > 0 ? 1 : 0, // Derive evseId
+            connectorId: payload.connectorId,
+            status: payload.status,
+            errorCode: payload.errorCode,
+            timestamp: payload.timestamp,
+            info: payload.info,
+            vendorId: payload.vendorId,
+            vendorErrorCode: payload.vendorErrorCode,
+        };
+    },
+
+    /**
+     * Authorize normalizer
+     * 1.6: { idTag }
+     * 2.0.1: { idToken: { idToken, type } }
+     * Unified: { idToken, idTokenType }
+     */
+    Authorize: (payload, version) => {
+        if (version === '2.0.1') {
+            return {
+                idToken: payload.idToken?.idToken,
+                idTokenType: payload.idToken?.type,
+            };
+        }
+        // OCPP 1.6
+        return {
+            idToken: payload.idTag,
+            idTokenType: 'ISO14443', // Default for 1.6
+        };
+    },
+
+    /**
+     * StartTransaction / TransactionEvent normalizer
+     */
+    StartTransaction: (payload, version) => {
+        return {
+            connectorId: payload.connectorId,
+            idToken: payload.idTag,
+            meterStart: payload.meterStart,
+            timestamp: payload.timestamp,
+            reservationId: payload.reservationId,
+        };
+    },
+
+    TransactionEvent: (payload, version) => {
+        // 2.0.1 only
+        const tx = payload.transactionInfo || {};
+        return {
+            eventType: payload.eventType,
+            timestamp: payload.timestamp,
+            triggerReason: payload.triggerReason,
+            seqNo: payload.seqNo,
+            transactionId: tx.transactionId,
+            chargingState: tx.chargingState,
+            evseId: payload.evse?.id,
+            connectorId: payload.evse?.connectorId,
+            idToken: payload.idToken?.idToken,
+            idTokenType: payload.idToken?.type,
+            meterValue: payload.meterValue,
+        };
+    },
+
+    /**
+     * MeterValues normalizer
+     */
+    MeterValues: (payload, version) => {
+        if (version === '2.0.1') {
+            return {
+                evseId: payload.evseId,
+                meterValue: payload.meterValue,
+            };
+        }
+        // OCPP 1.6
+        return {
+            connectorId: payload.connectorId,
+            transactionId: payload.transactionId,
+            meterValue: payload.meterValue,
+        };
+    },
+
+    /**
+     * Heartbeat - no transformation needed
+     */
+    Heartbeat: (payload, version) => payload,
+};
+
+// ============================================================================
+// Action-specific Denormalizers (Unified -> OCPP 1.6/2.0.1)
+// ============================================================================
+
+const denormalizers = {
+    /**
+     * BootNotification response denormalizer
+     */
+    BootNotification: (payload, version) => {
+        if (version === '2.0.1') {
+            return {
+                currentTime: payload.currentTime || new Date().toISOString(),
+                interval: payload.interval || 300,
+                status: payload.status || 'Accepted',
+            };
+        }
+        // OCPP 1.6
+        return {
+            currentTime: payload.currentTime || new Date().toISOString(),
+            interval: payload.interval || 300,
+            status: payload.status || 'Accepted',
+        };
+    },
+
+    /**
+     * StatusNotification response (empty for both versions)
+     */
+    StatusNotification: (payload, version) => ({}),
+
+    /**
+     * Authorize response denormalizer
+     */
+    Authorize: (payload, version) => {
+        if (version === '2.0.1') {
+            return {
+                idTokenInfo: {
+                    status: payload.status || 'Accepted',
+                },
+            };
+        }
+        // OCPP 1.6
+        return {
+            idTagInfo: {
+                status: payload.status || 'Accepted',
+                expiryDate: payload.expiryDate,
+                parentIdTag: payload.parentIdTag,
+            },
+        };
+    },
+
+    /**
+     * Heartbeat response
+     */
+    Heartbeat: (payload, version) => ({
+        currentTime: payload.currentTime || new Date().toISOString(),
+    }),
+
+    /**
+     * StartTransaction response
+     */
+    StartTransaction: (payload, version) => ({
+        transactionId: payload.transactionId,
+        idTagInfo: {
+            status: payload.status || 'Accepted',
+            expiryDate: payload.expiryDate,
+            parentIdTag: payload.parentIdTag,
+        },
+    }),
+
+    /**
+     * TransactionEvent response (2.0.1 only)
+     */
+    TransactionEvent: (payload, version) => ({
+        // 2.0.1 response is mostly optional
+        ...(payload.totalCost !== undefined && { totalCost: payload.totalCost }),
+        ...(payload.chargingPriority !== undefined && { chargingPriority: payload.chargingPriority }),
+        ...(payload.idTokenInfo && { idTokenInfo: payload.idTokenInfo }),
+        ...(payload.updatedPersonalMessage && { updatedPersonalMessage: payload.updatedPersonalMessage }),
+    }),
+
+    /**
+     * MeterValues response (empty)
+     */
+    MeterValues: (payload, version) => ({}),
+};
+
+/**
+ * Build OCPP response message
+ * @param {string} messageId - Original message ID
+ * @param {object} payload - Response payload
+ * @returns {string} JSON string of OCPP response
+ */
+function buildResponse(messageId, payload) {
+    return JSON.stringify([MessageType.CALLRESULT, messageId, payload]);
+}
+
+/**
+ * Build OCPP error message
+ * @param {string} messageId - Original message ID
+ * @param {string} errorCode - OCPP error code
+ * @param {string} errorDescription - Error description
+ * @param {object} errorDetails - Optional error details
+ * @returns {string} JSON string of OCPP error
+ */
+function buildError(messageId, errorCode, errorDescription, errorDetails = {}) {
+    return JSON.stringify([
+        MessageType.CALLERROR,
+        messageId,
+        errorCode,
+        errorDescription,
+        errorDetails,
+    ]);
+}
+
+/**
+ * Build OCPP CALL message (for CSMS-initiated commands)
+ * @param {string} messageId - Unique message ID
+ * @param {string} action - OCPP action name
+ * @param {object} payload - Request payload
+ * @returns {string} JSON string of OCPP call
+ */
+function buildCall(messageId, action, payload) {
+    return JSON.stringify([MessageType.CALL, messageId, action, payload]);
+}
+
+module.exports = {
+    MessageType,
+    parseStreamMessage,
+    normalize,
+    denormalize,
+    buildResponse,
+    buildError,
+    buildCall,
+    normalizers,
+    denormalizers,
+};

package/lib/redis-client.js

@@ -0,0 +1,97 @@
+/**
+ * Redis Client Manager for OCPP Node-RED nodes
+ * Manages shared Redis connections with connection pooling
+ */
+const Redis = require('ioredis');
+
+// Store connections by config node ID
+const connections = new Map();
+
+/**
+ * Get or create a Redis connection for a config node
+ * @param {string} configId - The config node ID
+ * @param {object} config - Redis connection configuration
+ * @returns {Redis} Redis client instance
+ */
+function getConnection(configId, config) {
+    if (connections.has(configId)) {
+        return connections.get(configId);
+    }
+
+    const redisConfig = {
+        host: config.host || 'localhost',
+        port: config.port || 6379,
+        password: config.password || undefined,
+        db: config.db || 0,
+        retryDelayOnFailover: 100,
+        maxRetriesPerRequest: 3,
+        lazyConnect: false,
+    };
+
+    const client = new Redis(redisConfig);
+
+    client.on('error', (err) => {
+        console.error(`[ocpp-redis] Connection error for ${configId}:`, err.message);
+    });
+
+    client.on('connect', () => {
+        console.log(`[ocpp-redis] Connected to Redis for ${configId}`);
+    });
+
+    client.on('close', () => {
+        console.log(`[ocpp-redis] Connection closed for ${configId}`);
+    });
+
+    connections.set(configId, client);
+    return client;
+}
+
+/**
+ * Close and remove a Redis connection
+ * @param {string} configId - The config node ID
+ */
+function closeConnection(configId) {
+    if (connections.has(configId)) {
+        const client = connections.get(configId);
+        client.quit().catch(() => {});
+        connections.delete(configId);
+    }
+}
+
+/**
+ * Close all Redis connections
+ */
+function closeAllConnections() {
+    for (const [configId, client] of connections) {
+        client.quit().catch(() => {});
+    }
+    connections.clear();
+}
+
+/**
+ * Redis key helpers matching wsserver/redis/keys.go
+ */
+const Keys = {
+    // Inbound stream (device -> business logic)
+    inbound: () => 'ws:inbound',
+
+    // Outbound stream (business logic -> device)
+    outbound: (tenant, deviceId) => `ws:out:${tenant}:${deviceId}`,
+
+    // Connection registry
+    connection: (tenant, deviceId) => `ws:conn:${tenant}:${deviceId}`,
+
+    // Pending responses
+    pending: (tenant, deviceId) => `ws:pending:${tenant}:${deviceId}`,
+
+    // Control channels
+    disconnect: () => 'ws:ctrl:disconnect',
+    broadcast: () => 'ws:broadcast',
+};
+
+module.exports = {
+    getConnection,
+    closeConnection,
+    closeAllConnections,
+    Keys,
+};