@machhub-dev/node-red-nodes 1.0.5 → 1.0.7

package/README.md

@@ -0,0 +1,371 @@
+# 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](#installation)
+- [Configuration](#configuration)
+- [Available Nodes](#available-nodes)
+  - [MACHHUB Config](#machhub-config)
+  - [Tag Read](#tag-read)
+  - [Tag Write](#tag-write)
+  - [Bulk Tag Write](#bulk-tag-write)
+  - [Collection](#collection)
+  - [DB Query](#db-query)
+- [Usage Examples](#usage-examples)
+- [License](#license)
+
+## Installation
+
+1. Navigate to your Node-RED user directory (typically `~/.node-red`)
+2. Install the MACHHUB nodes package:
+   ```bash
+   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:**
+```javascript
+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:**
+```javascript
+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:**
+```javascript
+msg.payload = [
+    { field1: "value1", field2: "value2" },
+    { field1: "value3", field2: "value4" }
+];
+```
+
+#### 2. Create
+Insert a new record into a collection.
+
+**Input:**
+```javascript
+msg.payload = {
+    field1: "value1",
+    field2: "value2"
+};
+```
+
+**Output:**
+```javascript
+msg.payload = {
+    id: "table_name:new_record_id",
+    field1: "value1",
+    field2: "value2"
+};
+```
+
+#### 3. Update
+Modify an existing record in a collection.
+
+**Input:**
+```javascript
+msg.payload = {
+    id: "table_name:05nwoy566jasfwgak5r3",
+    record: {
+        field1: "updated_value1",
+        field2: "updated_value2"
+    }
+};
+```
+
+#### 4. Delete
+Remove a record from a collection.
+
+**Input:**
+```javascript
+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:**
+```sql
+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:**
+```javascript
+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:**
+```javascript
+// 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:**
+```javascript
+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:**
+```sql
+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](LICENSE) file for details.
+
+---
+
+## Support
+
+For issues, questions, or contributions, please contact your MACHHUB administrator or refer to the MACHHUB documentation.

package/dist/lib/services/http.api.services.js

@@ -112,12 +112,14 @@ class HTTPAPIService {
         });
     }
     // Collection Example
-    static getCollectionsExample(settings, collectionID) {
+    static getCollectionsExample(settings, collectionID, isSelectQuery) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const res = yield this.service(settings).request
                     .post('collections/example', undefined, {
-                    collectionID
+                    collectionID,
+                    // @ts-ignore: need to pass as boolean not string
+                    isSelectQuery: isSelectQuery
                 });
                 return res;
             }

package/dist/nodes/collections.html

@@ -205,7 +205,8 @@
           let url = "/collections/example";
           
           const requestBody = {
-            collectionID: collectionID
+            collectionID, 
+            isSelectQuery: $action.val() === "select"
           };
 
           if (useConfigNode) {

package/dist/nodes/collections.js

@@ -208,7 +208,7 @@ function default_1(RED) {
     // HTTP endpoint to fetch collection example for admin UI
     RED.httpAdmin.post("/collections/example", (req, res) => __awaiter(this, void 0, void 0, function* () {
         try {
-            const { collectionID, host, httpPort, clientId, clientSecret } = req.body;
+            const { collectionID, isSelectQuery, host, httpPort, clientId, clientSecret } = req.body;
             let configData;
             // Check if credentials are provided (config node)
             if (clientId && clientSecret) {
@@ -229,7 +229,7 @@ function default_1(RED) {
                     clientSecret: envConfig.clientSecret
                 };
             }
-            const result = yield http_api_services_1.HTTPAPIService.getCollectionsExample(configData, collectionID);
+            const result = yield http_api_services_1.HTTPAPIService.getCollectionsExample(configData, collectionID, isSelectQuery);
             res.json(result);
         }
         catch (e) {

package/dist/nodes/machhub-config.html

@@ -2,6 +2,7 @@
     RED.nodes.registerType('machhub-config', {
         category: 'config',
         defaults: {
+            name: { value: "", required: false },
             host: { value: "localhost", required: true },
             httpPort: { value: 6188, required: true, validate: RED.validators.number() },
             mqttPort: { value: 1883, required: true, validate: RED.validators.number() },
@@ -9,12 +10,16 @@
             clientSecret: { value: "", required: true }
         },
         label: function() {
-            return this.host + ":" + this.httpPort + " / MQTT:" + this.mqttPort;
+            return this.name || (this.host + ":" + this.httpPort + " / MQTT:" + this.mqttPort);
         }
     });
 </script>
 
 <script type="text/html" data-template-name="machhub-config">
+    <div class="form-row">
+        <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-config-input-name" placeholder="My MACHHUB Server">
+    </div>
     <div class="form-row">
         <label for="node-config-input-host"><i class="fa fa-server"></i> Host</label>
         <input type="text" id="node-config-input-host" placeholder="localhost">

package/dist/nodes/tag-write.html

@@ -54,28 +54,32 @@
         try {
           // Get the selected machhub config
           const machhubConfigId = $machhub.val();
+          const useConfigNodeChecked = $useConfigNode.is(":checked");
           let configData = {};
           
-          if (machhubConfigId) {
+          if (useConfigNodeChecked && machhubConfigId) {
             const configNode = RED.nodes.node(machhubConfigId);
             if (configNode) {
               configData = {
+                useConfigNode: "true",
                 host: configNode.host || "127.0.0.1",
                 httpPort: configNode.httpPort || 6188,
                 clientId: configNode.clientId || "",
                 clientSecret: configNode.clientSecret || ""
               };
             }
-          } else if (machhubNodes.length > 0) {
+          } else if (useConfigNodeChecked && machhubNodes.length > 0) {
             // Use first available config
             const configNode = machhubNodes[0];
             configData = {
+              useConfigNode: "true",
               host: configNode.host || "127.0.0.1",
               httpPort: configNode.httpPort || 6188,
               clientId: configNode.clientId || "",
               clientSecret: configNode.clientSecret || ""
             };
           }
+          // If useConfigNode is false, send empty params to use machhub.env.json
 
           // Build query string (revert back to working approach)
           const queryParams = new URLSearchParams(configData).toString();
@@ -100,10 +104,11 @@
 
           const tags = await res.json();
 
-          // Populate dropdown
+          // Populate datalist
+          const $datalist = $("#node-input-selectedTag-datalist");
           if (tags && tags.length > 0) {
-            let options = tags.map(tag => `<option value="${tag}">${tag}</option>`);
-            $selected_tag.html(options.join("")); // Set options
+            let options = tags.map(tag => `<option value="${tag}">`);
+            $datalist.html(options.join("")); // Set options
           } else {
             console.log("No tags available from API");
           }
@@ -114,9 +119,9 @@
           }
         } catch (error) {
           console.error("Error fetching tags:", error);
-          // Show only the currently selected tag as an option
+          // Keep the currently selected tag value
           if (node.selectedTag) {
-            $selected_tag.html(`<option value="${node.selectedTag}">${node.selectedTag}</option>`);
+            $selected_tag.val(node.selectedTag);
           }
         }
       }
@@ -139,7 +144,8 @@
   </div>
   <div class="form-row">
     <label for="node-input-selectedTag"><i class="fa fa-list"></i> Select Tag</label>
-    <select id="node-input-selectedTag"></select>
+    <input type="text" id="node-input-selectedTag" list="node-input-selectedTag-datalist" placeholder="Start typing or select a tag...">
+    <datalist id="node-input-selectedTag-datalist"></datalist>
   </div>
   <div class="form-row">
     <label for="node-input-useConfigNode" style="width: auto; padding-right: 10px;">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@machhub-dev/node-red-nodes",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Node-RED API for MACHHUB EDGE",
   "scripts": {
     "build": "yarn clean && npx tsc && yarn copy-files",