@blokcert/node-red-contrib-ocpp 1.0.0

package/nodes/ocpp-in.html

@@ -0,0 +1,131 @@
+<script type="text/javascript">
+    RED.nodes.registerType('ocpp-in', {
+        category: 'OCPP',
+        color: '#4CAF50',
+        defaults: {
+            name: { value: '' },
+            server: { value: '', type: 'ocpp-config', required: true },
+            blockTimeout: { value: 5000, validate: RED.validators.number() },
+            batchSize: { value: 10, validate: RED.validators.number() },
+            autoAck: { value: true },
+            normalizePayload: { value: true },
+            filterAction: { value: '' },
+        },
+        inputs: 0,
+        outputs: 1,
+        icon: 'font-awesome/fa-sign-in',
+        paletteLabel: 'ocpp in',
+        label: function () {
+            if (this.filterAction) {
+                return this.name || `ocpp in (${this.filterAction})`;
+            }
+            return this.name || 'ocpp in';
+        },
+        labelStyle: function () {
+            return this.name ? 'node_label_italic' : '';
+        },
+    });
+</script>
+
+<script type="text/html" data-template-name="ocpp-in">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+        <input type="text" id="node-input-server">
+    </div>
+    <div class="form-row">
+        <label for="node-input-blockTimeout"><i class="fa fa-clock-o"></i> Block Timeout (ms)</label>
+        <input type="number" id="node-input-blockTimeout" placeholder="5000">
+    </div>
+    <div class="form-row">
+        <label for="node-input-batchSize"><i class="fa fa-list"></i> Batch Size</label>
+        <input type="number" id="node-input-batchSize" placeholder="10">
+    </div>
+    <div class="form-row">
+        <label for="node-input-autoAck"><i class="fa fa-check"></i> Auto Acknowledge</label>
+        <input type="checkbox" id="node-input-autoAck" style="width: auto; margin-left: 0;">
+        <span style="margin-left: 10px;">Automatically ACK messages after processing</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-normalizePayload"><i class="fa fa-exchange"></i> Normalize</label>
+        <input type="checkbox" id="node-input-normalizePayload" style="width: auto; margin-left: 0;">
+        <span style="margin-left: 10px;">Convert OCPP 1.6/2.0.1 to unified format</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-filterAction"><i class="fa fa-filter"></i> Filter Action</label>
+        <input type="text" id="node-input-filterAction" placeholder="(all actions)">
+    </div>
+</script>
+
+<script type="text/html" data-help-name="ocpp-in">
+    <p>Receives OCPP messages from charging stations via Redis Streams.</p>
+
+    <h3>Outputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd>The OCPP message payload (normalized if enabled).</dd>
+
+        <dt>ocpp <span class="property-type">object</span></dt>
+        <dd>OCPP message metadata:
+            <ul>
+                <li><code>messageId</code> - Unique message ID</li>
+                <li><code>action</code> - OCPP action (e.g., BootNotification, Heartbeat)</li>
+                <li><code>version</code> - OCPP version (1.6 or 2.0.1)</li>
+                <li><code>tenant</code> - Operator/tenant identifier</li>
+                <li><code>deviceId</code> - Charger/station ID</li>
+                <li><code>identity</code> - Combined tenant:deviceId</li>
+                <li><code>timestamp</code> - Message timestamp</li>
+                <li><code>streamId</code> - Redis Stream message ID</li>
+                <li><code>_original</code> - Original payload before normalization</li>
+            </ul>
+        </dd>
+    </dl>
+
+    <h3>Properties</h3>
+    <dl class="message-properties">
+        <dt>Server <span class="property-type">ocpp-config</span></dt>
+        <dd>The OCPP configuration node with Redis connection settings.</dd>
+
+        <dt>Block Timeout <span class="property-type">number</span></dt>
+        <dd>How long to wait (ms) for new messages before checking again.</dd>
+
+        <dt>Batch Size <span class="property-type">number</span></dt>
+        <dd>Maximum number of messages to read per batch.</dd>
+
+        <dt>Auto Acknowledge <span class="property-type">boolean</span></dt>
+        <dd>If enabled, messages are automatically acknowledged after being sent.
+        Disable if you need manual control over acknowledgment.</dd>
+
+        <dt>Normalize <span class="property-type">boolean</span></dt>
+        <dd>If enabled, converts OCPP 1.6 and 2.0.1 messages to a unified format.
+        This allows your flow to handle both versions with the same logic.</dd>
+
+        <dt>Filter Action <span class="property-type">string</span></dt>
+        <dd>Optional. Only output messages with this action name.
+        Leave empty to receive all actions.</dd>
+    </dl>
+
+    <h3>Details</h3>
+    <p>This node reads from the <code>ws:inbound</code> Redis Stream using consumer groups,
+    allowing multiple Node-RED instances to share the message load.</p>
+
+    <h3>Supported Actions</h3>
+    <p>Common OCPP actions that can be filtered:</p>
+    <ul>
+        <li><code>BootNotification</code></li>
+        <li><code>Heartbeat</code></li>
+        <li><code>StatusNotification</code></li>
+        <li><code>Authorize</code></li>
+        <li><code>StartTransaction</code> / <code>TransactionEvent</code></li>
+        <li><code>StopTransaction</code></li>
+        <li><code>MeterValues</code></li>
+    </ul>
+
+    <h3>Example Flow</h3>
+    <pre>
+[ocpp in] → [switch (by action)] → [handler] → [ocpp out]
+    </pre>
+</script>

package/nodes/ocpp-in.js

@@ -0,0 +1,213 @@
+/**
+ * OCPP Input Node
+ * Reads OCPP messages from Redis Stream (ws:inbound) using Consumer Groups
+ */
+const { Keys } = require('../lib/redis-client');
+const { parseStreamMessage, normalize } = require('../lib/ocpp-normalizer');
+
+module.exports = function (RED) {
+    function OCPPInNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Get config node
+        node.server = RED.nodes.getNode(config.server);
+        if (!node.server) {
+            node.error('No OCPP config node configured');
+            node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+            return;
+        }
+
+        // Node configuration
+        node.blockTimeout = parseInt(config.blockTimeout, 10) || 5000;
+        node.batchSize = parseInt(config.batchSize, 10) || 10;
+        node.autoAck = config.autoAck !== false; // Default true
+        node.normalizePayload = config.normalizePayload !== false; // Default true
+        node.filterAction = config.filterAction || ''; // Optional action filter
+
+        // State
+        let running = false;
+        let consumerGroupCreated = false;
+
+        const redis = node.server.redis;
+        const consumerGroup = node.server.consumerGroup;
+        const consumerName = node.server.consumerName;
+        const streamKey = Keys.inbound();
+
+        /**
+         * Ensure consumer group exists
+         */
+        async function ensureConsumerGroup() {
+            if (consumerGroupCreated) return;
+
+            try {
+                await redis.xgroup('CREATE', streamKey, consumerGroup, '0', 'MKSTREAM');
+                node.log(`Created consumer group: ${consumerGroup}`);
+            } catch (err) {
+                if (err.message.includes('BUSYGROUP')) {
+                    // Group already exists, that's fine
+                    node.log(`Consumer group already exists: ${consumerGroup}`);
+                } else {
+                    throw err;
+                }
+            }
+            consumerGroupCreated = true;
+        }
+
+        /**
+         * Read messages from stream
+         */
+        async function readMessages() {
+            if (!running) return;
+
+            try {
+                // XREADGROUP GROUP group consumer [COUNT count] [BLOCK milliseconds] STREAMS key id
+                const results = await redis.xreadgroup(
+                    'GROUP', consumerGroup, consumerName,
+                    'COUNT', node.batchSize,
+                    'BLOCK', node.blockTimeout,
+                    'STREAMS', streamKey, '>'
+                );
+
+                if (results && results.length > 0) {
+                    const [, messages] = results[0]; // [streamKey, [[id, fields], ...]]
+
+                    for (const [streamId, fields] of messages) {
+                        await processMessage(streamId, fields);
+                    }
+                }
+            } catch (err) {
+                if (err.message.includes('NOGROUP')) {
+                    // Consumer group was deleted, recreate it
+                    consumerGroupCreated = false;
+                    await ensureConsumerGroup();
+                } else {
+                    node.error(`Read error: ${err.message}`);
+                    node.status({ fill: 'red', shape: 'dot', text: 'read error' });
+                    // Wait before retry
+                    await new Promise(resolve => setTimeout(resolve, 1000));
+                }
+            }
+
+            // Continue reading
+            if (running) {
+                setImmediate(readMessages);
+            }
+        }
+
+        /**
+         * Process a single message from the stream
+         */
+        async function processMessage(streamId, fields) {
+            try {
+                // Convert Redis fields array to object
+                // fields = ['key1', 'val1', 'key2', 'val2', ...]
+                const data = {};
+                for (let i = 0; i < fields.length; i += 2) {
+                    data[fields[i]] = fields[i + 1];
+                }
+
+                // Parse the stream message
+                let msg = parseStreamMessage(data);
+                msg.streamId = streamId;
+
+                // Apply action filter if configured
+                if (node.filterAction && msg.action !== node.filterAction) {
+                    // Auto-ack filtered messages if autoAck is enabled
+                    if (node.autoAck) {
+                        await redis.xack(streamKey, consumerGroup, streamId);
+                    }
+                    return;
+                }
+
+                // Normalize payload if enabled
+                if (node.normalizePayload) {
+                    msg = normalize(msg);
+                }
+
+                // Build Node-RED message
+                const nodeMsg = {
+                    payload: msg.payload,
+                    ocpp: {
+                        messageId: msg.messageId,
+                        action: msg.action,
+                        version: msg.version,
+                        protocol: msg.protocol,
+                        tenant: msg.tenant,
+                        deviceId: msg.deviceId,
+                        identity: msg.identity,
+                        timestamp: msg.timestamp,
+                        streamId: streamId,
+                        _original: msg._original,
+                    },
+                    _msgid: RED.util.generateId(),
+                };
+
+                // Update status
+                node.status({
+                    fill: 'green',
+                    shape: 'dot',
+                    text: `${msg.action} from ${msg.identity}`,
+                });
+
+                // Send to output
+                node.send(nodeMsg);
+
+                // Auto-acknowledge if enabled
+                if (node.autoAck) {
+                    await redis.xack(streamKey, consumerGroup, streamId);
+                }
+
+            } catch (err) {
+                node.error(`Process error: ${err.message}`, { streamId, fields });
+                node.status({ fill: 'red', shape: 'dot', text: 'process error' });
+            }
+        }
+
+        /**
+         * Start reading from stream
+         */
+        async function start() {
+            if (running) return;
+
+            try {
+                await ensureConsumerGroup();
+                running = true;
+                node.status({ fill: 'green', shape: 'ring', text: 'listening' });
+                node.log(`Started listening on ${streamKey}`);
+                readMessages();
+            } catch (err) {
+                node.error(`Start error: ${err.message}`);
+                node.status({ fill: 'red', shape: 'ring', text: 'start failed' });
+            }
+        }
+
+        /**
+         * Stop reading
+         */
+        function stop() {
+            running = false;
+            node.status({ fill: 'grey', shape: 'ring', text: 'stopped' });
+        }
+
+        // Start when Node-RED is ready
+        if (redis) {
+            redis.once('ready', () => {
+                start();
+            });
+
+            // If already connected
+            if (redis.status === 'ready') {
+                start();
+            }
+        }
+
+        // Cleanup on node removal
+        node.on('close', (done) => {
+            stop();
+            done();
+        });
+    }
+
+    RED.nodes.registerType('ocpp-in', OCPPInNode);
+};

package/nodes/ocpp-out.html

@@ -0,0 +1,129 @@
+<script type="text/javascript">
+    RED.nodes.registerType('ocpp-out', {
+        category: 'OCPP',
+        color: '#2196F3',
+        defaults: {
+            name: { value: '' },
+            server: { value: '', type: 'ocpp-config', required: true },
+            denormalizePayload: { value: true },
+            autoAck: { value: true },
+            streamMaxLen: { value: 1000, validate: RED.validators.number() },
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: 'font-awesome/fa-sign-out',
+        paletteLabel: 'ocpp out',
+        label: function () {
+            return this.name || 'ocpp out';
+        },
+        labelStyle: function () {
+            return this.name ? 'node_label_italic' : '';
+        },
+        align: 'right',
+    });
+</script>
+
+<script type="text/html" data-template-name="ocpp-out">
+    <div class="form-row">
+        <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+        <input type="text" id="node-input-server">
+    </div>
+    <div class="form-row">
+        <label for="node-input-denormalizePayload"><i class="fa fa-exchange"></i> Denormalize</label>
+        <input type="checkbox" id="node-input-denormalizePayload" style="width: auto; margin-left: 0;">
+        <span style="margin-left: 10px;">Convert unified format back to OCPP version</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-autoAck"><i class="fa fa-check"></i> Auto ACK</label>
+        <input type="checkbox" id="node-input-autoAck" style="width: auto; margin-left: 0;">
+        <span style="margin-left: 10px;">Acknowledge inbound message after response</span>
+    </div>
+    <div class="form-row">
+        <label for="node-input-streamMaxLen"><i class="fa fa-list-ol"></i> Stream Max Len</label>
+        <input type="number" id="node-input-streamMaxLen" placeholder="1000">
+    </div>
+</script>
+
+<script type="text/html" data-help-name="ocpp-out">
+    <p>Sends OCPP responses back to charging stations via Redis Streams.</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd>The response payload to send back to the device.</dd>
+
+        <dt>ocpp <span class="property-type">object</span></dt>
+        <dd>OCPP metadata from the input node (required):
+            <ul>
+                <li><code>messageId</code> - Original message ID (required)</li>
+                <li><code>action</code> - OCPP action for denormalization</li>
+                <li><code>version</code> - OCPP version for denormalization</li>
+                <li><code>tenant</code> - Operator/tenant identifier (required)</li>
+                <li><code>deviceId</code> - Charger/station ID (required)</li>
+                <li><code>streamId</code> - For auto-acknowledge</li>
+            </ul>
+        </dd>
+
+        <dt>ocpp.error <span class="property-type">boolean</span></dt>
+        <dd>If true, sends an error response instead of a normal response.</dd>
+
+        <dt>ocpp.errorCode <span class="property-type">string</span></dt>
+        <dd>OCPP error code (e.g., InternalError, NotImplemented).</dd>
+
+        <dt>ocpp.errorDescription <span class="property-type">string</span></dt>
+        <dd>Human-readable error description.</dd>
+    </dl>
+
+    <h3>Outputs</h3>
+    <p>The message is passed through unchanged after sending the response.</p>
+
+    <h3>Properties</h3>
+    <dl class="message-properties">
+        <dt>Server <span class="property-type">ocpp-config</span></dt>
+        <dd>The OCPP configuration node with Redis connection settings.</dd>
+
+        <dt>Denormalize <span class="property-type">boolean</span></dt>
+        <dd>If enabled, converts unified format back to OCPP 1.6 or 2.0.1
+        based on the original message version.</dd>
+
+        <dt>Auto ACK <span class="property-type">boolean</span></dt>
+        <dd>If enabled and streamId is present, acknowledges the original
+        inbound message after sending the response.</dd>
+
+        <dt>Stream Max Len <span class="property-type">number</span></dt>
+        <dd>Maximum length of the outbound stream (older messages are trimmed).</dd>
+    </dl>
+
+    <h3>Details</h3>
+    <p>This node sends responses to the device-specific outbound stream:
+    <code>ws:out:{tenant}:{deviceId}</code></p>
+
+    <p>The WebSocket server reads from this stream and forwards the response
+    to the connected charging station.</p>
+
+    <h3>Error Responses</h3>
+    <p>To send an error response, set <code>msg.ocpp.error = true</code>:</p>
+    <pre>
+msg.ocpp.error = true;
+msg.ocpp.errorCode = "NotImplemented";
+msg.ocpp.errorDescription = "This action is not supported";
+return msg;
+    </pre>
+
+    <h3>Example Flow</h3>
+    <pre>
+[ocpp in] → [handler function] → [ocpp out]
+
+// Handler function example:
+msg.payload = {
+    status: "Accepted",
+    currentTime: new Date().toISOString(),
+    interval: 300
+};
+return msg;
+    </pre>
+</script>

package/nodes/ocpp-out.js

@@ -0,0 +1,153 @@
+/**
+ * OCPP Output Node
+ * Sends OCPP responses back to charging stations via Redis Stream
+ */
+const { Keys } = require('../lib/redis-client');
+const { denormalize, buildResponse, buildError } = require('../lib/ocpp-normalizer');
+
+module.exports = function (RED) {
+    function OCPPOutNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Get config node
+        node.server = RED.nodes.getNode(config.server);
+        if (!node.server) {
+            node.error('No OCPP config node configured');
+            node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+            return;
+        }
+
+        // Node configuration
+        node.denormalizePayload = config.denormalizePayload !== false; // Default true
+        node.autoAck = config.autoAck !== false; // Default true
+        node.streamMaxLen = parseInt(config.streamMaxLen, 10) || 1000;
+
+        const redis = node.server.redis;
+        const consumerGroup = node.server.consumerGroup;
+
+        /**
+         * Handle incoming messages
+         */
+        node.on('input', async (msg, send, done) => {
+            try {
+                // Extract OCPP metadata
+                const ocpp = msg.ocpp || {};
+                const {
+                    messageId,
+                    action,
+                    version,
+                    tenant,
+                    deviceId,
+                    identity,
+                    streamId,
+                } = ocpp;
+
+                // Validate required fields
+                if (!messageId) {
+                    throw new Error('Missing ocpp.messageId');
+                }
+                if (!tenant || !deviceId) {
+                    throw new Error('Missing ocpp.tenant or ocpp.deviceId');
+                }
+
+                let responsePayload = msg.payload;
+
+                // Check if this is an error response
+                const isError = msg.ocpp?.error || msg.error;
+
+                if (isError) {
+                    // Build error response
+                    const errorCode = msg.ocpp?.errorCode || 'InternalError';
+                    const errorDescription = msg.ocpp?.errorDescription || msg.error?.message || 'Unknown error';
+                    const errorDetails = msg.ocpp?.errorDetails || {};
+
+                    const response = buildError(messageId, errorCode, errorDescription, errorDetails);
+
+                    await sendToDevice(tenant, deviceId, response, messageId);
+
+                } else {
+                    // Denormalize payload if enabled
+                    if (node.denormalizePayload && action) {
+                        const denormalized = denormalize({
+                            action,
+                            payload: responsePayload,
+                            version,
+                        }, version);
+                        responsePayload = denormalized.payload;
+                    }
+
+                    // Build OCPP response
+                    const response = buildResponse(messageId, responsePayload);
+
+                    await sendToDevice(tenant, deviceId, response, messageId);
+                }
+
+                // Auto-acknowledge the original message if streamId is present
+                if (node.autoAck && streamId) {
+                    const inboundKey = Keys.inbound();
+                    await redis.xack(inboundKey, consumerGroup, streamId);
+                }
+
+                // Update status
+                node.status({
+                    fill: 'green',
+                    shape: 'dot',
+                    text: `${action || 'response'} → ${identity}`,
+                });
+
+                // Forward message if needed
+                if (send) {
+                    send(msg);
+                }
+
+                if (done) {
+                    done();
+                }
+
+            } catch (err) {
+                node.error(`Output error: ${err.message}`, msg);
+                node.status({ fill: 'red', shape: 'dot', text: err.message });
+
+                if (done) {
+                    done(err);
+                }
+            }
+        });
+
+        /**
+         * Send response to device via Redis Stream
+         */
+        async function sendToDevice(tenant, deviceId, response, messageId) {
+            const outboundKey = Keys.outbound(tenant, deviceId);
+
+            // XADD with MAXLEN to prevent unbounded growth
+            await redis.xadd(
+                outboundKey,
+                'MAXLEN', '~', node.streamMaxLen,
+                '*',
+                'messageId', messageId,
+                'data', response,
+                'timestamp', Date.now().toString()
+            );
+
+            node.log(`Sent response to ${outboundKey}: ${messageId}`);
+        }
+
+        // Initial status
+        node.status({ fill: 'grey', shape: 'ring', text: 'ready' });
+
+        // Update status when Redis is ready
+        if (redis) {
+            redis.once('ready', () => {
+                node.status({ fill: 'green', shape: 'ring', text: 'connected' });
+            });
+
+            if (redis.status === 'ready') {
+                node.status({ fill: 'green', shape: 'ring', text: 'connected' });
+            }
+        }
+    }
+
+    RED.nodes.registerType('ocpp-out', OCPPOutNode);
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@blokcert/node-red-contrib-ocpp",
+  "version": "1.0.0",
+  "description": "Node-RED nodes for OCPP (Open Charge Point Protocol) message handling via Redis Streams",
+  "keywords": [
+    "node-red",
+    "ocpp",
+    "ocpp1.6",
+    "ocpp2.0.1",
+    "ev-charging",
+    "redis-streams"
+  ],
+  "author": "BLOKcert",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MingShyanWei/node-red-contrib-ocpp"
+  },
+  "node-red": {
+    "version": ">=2.0.0",
+    "nodes": {
+      "ocpp-in": "nodes/ocpp-in.js",
+      "ocpp-out": "nodes/ocpp-out.js",
+      "ocpp-command": "nodes/ocpp-command.js",
+      "ocpp-config": "nodes/ocpp-config.js"
+    }
+  },
+  "dependencies": {
+    "ioredis": "^5.3.2"
+  },
+  "devDependencies": {
+    "node-red": "^3.0.0",
+    "node-red-node-test-helper": "^0.3.2",
+    "mocha": "^10.2.0",
+    "chai": "^4.3.7"
+  },
+  "scripts": {
+    "test": "mocha 'test/**/*_spec.js' --timeout 10000"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}