node-red-contrib-octocore 0.0.13
OctoCore implementation for node-red
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 Jestnpm run lint
- Run ESLint for code quality checksnpm run lint:fix
- Fix ESLint issues automaticallynpm 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 configurationmsg.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 usedmsg.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