node-red-contrib-octocore 0.0.13

OctoCore implementation for node-red

npm install node-red-contrib-octocore

node-red-contrib-octocore

NPM version

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 uptime (e.g., "connected (2h 15m)")
  • Disconnected: Shows reconnect attempts (e.g., "disconnected (3/10)")
  • Connecting: Shows current attempt (e.g., "connecting (4)")
  • Failed: Shows when max attempts 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, RAW Value, Specific Topic, Use msg.topic).
  • Datapoint / Subject: The datapoint or subject to publish to.

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

Example Flow

Here is an 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

Node Info

Version: 0.0.13
Updated 3 weeks, 1 day ago
License: MIT
Rating: 5.0 4

Categories

Actions

Rate:

Downloads

15 in the last week

Nodes

  • uns-publish
  • uns-subscribe
  • uns-request
  • nats-server
  • nats-health
  • uns-stream-publisher
  • uns-stream-consumer

Keywords

  • node-red
  • octocore
  • nats
  • iot
  • manufacturing