smithtek-mako-rf 3.3.4 → 3.4.1

package/README.md

@@ -1,602 +1,225 @@
-**Installation**
-Install using the `NodeRED palette manager`
-
-
-** Smithtek Mako RF Nodes**
-
-The Smithtek Mako RF nodes are designed specifically for the Mako PLC, while remaining fully compatible with other Modbus RTU devices connected over RS485.
-
-They support communication to one or multiple devices across hard-wired RS485 channels or long-range RF, all from a single, unified node. Whether you’re polling a single PLC or managing a full remote site, the node handles device sequencing and bus control automatically.
-
-Built for industrial environments, the node includes integrated queue management, retry handling, timeout control, gap spacing, and automatic reconnection logic. These features provide stable, predictable polling without requiring complex flow logic.
-
-The Smithtek Mako RF node effectively replaces the traditional Modbus contrib nodes and the separate Mako decoder node, combining communication and decoding into a single streamlined tool.
-
-One node. One inject. Full control.
-
-
-
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/Smithtek%20Mako%20RF%20Nodes%20page%201.png?raw=true)
-
-The Smithtek Mako RF node operates in two modes:
-Read Mode – Poll slave devices and retrieve data from registers.
-Write Mode – Send commands or values to slave devices.
-The PassPort Gateway provides three communication channels:
-RS485-1
-RS485-2
-Long Range RF
-You can assign any node to any bus channel, allowing wired and RF devices to operate independently while the node manages sequencing and communication control in the background.
-
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/Smithtek%20Mako%20RF%20Nodes%20page%202.png?raw=true)
----
-
-## 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.
-
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/Smithtek%20Mako%20RF%20Nodes%20page%203.png?raw=true)
----
-
-
-
-
-### 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.
-
-Polls registers from the remote Mako and outputs structured JSON.
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/Smithtek%20Mako%20RF%20Nodes%20page%204.png?raw=true)
-
-
----
-
-## 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`.  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  
-- 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 applied after the Modbus register is read.
-
-Decoded numeric readings are rounded to a maximum of six decimal places after Math or Range scaling. Values remain numbers, without added trailing zeros. Very small values may round to zero. Raw data in `msg.modbus.raw` is unchanged.
-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 +
-Adds a number to the value.
-Example:
-+10 → adds 10 to the parsed value
-
-- Subtraction -
-Subtracts a number from the value.
-Example:
--5 → subtracts 5 from the parsed value
-
-- Multiply *
-Multiplies the value by a number.
-Example:
-*10 → multiplies the parsed value by 10
-
-- Divide /
-Divides the value by a number.
-Example:
-/100 → divides the parsed value by 100
-
-- Modulus %
-Returns the remainder after division.
-Example:
-%10 → returns remainder when value is divided by 10
-
-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 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
-
-- `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.
-
----
-## Decoder Mapping V-NET v NodeRED
-
-
-The Decoder Map in the Mako RF node must match your V-NET Modbus table exactly.
-Every register must appear in the same order in both tools.
-If the order does not match, the decoded values will be incorrect.
-Think of it as a mirror:
-V-NET defines the Modbus table.
-The Node-RED Decoder reads it back in the exact same sequence.
-Register type, size (16-bit or 32-bit), and position must align between both.
-Digital to Unsigned Binary Encoder
-When using Digital to Unsigned Binary Encoder in V-NET:
-A single 16-bit register holds up to 16 digital values
-Each digital output occupies one bit (0–15)
-In the Node-RED Decoder Map, you select the same register type
-Then assign the correct bit number for each digital
-
-Example:
-
-Bit 0 = Digital 1
-Bit 1 = Digital 2
-Up to Bit 15
-This allows one register to represent 16 individual digital states.
-
-Best Practice
-It is recommended to place Digital to Unsigned registers at the end of your Modbus table.
-This gives you flexibility to:
-Add new digital points later
-Adjust bit assignments
-Expand without shifting existing analog register positions
-Keeping digitals grouped at the end prevents breaking your existing register structure in future revisions.
-
-Correct mapping ensures clean decoding, predictable data, and stable long-term expansion.
-
-## Example Configuration reading registers ##
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/Decoder%20Map.png?raw=true)
-
-
-
-In the screen shot example above is a typical reading the Mako map/\ ,
-
-The V-NET screenshot shows on the left shows.
-
-Device ID: 1
-Start register: 0
-Modbus table type: Input Registers
-2 × 32-bit floats
-2 × 16-bit unsigned registers
-
-The second 16-bit unsigned register is used as a Digital to Unsigned Binary Encoder, allowing up to 16 digital values to be packed into a single register.
-On the Node-RED Mako RF node properties, you can see these settings match exactly:
-Device ID is set to 1
-Function Code matches Input Registers
-Start address is 0
-Quantity shows 16, this is higher than needed but a good habbit to do as it ensurs you dont miss a register. If we wanted to match it completely we would have this set to 6 length!
-
-Decoder Map mirrors the exact register order and types from V-NET
-In this example, RF is used as the communication interface on both the Mako PLC and the PassPort Gateway.
-Once deployed, each poll from the PassPort will correctly read the Mako Modbus table.
-The decoded data will then be output from the node, ready for use in dashboards, logic, or cloud transmission.
-
----
-## Example Configuration writing a single coil register ##
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/decoder%20write%20to%20a%20coil.png?raw=true)
-
-In this example, an additional coil has been added to the V-NET Modbus map.
-The Node-RED Mako RF node is now set to Write mode, and the settings match the V-NET configuration:
-Device ID matches the Mako
-Function Code matches the coil type
-Address matches the coil register in V-NET
-Communication channel remains the same (RF or RS485)
-When triggered with an inject node:
-If using msg.payload, the value (true/false) will be written directly to the selected coil.
-If using Fixed, the configured value will be sent on every inject.
-Once deployed, each trigger will send a write command to the Mako, updating the coil state in real time.
-
----
-## Example Configuration writing a single holding register ##
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/Decoder%20writing%20a%20single%20register.png?raw=true)
-
-In this example, a Holding Register has been added in the V-NET Modbus map at address 0.
-The Node-RED Mako RF node is set to Write mode, configured as:
-Device ID matches the Mako
-Function Code set to Write Single Register (FC6)
-Address set to 0 to match V-NET
-Communication channel matches the system (RF or RS485)
-When triggered:
-From msg.payload – the numeric value in the payload is written directly to the holding register.
-Fixed mode – the configured value is written on every inject.
-Once deployed, each inject sends the write command to the Mako, updating the holding register immediately. The value is then available inside the V-NET program just like any other mapped register.
-
-
----
-## Node Status ##
-
-Each Mako RF node shows a live status under the node so you can see what it’s doing without opening debug panels. This is especially useful when polling multiple devices, troubleshooting timeouts, or confirming that queues are being processed correctly.
-
-What you’ll see
-
-`Idle / waiting`
-No active request is being processed. The node is ready for the next poll.
-
-`Polling (in progress)`
-Blue dot status while a request is being sent and a reply is expected.
-Typical text includes the bus name, function code, unit id, and address, for example:
-RF: fc4 uid1 @0 (try 1/3)
-
-`Success (response received)`
-Green dot status when the device responded correctly.
-Example:
-RF: ok fc4 uid1
-
-`Failure / timeout / comms fault`
-Red ring status when a request fails after retries or times out.
-Example:
-RF: fail fc4 uid1
-The reason will also be available in msg.modbus.error on the output message.
-
-`Queue activity (multiple devices)`
-When multiple polls are triggered together, the status will “walk” through each device one at a time as the queue processes. This is normal and confirms the node is sequencing requests rather than blasting the bus.
-
-``Notes``
-
-The (try x/y) indicator shows retry behaviour. For example try 2/3 means the first attempt failed and it is retrying.
-
-If you see repeated red failures on a single device, it usually points to ID/address mismatch, wiring/RF link quality, or the poll rate being too aggressive for the link.
-
-
----
-## RSSI (RF Signal Strength Diagnostic) ##
-
-RSSI (Received Signal Strength Indicator) provides a live measurement of the RF signal strength between the PassPort and the remote Mako device when using the RF channel.
-
-When enabled, the node performs an additional request to the LoRa module after each successful Modbus read. The returned signal strength (in dBm) is then appended to the output payload.
-
-This allows you to:
-- Verify RF link quality during installation
-- Diagnose weak or marginal radio paths
-- Confirm antenna alignment and placement
-- Monitor signal health during maintenance
-How to Enable
-- Open the Bus configuration node (smithtek-mako-rf-bus).
-- Select the RF channel.
-- Tick the RSSI checkbox.
-- Deploy.
-- To disable RSSI, simply untick the checkbox and deploy again.
-
-
-## RSSI Output Behaviour (msg.payload) ##
-
-When enabled:
-RSSI is appended to the normal decoded payload (msg.payload).
-It is added to the same JSON object generated by the Decoder map.
-The property name is automatically derived from the node block name.
-
-`RSSI Guard & Timeout Settings`
-
-The RSSI feature includes two adjustable timing parameters to fine-tune how the LoRa module is queried after a Modbus poll.
-In most installations.
-`The default values (10ms guard / 100ms timeout) are ideal and do not require adjustment.
-
-`RSSI Guard (ms)`
-
-The RSSI Guard is the delay between the completed Modbus response and the RSSI request being sent to the LoRa module.
-- This short pause ensures:
-- The Modbus transaction has fully completed
-- The UART buffer has settled
-- The RF module is ready to respond cleanly
-
-Typical range: 5–10ms
-Default: 10ms
-
-Lower values may work, but 10ms provides stable behaviour across most installations.
-
-`RSSI Timeout (ms)`
-
-The RSSI Timeout defines how long the system will wait for the LoRa module to respond with the RSSI value before aborting the request.
-Default: 100ms
-
-This is usually more than sufficient. Increasing the timeout:
-Does not improve signal strength
-Only increases the wait time if the module does not respond
-The timeout should only be increased if diagnosing unusual behaviour on a slow or noisy link.
-
-## RSSI Practical Guidance ##
-
-- Leave both values at default unless diagnosing an issue.
-- Use RSSI primarily during install or maintenance.
-- If RSSI is enabled permanently, keep guard low and timeout reasonable to avoid unnecessary bus slowdown.
-
-In short, the defaults are tuned for real-world PassPort + Mako RF deployments and will suit almost every scenario.
-
-![SmithTek Control](https://github.com/smithtekIOT/ArtWork/blob/master/RSSI%20switch.png?raw=true)
-
-
----
-## Polling Tips – Long Range RF ##
-
-RF polling is different to hard-wired RS485. Even though it still looks like Modbus, the request and reply must travel through the radio link and be processed at both ends. That adds “time of flight” and a bit of overhead, so the fastest possible poll rate is always slower than RS485.
-
-On the PassPort, the RF channel hides baud/parity/stop settings because the radio link is handled internally. What you control instead is the pacing: timeout, retries, gap, and your inject interval.
-
-``What slows RF down``
-
-- Air link latency (packetising + radio turnaround)
-- Retries when the link is marginal
-- Bigger register reads (more bytes to move)
-- Polling too frequently, causing requests to stack up
-- Best practice for multiple Makos
-- Polling should be treated as a “cycle”: each device gets a turn, one at a time.
-
-Choose an inject interval that allows the whole device list to complete without building a backlog.
-If you trigger multiple devices at once (single inject feeding multiple RF nodes), the queue will serialize them.
-
-Cycle time rule (use this in your markdown)
-
-`Cycle time ≈ (N × (typical RF transaction time + gap_s)), plus a bit of margin.`
-
-``Where:``
-- N = number of RF devices
-- typical RF transaction time = how long one poll normally takes (including reply)
-- gap_s = the deliberate spacing you set between requests
-
-## Practical tuning tips ##
-
-- Start conservative: increase speed only after you’ve proven stability.
-
-- If you see timeouts, the first fix is usually: slow the cycle down (longer inject interval), not bigger timeouts.
-
-- Keep read sizes sensible. Large reads are fine, but they raise transaction time, so the cycle must be longer.
-- For RF, it’s usually better to have one inject per site (simple) but set the inject interval long enough that the queue clears every cycle.
-
-- If you want “no backlog ever”, do not inject faster than the cycle time, otherwise requests will pile up behind the queue and devices will start timing out.
----
-
-## RF Polling Guide (≈100 Bytes Per Device) ##
-
-| RF Devices | Typical Per-Device Time (s) | Recommended Gap (s) | Safe Cycle Time (s) | Recommended Inject Interval |
-|------------|----------------------------|---------------------|---------------------|-----------------------------|
-| 1          | 1.5                        | 0.5–1.0             | ~2–3                | 3 seconds                   |
-| 2          | 1.5                        | 0.5–1.0             | ~4–5                | 6 seconds                   |
-| 3          | 1.5                        | 0.5–1.0             | ~6–7                | 8–10 seconds                |
-| 4          | 1.5                        | 0.5–1.0             | ~8–10               | 12 seconds                  |
-| 5          | 1.5                        | 0.5–1.0             | ~10–12              | 15 seconds                  |
-| 6          | 1.5                        | 0.5–1.0             | ~12–15              | 18 seconds                  |
-| 7          | 1.5                        | 0.5–1.0             | ~15–18              | 20 seconds                  |
-| 8          | 1.5                        | 0.5–1.0             | ~18–21              | 25 seconds                  |
-| 9          | 1.5                        | 0.5–1.0             | ~20–24              | 30 seconds                  |
-| 10         | 1.5                        | 0.5–1.0             | ~22–26              | 30–35 seconds               |
-
-`Important notes read below `
-
-## RF Spreading Factor Note ##
-
-The above table is based on the default spreading factor of 1024.
-
-At this setting, the transaction times shown are realistic for stable industrial polling with approximately 100 bytes per device.
-If you increase the spreading factor for longer range transmission, the air time increases significantly.
-As a simple rule:
-Add at least 2 seconds per spreading step increase
-
-Maximum spreading factor supported is 4096
-
-Example:
-
-- 1024 → use table values
-
-- 2048 → add ~2 seconds to the recommended inject interval
-
-- 4096 → add ~4 seconds to the recommended inject interval
-
-Increasing spreading improves range and link robustness, but it reduces throughput. Always adjust your inject interval to suit the radio configuration to avoid queue build-up and timeouts.
-
-In RF systems, range and stability always win over speed.
-
----
-# Troubleshooting Guide – Smithtek Mako RF Node
-
-| Issue / Symptom | Possible Cause | Recommended Action |
-|-----------------|---------------|--------------------|
-| Red status: `fail fcX uidY` | Device ID mismatch | Confirm Device ID in Node-RED matches V-NET configuration |
-| Red status: timeout | Polling too fast | Increase inject interval (slow the cycle time) |
-| Red status: timeout | RF link marginal | Increase spreading factor or improve antenna alignment |
-| Red status: timeout | Inject interval shorter than cycle time | Ensure inject interval is longer than full device cycle |
-| Red status: timeout after working normally | Bus overloaded | Reduce number of devices per cycle or increase interval |
-| Only first and last device polling | Queue dropping logic enabled | Disable aggressive queue dropping or increase maxQueue |
-| Devices poll intermittently | Retries too high | Reduce retries to prevent blocking the queue |
-| Devices stop polling after deploy | Serial port locked | Restart Node-RED or power cycle PassPort |
-| Data values incorrect | Register order mismatch | Ensure V-NET Modbus table matches Node-RED decoder map exactly |
-| 32-bit values incorrect | Wrong word order | Confirm correct 32-bit interpretation (float / unsigned / integer) |
-| Digital bits incorrect | Bit index mismatch | Ensure correct bit number (0–15) selected in decoder |
-| Write command not working | Wrong function code | Confirm FC5 for coil, FC6 for single register, FC15/16 for multiples |
-| Write works but value wrong | Payload type mismatch | Ensure msg.payload is correct type (bool or number) |
-| Write command appears successful but nothing changes | Writing to wrong register type | Confirm coil vs holding register mapping in V-NET |
-| Queue growing continuously | Inject too fast | Increase inject interval |
-| Random comms drops on RF | Spreading factor too low for range | Increase spreading factor (add time to cycle) |
-| RF very slow but stable | High spreading factor | Increase inject interval accordingly |
-| Works on RS485 but not RF | Wrong Bus selected | Confirm correct Bus channel assigned |
-| RS485 unstable | Wiring issue | Check termination resistors and polarity (A/B swapped) |
-| All devices fail at once | Bus configuration changed | Confirm baud rate, parity, stop bits match |
-| Node shows “bus config missing” | Config node deleted | Reassign or recreate the Bus config |
-| Node invisible / unknown type | HTML/JS syntax error | Check node installtion, reinstall or contact smithtek support |
-
-## Golden Rule
-
-Always make your inject interval longer than your full device cycle time.
-
-Cycle time ≈ (Number of devices × transaction time + gap).
-
-If the inject interval is shorter than the cycle time, the queue will grow, timeouts will occur, and stability will suffer.
-
-Slow and stable always beats fast and failing.
-
-
-
-
-
-
-
----
-# 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
+# Smithtek Mako RF and PassPort Connect
+
+Node-RED nodes for communicating with Smithtek Mako and Solaris PLCs from a PassPort.
+
+## Included nodes
+
+- **PassPort Connect (PPC)** is Smithtek’s proprietary communication link between PassPort, Mako and Solaris. It reads measurements and writes controls using the matching table created in V-NET2. Supports RF and RS485, plus USB for Mako.
+- **Original Mako RF** provides basic Modbus communication and remains available for existing flows. Its settings and message formats are described in the [original Mako RF guide](https://github.com/smithtekIOT/makorf/blob/main/MAKO-RF.md). Use that guide when working with the original node.
+
+## Install
+
+In Node-RED, open the menu, choose **Manage palette**, open **Install**, search for **smithtek-mako-rf**, and install it. If it is already installed, use the available update. Restart Node-RED if requested. The package includes both the original Mako RF node and the new **PassPort Connect** node.
+
+Before updating an existing installation, export a backup of your flows. After installation, check that **PassPort Connect** appears in the Node-RED palette before importing your V-NET2 export.
+
+## Which guide should I use?
+
+For a new V-NET2 PassPort Connect project, follow the instructions below. A separate copy is available in [PassPort Connect setup and everyday use](https://github.com/smithtekIOT/makorf/blob/main/PASSPORT-CONNECT.md). For an existing original Mako RF flow, use the [original Mako RF instructions](https://github.com/smithtekIOT/makorf/blob/main/MAKO-RF.md). The two nodes use different message formats.
+
+## PassPort Connect · setup and everyday use
+
+PassPort Connect (PPC) is Smithtek’s proprietary communication link between PassPort, Mako and Solaris. It lets your PassPort read measurements and send commands to a Mako or Solaris. For example, you can check a tank level, change a setting or start a pump.
+
+The smithtek-mako-rf package includes two communication nodes. Original Mako RF is for basic Modbus reads and writes. PassPort Connect is for the matching PassPort Connect table in V-NET2. Choose PassPort Connect for this guide; the two nodes use different message formats.
+
+In V-NET2, use the PassPort Connect logic block to choose the readings and controls you want to share. Export from that logic block to create matching Read and Write nodes in Node-RED. Read means “tell me the values”; Write means “change this value”.
+
+### Setup
+
+1. In V-NET2, click New project in the top toolbar. Enter a project name, choose Mako or Solaris, then create the project. Save any existing work you want to keep.
+2. In the logic-block library on the right of V-NET2, open Communication and click PassPort Connect. Read the introduction, then click Add PassPort Connect to place the logic block on your diagram.
+3. Click the PassPort Connect logic block on your V-NET2 diagram. In its Properties panel on the left, enter a Unit ID from 1 to 247. Give every PLC sharing a PassPort connection a different Unit ID. Set Connections to the number of communication links this logic block will use.
+4. In that same Properties panel, click Edit Analog & Digital table. Add a row for each reading or control, enter a clear name such as Tank level or Pump start, and choose its value type and starting value. Click Apply table to save the table to the logic block.
+5. On the V-NET2 diagram, wire each measurement to its named input on the left of the PassPort Connect logic block. Wire each control from its named output on the right to the equipment output or logic block it should operate.
+6. Select the PassPort Connect logic block again. In its left-hand Properties panel, click PassPort Connect · export nodes. This opens the connection and export window.
+7. In that window, under Match the connections, choose the communication port used on your Mako or Solaris and the port used on your PassPort. For example, choose RF on both sides for radio, or Solaris RS485 and PassPort RS485-1 for a wired link. Open Review or change settings before export and check the settings for your chosen connection.
+8. In the same window, click Export read & write nodes. Choose a filename and folder, then save. V-NET2 creates the Node-RED JSON file and adds any missing Send and Receive wires to the selected PLC port on your diagram. Existing wires are kept. Apply settings is available if you want to save these connection choices without exporting a file.
+9. Back in V-NET2, save the project using Save in the toolbar. When ready, use Build program to build and upload it to the selected PLC. The export file alone does not update the PLC. If using RF, also set the PassPort radio to match the PLC.
+10. In Node-RED, open the flow page where you want the nodes. Open the menu, choose Import, select the JSON file saved by V-NET2 and choose Current flow. Click Import and place the Read and Write nodes on that page. Do not paste this JSON into an existing node’s settings.
+11. In Node-RED, double-click each imported node to check its Action, Unit ID and Connection. Add an Inject node before Read and connect a Debug node to each output. Leave Inject once after startup and Repeat off for this first test. Click Deploy, then press the Inject button to read the PLC.
+
+### 1 · Choose your connection
+
+| Connection | How to connect |
+| --- | --- |
+| RF · Mako or Solaris | Choose RF at both ends. Match the frequency, range and Network ID on the PLC and PassPort. If you use an encryption key, match that too. |
+| RS485 · Mako | Choose RS485-1 or RS485-2 on the Mako and the wired port you are using on PassPort. Connect A to A and B to B. Match the baud rate and serial format at both ends. |
+| RS485 · Solaris | Choose RS485 for Solaris and RS485-1 or RS485-2 for PassPort. Connect A to A and B to B. Set the Solaris serial switch to RS485. It uses the shared Monitor / RS485 Send and Receive pins. Match the baud rate and serial format at both ends. |
+| USB · Mako | Connect the Mako USB socket above RS485-1 to a PassPort USB slot with the specified USB-A to USB-A data cable. Choose USB in V-NET2. This uses the Mako Monitor Send and Receive pins. In Node-RED, USB · Auto detect finds a single connected USB serial device. If several are connected, use Refresh USB and choose your device in Connection. |
+
+USB detection runs on the PassPort, where the cable is plugged in. It finds available USB connections; it cannot prove that a device is a Mako. Confirm the selected device and Unit ID with a test read before sending commands. With several devices connected, choose the right one rather than letting the software guess.
+
+If no USB device is found, check power and the data cable, then refresh the list. Devices with a unique identity can be found again if their connection number changes. If a device has no unique identity, check the selection again after unplugging or restarting.
+
+Solaris has one shared Monitor / RS485 port. In your V-NET2 diagram, if a sensor logic block already uses that port, choose RF for the PassPort Connect logic block. The same Send port cannot be connected to both the sensor logic block and the PassPort Connect logic block.
+
+Changing the export settings does not change the PassPort radio. Set that separately. Short range and Long range are radio settings, not promises about how far a signal will travel.
+
+Keep the selected connection for PassPort messages. Do not also send ordinary Monitor text over it: mixed messages can stop readings and commands from working.
+
+### 2 · Make your channel table
+
+| Choice | When to use it |
+| --- | --- |
+| Float | A 32-bit floating-point number, such as 12.5 volts. Stores about seven significant digits. Large whole numbers can round: 123456789 becomes 123456792. Choose 32-bit unsigned or 32-bit signed when you need that whole number exactly. |
+| 16-bit signed | Whole numbers from −32768 to 32767. |
+| 16-bit unsigned | Whole numbers from 0 to 65535. |
+| 32-bit signed | Whole numbers from −2147483648 to 2147483647. |
+| 32-bit unsigned | Whole numbers from 0 to 4294967295. |
+| Digital | On or off: true or false. Use this for switches and simple controls. |
+
+An Analog row holds a number. A Digital row holds on or off. Mako supports up to 64 rows; Solaris supports up to 16, with space also needed for the rest of your program.
+
+Use a different name for each row, up to 40 characters. Capital letters matter: Pump and pump are different names. The editor will tell you if a name cannot be used.
+
+V-NET2 works out the table addresses for you. An address is simply where a value is kept. Leave these alone when using an exported table.
+
+Keep the PLC table and both Node-RED tables the same. After changing a table in V-NET2, upload the changed PLC program and export fresh nodes. Replace the old nodes so you do not accidentally read or send commands twice.
+
+Starting values apply when the PLC starts. They do not make Node-RED send a command. A signal wired into a row on the left can keep replacing a command sent from PassPort. Leave that input unwired for a remote-only control.
+
+Use a separate feedback row when you need to know what actually happened. A Pump start command and a Pump running sensor tell you different things.
+
+### 3 · Read your measurements
+
+A Read node waits until another node asks it to work. Connect an Inject node to its input and press the Inject button. Each press reads the whole table. The value inside the Inject message does not choose a channel.
+
+To start, leave Repeat and Inject once after startup off. After a successful test, you can set Inject to repeat. Allow enough time for one reading to finish before asking again.
+
+Connect a Debug node to the first output to see successful readings. Values are listed by their table names in msg.payload. For example, {"Level":12.5,"Pump":false} means the level is 12.5 and the Pump value is off.
+
+The second output reports problems. If part of a read fails, the node reports an error instead of sending an incomplete set of readings.
+
+The PLC may need several requests to return a table. Values are collected one after another, so they are not all measured at exactly the same moment.
+
+Prefix helps you tell PLCs apart. Enter North Mako and a row called Level appears as North Mako Level in the readings. The row name used for commands is still Level.
+
+For more detailed flows, msg.ts records when Node-RED finished the read. It is not the time the PLC measured each value. msg.channels holds the original, unscaled numbers and on/off values; msg.passport holds the result and progress details. Most everyday flows only need msg.payload.
+
+### 4 · Send a command
+
+| Write input | How to use it |
+| --- | --- |
+| Single channel · easiest | Choose the row in Write channel. Send a number for Analog, or Boolean true / false for Digital. Only that row changes. |
+| Named values | Send a JSON object such as {"Pump":true,"Setpoint":25}. Only the named rows change. Use the exact table names, without a read Prefix. |
+| Mapped arrays · advanced | Use this only if your flow already works with lists of values. Send the matching mappingId and the full Analog or Digital list in table order. The Digital list is called switches. |
+
+Open the Write node, choose Single channel, then choose the row you want to control. Exported writers initially select the first row, so always check this before connecting commands.
+
+In Inject, choose number for a numeric setting or Boolean for an on/off command. Do not choose string: the text “true” is not the same as the Boolean value true. For several named values, choose JSON.
+
+Analog commands must fit the row type. Whole-number rows need whole numbers. Digital accepts true and false, or 1 and 0. Send an ordinary number even for a 32-bit row; the node handles its size.
+
+The first output confirms that the PLC answered the command. It does not prove a motor turned or a valve moved. Read a feedback sensor to check the equipment.
+
+Commands are not automatically repeated after a failed reply. A PLC can receive a command even when its reply is lost. Check the equipment or read it back before repeating a start, reset or pulse command.
+
+If you change several values together and a later part fails, earlier values may already have changed. Read the values back before deciding what to send next.
+
+Do not connect Read straight into Write. That can turn every repeat reading into another command. Make separate buttons or control logic for the changes you intend.
+
+For advanced list-based flows, move the unscaled msg.channels object into msg.payload before using it as a Mapped arrays command. A one-Analog, one-Digital table could use {"mappingId":"the matching table ID","analog":[25],"switches":[true]}. Keep each supplied list complete and in order. The table ID checks the message against the node; it does not check which program was uploaded to the PLC.
+
+### 5 · Short pulses, remote resets and lost communication
+
+Pulse on write works like a quick button press. Turn it on for a Digital row in V-NET2. A command turns the output on briefly, then it turns off by itself. The default is 250 milliseconds, or a quarter of a second. You can choose 1 to 1000 milliseconds.
+
+This is useful for remote resets or restarts. For example, connect a Reset pulse to the reset input of the equipment logic you want to restart. Connect it to the PLC Reset input only when you intend to restart the whole PLC. A PLC restart interrupts communication, so its reply may be lost.
+
+Each accepted write triggers a pulse, even a repeated value or false. Send one true command for each intended press. Do not send a second false command to release it: that would trigger another pulse. Another command during a pulse extends it. Reading the row does not trigger it.
+
+Pulse settings belong to the PLC program. Save and upload after changing them, then export matching nodes.
+
+The communications watchdog is a way for your program to notice missing messages. Set Timeout to the number of seconds it should wait. Zero turns it off.
+
+If no valid communication arrives for that whole time, Watchdog sends false once. It waits another full timeout before checking for recovery. It sends true once when recent communication has returned, or waits and checks again if it has not. It sends no startup command.
+
+Choose the response by wiring Watchdog into your program. It does not stop a pump or clear other values by itself. Use regular reads if you rely on them to keep communication active; manual clicks leave gaps between messages.
+
+### 6 · Copy a node and adjust how readings look
+
+A useful tip: copy and paste your complete Read node, then change the copy’s Action to Write. This copies the entire channel table and connection settings, so you do not have to work out the table again. Choose Single channel and select the row you want to control before using it.
+
+The copy is independent. Later edits to one node do not change the other. Keep both tables matched to the uploaded PLC program.
+
+Scaling changes how a reading is displayed. For example, Math /100 turns 1250 into 12.5. None leaves it unchanged. Math allows one simple operation, such as *2, /100, +5 or -7. Do not enter a long formula.
+
+Range converts between two scales. For example, Input low 4 and Input high 20, with Output low 0 and Output high 100, turns a 4–20 reading into 0–100. Clamp keeps the displayed result inside that range. Without Clamp, readings outside the input range can produce results below or above the output range.
+
+Hide range only folds the settings away; it does not turn scaling off. Choose None to stop scaling. Scaling is for Analog rows.
+
+Scaling and Prefix change named readings only. They do not change the PLC or commands. If /100 displays a stored value of 1250 as 12.5, a Write command still needs 1250 to request that original value.
+
+You normally do not need to edit addresses. If you do, they must match the PLC. Moving rows in Node-RED does not change their addresses. Exporting again from V-NET2 uses the V-NET2 table and does not keep separate edits made in Node-RED.
+
+### 7 · Sharing a connection and avoiding delays
+
+PLCs using the same PassPort RF or wired port share one Connection setting. Select that existing Connection in each Read and Write node. Give each PLC its own Unit ID.
+
+Think of the connection as a single lane: messages take turns. A long table or a PLC that does not answer can hold up the next message, including a command.
+
+Timeout is how long PassPort waits for an answer. Read retries is how many extra times it tries a failed read. The exported defaults wait up to 8 seconds and allow 2 extra read attempts. Commands do not use these extra attempts.
+
+A queue is a waiting list of messages. If you ask for readings too quickly, the list grows and replies get late. Slow down the Inject repeat rate and remove duplicate triggers if this happens.
+
+Each Read or Write node can have up to 16 waiting messages. The shared connection also has a limit. Use a Catch node to show queue-full errors, as well as Debug on the second output for other problems.
+
+Start with one PLC and manual reads. Add regular reads and other PLCs gradually, checking how long replies take. Signal conditions and the amount of information affect the speed.
+
+Signal-strength options used by the older RF node do not add a signal-strength reading to PassPort Connect.
+
+### 8 · If something is not working
+
+| Problem | What to try |
+| --- | --- |
+| Unknown node after import | Check that PassPort Connect is available in your Node-RED palette. If it is missing, ask your installer to update PassPort Connect. |
+| No reading after Deploy | Press the Inject button. Deploy saves the flow; it does not ask for a reading. |
+| No answer or timeout | Check power, cables, Unit ID and matching communication settings. Confirm you uploaded the intended PLC program. For USB, refresh the detected-device list and confirm your selection. |
+| Numbers look wrong | Compare the table and value types with V-NET2. Check whether scaling has changed the displayed number. |
+| A command is rejected | Check the selected row, spelling and value type. If using lists, check they match the whole current table. |
+| A command changes back immediately | Look for a local signal or other logic that keeps writing to that row. |
+| A command reports an error | Check the equipment and read the value back. The command may have arrived even if its reply did not. |
+| Replies are slow or the queue is full | Read less often. Remove duplicate Inject timers and make sure nodes sharing a port use the same Connection. |
+
+Connect Debug to the second output to see the error message. Add a Catch node for errors such as a full waiting list. Both can report the same problem, so avoid making two automatic responses to one fault.
+
+The error details can show how many parts completed and whether a command may already have reached the PLC. Use that information before trying again.
+
+A green completed status means the last request worked. It does not prove the PLC is still connected now. A screen showing old readings should also show when they were last updated.
+
+Before using a new setup unattended, test the readings, commands and loss-of-communication response on your equipment.
+
+### 9 · Export and import into Node-RED
+
+In V-NET2, click the PassPort Connect logic block on your diagram. In the left-hand Properties panel, click PassPort Connect · export nodes. Choose the connections in the window that opens, then click Export read & write nodes and save the JSON file.
+
+In Node-RED, open the flow page you want to use. Open the menu and choose Import. Select the JSON file saved by V-NET2, choose Current flow, click Import and place the nodes. This adds complete Read and Write nodes with your table. It does not create a new flow tab.
+
+You can also copy the contents of that JSON file and paste them into the text box in the Node-RED Import window. You must still click Import. Do not paste the complete file into a Read or Write node’s settings.
+
+In Node-RED, double-click each imported node. Check Unit ID and Connection. If that PassPort port is already in use, choose the existing Connection. Click Done, add your Inject buttons and Debug nodes, then click Deploy.
+
+The other button in the V-NET2 logic block’s Properties panel is Export connection setup JSON. It saves a reference copy of your table and settings. It does not create Node-RED nodes and cannot be imported as a flow or pasted into a node. Use PassPort Connect · export nodes when you want the Read and Write nodes.
+
+Neither export uploads the PLC program or changes the PassPort radio. Save and upload the PLC project from V-NET2 separately.
+
+If PassPort Connect is missing from the Node-RED palette, ask your installer to add or update it.
+
+Older projects using the ordinary Modbus logic block still have their separate single-node export. Farming quick templates use the PassPort Connect logic block and export the complete Read and Write pair.
+
+### 10 · Try it: battery reading and a relay command
+
+Create a test project for your PLC. Add PassPort Connect with Unit ID 7 and one connection. Add Battery as a Float Analog row, and TestRelay as a normal Digital row with Pulse on write off.
+
+Wire Battery Voltage to Battery on the left. Wire TestRelay on the right to a spare Mako output or Solaris relay. Leave TestRelay on the left unwired. Use an output whose connected equipment is suitable for your test.
+
+In PassPort Connect, choose RF or an available RS485 connection and match the settings. Export the Read and Write nodes. Save and upload the PLC program when ready.
+
+In Node-RED, import into Current flow. Connect Inject to Read and Debug to both outputs. Deploy and press Inject. The result should include a Battery number and TestRelay as true or false.
+
+Open Write, choose Single channel and select TestRelay. Do not leave Battery selected. Make one Inject with Boolean true and another with Boolean false. Leave automatic startup and Repeat off. Wire both to Write, Deploy, and test each button.
+
+Check the relay itself or a feedback sensor, as well as the reply. For an Analog setpoint later, select that row and send a number in the original units.
+
+For a ready-wired farm project, open Farmers quick templates. Choose the picture, enter a unique Unit ID and the required sensor settings, then choose Load & export Node-RED. The project uses PassPort Connect, includes battery voltage and exports the complete Read and Write pair onto your current flow.