smithtek-mako-rf 3.2.4 → 3.3.3

package/README.md

@@ -1,47 +1,3 @@
-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
-
-The bus editor retains the original timeout, retries, gap, maximum queue and RSSI controls. Queue age, coalescing, offline probe and recovery-quiet controls have been removed. Any saved values for those removed controls are ignored. All accepted requests wait in FIFO order; recovery timing is managed internally. The Range option in the decoder table remains available.
-
-Each numeric decoder row has a compact Scaling dropdown: None (unchanged), Math (+ − × ÷), or Range (input → output). New rows start at None, with all calculation fields hidden. Math and Range settings appear beside the dropdown on the same line. Range shows In low, In high, Out low, Out high and Clamp side by side. Every decoder entry stays on one line; narrow dialogs scroll horizontally. Selecting None hides the fields and disables both calculations, retaining the entered settings for reuse. Existing configured Math and Range rows keep their active mode.
-
-For Range, enter Input low, Input high, Output low and Output high. For example:
-
-| Input low | Input high | Output low | Output high | Result at input 12 |
-|---|---|---|---|---|
-| 4 | 20 | 0 | 100 | 50 |
-
-The input endpoints must match the values reported in Modbus registers. If a sensor reports 4000–20000 instead of 4–20, enter 4000 and 20000. No PLC calculation or extra Function node is needed.
-
-Range scaling uses outputLow + (value - inputLow) * (outputHigh - outputLow) / (inputHigh - inputLow). It operates on the decoded numeric value after any existing integer mask. Range replaces the Math expression, retaining that expression for switching back. Negative, decimal and reversed ranges are supported. Equal input endpoints and invalid/nonfinite values are rejected. Digital/boolean rows cannot use Range mode.
-
-Values outside the input span continue along the same line unless Clamp to output range is checked. For example, 0 mA maps to -25 for a 4–20 to 0–100 range; with Clamp it maps to 0. Floating-point results are not automatically rounded.
-
-Existing rows without a scaling mode continue using Math. Raw Modbus data remains available in msg.modbus.raw. All FIFO queue and recovery behaviour from 3.1.2 is retained, and dependencies are unchanged.
-
----
-# Reliability update 3.1.2
-
-This release retains the pinned serial dependencies and supports Node.js 14 syntax.
-
-- 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.
-- 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.
-- RSSI queries verify their checksum, isolate diagnostic bytes, settle on cancellation and retain the serial connection after success.
-- Invalid addresses, quantities and write values are rejected before transmission. Signed scale expressions add/subtract, and incomplete 32-bit values are rejected.
-
-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.
-
-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.
-
----
 **Installation**
 Install using the `NodeRED palette manager`
 
@@ -159,6 +115,12 @@ Each row defines how raw Modbus data is converted into structured JSON.
 ### Name
 Becomes the output key in `msg.payload`.  The name could be your sensor name like "level sensor" or " thermal trip" " pump control" choose a name that suits your SCADA scheme.
 
+### Prefix
+
+The Prefix field applies to every name in the decoder table. Enter `b1` and a row named `Pressure` becomes `b1 Pressure` in `msg.payload`, with a space between the prefix and name.
+
+Copy the node and change only the prefix to reuse the same table for another asset. Leave it blank to use the table names as entered.
+
 ### Register Data Type
 
 - 16 bit integer  
@@ -194,6 +156,16 @@ After Bit 15, the next row moves to the next register.
 Optional value transformation applied after the Modbus register is read.
 The Scale field lets you adjust raw register data into meaningful engineering values without needing extra function nodes. Think of it as lightweight post-processing built directly into the driver.
 
+Choose a scaling mode for each row:
+
+- **None** leaves the value unchanged.
+- **Math** applies an operator and number, such as `/100` or `+5`.
+- **Range** maps input low/high values to output low/high values.
+
+All controls stay on the same row. Selecting None disables the calculation while keeping the entered settings for reuse.
+
+### Math
+
 You can apply the following operators:
 
 - Addition +
@@ -223,11 +195,48 @@ Example:
 
 If you want to multiple your modbus value by 10 you would put "* 10"   without the quotes and use a space between the number and the match function.
 
+### Range — 4–20 mA Scaling
+
+Select **Range** and enter **In low**, **In high**, **Out low** and **Out high**. This converts a sensor reading into engineering units in the Passport without a separate Function node or a calculation in the Mako.
+
+For a 4–20 mA signal representing 0–100%:
+
+| In low | In high | Out low | Out high |
+|---|---|---|---|
+| 4 | 20 | 0 | 100 |
+
+A reading of 4 becomes 0, 12 becomes 50, and 20 becomes 100.
+
+Use the values actually reported by the register. If it reports 4000–20000, enter 4000 and 20000 as the input limits instead of 4 and 20.
+
+Tick **Clamp** to keep the result within the output limits. Otherwise, values outside the input limits continue scaling beyond the output range. Input low and high must differ. Negative, decimal and reversed ranges are supported. Range applies to numeric values and replaces the Math calculation for that row.
+
 This allows you to convert raw Modbus numbers into readable, usable data straight from the node — reducing additional processing and keeping flows clean and simple.
 
 ---
 
-## Output Behaviour
+## Output Behaviour
+
+### Output Pins
+
+- **Top pin — Data / alarm:** sends parsed Modbus readings or write confirmations. If a request fails, it sends the friendly fault JSON for the cloud instead.
+- **Bottom pin — Debug:** sends technical error details for a local Debug node. Leave it disconnected if these details are not needed. Successful requests send nothing from this pin.
+
+### Fault Messages
+
+Example payload from the top pin:
+
+```json
+{"b1 RF ID1 Not communicating — check power/RF; disable if out of service":1}
+```
+
+The fault name identifies the prefix, bus and device ID, followed by an operator message. If the prefix is blank, the node Name is used. Other problems, such as an unsupported register or invalid settings, receive a message appropriate to that fault.
+
+A timeout fault is sent after one poll exhausts its retries: retries set to 0 means one failed attempt; retries set to 2 means three failed attempts. A successful retry sends normal data only. An unsupported-register error is reported immediately because retrying cannot correct the address. Each failed poll sends a fault; a redeploy cancellation does not.
+
+The bottom pin carries `msg.payload.ok`, `msg.payload.error`, `msg.payload.code` and `msg.payload.req` for troubleshooting. Technical details are also available in `msg.modbus`. Node-RED error logs and Catch handling remain available.
+
+When communication succeeds again, the top pin resumes normal readings. No automatic zero/clear alarm is sent.
 
 ### Successful Read
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithtek-mako-rf",
-  "version": "3.2.4",
+  "version": "3.3.3",
   "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;