node-red-contrib-modbus-modpackqt 1.1.5 → 1.1.7

package/README.md

@@ -45,11 +45,28 @@ npm install node-red-contrib-modbus-modpackqt
 
 ## Prerequisites
 
-1. **Download and start the ModPackQT Gateway app:**
+1. **Sign up at [modpackqt.com](https://modpackqt.com)**
+   A free account works for all master nodes. Slave nodes require a **paid plan**.
+
+2. **Download and start the ModPackQT Gateway app**
    Download it from [modpackqt.com/download](https://modpackqt.com/download) and run it.
    By default it listens on **port 8502** (`localhost:8502`).
 
-2. For slave nodes, create and start at least one slave in the ModPackQT app first.
+3. **Create an API key**
+   In the ModPackQT web app go to **Settings → API Keys → New Key**. Paste it into the `modpackqt-config` node.
+
+4. **For slave nodes** — create and start at least one slave in the ModPackQT app first (Slave Simulator → New Slave). Note the **Slave ID** shown — you'll need it in Node-RED.
+
+> **Plan limits**
+>
+> | Feature | Free | Paid |
+> |---|---|---|
+> | Master Read (`modpackqt-master-read`) | ✓ | ✓ |
+> | Master Write (`modpackqt-master-write`) | ✓ | ✓ |
+> | Slave Write (`modpackqt-slave-write`) | ✗ | ✓ |
+> | Slave Read (`modpackqt-slave-read`) | ✗ | ✓ |
+>
+> [View plans & upgrade →](https://modpackqt.com/#pricing)
 
 ---
 
@@ -60,8 +77,8 @@ npm install node-red-contrib-modbus-modpackqt
 | `modpackqt-config` | Config | Shared gateway connection (host, port, API key) |
 | `modpackqt-master-read` | Modbus Master | Read Modbus TCP registers — FC1/FC2/FC3/FC4 |
 | `modpackqt-master-write` | Modbus Master | Write Modbus TCP registers — FC5/FC6/FC15/FC16 |
-| `modpackqt-slave-read` | Modbus Slave | Read registers from a ModPackQT simulated slave |
-| `modpackqt-slave-write` | Modbus Slave | Write registers into a ModPackQT simulated slave |
+| `modpackqt-slave-read` | Modbus Slave *(paid)* | Read registers from a ModPackQT slave |
+| `modpackqt-slave-write` | Modbus Slave *(paid)* | Push values into a ModPackQT slave (build a live Modbus device from Node-RED) |
 
 ---
 
@@ -114,21 +131,45 @@ The `modpackqt-master-write` node writes registers to **any Modbus TCP slave dev
 
 ---
 
-## Node-RED Modbus Slave — Read & Write Simulated Registers
+## Building a Modbus Slave from Node-RED *(Paid plan)*
 
-The `modpackqt-slave-read` and `modpackqt-slave-write` nodes interact with ModPackQT's **built-in slave simulator** — a virtual PLC register map you control.
+Use `modpackqt-slave-write` to make Node-RED the **data source** for a live Modbus slave device. Any external Modbus master (PLC, SCADA, HMI) that connects to the ModPackQT slave port will read whatever values you last pushed from Node-RED.
+
+**Typical flow:**
+```
+[MQTT / Sensor / Timer] → [Function: scale to integer] → [modpackqt-slave-write addr=0] → [External Modbus master reads]
+```
 
-**Register types:** Holding Registers, Coils, Input Registers, Discrete Inputs
+**Use cases:**
+- Publish MQTT sensor data as Modbus TCP registers
+- Simulate a PLC register map for HMI/SCADA testing
+- Bridge OPC-UA, REST, or database data to Modbus
+
+**Slave write input — all of these work:**
+```js
+msg.payload = 234;               // single integer
+msg.payload = [234, 1013, 65];   // array — writes 3 registers starting at address 0
+msg.payload = "[234, 1013, 65]"; // JSON string also works (inject string type)
+```
+
+**Override at runtime:**
+```js
+msg.slaveId      = "42";    // select a different slave per message
+msg.address      = 10;      // start at register 10 instead of the configured address
+msg.registerType = "coil";  // override register type
+```
 
 **Slave read output:**
 ```json
 {
   "payload": {
-    "values": [0, 42, 100],
+    "values": [234, 1013, 65],
     "registerType": "holding",
-    "address": 0
+    "address": 0,
+    "quantity": 3,
+    "slaveId": "42"
   },
-  "topic": "slave/{slaveId}/holding/0"
+  "topic": "slave/42/holding/0"
 }
 ```
 
@@ -136,7 +177,7 @@ The `modpackqt-slave-read` and `modpackqt-slave-write` nodes interact with ModPa
 
 ## Example Flows
 
-### Poll Holding Registers Every 5 Seconds (Node-RED Modbus Master)
+### Poll Holding Registers Every 5 Seconds (Modbus Master)
 
 ```
 [Inject (repeat 5s)] → [modpackqt-master-read FC3 target=192.168.1.10:502 unitId=1 addr=0 qty=10] → [Debug]
@@ -148,13 +189,14 @@ The `modpackqt-slave-read` and `modpackqt-slave-write` nodes interact with ModPa
 [Inject (payload=1234)] → [modpackqt-master-write FC6 target=192.168.1.10:502 unitId=1 addr=100] → [Debug]
 ```
 
-### Inject Test Values into a Modbus Slave Simulator
+### Build a Slave — Publish Sensor Data as Modbus (Paid plan)
 
 ```
-[Inject ([10,20,30])] → [modpackqt-slave-write Holding addr=0]
-[modpackqt-slave-read Holding addr=0 qty=3] → [Debug]
+[MQTT in] → [Function: msg.payload = parseInt(msg.payload * 10)] → [modpackqt-slave-write Holding addr=0] → [Debug]
 ```
 
+Any Modbus master on the network now reads live sensor values from the slave.
+
 ### Import the Demo Flow
 
 1. Open Node-RED → **Menu → Import**
@@ -191,9 +233,11 @@ Add one `modpackqt-config` node per gateway instance. All other nodes reference
 
 | Issue | Solution |
 |---|---|
-| `connect ECONNREFUSED localhost:8502` | Make sure the ModPackQT Gateway app is running. Check host/port in the config node. |
-| `404 Slave not found` | Check the Slave ID — find it in the ModPackQT app under your slave's settings. |
-| `Slave not running` (slave-write) | Start the slave in the ModPackQT app before writing. |
+| `connect ECONNREFUSED localhost:8502` | The ModPackQT Gateway app is not running. Start it first. |
+| `401 Unauthorized` | Missing or invalid API key — check `modpackqt-config`. |
+| `403 Forbidden` on slave nodes | Your plan does not include the Slave Simulator. [Upgrade your plan →](https://modpackqt.com/#pricing) |
+| `slave not found — check Slave ID` | The Slave ID is wrong or that slave was deleted. Check in ModPackQT → Slave Simulator. |
+| `gateway not running` on slave nodes | The Gateway app is stopped. Open ModPackQT and click Start Gateway. |
 | `Cannot find module 'axios'` | Run `npm install` in `~/.node-red`. |
 | Nodes not appearing after install | Restart Node-RED completely after `npm install`. |
 | Node-RED version error | Requires Node-RED ≥ 2.0.0 and Node.js ≥ 14. |

package/nodes/modpackqt-config.html

@@ -2,15 +2,15 @@
   RED.nodes.registerType('modpackqt-config', {
     category: 'config',
     defaults: {
-      name:  { value: 'ModPackQT', required: false },
+      name:  { value: 'ModPackQT Gateway', required: false },
       host:  { value: 'localhost', required: true },
-      port:  { value: 3000, required: true, validate: RED.validators.number() }
+      port:  { value: 8502, required: true, validate: RED.validators.number() }
     },
     credentials: {
       apiKey: { type: 'password' }
     },
     label: function() {
-      return this.name || `${this.host}:${this.port}`;
+      return this.name || (this.host + ':' + this.port);
     }
   });
 </script>
@@ -18,7 +18,7 @@
 <script type="text/html" data-template-name="modpackqt-config">
   <div class="form-row">
     <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
-    <input type="text" id="node-config-input-name" placeholder="ModPackQT">
+    <input type="text" id="node-config-input-name" placeholder="ModPackQT Gateway">
   </div>
   <div class="form-row">
     <label for="node-config-input-host"><i class="fa fa-globe"></i> Host</label>
@@ -26,23 +26,103 @@
   </div>
   <div class="form-row">
     <label for="node-config-input-port"><i class="fa fa-plug"></i> Port</label>
-    <input type="number" id="node-config-input-port" placeholder="3000" min="1" max="65535">
+    <input type="number" id="node-config-input-port" placeholder="8502" min="1" max="65535">
   </div>
   <div class="form-row">
     <label for="node-config-input-apiKey"><i class="fa fa-key"></i> API Key</label>
-    <input type="password" id="node-config-input-apiKey" placeholder="optional">
+    <input type="password" id="node-config-input-apiKey" placeholder="Paste your API key from ModPackQT → Settings">
+  </div>
+  <div class="form-tips">
+    <b>Default setup:</b> Host <code>localhost</code>, Port <code>8502</code>.<br>
+    Get your API key from <b>ModPackQT app → Settings → API Keys</b>.
   </div>
 </script>
 
 <script type="text/html" data-help-name="modpackqt-config">
-  <p>Connection configuration for a ModPackQT instance.</p>
+  <p>
+    Shared connection settings for all ModPackQT nodes. Defines which
+    <b>ModPackQT Gateway</b> instance to communicate with and how to authenticate.
+  </p>
+
+  <h3>What is the ModPackQT Gateway?</h3>
+  <p>
+    The Gateway is a small app that runs on your local machine (or a server on your network).
+    It acts as a bridge between Node-RED and your Modbus devices, and also hosts the
+    Slave Simulator. All ModPackQT nodes talk to this Gateway's REST API.
+  </p>
+
+  <h3>First-time setup</h3>
+  <ol>
+    <li>
+      <b>Sign up</b> at <a href="https://modpackqt.com" target="_blank">modpackqt.com</a>
+      — a free account lets you use the master read/write nodes.
+      Slave and advanced features require a paid plan.
+    </li>
+    <li>
+      <b>Download the Gateway app</b> — log in to ModPackQT, open
+      <em>Settings → Gateway</em> and download the installer for your OS (Windows/Mac/Linux).
+    </li>
+    <li>
+      <b>Run the Gateway</b> — it starts a local REST API on port <code>8502</code> by default.
+      You will see a <em>Running</em> status in the app when it is ready.
+    </li>
+    <li>
+      <b>Create an API Key</b> — in the ModPackQT web app, go to
+      <em>Settings → API Keys → New Key</em>. Copy the key and paste it into the
+      <em>API Key</em> field in this config node.
+    </li>
+    <li>
+      <b>Set Host and Port</b>:
+      <ul>
+        <li>If Node-RED runs on the same machine as the Gateway: <code>localhost</code> / <code>8502</code></li>
+        <li>If the Gateway is on another machine: use that machine's IP address</li>
+      </ul>
+    </li>
+  </ol>
+
   <h3>Properties</h3>
   <dl class="message-properties">
     <dt>Host <span class="property-type">string</span></dt>
-    <dd>Hostname or IP address of the ModPackQT server (default: <code>localhost</code>).</dd>
+    <dd>
+      Hostname or IP address of the machine running the ModPackQT Gateway.
+      Default: <code>localhost</code>.
+    </dd>
     <dt>Port <span class="property-type">number</span></dt>
-    <dd>TCP port the ModPackQT REST API listens on (default: <code>3000</code>).</dd>
+    <dd>
+      TCP port the Gateway REST API listens on. Default: <code>8502</code>.
+      Change this only if you configured a custom port in the Gateway settings.
+    </dd>
     <dt>API Key <span class="property-type">password</span></dt>
-    <dd>Optional API key sent as the <code>x-api-key</code> header.</dd>
+    <dd>
+      Your ModPackQT API key. Required for authenticated operations.
+      Get it from <em>ModPackQT → Settings → API Keys</em>.
+    </dd>
   </dl>
+
+  <h3>Plan limits</h3>
+  <table>
+    <thead><tr><th>Feature</th><th>Free</th><th>Paid</th></tr></thead>
+    <tbody>
+      <tr><td>Master Read (modpackqt-master-read)</td><td>✓</td><td>✓</td></tr>
+      <tr><td>Master Write (modpackqt-master-write)</td><td>✓</td><td>✓</td></tr>
+      <tr><td>Slave Write (modpackqt-slave-write)</td><td>✗</td><td>✓</td></tr>
+      <tr><td>Slave Read (modpackqt-slave-read)</td><td>✗</td><td>✓</td></tr>
+      <tr><td>Number of Slaves</td><td>0</td><td>Plan dependent</td></tr>
+    </tbody>
+  </table>
+  <p>
+    <a href="https://modpackqt.com/#pricing" target="_blank">View plans &amp; upgrade →</a>
+  </p>
+
+  <h3>Troubleshooting</h3>
+  <ul>
+    <li><b>ECONNREFUSED</b> — the Gateway app is not running. Start it from the ModPackQT app.</li>
+    <li><b>401 Unauthorized</b> — missing or invalid API key.</li>
+    <li><b>403 Forbidden</b> — your plan does not include this feature, or you have reached a limit.</li>
+    <li><b>404 Not Found</b> — the Slave ID or Connection Profile ID does not exist in your account.</li>
+  </ul>
+
+  <p>
+    <a href="https://modpackqt.com/node-red" target="_blank">Full Node-RED documentation →</a>
+  </p>
 </script>

package/nodes/modpackqt-slave-read.html

@@ -5,7 +5,7 @@
     defaults: {
       name:         { value: '' },
       server:       { value: '', type: 'modpackqt-config', required: true },
-      slaveId:      { value: '', required: true },
+      slaveId:      { value: '' },
       registerType: { value: 'holding', required: true },
       address:      { value: 0,  required: true, validate: RED.validators.number() },
       quantity:     { value: 1,  required: true, validate: RED.validators.number() },
@@ -15,7 +15,7 @@
     outputs: 1,
     icon: 'font-awesome/fa-server',
     label: function() {
-      return this.name || `Slave Read ${this.registerType} @${this.address}`;
+      return this.name || ('Slave Read ' + (this.registerType || 'holding') + ' @' + this.address);
     },
     paletteLabel: 'slave read'
   });
@@ -32,12 +32,12 @@
   </div>
   <div class="form-row">
     <label for="node-input-slaveId"><i class="fa fa-id-card"></i> Slave ID</label>
-    <input type="text" id="node-input-slaveId" placeholder="Slave ID from ModPackQT app">
+    <input type="text" id="node-input-slaveId" placeholder="e.g. 42  (or leave blank, set via msg.slaveId)">
   </div>
   <div class="form-row">
     <label for="node-input-registerType"><i class="fa fa-list"></i> Register Type</label>
     <select id="node-input-registerType">
-      <option value="holding" selected>Holding Registers</option>
+      <option value="holding">Holding Registers</option>
       <option value="coil">Coils</option>
       <option value="input">Input Registers</option>
       <option value="discrete">Discrete Inputs</option>
@@ -53,25 +53,92 @@
   </div>
   <div class="form-row">
     <label for="node-input-pollInterval"><i class="fa fa-clock-o"></i> Poll Interval (ms)</label>
-    <input type="number" id="node-input-pollInterval" min="0" placeholder="0 = disabled">
+    <input type="number" id="node-input-pollInterval" min="0" placeholder="0 = trigger only">
+  </div>
+  <div class="form-tips">
+    <b>Tip:</b> Override at runtime via <code>msg.slaveId</code>, <code>msg.address</code>,
+    <code>msg.quantity</code>, or <code>msg.registerType</code>.
   </div>
 </script>
 
 <script type="text/html" data-help-name="modpackqt-slave-read">
-  <p>Reads registers from a ModPackQT simulated slave via the ModPackQT Gateway app.</p>
-  <p>Calls <code>GET /api/slaves/:id/registers</code> on the gateway.</p>
+  <p>
+    Reads the current register values from a <b>ModPackQT Slave</b>. Use this to monitor or
+    verify what your slave is currently serving to external Modbus masters.
+  </p>
+
+  <h3>Quick Setup — 4 steps</h3>
+  <ol>
+    <li>
+      <b>Create a free account</b> at
+      <a href="https://modpackqt.com" target="_blank">modpackqt.com</a>
+      (slave feature requires a paid plan — see below).
+    </li>
+    <li>
+      <b>Download and run the Gateway app.</b>
+      The gateway exposes a local REST API (default port <code>8502</code>).
+      Open the ModPackQT app and click <em>Download Gateway</em>.
+    </li>
+    <li>
+      <b>Create a Slave</b> in the ModPackQT app:
+      go to <em>Slave Simulator</em> → <em>New Slave</em>, set a Modbus port (e.g. <code>502</code>),
+      then click <em>Start</em>. Copy the <b>Slave ID</b> shown in the app.
+    </li>
+    <li>
+      <b>Add a ModPackQT Config node</b> (click the pencil next to Gateway above),
+      set Host to <code>localhost</code> and Port to <code>8502</code>.
+      Paste your API key from <em>ModPackQT → Settings → API Keys</em>.
+    </li>
+  </ol>
+
+  <h3>Plan requirement</h3>
+  <p>
+    The Slave Simulator is a <b>paid-plan feature</b>.
+    Free accounts cannot use slave nodes. If you receive a <code>403</code> error,
+    upgrade your plan first.
+    <a href="https://modpackqt.com/#pricing" target="_blank">View plans &amp; upgrade →</a>
+  </p>
+
   <h3>Inputs</h3>
   <dl class="message-properties">
     <dt>payload <span class="property-type">any</span></dt>
-    <dd>Any message triggers a read (when Poll Interval is 0).</dd>
+    <dd>Any message triggers a read (when Poll Interval is 0 or disabled).</dd>
+    <dt class="optional">slaveId <span class="property-type">string | number</span></dt>
+    <dd>Overrides the Slave ID configured in the node.</dd>
+    <dt class="optional">address <span class="property-type">number</span></dt>
+    <dd>Overrides the start address.</dd>
+    <dt class="optional">quantity <span class="property-type">number</span></dt>
+    <dd>Overrides how many registers to read.</dd>
+    <dt class="optional">registerType <span class="property-type">string</span></dt>
+    <dd>Overrides the register type: <code>holding</code>, <code>coil</code>, <code>input</code>, or <code>discrete</code>.</dd>
   </dl>
+
   <h3>Outputs</h3>
   <dl class="message-properties">
-    <dt>payload <span class="property-type">object</span></dt>
-    <dd>Contains <code>values</code> (array), <code>registerType</code>, <code>address</code>, and <code>total</code>.</dd>
+    <dt>payload.values <span class="property-type">array</span></dt>
+    <dd>Array of register values (integers for holding/input, booleans for coil/discrete).</dd>
+    <dt>payload.registerType <span class="property-type">string</span></dt>
+    <dd>Register type that was read.</dd>
+    <dt>payload.address <span class="property-type">number</span></dt>
+    <dd>Start address that was read.</dd>
+    <dt>payload.quantity <span class="property-type">number</span></dt>
+    <dd>Number of values returned.</dd>
+    <dt>payload.slaveId <span class="property-type">string</span></dt>
+    <dd>The Slave ID that was queried.</dd>
     <dt>topic <span class="property-type">string</span></dt>
     <dd><code>slave/{slaveId}/{registerType}/{address}</code></dd>
   </dl>
-  <h3>Details</h3>
-  <p><b>Slave ID</b> — the ID of the slave as configured in the ModPackQT app. Find it in the app or via <code>GET /api/slaves</code>.</p>
+
+  <h3>Status messages</h3>
+  <ul>
+    <li><b>yellow ring</b> — polling active, waiting for first response</li>
+    <li><b>green dot</b> — last read succeeded, shows register info + timestamp</li>
+    <li><b>red dot</b> — error (check API key / plan / gateway)</li>
+    <li><i>slave not found</i> — Slave ID is wrong or slave was deleted</li>
+    <li><i>gateway not running</i> — Gateway app is not started</li>
+  </ul>
+
+  <p>
+    <a href="https://modpackqt.com/node-red" target="_blank">Full documentation &amp; example flows →</a>
+  </p>
 </script>

package/nodes/modpackqt-slave-read.js

@@ -6,39 +6,67 @@ module.exports = function(RED) {
 
     node.slaveId      = config.slaveId      || '';
     node.registerType = config.registerType || 'holding';
-    node.address      = parseInt(config.address)      || 0;
-    node.quantity     = parseInt(config.quantity)     || 1;
-    node.pollInterval = parseInt(config.pollInterval) || 0;
+    node.address      = parseInt(config.address,      10) || 0;
+    node.quantity     = parseInt(config.quantity,     10) || 1;
+    node.pollInterval = parseInt(config.pollInterval, 10) || 0;
 
     let timer = null;
 
-    async function doRead() {
+    async function doRead(msg) {
       if (!server) {
-        node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+        node.status({ fill: 'red', shape: 'ring', text: 'no config — add a ModPackQT Config node' });
         return;
       }
-      if (!node.slaveId) {
+
+      const slaveId = (msg && msg.slaveId) || node.slaveId;
+      if (!slaveId) {
         node.status({ fill: 'red', shape: 'ring', text: 'slave ID required' });
+        node.error('No Slave ID set. Configure it in the node or send msg.slaveId.', msg);
         return;
       }
+
+      const registerType = (msg && msg.registerType) || node.registerType;
+      const address      = (msg && msg.address !== undefined) ? parseInt(msg.address, 10) : node.address;
+      const quantity     = (msg && msg.quantity !== undefined) ? parseInt(msg.quantity, 10) : node.quantity;
+
       try {
         const result = await server.request(
           'GET',
-          `/api/slaves/${encodeURIComponent(node.slaveId)}/registers?type=${node.registerType}&offset=${node.address}&limit=${node.quantity}`
+          `/api/slaves/${encodeURIComponent(slaveId)}/registers?type=${registerType}&offset=${address}&limit=${quantity}`
         );
-        node.status({ fill: 'green', shape: 'dot', text: `${node.registerType} @${node.address}` });
-        node.send({ payload: { values: result.values || [], registerType: node.registerType, address: node.address, total: result.total }, topic: `slave/${node.slaveId}/${node.registerType}/${node.address}` });
+
+        const values = result.values || [];
+        const now    = new Date().toLocaleTimeString();
+        const pollTxt = node.pollInterval > 0 ? ` (poll ${node.pollInterval}ms)` : '';
+        node.status({ fill: 'green', shape: 'dot', text: `${registerType} @${address} [${values.length}] · ${now}${pollTxt}` });
+
+        node.send({
+          payload: {
+            values,
+            registerType,
+            address,
+            quantity: values.length,
+            total:    result.total,
+            slaveId
+          },
+          topic: `slave/${slaveId}/${registerType}/${address}`
+        });
       } catch (err) {
-        node.status({ fill: 'red', shape: 'dot', text: err.message });
-        node.error(err.message);
+        const hint = err.message.includes('403') ? 'check API key / plan limit'
+          : err.message.includes('404') ? 'slave not found — check Slave ID'
+          : err.message.includes('ECONNREFUSED') ? 'gateway not running'
+          : err.message;
+        node.status({ fill: 'red', shape: 'dot', text: hint });
+        node.error(err.message, msg);
       }
     }
 
     if (node.pollInterval > 0) {
-      timer = setInterval(doRead, node.pollInterval);
+      node.status({ fill: 'yellow', shape: 'ring', text: `polling every ${node.pollInterval}ms…` });
+      timer = setInterval(() => doRead(null), node.pollInterval);
     }
 
-    node.on('input', async function() { await doRead(); });
+    node.on('input', async function(msg) { await doRead(msg); });
     node.on('close', function() { if (timer) clearInterval(timer); });
   }
   RED.nodes.registerType('modpackqt-slave-read', ModPackQTSlaveReadNode);

package/nodes/modpackqt-slave-write.html

@@ -5,7 +5,7 @@
     defaults: {
       name:         { value: '' },
       server:       { value: '', type: 'modpackqt-config', required: true },
-      slaveId:      { value: '', required: true },
+      slaveId:      { value: '' },
       registerType: { value: 'holding', required: true },
       address:      { value: 0, required: true, validate: RED.validators.number() }
     },
@@ -13,7 +13,7 @@
     outputs: 1,
     icon: 'font-awesome/fa-hdd-o',
     label: function() {
-      return this.name || `Slave Write ${this.registerType} @${this.address}`;
+      return this.name || ('Slave Write ' + (this.registerType || 'holding') + ' @' + this.address);
     },
     paletteLabel: 'slave write'
   });
@@ -30,13 +30,13 @@
   </div>
   <div class="form-row">
     <label for="node-input-slaveId"><i class="fa fa-id-card"></i> Slave ID</label>
-    <input type="text" id="node-input-slaveId" placeholder="Slave ID from ModPackQT app">
+    <input type="text" id="node-input-slaveId" placeholder="e.g. 42  (or leave blank, set via msg.slaveId)">
   </div>
   <div class="form-row">
     <label for="node-input-registerType"><i class="fa fa-list"></i> Register Type</label>
     <select id="node-input-registerType">
-      <option value="holding" selected>Holding Registers</option>
-      <option value="coil">Coils</option>
+      <option value="holding">Holding Registers (FC16)</option>
+      <option value="coil">Coils (FC15)</option>
       <option value="input">Input Registers</option>
       <option value="discrete">Discrete Inputs</option>
     </select>
@@ -45,21 +45,94 @@
     <label for="node-input-address"><i class="fa fa-map-marker"></i> Start Address</label>
     <input type="number" id="node-input-address" min="0" max="65535" placeholder="0">
   </div>
+  <div class="form-tips">
+    <b>Tip:</b> Send <code>msg.slaveId</code> to override the Slave ID at runtime.<br>
+    Send <code>msg.address</code> to override the start address.<br>
+    Payload: number, array, or JSON string <code>"[100,200,300]"</code>
+  </div>
 </script>
 
 <script type="text/html" data-help-name="modpackqt-slave-write">
-  <p>Writes values into a ModPackQT simulated slave register table via the ModPackQT Gateway app.</p>
-  <p>Calls <code>PATCH /api/slaves/:id/registers</code> on the gateway. The slave must be running.</p>
+  <p>
+    Push values into a <b>ModPackQT Slave</b> register table. Any external Modbus master that
+    connects to that slave will read whatever values you last wrote here.
+  </p>
+
+  <h3>Quick Setup — 4 steps</h3>
+  <ol>
+    <li>
+      <b>Create a free account</b> at
+      <a href="https://modpackqt.com" target="_blank">modpackqt.com</a>
+      (slave feature requires a paid plan — see below).
+    </li>
+    <li>
+      <b>Download and run the Gateway app.</b>
+      The gateway exposes a local REST API (default port <code>8502</code>) that this
+      node talks to. Open the ModPackQT app and click <em>Download Gateway</em>.
+    </li>
+    <li>
+      <b>Create a Slave</b> in the ModPackQT app:
+      go to <em>Slave Simulator</em> → <em>New Slave</em>, set a Modbus port (e.g. <code>502</code>),
+      then click <em>Start</em>. Copy the <b>Slave ID</b> shown in the app.
+    </li>
+    <li>
+      <b>Add a ModPackQT Config node</b> (click the pencil next to Gateway above),
+      set Host to <code>localhost</code> and Port to <code>8502</code>.
+      Paste your API key from <em>ModPackQT → Settings → API Keys</em>.
+    </li>
+  </ol>
+
+  <h3>Plan requirement</h3>
+  <p>
+    The Slave Simulator is a <b>paid-plan feature</b>.
+    Free accounts cannot create slaves. If you receive a <code>403</code> error,
+    your plan does not include slaves or you have reached your slave limit.
+    <a href="https://modpackqt.com/#pricing" target="_blank">View plans &amp; upgrade →</a>
+  </p>
+
   <h3>Inputs</h3>
   <dl class="message-properties">
-    <dt>payload <span class="property-type">number | array</span></dt>
-    <dd>Value(s) to write into the slave register table.</dd>
+    <dt>payload <span class="property-type">number | array | string</span></dt>
+    <dd>
+      Value(s) to write. Accepts: a single number (<code>42</code>),
+      an array (<code>[10, 20, 30]</code>), or a JSON string (<code>"[10,20,30]"</code>).
+      All values are converted to integers automatically.
+    </dd>
+    <dt class="optional">slaveId <span class="property-type">string | number</span></dt>
+    <dd>Overrides the Slave ID configured in the node editor.</dd>
+    <dt class="optional">address <span class="property-type">number</span></dt>
+    <dd>Overrides the start address configured in the node editor.</dd>
+    <dt class="optional">registerType <span class="property-type">string</span></dt>
+    <dd>Overrides the register type: <code>holding</code>, <code>coil</code>, <code>input</code>, or <code>discrete</code>.</dd>
   </dl>
+
   <h3>Outputs</h3>
   <dl class="message-properties">
     <dt>payload <span class="property-type">any</span></dt>
-    <dd>Original message passed through with <code>msg.success = true</code>.</dd>
+    <dd>Original message passed through unchanged.</dd>
+    <dt>success <span class="property-type">boolean</span></dt>
+    <dd><code>true</code> when the write succeeded.</dd>
+    <dt>valuesWritten <span class="property-type">array</span></dt>
+    <dd>The integer values that were written.</dd>
   </dl>
-  <h3>Details</h3>
-  <p><b>Slave ID</b> — the ID of the slave as configured in the ModPackQT app. The slave must be started before writing.</p>
+
+  <h3>Status messages</h3>
+  <ul>
+    <li><b>blue ring</b> — write in progress</li>
+    <li><b>green dot</b> — write succeeded, shows count + timestamp</li>
+    <li><b>red dot</b> — error (check API key / plan / gateway)</li>
+    <li><i>slave not found</i> — Slave ID is wrong or slave was deleted</li>
+    <li><i>gateway not running</i> — Gateway app is not started</li>
+  </ul>
+
+  <h3>Example use case</h3>
+  <p>
+    Read temperature from an MQTT topic → convert to integer → send to this node.
+    Any PLC or SCADA system on the network can then read that temperature via
+    standard Modbus TCP from the ModPackQT slave port.
+  </p>
+
+  <p>
+    <a href="https://modpackqt.com/node-red" target="_blank">Full documentation &amp; example flows →</a>
+  </p>
 </script>

package/nodes/modpackqt-slave-write.js

@@ -6,29 +6,56 @@ module.exports = function(RED) {
 
     node.slaveId      = config.slaveId      || '';
     node.registerType = config.registerType || 'holding';
-    node.address      = parseInt(config.address) || 0;
+    node.address      = parseInt(config.address, 10) || 0;
 
     node.on('input', async function(msg) {
       if (!server) {
-        node.status({ fill: 'red', shape: 'ring', text: 'no config' });
+        node.status({ fill: 'red', shape: 'ring', text: 'no config — add a ModPackQT Config node' });
         return;
       }
-      if (!node.slaveId) {
+
+      const slaveId = msg.slaveId || node.slaveId;
+      if (!slaveId) {
         node.status({ fill: 'red', shape: 'ring', text: 'slave ID required' });
+        node.error('No Slave ID set. Configure it in the node or send msg.slaveId.', msg);
         return;
       }
+
       try {
-        const values = Array.isArray(msg.payload) ? msg.payload : [msg.payload];
-        await server.request('PATCH', `/api/slaves/${encodeURIComponent(node.slaveId)}/registers`, {
-          registerType: node.registerType,
-          address:      node.address,
+        // Accept string JSON ("[100,200]"), plain number string, actual array, or number
+        let raw = msg.payload;
+        if (typeof raw === 'string') {
+          try { raw = JSON.parse(raw); } catch (_) { raw = Number(raw); }
+        }
+
+        // Always convert every value to an integer to avoid encoding corruption
+        const values = Array.isArray(raw)
+          ? raw.map(v => parseInt(v, 10))
+          : [parseInt(raw, 10)];
+
+        if (values.some(v => isNaN(v))) {
+          throw new Error(`Invalid payload — expected number or array of numbers, got: ${JSON.stringify(msg.payload)}`);
+        }
+
+        node.status({ fill: 'blue', shape: 'ring', text: `writing ${values.length} value(s)…` });
+
+        await server.request('PATCH', `/api/slaves/${encodeURIComponent(slaveId)}/registers`, {
+          registerType: msg.registerType || node.registerType,
+          address:      msg.address      !== undefined ? parseInt(msg.address, 10) : node.address,
           values
         });
-        node.status({ fill: 'green', shape: 'dot', text: `${node.registerType} @${node.address}` });
+
+        const now = new Date().toLocaleTimeString();
+        node.status({ fill: 'green', shape: 'dot', text: `wrote ${values.length} @ addr ${node.address} · ${now}` });
         msg.success = true;
+        msg.valuesWritten = values;
         node.send(msg);
       } catch (err) {
-        node.status({ fill: 'red', shape: 'dot', text: err.message });
+        const hint = err.message.includes('403') ? 'check API key / plan limit'
+          : err.message.includes('404') ? 'slave not found — check Slave ID'
+          : err.message.includes('ECONNREFUSED') ? 'gateway not running'
+          : err.message;
+        node.status({ fill: 'red', shape: 'dot', text: hint });
         node.error(err.message, msg);
       }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-modbus-modpackqt",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Node-RED nodes for ModPackQT — read/write Modbus TCP registers (master & slave) via the ModPackQT Gateway app. Supports FC1/FC2/FC3/FC4 reads and FC5/FC6/FC15/FC16 writes.",
   "keywords": [
     "node-red",