node-red-contrib-octocore

A Node-RED module to communicate with the OctoCore platform from Octotronic.

Overview

This Node-RED module provides nodes to publish and subscribe to messages on the OctoCore platform using NATS. It includes the following nodes:

Core Nodes:

• uns-publish: Publish messages to the OctoCore platform with advanced features (buffering, batching, rate limiting).
• uns-subscribe: Subscribe to messages from the OctoCore platform with automatic JSON parsing.
• uns-request: Send requests to the OctoCore platform and receive responses.
• uns-server: Configure the NATS server connection with enhanced security (TLS, JWT, NKey authentication).

Installation

To install the module, run the following command in your Node-RED user directory (typically ~/.node-red):

npm install node-red-contrib-octocore

Development Setup

For development, clone the repository and install dependencies:

git clone https://git.octotronic.com/manufacturinghub/node-red-contrib-octocore.git
cd node-red-contrib-octocore
npm install

Available Scripts

• npm test - Run tests with Jest
• npm run lint - Run ESLint for code quality checks
• npm run lint:fix - Fix ESLint issues automatically
• npm run format - Format code with Prettier

Makefile Commands

For convenience, you can also use the provided Makefile:

make help          # Show all available commands
make dev-setup     # Setup development environment
make dev-cycle     # Run development cycle (format, lint, test)
make docker-up     # Start Node-RED with Docker
make docker-logs   # Show Docker logs

See docs/makefile-usage.md for complete documentation.

Nodes

NATS Server Configuration

uns-server

This node is used to configure the connection to the NATS server with comprehensive security features.

🔐 Enhanced Security & Authentication:

• Authentication Methods (Dropdown Selection):
  • No Authentication: For local development or unsecured servers
  • Username/Password: Traditional authentication (default, backward compatible)
  • Token Authentication: Single authentication token for NATS server
  • JWT Authentication: NATS 2.x JSON Web Token with NKey seed
  • NKey Authentication: Cryptographic authentication using NKey seed
• TLS/SSL Encryption Support:
  • Enable/disable TLS encryption with checkbox
  • CA Certificate: Server verification with custom CA certificate file
  • Client Certificate: Mutual TLS (mTLS) with client certificate
  • Client Key: Client private key for mTLS authentication
  • Verify Server Certificate: Optional certificate verification (enabled by default)
• Security Features:
  • All credentials stored encrypted in Node-RED's secure credentials system
  • Automatic security warnings for production connections without TLS
  • JWT validation ensures both JWT token and NKey seed are provided
  • File-based certificate loading with path validation
  • Debug logging shows auth method and TLS status (with masked credentials)

Connection Settings:

• Server: The URL of the NATS server.
• Max Reconnect Attempts: Maximum number of reconnection attempts (default: 10).
• Reconnect Wait Time: Time to wait between reconnection attempts in milliseconds (default: 1000).
• Connection Timeout: Connection timeout in milliseconds (default: 10000).
• Ping Interval: Interval between ping messages in milliseconds (default: 30000).
• Max Ping Outs: Maximum number of ping timeouts before disconnect (default: 3).

Connection Status:

• Connected: Shows connection status
• Disconnected: Shows reconnect attempts
• Connecting: Shows current attempt
• Failed: Shows when connection fails

Security Best Practices:

• Always use TLS/SSL for production environments
• Use JWT or NKey authentication for enhanced security
• Keep "Verify Server Certificate" enabled in production
• All credentials are encrypted and never visible in flow exports

Publish Node

uns-publish

This node is used to publish messages to the OctoCore platform with advanced features.

Core Features:

• Name: The name of the node.
• Server: The NATS server configuration to use.
• Dataformat: The format of the data to publish (UNS Value, UNS Event, UNS Reply, Specific Topic).
• Datapoint / Subject: The datapoint or subject to publish to.
• Debug: Optional debug logging (enable via checkbox)

🔧 Advanced Features:

• Message Buffering: Queue messages when connection is lost
  • Buffer Limit Types: Message count (max: 10,000) or buffer size in bytes (max: 100 MB)
  • Buffer Modes: Drop oldest (FIFO), drop newest, or reject on full
  • Buffer Persistence: None (RAM), Context Storage, File System, or Both
  • Auto-Save: Automatic periodic saving (5-300 seconds, default: 30s)
  • Timestamp Preservation: Original timestamps preserved when buffered messages are flushed
  • Parallel Transmission: All buffered messages sent simultaneously when connection is restored (~10x faster)
• Manual UNS Datatype Override: Force specific datatype (Integer, Float, Boolean, String, Object) with strict validation
• Batch Publishing: Group multiple messages for efficient transmission
  • Batch Size: Number of messages per batch (default: 100, range: 1-1000)
  • Batch Interval: Time window in milliseconds (default: 1000ms, range: 100-60000ms)
  • Batch Modes:
    • Size Only: Publish only when batch is full (recommended for high-throughput scenarios)
    • Hybrid: Publish when batch is full OR interval expires (whichever comes first)
    • Time Only: Publish at regular intervals regardless of batch size
  • Status Display: Shows current queue state batching (X/Y) where X = queued messages, Y = batch size
  • Timestamp Preservation: Original message creation timestamps are preserved when batching
  • Parallel Transmission: All batch messages sent simultaneously (~10x faster than sequential)
• Auto-Reply Handler: Process request-reply patterns with configurable timeout and output port
  • Note: The output port is only used when Auto-Reply Handler is enabled. When disabled, messages are published directly without forwarding to the output.
• Rate Limiting: Token bucket algorithm to prevent message flooding (configurable rate, burst, actions: drop, delay)
• Connection Pooling: Shared connections for resource efficiency

Output Properties (only used when Auto-Reply Handler is enabled):

• msg.payload: The message payload
• msg.topic: The NATS subject used
• msg._buffered: Indicates if message was buffered during disconnect
• msg._batched: Indicates if message was part of a batch
• msg._rateLimited: Indicates if message was rate limited
• msg._originalTimestamp: Original timestamp when message was buffered (preserved during flush)

The payload of the message to publish can be set via the msg.payload property.

Subscribe Node

uns-subscribe

This node is used to subscribe to messages from the OctoCore platform with automatic parsing and connection pooling.

Core Features:

• Name: The name of the node.
• Server: The NATS server configuration to use.
• Dataformat: The format of the data to subscribe to (UNS Value, UNS Command, UNS Event, Specific Subject).
• Datapoint / Subject: The datapoint or subject to subscribe to.
• Topic Field: Select what value to use for msg.topic (NATS Subject, Datapoint ID, Datapoint Name, Data Type).

🔧 Advanced Features:

• Automatic JSON Parsing: For Specific Subject format, automatically attempts JSON parsing with fallback to string
• Connection Pooling: Shared connections for resource efficiency
• Format Detection: Adds _format property ('json' or 'string') for downstream processing

Output Properties:

• msg.payload: Only the value of the datapoint (for UNS Value format)
• msg.topic: The topic field value based on configuration
• msg.datatype: Data type of the UNS value (only for UNS Value format)
• msg.id: Datapoint ID (only for UNS Value format)
• msg.name: Datapoint name (only for UNS Value format)
• msg.timestamp: Timestamp of the message (only for UNS Value format)
• msg._format: Format indicator ('json' or 'string') for Specific Subject

UNS Event Properties:

• msg.id: Event ID (only for UNS Event format)
• msg.type: Event type (only for UNS Event format)
• msg.startTime: Event start time (only for UNS Event format)
• msg.endTime: Event end time (only for UNS Event format)

Data Type Handling:

• datatype 1 (Integer): String converted to Integer
• datatype 2 (Float): String converted to Float
• datatype 3 (Boolean): String converted to Boolean
• datatype 4 (String): Remains as String
• datatype 5 (Unix Timestamp): Unix timestamp in milliseconds
• datatype 6 (Object): String parsed to JSON object

Request Node

uns-request

This node is used to send requests to the OctoCore platform and receive responses.

• Name: The name of the node.
• Server: The NATS server configuration to use.
• Dataformat: The format of the data (UNS Command, Specific Subject).
• Subject: The subject to send the request to.
• Timeout: Timeout in milliseconds for the request (default: 1000ms).
• Handle Timeout as Message: If enabled, timeout errors are sent as regular messages instead of node errors.

Output Properties:

• msg.payload: The response data (or error object if timeout/service unavailable)
• msg.status: "success", "timeout", or "service_unavailable"
• msg.topic: The NATS subject used
• msg.error: Error details (only present when status is "timeout" or "service_unavailable")

Node Status Indicators:

• 🟢 Grey "ready": Node ready for requests
• 🟡 Yellow "requesting...": Request in progress
• 🟠 Orange "timeout": Request timed out
• 🟠 Orange "no service": Service unavailable (503)
• 🟠 Orange "error": Other errors
• 🔴 Red: Server connection problem

The payload of the request can be set via the msg.payload property.

Security

🔐 Enhanced Security Features

The OctoCore module includes comprehensive security features for production environments:

Authentication Methods:

• No Authentication: For local development
• Username/Password: Traditional authentication (backward compatible)
• Token Authentication: Single authentication token
• JWT Authentication: NATS 2.x JSON Web Token with NKey seed
• NKey Authentication: Cryptographic authentication

TLS/SSL Encryption:

• Enable/disable TLS encryption
• CA certificate verification
• Mutual TLS (mTLS) with client certificates
• Certificate verification options

Security Best Practices:

• All credentials stored encrypted in Node-RED's secure credentials system
• Automatic security warnings for production connections without TLS
• File-based certificate loading with path validation
• Debug logging with masked credentials

For detailed security documentation, see SECURITY.md.

Examples

Comprehensive Example Flow

A complete example flow is included in the examples/ directory. The flow demonstrates all OctoCore nodes with real-world use cases.

To use the example flow:

1. Import examples/flows.json into Node-RED
2. Or view it in the repository: examples/flows.json

See examples/README.md for detailed documentation.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Testing

Run the test suite:

npm test

For coverage reports:

npm test -- --coverage

Links

• Octotronic Website
• Node-RED Documentation
• NATS Documentation

Basic Example Flow

Here is a basic example flow that demonstrates how to use the uns-publish, uns-subscribe, and uns-request nodes:

[
    {
        "id": "publish-node",
        "type": "uns-publish",
        "z": "0b30cc47ed4855ca",
        "name": "Publish to OctoCore",
        "server": "uns-server-config",
        "dataformat": "uns_value",
        "datapointid": "example.datapoint",
        "x": 1900,
        "y": 1100,
        "wires": []
    },
    {
        "id": "subscribe-node",
        "type": "uns-subscribe",
        "z": "0b30cc47ed4855ca",
        "name": "Subscribe from OctoCore",
        "server": "uns-server-config",
        "dataformat": "uns_value",
        "datapointid": "example.datapoint",
        "x": 1890,
        "y": 1140,
        "wires": [
            [
                "debug-node"
            ]
        ]
    },
    {
        "id": "request-node",
        "type": "uns-request",
        "z": "0b30cc47ed4855ca",
        "name": "Request from OctoCore",
        "server": "uns-server-config",
        "subject": "example.subject",
        "x": 1890,
        "y": 1200,
        "wires": [
            [
                "debug-node"
            ]
        ]
    },
    {
        "id": "debug-node",
        "type": "debug",
        "z": "0b30cc47ed4855ca",
        "name": "Debug",
        "active": true,
        "console": "false",
        "complete": "false",
        "x": 2210,
        "y": 1160,
        "wires": []
    },
    {
        "id": "fc641d9a3139e434",
        "type": "inject",
        "z": "0b30cc47ed4855ca",
        "name": "",
        "props": [
            {
                "p": "payload"
            },
            {
                "p": "topic",
                "vt": "str"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "testtring",
        "payloadType": "str",
        "x": 1650,
        "y": 1100,
        "wires": [
            [
                "publish-node"
            ]
        ]
    },
    {
        "id": "6da3165904b618b3",
        "type": "inject",
        "z": "0b30cc47ed4855ca",
        "name": "",
        "props": [
            {
                "p": "payload"
            },
            {
                "p": "topic",
                "vt": "str"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "10",
        "payloadType": "num",
        "x": 1650,
        "y": 1200,
        "wires": [
            [
                "request-node"
            ]
        ]
    },
    {
        "id": "uns-server-config",
        "type": "uns-server",
        "server": "nats://localhost:4222",
        "user": "username",
        "pass": "password"
    },
    {
        "id": "4a72a6bb1c07bac1",
        "type": "global-config",
        "env": [],
        "modules": {
            "node-red-contrib-octocore": "0.0.16"
        }
    }
]