node-red-contrib-octocore 0.0.16

OctoCore implementation for node-red

npm install node-red-contrib-octocore

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:

• uns-publish: Publish messages to the OctoCore platform.
• uns-subscribe: Subscribe to messages from the OctoCore platform.
• uns-request: Send requests to the OctoCore platform and receive responses.
• nats-server: Configure the NATS server connection.
• connection-health: Monitor NATS server health and connection status with advanced metrics.

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

nats-server

This node is used to configure the connection to the NATS server.

• Server: The URL of the NATS server.
• User: The username for the NATS server (optional).
• Password: The password for the NATS server (optional).
• 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 only "connected" (no uptime)
• Disconnected: shows reconnect attempts (e.g., "disconnected (3/10)")
• Connecting: shows current attempt (e.g., "connecting (4)")
• Failed: shows when max attempts are reached

Publish Node

uns-publish

This node is used to publish messages to the OctoCore platform.

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

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.

• 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).

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)

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 (JSON): 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.

Health Monitoring Node

connection-health

This node monitors the health and status of the NATS server connection with advanced metrics and connectivity tests.

• Name: The name of the node.
• Server: The NATS server configuration to use.
• Check on Start: If enabled, performs a health check when the node starts.
• Periodic Check: If enabled, performs health checks at regular intervals.
• Check Interval: The interval in seconds between periodic health checks.
• Enable Connectivity Tests: If enabled, performs publish/subscribe and request/response connectivity tests.
• Latency Threshold: Warning threshold for connection latency in milliseconds (10-1000ms).
• Reconnect Threshold: Warning threshold for number of reconnection attempts (1-50).
• Throughput Threshold: Info threshold for message throughput in messages per second (100-10000).

Output Properties:

• msg.payload: Comprehensive health status information including:
  • Extended server information (cluster, JetStream, TLS)
  • Enhanced connection details (latency, stability)
  • Advanced statistics (throughput, bandwidth)
  • Connectivity test results
  • Alerting and thresholds
  • Health summary
• msg.status: "success" or "error"
• msg.topic: Always "nats.health"

Enhanced Features:

• Extended Server Info: Cluster details, JetStream status, TLS configuration
• Connection Metrics: Latency measurement, connection stability assessment
• Performance Monitoring: Throughput calculation, bandwidth usage
• Connectivity Tests: End-to-end publish/subscribe and request/response validation
• Configurable Thresholds: Alerting for latency, reconnects, and throughput
• Health Summary: Overall status, connection quality, performance rating

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.

Basic Example Flow

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

[
    {
        "id": "nats-server-config",
        "type": "nats-server",
        "z": "",
        "name": "NATS Server",
        "server": "nats://localhost:4222",
        "user": "username",
        "pass": "password"
    },
    {
        "id": "publish-node",
        "type": "uns-publish",
        "z": "",
        "name": "Publish to OctoCore",
        "server": "nats-server-config",
        "dataformat": "uns_value",
        "datapointid": "example.datapoint",
        "wires": []
    },
    {
        "id": "subscribe-node",
        "type": "uns-subscribe",
        "z": "",
        "name": "Subscribe from OctoCore",
        "server": "nats-server-config",
        "dataformat": "uns_value",
        "datapointid": "example.datapoint",
        "wires": [["debug-node"]]
    },
    {
        "id": "request-node",
        "type": "uns-request",
        "z": "",
        "name": "Request from OctoCore",
        "server": "nats-server-config",
        "subject": "example.subject",
        "wires": [["debug-node"]]
    },
    {
        "id": "health-node",
        "type": "nats-health",
        "z": "",
        "name": "Connection Health",
        "server": "nats-server-config",
        "checkOnStart": true,
        "periodicCheck": true,
        "checkInterval": 60,
        "enableConnectivityTests": true,
        "latencyThreshold": 100,
        "reconnectThreshold": 5,
        "throughputThreshold": 1000,
        "wires": [["debug-node"]]
    },
    {
        "id": "debug-node",
        "type": "debug",
        "z": "",
        "name": "Debug",
        "active": true,
        "console": "false",
        "complete": "false",
        "x": 500,
        "y": 300,
        "wires": []
    }
]

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Testing

Run the test suite:

```sh
npm test

For coverage reports:

npm test -- --coverage

Links

• Octotronic Website
• Node-RED Documentation
• NATS Documentation