smithtek-mako-rf 0.0.1

package/README.md

@@ -0,0 +1,190 @@
+
+**Dedicated PassPort Node that reads and parses the Mako over RF or RS485**
+
+
+
+
+
+**Installation**
+Install using the `NodeRED palette manager`
+
+**Smithtek Mako RF**  
+RS-485 / LoRa RF Modbus RTU Master for Mako PLC devices.
+
+This node combines Modbus polling, retry logic, queue management and structured decoding into a single industrial block.
+
+---
+
+## Bus Configuration
+
+Select the communication channel:
+
+- **RS485-1** → /dev/ttyAMA0  
+- **RS485-2** → /dev/ttyAMA1  
+- **RF** → Long range LoRa radio link  
+
+When RF is selected, serial parameters are automatically managed.
+
+Timeout, Retries and Gap are configured in **seconds**.
+
+---
+
+## Mode
+
+### Read
+Polls registers from the remote Mako and outputs structured JSON.
+
+### Write
+Sends values to the remote device using:
+
+- FC5 – Write Single Coil  
+- FC6 – Write Single Register  
+- FC15 – Write Multiple Coils  
+- FC16 – Write Multiple Registers  
+
+Values can come from `msg.payload` or be fixed in the node configuration.
+
+---
+
+## Device ID
+
+The Modbus Unit ID of the remote Mako (1–247).  
+Must match the ID configured in the target device.
+
+---
+
+## Function Code
+
+Must match the table type configured in your V-NET program:
+
+- Read Coils  
+- Read Digital Inputs  
+- Read Holding Registers  
+- Read Input Registers  
+
+---
+
+## Address
+
+Starting Modbus register address.  
+Must align exactly with the Modbus table built in your Mako V-NET program.
+
+---
+
+## Quantity
+
+Total number of registers to read.
+
+- 16 bit value = 1 register  
+- 32 bit value = 2 registers  
+
+**Example:**  
+3 × 32 bit floats = Quantity 6  
+
+Quantity must cover all registers defined in your decoder map.
+
+---
+
+## Decoder Map
+
+Build the register table in the exact same order as your Mako V-NET Modbus table.
+
+Each row defines how raw Modbus data is converted into structured JSON.
+
+### Name
+Becomes the output key in `msg.payload`.  
+Nested paths are supported using: `pump=>status`
+
+### Register Data Type
+
+- 16 bit integer  
+- 16 bit unsigned  
+- 32 bit integer  
+- 32 bit unsigned  
+- 32 bit float  
+- Digital to unsigned binary encoder  
+
+### Offset (regs)
+
+Offset is configured in registers.
+
+Automatic stepping behaviour:
+
+- 16 bit types increase by 1 register  
+- 32 bit types increase by 2 registers  
+- Digital encoder increases bit number from 0–15 before moving to the next register  
+
+Offsets must match your V-NET Modbus table layout exactly.
+
+---
+
+## Digital to Unsigned Binary Encoder
+
+Used when one 16 bit register contains multiple digital states.
+
+The Bit column becomes active.  
+Bit automatically increments when adding rows.  
+After Bit 15, the next row moves to the next register.
+
+---
+
+## Scale
+
+Optional value transformation.
+
+Examples:
+
+- `0.1` → multiply by 0.1  
+- `>100`  
+- `<50`  
+- `==1`  
+- `<<2`  
+- `>>1`  
+
+If blank, raw decoded value is used.
+
+---
+
+## Output Behaviour
+
+### Successful Read
+
+- `msg.payload` → Decoded structured JSON  
+- `msg.modbus.raw` → Raw Modbus response  
+- `msg.modbus.req` → Request metadata  
+
+### Successful Write
+
+- `msg.payload` → Device confirmation response  
+- `msg.modbus.raw` → Raw Modbus confirmation  
+
+The write response is the actual Modbus confirmation returned by the remote device.
+
+---
+
+## Industrial Behaviour
+
+- Single shared bus queue per channel  
+- One request processed at a time  
+- Timeout handled in seconds  
+- Configurable retry attempts  
+- Optional inter-request gap  
+
+Designed for stable Modbus RTU polling over RS485 or long-range RF links.
+
+
+
+# License
+Copyright (c) 2023 www.smithtek.com.au Licenced under the terms of the GPLv3
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL DAMIEN CLARK BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+www.smithtek.com.au

package/common-functions.js

@@ -0,0 +1,190 @@
+
+/**
+* number2bcd -> takes a bcd number and returns the corresponding decimal value
+* @param {Number} number BCD number to convert
+* @param {*} digits no of digits (default 4)
+*/
+const bcd2number = function (number, digits = 4) {
+    let loByte = (number & 0x00ff);
+    let hiByte = (number >> 8) & 0x00ff;
+    let n = 0;
+    n += (loByte & 0x0F) * 1;
+    if (digits < 2) return n;
+    n += ((loByte >> 4) & 0x0F) * 10;
+    if (digits < 3) return n;
+    n += (hiByte & 0x0F) * 100;
+    if (digits < 4) return n;
+    n += ((hiByte >> 4) & 0x0F) * 1000;
+    return n;
+}
+
+
+/**
+    * number2bcd -> takes a number and returns the corresponding BCD value.
+    * @param {Number} number number to convert to bcd
+    * @param {Number} [digits] no of digits (default 4)
+    * @returns {Buffer} nodejs buffer 
+    */
+const number2bcd = function (number, digits) {
+    var s = digits || 4; //default value: 4
+    var n = 0;
+
+    n = (number % 10);
+    number = (number / 10) | 0;
+    if (s < 2) return n;
+    n += (number % 10) << 4;
+    number = (number / 10) | 0;
+    if (s < 3) return n;
+    n += (number % 10) << 8;
+    number = (number / 10) | 0;
+    if (s < 4) return n;
+    n += (number % 10) << 12;
+    number = (number / 10) | 0;
+    return n;
+}
+
+function byteToBits(val) {
+    var bits = [];
+    for (let index = 0; index < 8; index++) {
+        const bit = getBit(val, index);
+        bits.push(bit);
+    }
+
+    return {
+        bits: bits,
+        bit0: bits[0],
+        bit1: bits[1],
+        bit2: bits[2],
+        bit3: bits[3],
+        bit4: bits[4],
+        bit5: bits[5],
+        bit6: bits[6],
+        bit7: bits[7],
+    }
+}
+function wordToBits(val) {
+    var bits = [];
+    for (let index = 0; index < 16; index++) {
+        const bit = getBit(val, index);
+        bits.push(bit);
+    }
+    return {
+        bits: bits,
+        bit0: bits[0],
+        bit1: bits[1],
+        bit2: bits[2],
+        bit3: bits[3],
+        bit4: bits[4],
+        bit5: bits[5],
+        bit6: bits[6],
+        bit7: bits[7],
+        bit8: bits[8],
+        bit9: bits[9],
+        bit10: bits[10],
+        bit11: bits[11],
+        bit12: bits[12],
+        bit13: bits[13],
+        bit14: bits[14],
+        bit15: bits[15],
+    }
+}
+
+//Get Bit
+function getBit(number, bitPosition) {
+    return (number & (1 << bitPosition)) === 0 ? 0 : 1;
+}
+//Set Bit            
+function setBit(number, bitPosition) {
+    return number | (1 << bitPosition);
+}
+//Clear Bit            
+function clearBit(number, bitPosition) {
+    const mask = ~(1 << bitPosition);
+    return number & mask;
+}
+//Update Bit            
+function updateBit(number, bitPosition, bitValue) {
+    const bitValueNormalized = bitValue ? 1 : 0;
+    const clearMask = ~(1 << bitPosition);
+    return (number & clearMask) | (bitValueNormalized << bitPosition);
+}
+function bitsToByte(bits) {
+    var byte = 0;
+    for (let index = 0; index < 8; index++) {
+        let bit = bits[index];
+        if (bit) byte = setBit(byte, index);
+    }
+    return byte;
+}
+function bitsToWord(val) {
+    var wd = 0;
+    for (let index = 0; index < 16; index++) {
+        let bit = val[index];
+        if (bit) wd = setBit(wd, index);
+    }
+    return wd;
+}
+
+const SWAPOPTS = ["swap16", "swap32", "swap64"];
+const TYPEOPTS = [
+    "int", "int8", "byte",
+    "uint", "uint8",
+    "int16", "int16le", "int16be", "uint16", "uint16le", "uint16be",
+    "int32", "int32le", "int32be", "uint32", "uint32le", "uint32be",
+    "bigint64", "bigint64le", "bigint64be", "biguint64", "biguint64le", "biguint64be",
+    "float", "floatle", "floatbe", "double", "doublele", "doublebe",
+    "8bit", "16bit", "16bitle", "16bitbe", "bool",
+    "bcd", "bcdle", "bcdbe",
+    "string", "hex", "ascii", "utf8", "utf-8", "utf16le", "ucs2", "latin1", "binary", "buffer"
+];
+
+/**
+ * helper function to set a nested property by path
+ * @param {*} obj - the object in which to set a properties value
+ * @param {string} path - the path to the property e.g. payload.value
+ * @param {*} val - the value to set in obj.path
+ */
+function setObjectProperty(obj, path, val, sep) {
+    sep = sep == null ? "." : sep;
+    const keys = path.split(sep);
+    const lastKey = keys.pop();
+    const lastObj = keys.reduce((obj, key) =>
+        obj[key] = obj[key] || {},
+        obj);
+    lastObj[lastKey] = val;
+}
+
+/**
+ * helper function to get a property by path
+ * @param {*} obj - the object in which to set a properties value
+ * @param {string} path - the path to the property e.g. payload.value
+ * @param {*} [sep] - the path property separator (defaults to `.`)
+ */
+function getObjectProperty(obj, path, sep) {
+    sep = sep == null ? "." : sep;
+    for (var i=0, path=path.split(sep), len=path.length; i<len; i++){
+        obj = obj[path[i]];
+    };
+    return obj;
+}
+
+function isNumber(n) {
+    if (n === "" || n === true || n === false) return false;
+    return !isNaN(parseFloat(n)) && isFinite(n);
+}
+
+exports.bcd2number = bcd2number;
+exports.number2bcd = number2bcd;
+exports.byteToBits = byteToBits;
+exports.wordToBits = wordToBits;
+exports.bitsToByte = bitsToByte;
+exports.bitsToWord = bitsToWord;
+exports.getBit = getBit;
+exports.setBit = setBit;
+exports.clearBit = clearBit;
+exports.updateBit = updateBit;
+exports.isNumber = isNumber;
+exports.setObjectProperty = setObjectProperty;
+exports.getObjectProperty = getObjectProperty;
+exports.SWAPOPTS = SWAPOPTS;
+exports.TYPEOPTS = TYPEOPTS;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "smithtek-mako-rf",
+  "version": "0.0.1",
+  "description": "Smithtek Mako RF: Modbus RTU (RS-485) over RF with shared bus queue, timeout seconds and retries.",
+  "keywords": [
+    "node-red",
+    "smithtek",
+    "modbus",
+    "rtu",
+    "rs485",
+    "lora"
+  ],
+  "license": "GPL-3.0-only",
+  "author": "Smithtek",
+  "homepage": "https://www.smithtek.com.au",
+  "dependencies": {
+    "modbus-serial": "^9.0.10"
+  },
+  "node-red": {
+    "nodes": {
+      "smithtek-mako-rf": "smithtek-mako-rf.js"
+    }
+  }
+}