smithtek-mako-rf 3.2.4 → 3.3.2

package/README.md

@@ -1,3 +1,38 @@
+# Cloud data/alarms and local debug — 3.3.2
+
+- **Top pin, output 1 — Data / alarm:** successful decoded readings and write responses, or the friendly named fault JSON when a request fails. Connect this to the cloud flow.
+- **Bottom pin, output 2 — Debug:** technical error payloads containing `ok:false`, `error`, `code` and `req`. Connect this to a local Debug node, or leave it disconnected. Successful requests send nothing here.
+
+A timeout alarm is emitted after **one poll exhausts its configured retries**. Retries 0 means one failed attempt; retries 2 means three failed attempts. There is no separate bad-poll counter. If a retry succeeds, only normal data is emitted. Permanent Modbus exceptions (such as an unsupported register), invalid configuration and queue rejection are reported immediately. Each failed poll emits one friendly alarm on output 1 and one technical message on output 2. Intentional shutdown/redeploy cancellation emits neither.
+
+Existing first-output wires keep both data and friendly alarms. Node-RED logs, status and Catch handling remain enabled. Refresh the editor after updating to see the pin labels. This corrects the output routing introduced in 3.3.1.
+
+---
+
+# Prefixes and operator fault messages — 3.3.0
+
+## Prefix
+
+Set the node's **Prefix** once, for example `b1`. A decoder row named `Pressure` then outputs `{"b1 Pressure":12}`. Copy the node and change its prefix to `b2` to reuse every table entry without renaming them. Leading/trailing prefix whitespace is trimmed, and exactly one space separates it from the row name. A blank prefix preserves existing output names. Existing nested names retain their structure: `tank=>level` becomes `{"b1 tank":{"level":12}}`.
+
+## Operator fault JSON
+
+Failed requests emit a flat numeric alarm on output 1 in `msg.payload`, suitable for forwarding as a named cloud value. For example:
+
+```json
+{"b1 RF ID2 Not communicating — check power/RF; disable if out of service":1}
+```
+
+The key uses the prefix (or node Name when no prefix is set), actual channel (RF, RS485-1 or RS485-2), device ID and a short operator message. RS485 timeouts advise checking power and wiring. Disabling an out-of-service asset is operator advice; the node never disables a device automatically.
+
+Only a final failed request emits this alarm: a timeout that recovers within its configured retries produces normal data, with no fault payload. Permanent device exceptions and configuration errors are reported immediately when retrying cannot help. Each failed poll emits one fault message. Queue overload, gateway port problems, invalid configuration and decoding failures have distinct messages; they are not described as RF failures. Intentional shutdown/redeploy cancellation emits no fault alarm. An optional RSSI diagnostic failure remains in `msg.rssi_error` and does not turn a successful register read into an asset communication fault.
+
+Full technical details remain in `msg.modbus`: `ok:false`, `code`, `error`, `req`, and `fault` (key, reason, operator summary, channel, device ID, prefix, node name and timestamp). Node-RED Catch handling remains supported. Successful requests output normal prefixed readings. No synthetic zero/clear alarm is sent on recovery; cloud alarm reset/expiry must be handled by the receiving flow or service.
+
+**Output change:** failure payloads previously contained `{ok:false,error,req}`; they now contain the flat named alarm above. Use `msg.modbus.ok`, `msg.modbus.error` and `msg.modbus.req` in flows that inspect errors. This package does not connect to or configure 3dm.space; compatibility with a particular cloud ingestion schema must be verified there.
+
+---
+
 Digital read outputs in msg.payload use numeric 1 (on) and 0 (off), including coils (FC1), discrete inputs (FC2), and individual register bits. The raw Modbus response retains its original representation. Coil writes still accept true/false and 1/0.
 
 # Simple bus settings and range scaling — 3.2.4
@@ -28,7 +63,7 @@ This release retains the pinned serial dependencies and supports Node.js 14 synt
 - One worker owns each bus. Closing a runtime node cancels only its own work.
 - Open, request, diagnostic and close operations have deadlines. A port whose close cannot be confirmed stays quarantined rather than acquiring a second owner.
 - Serial errors are handled. Dead connections are retired before reopening.
-- Writes use FIFO order. Queue overflow, expiry and superseded polls return explicit errors and complete once.
+- Reads and writes use FIFO order. Queue overflow returns an explicit error and completes once.
 - Every accepted request is retained in FIFO order, including repeated reads from the same node. Requests are not coalesced or expired while waiting.
 - Each queued request gets the configured timeout retry count before moving to the next. There is no offline cooldown or skipped polling.
 - After a communication error, the bus waits for a quiet period and flushes stale buffered data. Automatic quiet time is the response timeout on RF and 100ms on RS485. Late RF frames outside that interval remain a protocol limitation: Modbus RTU read replies carry no register address or transaction ID.
@@ -37,7 +72,7 @@ This release retains the pinned serial dependencies and supports Node.js 14 synt
 
 No additional bus settings are required. Recovery timing is automatic: the response timeout on RF and 100ms on RS485.
 
-Failures still emit msg.modbus.ok=false and a failure payload. msg.modbus.code identifies queue, offline and transport conditions; done(error) also enables Node-RED Catch handling. Intentional node/bus shutdown settles callbacks without emitting from closed nodes. No retry can guarantee a timed-out write was not applied at the device: retain an appropriate retry setting for the PLC command semantics.
+Failures emit msg.modbus.ok=false and the fault payload documented above. msg.modbus.code identifies queue, offline and transport conditions; done(error) also enables Node-RED Catch handling. Intentional node/bus shutdown settles callbacks without emitting from closed nodes. No retry can guarantee a timed-out write was not applied at the device: retain an appropriate retry setting for the PLC command semantics.
 
 Validated on a Passport with Raspbian Buster, Node.js 14.21.3, native serial dependencies and two physical RF Makos. Node.js 16 has not been separately executed. No dependency upgrade is required.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithtek-mako-rf",
-  "version": "3.2.4",
+  "version": "3.3.2",
   "description": "Smithtek dedicated node for communicating with the Mako PLC over RS485 or RF",
   "keywords": [
     "node-red",

package/smithtek-mako-rf.html

@@ -369,6 +369,7 @@
     color: "#B9B6B8",
     defaults: {
       name: { value: "" },
+      prefix: { value: "" },
       bus: { type: "smithtek-mako-rf-bus", required: true },
 
       mode: { value: "read" },
@@ -385,7 +386,8 @@
       items: { value: [ defaultItemRow() ], validate: validDecoderItems }
     },
     inputs: 1,
-    outputs: 1,
+    outputs: 2,
+    outputLabels: ["Data / alarm", "Debug"],
     icon: "bridge.svg",
     label: function () { return this.name || "Smithtek Mako RF"; },
 
@@ -547,6 +549,12 @@
     <input type="text" id="node-input-name" placeholder="">
   </div>
 
+  <div class="form-row">
+    <label for="node-input-prefix"><i class="fa fa-tag"></i> Prefix</label>
+    <input type="text" id="node-input-prefix" placeholder="e.g. b1">
+    <div class="form-tips">Added before each decoder name with a space: b1 + Pressure becomes b1 Pressure. Leave blank to keep existing names.</div>
+  </div>
+
   <div class="form-row">
     <label for="node-input-bus"><i class="fa fa-sitemap"></i> Bus</label>
     <input type="text" id="node-input-bus" style="width: 25%;">
@@ -673,5 +681,11 @@ Smithtek Mako RF / RS485.
 Read mode outputs decoded JSON in msg.payload using the Decoder map rows. Digital points (coils, discrete inputs and register bits) output numeric 1 for on and 0 for off.
 Raw modbus response is kept in msg.modbus.raw.
 
+Prefix adds text and one space before each decoder name. Leave blank to preserve names.
+
+Output 1 (Data / alarm) carries successful readings and write responses, or the friendly named fault JSON on failure. Output 2 (Debug) carries technical error details: ok, error, code and req. Connect it to a local Debug node or leave it disconnected. Node-RED error logs and Catch handling remain enabled. A timeout alarm is sent after one poll exhausts its retries (retries 2 means 3 attempts), not after multiple bad polls. Permanent Modbus exceptions report immediately. Each failed poll emits one alarm and one debug message.
+
+Failed requests output a named numeric alarm on output 1, for example {"b1 RF ID2 Not communicating — check power/RF; disable if out of service":1}. Details remain in msg.modbus, including ok, code, error and fault. Only final failures are reported; a successful retry or intentional shutdown does not emit an alarm. Successful reads resume normal data; no automatic alarm-clear value is sent.
+
 Each numeric decoder row starts compact with None (unchanged). Choose Math or Range to show the inline settings and enable scaling. Selecting None hides both controls and disables both calculations, while retaining the entered settings. Range maps input low/high to output low/high using a straight line; for example 4–20 maps to 0–100, with 12 mapping to 50. Use raw register endpoints, not assumed electrical units. Input endpoints must differ. Reversed ranges and negative/decimal endpoints are supported. Clamp optionally limits output to the configured range. Existing rows without a scaling mode retain their Math expression.
 </script>

package/smithtek-mako-rf.js

@@ -78,7 +78,7 @@ function toNum(v, fallback) {
   }
 
   // Nested property setter using delimiter "=>"
-  function setObjectProperty(obj, path, value, delimiter) {
+  function setObjectProperty(obj, path, value, delimiter, prefix) {
     if (!path || typeof path !== "string") {
       obj[path] = value;
       return;
@@ -91,6 +91,9 @@ function toNum(v, fallback) {
     if (!parts.length) return;
 
     if (parts.some(k => ["__proto__","prototype","constructor"].includes(k))) throw new Error("Invalid decoder property path");
+    // Prefix is literal text, even if it contains the nesting delimiter.
+    const labelPrefix = String(prefix == null ? '' : prefix).trim();
+    if (labelPrefix) parts[0] = labelPrefix + ' ' + parts[0];
     let ref = obj;
     for (let i = 0; i < parts.length - 1; i++) {
       const k = parts[i];
@@ -252,7 +255,7 @@ function toNum(v, fallback) {
     }
   }
 
-  function decodeWithItems(regArray, items) {
+  function decodeWithItems(regArray, items, prefix) {
     const decoded = {};
     if (!Array.isArray(regArray) || !Array.isArray(items) || !items.length) return decoded;
 
@@ -305,7 +308,7 @@ function toNum(v, fallback) {
       // Digital points are numeric at the output boundary. Keep the internal
       // boolean until here so saved math/masks cannot change a bit into another value.
       if (typeof val === 'boolean') val = val ? 1 : 0;
-      setObjectProperty(decoded, name, val, "=>");
+      setObjectProperty(decoded, name, val, "=>", prefix);
     }
 
     return decoded;
@@ -370,6 +373,45 @@ function toNum(v, fallback) {
     return req;
   }
 
+  function faultInfo(err, config, cfg, req) {
+    const code = err.code || (err.modbusCode ? 'MODBUS_EXCEPTION_'+err.modbusCode : 'ECOMM');
+    const message = String(err.message || err);
+    const labels = {ECONFIG:'Configuration error',EDECODE:'Decode error',EQUEUEFULL:'Queue full',
+      EQUEUEEXPIRED:'Queue expired',EOFFLINE:'Offline',EPORTBUSY:'Port busy',ECLOSE:'Serial close failure',
+      EDISCONNECT:'Serial disconnected',EIO:'Serial error',ENOENT:'Serial port unavailable',EACCES:'Serial permission denied'};
+    let reason = labels[code];
+    if (!reason && err.modbusCode) reason = 'Modbus exception '+err.modbusCode;
+    if (!reason && (code === 'ETIMEDOUT' || /timed?\s*out|timeout/i.test(message))) reason = 'Timeout';
+    if (!reason && code === 'EDEADLINE') reason = /request/i.test(message) ? 'Timeout' : 'Operation deadline';
+    if (!reason && /crc/i.test(message)) reason = 'CRC error';
+    if (!reason) reason = 'Communication error';
+    const port = cfg && cfg.serialPort;
+    const channel = {'/dev/ttyAMA2':'RF','/dev/ttyAMA0':'RS485-1','/dev/ttyAMA1':'RS485-2'}[port] || (cfg && cfg.busName) || 'Bus';
+    const prefix = String(config.prefix == null ? '' : config.prefix).trim();
+    const label = prefix || String(config.name || '').trim();
+    const unitid = req ? req.unitid : (config.unitid == null ? 1 : config.unitid);
+    const link = channel === 'RF' ? 'RF' : /^RS485/.test(channel) ? 'RS485 wiring' : 'connection';
+    const advice = {
+      'Timeout':'Not communicating — check power/'+link+'; disable if out of service',
+      'Configuration error':'Setup error — check node settings',
+      'Decode error':'Data format error — check register map/scaling',
+      'Queue full':'Polling overloaded — reduce polling rate',
+      'Queue expired':'Polling delayed — reduce polling rate',
+      'Offline':'Polling paused — check device availability',
+      'Port busy':'Bus in use — check duplicate bus settings',
+      'Serial close failure':'Gateway port fault — check bus connection',
+      'Serial disconnected':'Gateway disconnected — check bus connection',
+      'Serial error':'Gateway port fault — check bus connection',
+      'Serial port unavailable':'Gateway port missing — check bus settings',
+      'Serial permission denied':'Gateway port blocked — check access permissions',
+      'Operation deadline':'Gateway operation stalled — check bus connection',
+      'CRC error':'Invalid reply — check '+link+' link'
+    };
+    const summary = advice[reason] || (err.modbusCode ? 'Request rejected — check function/register settings' : 'Communication fault — check power/'+link);
+    const key = [label,channel,'ID'+unitid,summary].filter(Boolean).join(' ');
+    return {key,code,message,reason,summary,channel,unitid,prefix,node:config.name || '',timestamp:new Date().toISOString()};
+  }
+
   function SmithtekMakoRfNode(config) {
     RED.nodes.createNode(this,config);
     const node = this;
@@ -383,23 +425,41 @@ function toNum(v, fallback) {
       const cfg = RED.nodes.getNode(config.bus);
       let req;
       const complete = (err,res) => {
+        let failure = err;
         try {
-          if(node._makoClosed || (err && err.code === 'ECANCELLED')) return;
-          msg.modbus = {ok:!err,bus:cfg && cfg.busName,req};
-          if(err) {
-            msg.modbus.error = err.message || String(err);
-            msg.modbus.code = err.code || (err.modbusCode ? 'MODBUS_EXCEPTION_'+err.modbusCode : 'ECOMM');
-            msg.payload = {ok:false,error:msg.modbus.error,req};
-            node.status({fill:err.code === 'EOFFLINE' ? 'yellow' : 'red',shape:'ring',text:msg.modbus.error});
+          if(node._makoClosed || (failure && failure.code === 'ECANCELLED')) return;
+          let payload;
+          if (!failure) {
+            try {
+              payload = req.mode === 'read' && res && Array.isArray(res.data) ? decodeWithItems(res.data,config.items || [],config.prefix) : res;
+            } catch (decodeError) {
+              failure = decodeError;
+              failure.code = 'EDECODE';
+            }
+          }
+          msg.modbus = {ok:!failure,bus:cfg && cfg.busName,req};
+          if(res) msg.modbus.raw = res;
+          if(failure) {
+            const fault = faultInfo(failure,config,cfg,req);
+            msg.modbus.error = fault.message;
+            msg.modbus.code = fault.code;
+            msg.modbus.fault = fault;
+            msg.payload = {[fault.key]:1};
+            node.status({fill:failure.code === 'EOFFLINE' ? 'yellow' : 'red',shape:'ring',text:fault.message});
           } else {
-            msg.modbus.raw = res;
-            msg.payload = req.mode === 'read' && res && Array.isArray(res.data) ? decodeWithItems(res.data,config.items || []) : res;
+            msg.payload = payload;
             if(msg._makoRssi != null) {msg.payload[sanitizeKey(node.name || config.name || cfg.busName)+'_rssi_dbm']=msg._makoRssi;delete msg._makoRssi;}
             node.status({fill:'green',shape:'dot',text:'ok uid'+req.unitid});
           }
-          send(msg);
+          // Cloud output always carries either decoded data or the friendly alarm.
+          // The second output contains a separate technical error payload.
+          const debugMsg = failure ? Object.assign({}, msg, {
+            payload: {ok:false,error:msg.modbus.error,code:msg.modbus.code,req},
+            modbus: Object.assign({}, msg.modbus)
+          }) : null;
+          send([msg, debugMsg]);
         } catch(e) {completeOnce(e);return;}
-        finally {completeOnce(err || undefined);}
+        finally {completeOnce(failure || undefined);}
       };
       try {
         req=requestFor(config,msg);
@@ -417,7 +477,7 @@ function toNum(v, fallback) {
             catch(e){if(e.code === 'ECANCELLED')throw e;msg.rssi_error=e.message;}
           }
         }});
-      }catch(err){complete(err);}
+      }catch(err){if(!err.code) err.code='ECONFIG';complete(err);}
     });
     node.on('close',(_removed,done)=>{
       node._makoClosed=true;