@fa_yoshinobu/node-red-contrib-plc-comm-slmp 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.2.1 - 2026-03-28
+
+- move npm package publishing to the scoped name `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`
+- refresh README and user documentation for Flow Library submission, npm badges, and scoped install commands
+
+## 0.2.0 - 2026-03-28
+
+- add `slmp-connection`, `slmp-read`, and `slmp-write` nodes for binary 3E/4E over TCP and UDP
+- add named address helpers including `,count`, string access, route overrides, and connection control messages
+- add editor validation, example flows, README improvements, and user/maintainer documentation
+- add local test coverage and package dry-run validation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yoshinobu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# Node-RED SLMP Nodes for Mitsubishi PLCs
+
+[![CI](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/actions/workflows/ci.yml/badge.svg)](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40fa_yoshinobu%2Fnode-red-contrib-plc-comm-slmp?logo=npm&color=CB3837)](https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp)
+[![npm downloads](https://img.shields.io/npm/dm/%40fa_yoshinobu%2Fnode-red-contrib-plc-comm-slmp?logo=npm&color=CB3837)](https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp)
+![Node-RED version](https://img.shields.io/badge/Node--RED-%E2%89%A53.0-B41F27?logo=nodered&logoColor=white)
+![Node.js version](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=node.js&logoColor=white)
+![SLMP frame](https://img.shields.io/badge/SLMP-Binary%203E%20%2F%204E-005BAC)
+![Transport](https://img.shields.io/badge/Transport-TCP%20%2F%20UDP-0A7D5C)
+![License](https://img.shields.io/badge/License-MIT-1F6FEB)
+
+![Node-RED SLMP hero](https://raw.githubusercontent.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/main/docsrc/assets/node-red-slmp.png)
+
+Node-RED nodes for Mitsubishi PLC communication over SLMP binary 3E/4E frames.
+
+This package uses the same named-device foundation as the SLMP libraries, extended here with Node-RED-friendly count and string forms:
+
+- `D100`
+- `D100,10`
+- `D200:F`
+- `D200:F,4`
+- `D300:L`
+- `D50.3`
+- `M1000`
+- `M1000,8`
+- `D100:STR,10`
+- `DSTR100,10`
+
+## Quick start
+
+1. Install the package into your Node-RED user directory and restart Node-RED.
+2. Add one `slmp-connection` config node and set `host`, `port`, `transport`, `PLC series`, and `frame type`.
+3. Add `slmp-read` for the first smoke test, using a safe address such as `D300`, `D300,4`, or `DSTR320,10`.
+4. When read works, add `slmp-write` and use known-safe test devices before moving to production addresses.
+
+If you are working from this repository, import one of the ready-to-run flows under [examples/flows](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/README.md) first. The safest first choices are:
+
+- [`slmp-basic-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-basic-read-write.json) for plain TCP scalar read/write
+- [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json) for `,count` and string access
+- [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json) for one-by-one high-level coverage across the matrix catalog
+- [`slmp-udp-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-udp-read-write.json) for UDP validation
+
+## Release information
+
+- package name: `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`
+- package version: `0.2.1`
+- npm package: <https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp>
+- Node-RED requirement: `>=3.0.0`
+- Node.js requirement: `>=18`
+- changelog: <https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/CHANGELOG.md>
+
+Install from npm:
+
+```bash
+cd ~/.node-red
+npm install @fa_yoshinobu/node-red-contrib-plc-comm-slmp
+```
+
+Install from this repository:
+
+```bash
+cd ~/.node-red
+npm install /path/to/node-red-contrib-plc-comm-slmp
+```
+
+Legacy note:
+
+- the original unscoped `node-red-contrib-plc-comm-slmp@0.2.0` remains on npm, but new releases move to the scoped package name above
+
+## Documentation
+
+- [User Guide](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/USER_GUIDE.md)
+- [Example Flows](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/README.md)
+- [Future Device Support](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/TODO.md)
+- [Maintainer Notes](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/maintainer/ARCHITECTURE.md)
+- [Validation Reports Directory](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/tree/main/docsrc/validation/reports)
+- [Documentation Index](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/index.md)
+
+## Current scope
+
+- Binary 3E and 4E frames
+- TCP and UDP transport
+- Reusable `slmp-connection` config node
+- `slmp-read` node powered by `readNamed`
+- `slmp-write` node powered by `writeNamed`
+- typed source selection for literal / `msg` / `flow` / `global` / `env`
+- per-request routing via `msg.target` or configured route sources
+- read output selection for object / array / single value
+- metadata emission selection for `msg.slmp`: `full` / `minimal` / `off`
+- configurable error handling with throw / `msg.error` / second output
+- connection control via `connect` / `disconnect` / `reinitialize` messages
+- editor-side validation for connection ranges, literal addresses, literal updates, and route JSON
+- importable example flow under `examples/flows/`
+- Local tests for codec and high-level helpers
+
+Set `frame type` and `PLC series` explicitly for each connection.
+
+Validated PLC models:
+
+- `FX5UC-32MT/D`
+- `Q06UDVCPU`
+- `R08CPU`
+
+## Supported devices
+
+Supported bit devices:
+
+- `SM`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`
+- `TS`, `TC`, `STS`, `STC`
+- `CS`, `CC`
+- `SB`, `DX`, `DY`
+
+Supported word devices:
+
+- `SD`, `D`, `W`
+- `TN`, `LTN`, `STN`, `LSTN`
+- `CN`, `LCN`
+- `SW`
+- `Z`
+- `R`, `ZR`, `RD`
+
+Address notes:
+
+- `X`, `Y`, `B`, `W`, `SB`, `SW`, `DX`, and `DY` use hexadecimal device numbers
+- most other devices use decimal numbers
+- word devices support `.bit`, for example `D50.3`
+- count and string forms work on supported devices, for example `D300,10`, `M1000,8`, and `DSTR320,10`
+- `LTN`, `LSTN`, and `LCN` default to 32-bit current-value access in the high-level nodes
+- future device support candidates such as `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, `LZ`, `G`, and `HG` are tracked in the [Future Device Support list](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/TODO.md)
+
+## Nodes
+
+### `slmp-connection`
+
+Holds the transport and SLMP profile settings:
+
+- host / port
+- transport: `tcp` or `udp`
+- timeout in milliseconds
+- PLC series: `ql` or `iqr`
+- frame type: `3e` or `4e`
+- target routing fields
+
+### `slmp-read`
+
+Reads one or more addresses and writes the result to `msg.payload`.
+
+Configured addresses can be overridden by:
+
+- `msg.addresses` as an array or string
+- `msg.payload` as an array or string
+
+Configured source modes:
+
+- literal editor text
+- `msg`
+- `flow`
+- `global`
+- `env`
+
+Examples:
+
+```text
+D100
+D100,10
+D200:F
+D200:F,4
+D50.3
+M1000
+M1000,8
+D100:STR,10
+DSTR100,10
+```
+
+Notes:
+
+- `,count` returns an array for numeric and direct-bit reads
+- `:STR,<length>` reads or writes a UTF-8 byte string packed two bytes per word
+- `DSTR100,10` is accepted as a compatibility alias for `D100:STR,10`
+- `LTN`, `LSTN`, and `LCN` use high-level 32-bit current values by default
+- when you send multiple addresses as a string, newline-separated input is the clearest form
+- per-request routing can be supplied as `msg.target`, `msg.slmp.target`, or a configured route source
+- metadata mode can keep full `msg.slmp`, emit only `target` plus `itemCount`, or leave `msg.slmp` unchanged
+- read errors can throw, attach to `msg.error`, or go to a second output
+- output can be object, array, or single value when one address is requested
+- send `msg.connect`, `msg.disconnect`, or `msg.reinitialize` as `true`, or use `msg.topic`, to control the shared connection
+
+### `slmp-write`
+
+Writes one or more addresses.
+
+Preferred dynamic input:
+
+```json
+{
+  "D100": 42,
+  "D100,3": [10, 11, 12],
+  "D200:F": 3.14,
+  "D200:F,2": [1.25, -2.5],
+  "D50.3": true,
+  "D100:STR,10": "HELLO"
+}
+```
+
+Accepted sources:
+
+- `msg.updates`
+- `msg.payload`
+- `msg.address` + optional `msg.dtype` + `msg.value`
+- static JSON or `address=value` lines in the editor
+- configured `msg` / `flow` / `global` / `env` sources
+
+Write errors can throw, attach to `msg.error`, or go to a second output.
+Send `msg.connect`, `msg.disconnect`, or `msg.reinitialize` to control the shared connection from the write node too.
+Route overrides use the same `target` object shape as reads.
+Metadata mode can keep full `msg.slmp`, emit only `target` plus `itemCount`, or leave `msg.slmp` unchanged.
+
+## Route overrides
+
+Use a `target` object when one request needs a different route than the shared connection default:
+
+```json
+{
+  "addresses": ["D300,4", "DSTR320,10"],
+  "target": {
+    "network": 0,
+    "station": 255,
+    "moduleIO": "03FF",
+    "multidrop": 0
+  }
+}
+```
+
+The editor validates connection ranges, literal address lists, literal update payloads, and literal route JSON before save.
+
+## Example flows
+
+Read:
+
+```json
+{
+  "addresses": ["D100", "D100,3", "D200:F", "D200:F,2", "D50.3", "D100:STR,10"]
+}
+```
+
+Write:
+
+```json
+{
+  "payload": {
+    "D100": 42,
+    "D100,3": [10, 11, 12],
+    "D50.3": true,
+    "D100:STR,10": "HELLO"
+  }
+}
+```
+
+Import one of the ready-to-run flows under [examples/flows](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/README.md):
+
+- [`slmp-demo.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-demo.json): combined demo
+- [`slmp-basic-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-basic-read-write.json): scalar, float, and bit read/write over TCP
+- [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json): array and string read/write over TCP
+- [`slmp-control-error.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-control-error.json): control messages, `msg` source, and second-output errors
+- [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json): one-by-one high-level read, write, and readback across the matrix catalog with completed-result history, run summary, and JSONL logging in `Node-RED userDir/logs/slmp-device-matrix-<session>.jsonl`
+- [`slmp-routing.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-routing.json): per-request routing with `msg.target`
+- [`slmp-udp-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-udp-read-write.json): basic UDP read/write
+
+Recommended first import:
+
+- start with [`slmp-basic-read-write.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-basic-read-write.json) if you only need to confirm a single PLC over TCP
+- use [`slmp-array-string.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-array-string.json) when you want to validate `,count` and string handling immediately
+- use [`slmp-device-matrix.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-device-matrix.json) when you need to step through the matrix catalog one by one from the high-level nodes and keep a persistent verification log
+- use [`slmp-control-error.json`](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/examples/flows/slmp-control-error.json) when you need `msg`-driven addresses, control messages, or second-output error routing
+
+## Known limitations
+
+- Set `frame type` and `PLC series` explicitly for each connection
+- `.bit,count` is not supported
+- A single client connection keeps requests serialized by default
+- Future high-level device support candidates are tracked in the [Future Device Support list](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/TODO.md)
+
+## Development
+
+Run the local test suite:
+
+```bash
+cmd /c npm.cmd test
+```
+
+## Notes
+
+- `.bit` notation is only valid for word devices such as `D50.3`
+- Direct bit devices should be addressed directly as `M1000`, `X1F`, `Y20`
+- Random read batching follows the Python helper layer for batchable word devices

package/docsrc/assets/README.md

@@ -0,0 +1,10 @@
+# Assets
+
+See also:
+
+- [Project README](../../README.md)
+- [Documentation Index](../index.md)
+
+Place shared documentation assets for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp` here.
+
+- `node-red-slmp.png`: README hero image for the Node-RED SLMP package

package/docsrc/index.md

@@ -0,0 +1,11 @@
+# Documentation Index
+
+Documentation landing page for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`.
+
+- [Project README](../README.md)
+- [Changelog](../CHANGELOG.md)
+- [Future Device Support](../TODO.md)
+- [User Guide](user/USER_GUIDE.md)
+- [Example Flows](../examples/flows/README.md)
+- [Maintainer Notes](maintainer/ARCHITECTURE.md)
+- [Validation Reports](validation/reports/README.md)

package/docsrc/maintainer/ARCHITECTURE.md

@@ -0,0 +1,36 @@
+# Node-RED SLMP Architecture
+
+See also:
+
+- [Project README](../../README.md)
+- [User Guide](../user/USER_GUIDE.md)
+- [Changelog](../../CHANGELOG.md)
+- [Documentation Index](../index.md)
+
+This package has three layers:
+
+1. `lib/slmp/core.js`
+   Encodes and decodes SLMP frames, devices, and response payloads.
+
+2. `lib/slmp/client.js` and `lib/slmp/high-level.js`
+   Provide the transport client plus the high-level named read/write helpers used by the nodes.
+
+3. `nodes/*.js` and `nodes/*.html`
+   Expose the Node-RED config, read, and write nodes.
+
+## Request policy
+
+Requests are serialized by default on a single client connection, including 4E.
+This matches the behavior observed on the current validation PLC more reliably than assuming multiple in-flight requests on one socket.
+
+## High-level behavior
+
+- contiguous words and bits are coalesced into block reads when practical
+- sparse word and dword reads use random read
+- writes are batched where the protocol path supports it
+
+## Runtime structure
+
+- `slmp-connection` owns the reusable client instance
+- `slmp-read` resolves addresses and writes results to `msg.payload`
+- `slmp-write` resolves updates and applies them through `writeNamed`

package/docsrc/user/USER_GUIDE.md

@@ -0,0 +1,238 @@
+# User Guide
+
+See also:
+
+- [Project README](../../README.md)
+- [Changelog](../../CHANGELOG.md)
+- [Future Device Support](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/TODO.md)
+- [Documentation Index](../index.md)
+- [Example Flows](../../examples/flows/README.md)
+
+## Purpose
+
+`@fa_yoshinobu/node-red-contrib-plc-comm-slmp` provides Node-RED nodes for Mitsubishi PLC communication over binary SLMP 3E/4E.
+
+## Quick start
+
+1. Install the package into your Node-RED user directory and restart Node-RED.
+2. Create one `slmp-connection` and set `host`, `port`, `transport`, `PLC series`, and `frame type`.
+3. Drop in `slmp-read` and try a safe address such as `D300`, `D300,4`, or `DSTR320,10`.
+4. Once reads work, add `slmp-write` and verify with known-safe test devices.
+
+npm package:
+
+- <https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-slmp>
+
+If you are starting from the example flows in this repository, import these in this order:
+
+- [`slmp-basic-read-write.json`](../../examples/flows/slmp-basic-read-write.json)
+- [`slmp-array-string.json`](../../examples/flows/slmp-array-string.json)
+- [`slmp-device-matrix.json`](../../examples/flows/slmp-device-matrix.json)
+- [`slmp-control-error.json`](../../examples/flows/slmp-control-error.json)
+- [`slmp-udp-read-write.json`](../../examples/flows/slmp-udp-read-write.json)
+
+## Available nodes
+
+- `slmp-connection`
+- `slmp-read`
+- `slmp-write`
+
+The package also ships importable example flows:
+
+- [`slmp-demo.json`](../../examples/flows/slmp-demo.json)
+- [`slmp-basic-read-write.json`](../../examples/flows/slmp-basic-read-write.json)
+- [`slmp-array-string.json`](../../examples/flows/slmp-array-string.json)
+- [`slmp-control-error.json`](../../examples/flows/slmp-control-error.json)
+- [`slmp-device-matrix.json`](../../examples/flows/slmp-device-matrix.json)
+- [`slmp-routing.json`](../../examples/flows/slmp-routing.json)
+- [`slmp-udp-read-write.json`](../../examples/flows/slmp-udp-read-write.json)
+
+## Connection settings
+
+Configure these explicitly on the connection node:
+
+- host
+- port
+- transport: `tcp` or `udp`
+- PLC series: `ql` or `iqr`
+- frame type: `3e` or `4e`
+- route fields: network, station, module I/O, multidrop
+
+Validated PLC models:
+
+- `FX5UC-32MT/D`
+- `Q06UDVCPU`
+- `R08CPU`
+
+## Supported devices
+
+Supported bit devices:
+
+- `SM`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`
+- `TS`, `TC`, `STS`, `STC`
+- `CS`, `CC`
+- `SB`, `DX`, `DY`
+
+Supported word devices:
+
+- `SD`, `D`, `W`
+- `TN`, `LTN`, `STN`, `LSTN`
+- `CN`, `LCN`
+- `SW`
+- `Z`
+- `R`, `ZR`, `RD`
+
+Address notes:
+
+- `X`, `Y`, `B`, `W`, `SB`, `SW`, `DX`, and `DY` use hexadecimal numbering
+- most other devices use decimal numbering
+- word devices support `.bit`, for example `D50.3`
+- count and string forms work on supported devices, for example `D300,10`, `M1000,8`, and `DSTR320,10`
+- `LTN`, `LSTN`, and `LCN` default to 32-bit current-value access in the high-level nodes
+- future device support candidates such as `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, `LZ`, `G`, and `HG` are tracked in [`TODO.md`](../../TODO.md)
+
+## Address model
+
+The high-level address grammar keeps the same named-device foundation as the SLMP Python and .NET libraries, then extends it for Node-RED count and string inputs:
+
+- `D100`
+- `D100,10`
+- `D200:F`
+- `D200:F,4`
+- `D300:L`
+- `D50.3`
+- `M1000`
+- `M1000,8`
+- `D100:STR,10`
+- `DSTR100,10`
+
+Rules:
+
+- `,count` returns an array for direct-bit, word, and DWord reads
+- `:STR,<length>` reads or writes a UTF-8 byte string packed two bytes per word
+- `DSTR100,10` is accepted as a compatibility alias for `D100:STR,10`
+- `.bit` stays scalar-only, so `.bit,count` is not supported
+- `LTN`, `LSTN`, and `LCN` use high-level 32-bit current values by default
+
+## Dynamic inputs
+
+Read accepts:
+
+- `msg.addresses`
+- `msg.payload`
+- `msg.target` or `msg.slmp.target` for per-request routing
+
+Configured source modes:
+
+- literal editor text
+- `msg`
+- `flow`
+- `global`
+- `env`
+
+When a read input is a string, newline-separated addresses are the clearest form:
+
+```text
+D100
+D100,10
+D200:F,4
+D100:STR,10
+```
+
+Write accepts:
+
+- `msg.updates`
+- `msg.payload`
+- `msg.address` with optional `msg.dtype` and `msg.value`
+- `msg.target` or `msg.slmp.target` for per-request routing
+- configured `msg` / `flow` / `global` / `env` sources
+
+Examples:
+
+```json
+{
+  "D100": 42,
+  "D100,3": [10, 11, 12],
+  "D200:F,2": [1.25, -2.5],
+  "M1000,4": [true, false, true, false],
+  "D100:STR,10": "HELLO"
+}
+```
+
+## Output and errors
+
+Read output modes:
+
+- `object`
+- `array`
+- `value` when exactly one address is requested
+
+Metadata modes:
+
+- `full`: emit `addresses` or `updates`, connection profile, and effective target in `msg.slmp`
+- `minimal`: emit only the effective `target`, `itemCount`, and `metadataMode` in `msg.slmp`
+- `off`: leave `msg.slmp` unchanged
+
+Read and write error modes:
+
+- throw
+- attach the error to `msg.error`
+- emit the failed message on the second output
+
+## Per-request routing
+
+Use a `target` object when one read or write must override the connection node route:
+
+```json
+{
+  "target": {
+    "network": 0,
+    "station": 255,
+    "moduleIO": "03FF",
+    "multidrop": 0
+  }
+}
+```
+
+You can supply that object through:
+
+- `msg.target`
+- `msg.slmp.target`
+- a configured route source using literal JSON, `msg`, `flow`, `global`, or `env`
+
+## Connection control
+
+Send any of these to `slmp-read` or `slmp-write`:
+
+- `msg.connect = true`
+- `msg.disconnect = true`
+- `msg.reinitialize = true`
+- or `msg.topic = "connect" | "disconnect" | "reinitialize"`
+
+## Example flows
+
+Import one of these into Node-RED, then update the connection host, port, transport, and safe device addresses before deploy:
+
+- [`slmp-demo.json`](../../examples/flows/slmp-demo.json): combined demo
+- [`slmp-basic-read-write.json`](../../examples/flows/slmp-basic-read-write.json): scalar, float, and bit read/write over TCP
+- [`slmp-array-string.json`](../../examples/flows/slmp-array-string.json): array and string read/write over TCP
+- [`slmp-control-error.json`](../../examples/flows/slmp-control-error.json): control messages, configured `msg` source, and second-output errors
+- [`slmp-device-matrix.json`](../../examples/flows/slmp-device-matrix.json): one-by-one high-level read, write, and readback across the matrix catalog with completed-result history, run summary, and JSONL logging under `Node-RED userDir/logs/slmp-device-matrix-<session>.jsonl`
+- [`slmp-routing.json`](../../examples/flows/slmp-routing.json): per-request routing with `msg.target`
+- [`slmp-udp-read-write.json`](../../examples/flows/slmp-udp-read-write.json): basic UDP read/write
+
+Recommended first import:
+
+- start with [`slmp-basic-read-write.json`](../../examples/flows/slmp-basic-read-write.json) for plain TCP smoke testing
+- move to [`slmp-array-string.json`](../../examples/flows/slmp-array-string.json) when you want to validate `,count` and string access
+- move to [`slmp-device-matrix.json`](../../examples/flows/slmp-device-matrix.json) when you want one-by-one high-level coverage across the matrix catalog and a persistent verification log
+- use [`slmp-control-error.json`](../../examples/flows/slmp-control-error.json) for `msg`-driven addresses, control messages, and second-output error routing
+
+## Notes
+
+- `.bit` notation is only valid on word devices such as `D50.3`
+- `.bit,count` is not supported
+- direct bit devices should be addressed directly as `M1000`, `X1F`, or `Y20`
+- a single client connection keeps requests serialized by default
+- read/write errors can throw, attach to `msg.error`, or go to a second output
+- the editor validates connection ranges, literal address lists, literal update payloads, and literal route JSON before save

package/docsrc/user/toc.yml

@@ -0,0 +1,2 @@
+- name: User Guide
+  href: USER_GUIDE.md

package/docsrc/validation/reports/README.md

@@ -0,0 +1,15 @@
+# Validation Reports
+
+See also:
+
+- [Project README](../../../README.md)
+- [User Guide](../../user/USER_GUIDE.md)
+- [Documentation Index](../../index.md)
+
+Place captured validation reports for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp` in this directory.
+
+Typical content:
+
+- hardware verification notes
+- benchmark summaries
+- regression validation results

package/examples/flows/README.md

@@ -0,0 +1,24 @@
+# Example Flows
+
+See also:
+
+- [Project README](../../README.md)
+- [User Guide](../../docsrc/user/USER_GUIDE.md)
+- [Documentation Index](../../docsrc/index.md)
+
+Import one of these files into Node-RED, then update the connection host, port, transport, and safe device addresses for the target PLC before deploy.
+
+Start here:
+
+- [`slmp-basic-read-write.json`](slmp-basic-read-write.json) for the first TCP smoke test
+- [`slmp-array-string.json`](slmp-array-string.json) when you want to check `,count` and `DSTR`
+- [`slmp-device-matrix.json`](slmp-device-matrix.json) when you want one-by-one high-level coverage across the matrix catalog with persistent JSONL logging, pending tracking, and timeout detection
+- [`slmp-udp-read-write.json`](slmp-udp-read-write.json) when you need UDP first
+
+- [`slmp-demo.json`](slmp-demo.json): combined demo with control messages, array read, string read, and error second output
+- [`slmp-basic-read-write.json`](slmp-basic-read-write.json): basic TCP read and write with scalar, float, and word-bit examples
+- [`slmp-array-string.json`](slmp-array-string.json): TCP array and string read/write examples using `,count` and `DSTR`
+- [`slmp-control-error.json`](slmp-control-error.json): connection control, configured `msg` source, and second-output error routing
+- [`slmp-device-matrix.json`](slmp-device-matrix.json): one-by-one high-level read, write, and readback across the matrix catalog with completed-result history, run summary, and `logs/slmp-device-matrix-<session>.jsonl`
+- [`slmp-routing.json`](slmp-routing.json): per-request routing using `msg.lookup` and `msg.target`
+- [`slmp-udp-read-write.json`](slmp-udp-read-write.json): basic UDP read and write example