@machhub-dev/node-red-nodes 1.0.6

Node-RED API for MACHHUB EDGE

npm install @machhub-dev/node-red-nodes

MACHHUB Node-RED Nodes

A collection of custom Node-RED nodes for integrating with the MACHHUB platform. These nodes provide seamless connectivity to MACHHUB's tag system, database collections, and real-time data capabilities.

Table of Contents

• Installation
• Configuration
• Available Nodes
  • MACHHUB Config
  • Tag Read
  • Tag Write
  • Bulk Tag Write
  • Collection
  • DB Query
• Usage Examples
• License

Installation

1. Navigate to your Node-RED user directory (typically ~/.node-red)
2. Install the MACHHUB nodes package:

   npm install <machhub-nodes-package>
   

3. Restart Node-RED

Configuration

MACHHUB Config Node

Before using any MACHHUB nodes, you need to configure a connection to your MACHHUB server. You have two options:

Option 1: Using Config Node (Recommended for multiple servers)

1. Add any MACHHUB node to your flow
2. Check "Use Config Node"
3. Click the pencil icon to create a new MACHHUB Config
4. Fill in the following details:
   • Name: A friendly name for this configuration
   • Host: MACHHUB server hostname or IP (default: localhost)
   • HTTP Port: MACHHUB HTTP API port (default: 6188)
   • MQTT Port: MACHHUB MQTT broker port (default: 1883)
   • Client ID: Your MACHHUB client ID
   • Client Secret: Your MACHHUB client secret

Option 2: Using machhub.env.json

1. Create a machhub.env.json file in your Node-RED working directory
2. Leave "Use Config Node" unchecked in your MACHHUB nodes
3. The nodes will automatically read configuration from the JSON file

Available Nodes

MACHHUB Config

Category: Config

A configuration node that stores connection details for MACHHUB server. This node is referenced by other MACHHUB nodes and doesn't appear in the flow directly.

Properties:

• Name: Optional friendly name
• Host: MACHHUB server address
• HTTP Port: HTTP API port number
• MQTT Port: MQTT broker port number
• Client ID: Authentication client ID
• Client Secret: Authentication client secret

---

Tag Read

Category: MACHHUB
Icon: 🏷️
Color: Purple (#c777f1)

Reads data from MACHHUB tags or subscribes to custom MQTT topics.

Configuration:

• Name: Optional node name
• Tag/Topic: Select from available tags or enter custom topic
• Use Config Node: Toggle between config node and machhub.env.json

Features:

• Dropdown list of available tags
• Manual topic entry support
• MQTT wildcard support:
  • + - Single level wildcard
  • # - Multi-level wildcard

Output:

• msg.payload: Data received from the subscribed topic

Examples:

sensor/temperature          → Specific tag
sensor/+/temperature       → All sensors' temperature
sensor/#                   → All topics under sensor

---

Tag Write

Category: MACHHUB
Icon: 🏷️
Color: Purple (#c777f1)

Writes data to a selected MACHHUB tag.

Configuration:

• Name: Optional node name
• Select Tag: Choose from available tags
• Use Config Node: Toggle between config node and machhub.env.json

Input:

• msg.payload: JSON data to publish to the tag

Example:

msg.payload = {
    temperature: 25.5,
    humidity: 60,
    timestamp: Date.now()
};
return msg;

---

Bulk Tag Write

Category: MACHHUB
Icon: 🏷️
Color: Purple (#c777f1)

Performs bulk write operations to multiple MACHHUB tags simultaneously.

Configuration:

• Name: Optional node name
• Use Config Node: Toggle between config node and machhub.env.json

Input:

• msg.payload: Object with tag paths as keys and values to write

Example:

msg.payload = {
    "Namespace1/FolderA/Tag1": 123,
    "Namespace1/FolderA/Tag2": 456,
    "Namespace2/FolderB/Temperature": 25.5
};
return msg;

---

Collection

Category: MACHHUB
Icon: 💾
Color: Purple (#c777f1)

Performs CRUD operations on MACHHUB database collections.

Configuration:

• Name: Optional node name
• Use Config Node: Toggle between config node and machhub.env.json
• Collection: Select target collection from dropdown
• Action: Choose operation type

Actions:

1. Select

Query and filter records from a collection.

Configuration:

• Select Fields: Comma-separated list of fields to return (leave empty for all)
• Filters: Add filter conditions with operators: =, !=, >, <, >=, <=

Output:

msg.payload = [
    { field1: "value1", field2: "value2" },
    { field1: "value3", field2: "value4" }
];

2. Create

Insert a new record into a collection.

Input:

msg.payload = {
    field1: "value1",
    field2: "value2"
};

Output:

msg.payload = {
    id: "table_name:new_record_id",
    field1: "value1",
    field2: "value2"
};

3. Update

Modify an existing record in a collection.

Input:

msg.payload = {
    id: "table_name:05nwoy566jasfwgak5r3",
    record: {
        field1: "updated_value1",
        field2: "updated_value2"
    }
};

4. Delete

Remove a record from a collection.

Input:

msg.payload = "table_name:05nwoy566jasfwgak5r3";

---

DB Query

Category: MACHHUB
Icon: 🔍
Color: Purple (#c777f1)

Execute custom SurrealQL queries against the MACHHUB database.

Configuration:

• Name: Optional node name
• Use Config Node: Toggle between config node and machhub.env.json
• Query: SurrealQL query to execute

Input (Optional):

• msg.query: Override the configured query at runtime

Output:

• msg.payload: Array of query results

Important: Wrap table names with backticks: `domain_id.table_name`

Example Queries:

SELECT * FROM `domain_id.purchase_orders` WHERE po_number = 'PO_0016'

SELECT id, name FROM `domain_id.products` LIMIT 10

SELECT COUNT(*) as total FROM `domain_id.orders`

SELECT * FROM `domain_id.sensors` WHERE temperature > 25

Runtime Override Example:

msg.query = "SELECT * FROM `domain_id.purchase_orders` WHERE status = 'pending'";
return msg;

---

Usage Examples

Example 1: Reading and Writing Tags

[Inject] → [Tag Read] → [Function] → [Tag Write]

Function Node:

// Read temperature, add 5, write to another tag
msg.payload = {
    value: msg.payload.value + 5,
    timestamp: Date.now()
};
return msg;

Example 2: Querying and Filtering Collection Data

[Inject] → [Collection: Select] → [Debug]

Collection Configuration:

• Action: Select
• Select Fields: id,name,status
• Filters:
  • status = active
  • priority > 5

Example 3: Bulk Tag Update

[Inject] → [Function] → [Bulk Tag Write]

Function Node:

msg.payload = {
    "Production/Line1/Speed": 1500,
    "Production/Line1/Temperature": 85.2,
    "Production/Line1/Status": "Running"
};
return msg;

Example 4: Custom Database Query

[Inject] → [DB Query] → [Function] → [Debug]

DB Query Configuration:

SELECT * FROM `domain_id.production_data`
WHERE timestamp > time::now() - 1h
ORDER BY timestamp DESC
LIMIT 100

Example 5: Create-Read-Update-Delete Workflow

[Inject] → [Collection: Create] → [Collection: Select] → [Function] → [Collection: Update]

---

Troubleshooting

Tags Not Loading

• Verify MACHHUB server is running and accessible
• Check Client ID and Client Secret are correct
• Ensure HTTP Port is correct (default: 6188)
• Check network connectivity to the MACHHUB server

Collection Operations Failing

• Verify the collection exists in the database
• Check field names match the collection schema
• Ensure proper permissions are set for the client

MQTT Subscription Not Receiving Data

• Verify MQTT Port is correct (default: 1883)
• Check the topic path is correct
• Ensure tags are publishing data
• Verify firewall settings allow MQTT traffic

---

License

See LICENSE file for details.

---

Support

For issues, questions, or contributions, please contact your MACHHUB administrator or refer to the MACHHUB documentation.