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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.3 - 2026-04-13
+
+- CI now checks out `plc-comm-slmp-cross-verify/specs/shared` before running the shared-vector tests, so the Node package validates against the canonical cross-library parity vectors.
+
+## 0.2.2 - 2026-04-01
+
+- add an optional `npm run smoke:editor` script that installs the local package into an isolated userDir, starts a temporary Node-RED runtime, imports `slmp-basic-read-write.json`, and verifies the flow starts cleanly
+- refresh README, user guide, and example-flow docs with the editor-smoke command and the current canonical-address helper exports
+
 ## 0.2.1 - 2026-03-28
 
 - move npm package publishing to the scoped name `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`

package/LICENSE

@@ -1,21 +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.
+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

@@ -1,5 +1,3 @@
-# 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)
@@ -9,6 +7,8 @@
 ![Transport](https://img.shields.io/badge/Transport-TCP%20%2F%20UDP-0A7D5C)
 ![License](https://img.shields.io/badge/License-MIT-1F6FEB)
 
+# Node-RED SLMP Nodes for Mitsubishi PLCs
+
 ![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.
@@ -26,7 +26,13 @@ This package uses the same named-device foundation as the SLMP libraries, extend
 - `D100:STR,10`
 - `DSTR100,10`
 
-## Quick start
+This package is documented for the high-level Node-RED workflow only:
+
+- `slmp-connection`
+- `slmp-read`
+- `slmp-write`
+
+## 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`.
@@ -40,10 +46,12 @@ If you are working from this repository, import one of the ready-to-run flows un
 - [`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
+Start with `D` word devices for the first smoke test. Do not start with `slmp-device-matrix.json`.
+
+## Release Information
 
 - package name: `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`
-- package version: `0.2.1`
+- package version: `0.2.3`
 - 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`
@@ -63,200 +71,71 @@ cd ~/.node-red
 npm install /path/to/node-red-contrib-plc-comm-slmp
 ```
 
+Optional local editor smoke test from the repository root:
+
+```bash
+npm run smoke:editor
+```
+
+This command installs the local package into an isolated temporary userDir, starts a temporary Node-RED runtime, imports `slmp-basic-read-write.json`, verifies the flow starts, and then shuts the runtime down again.
+
 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
 
+## Supported PLC Registers
+
+Start with these register/device families first:
+
+- word devices: `D`, `SD`, `R`, `ZR`, `TN`, `CN`
+- bit devices: `M`, `X`, `Y`, `SM`, `B`
+- typed forms: `D200:F`, `D300:L`
+- special Node-RED forms: `D100,10`, `M1000,8`, `D100:STR,10`, `DSTR100,10`
+- bit-in-word form: `D50.3`
+
+See the full public table in [Supported PLC Registers](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/SUPPORTED_REGISTERS.md).
+
 ## Documentation
 
+- [Getting Started](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/GETTING_STARTED.md)
+- [Supported PLC Registers](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/SUPPORTED_REGISTERS.md)
+- [Latest Communication Verification](https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-slmp/blob/main/docsrc/user/LATEST_COMMUNICATION_VERIFICATION.md)
 - [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
+Maintainer-only notes and retained evidence live under `internal_docs/`.
+
+## What You Can Do
 
 - 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`
+- reusable `slmp-connection`
+- high-level reads and writes through `slmp-read` and `slmp-write`
 - 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`
+- metadata emission selection for `msg.slmp`
 - 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:
+## Current Public Register Scope
+
+- bit devices: `SM`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`, `TS`, `TC`, `STS`, `STC`, `CS`, `CC`, `SB`, `DX`, `DY`
+- word devices: `SD`, `D`, `W`, `TN`, `LTN`, `STN`, `LSTN`, `CN`, `LCN`, `SW`, `Z`, `R`, `ZR`, `RD`
+- typed views: `:S`, `:D`, `:L`, `:F`
+- string/count views: `,count`, `:STR`, `DSTR`
+- word-bit view: `.bit`
+
+Validated public hardware summary:
 
 - `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):
+## Example Flows
 
 - [`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
@@ -266,19 +145,13 @@ Import one of the ready-to-run flows under [examples/flows](https://github.com/f
 - [`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
+## Known Limitations
 
-- Set `frame type` and `PLC series` explicitly for each connection
+- 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)
+- a single client connection keeps requests serialized by default
+- the read and write nodes keep the caller-visible logical request shape and do not silently retry with a different fallback split semantics
+- `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, `LZ`, `G`, and `HG` are not part of the current public high-level register table
 
 ## Development
 
@@ -291,5 +164,5 @@ 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
+- 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/index.md

@@ -4,8 +4,8 @@ Documentation landing page for `@fa_yoshinobu/node-red-contrib-plc-comm-slmp`.
 
 - [Project README](../README.md)
 - [Changelog](../CHANGELOG.md)
-- [Future Device Support](../TODO.md)
+- [Getting Started](user/GETTING_STARTED.md)
+- [Supported PLC Registers](user/SUPPORTED_REGISTERS.md)
+- [Latest Communication Verification](user/LATEST_COMMUNICATION_VERIFICATION.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/user/GETTING_STARTED.md

@@ -0,0 +1,87 @@
+# Getting Started
+
+## Start Here
+
+Use this package when you want the shortest Node-RED path to Mitsubishi SLMP communication through the public high-level nodes.
+
+Recommended first path:
+
+1. Install the package into your Node-RED user directory.
+2. Restart Node-RED.
+3. Add one `slmp-connection` config node.
+4. Set `host`, `port`, `transport`, `PLC series`, and `frame type`.
+5. Import `examples/flows/slmp-basic-read-write.json`.
+6. Replace the host and safe test addresses.
+7. Deploy and confirm that one `D` read succeeds.
+
+## First PLC Registers To Try
+
+Start with these first:
+
+- `D100`
+- `D100,4`
+- `D200:F`
+- `D300:L`
+- `D50.3`
+- `M1000`
+
+These stay on the public high-level surface and avoid the more complex routing and validation cases.
+
+Do not start with these:
+
+- `slmp-device-matrix.json`
+- routed or multi-station requests
+- future-tracked families such as `G`, `HG`, `LTS`, `LTC`, `LSTS`, `LSTC`, `LCS`, `LCC`, `LZ`
+
+## First Connection Checklist
+
+Set these fields explicitly on `slmp-connection`:
+
+- `host`
+- `port`
+- `transport`
+- `PLC series`
+- `frame type`
+- timeout
+
+If you do not already know a safe writable area, start with reads only.
+
+## First Successful Run
+
+The easiest sequence is:
+
+1. Import `slmp-basic-read-write.json`.
+2. Use a safe word address such as `D100`.
+3. Deploy.
+4. Confirm that `msg.payload` returns a scalar word value.
+5. Move to `slmp-array-string.json` only after the first read is stable.
+
+Expected result:
+
+- the flow deploys without editor validation errors
+- the read node returns a value in `msg.payload`
+- the connection node remains stable across repeated injects
+
+## What To Try Next
+
+After the basic flow succeeds:
+
+- import `slmp-array-string.json` for `,count` and string handling
+- use `slmp-udp-read-write.json` when you want to confirm UDP
+- use `slmp-device-matrix.json` only when you need one-by-one coverage across the public matrix
+
+## Common Beginner Checks
+
+If the first read fails, check these in order:
+
+- correct `PLC series`
+- correct `frame type`
+- correct `tcp` or `udp` selection
+- a simple `D` address instead of a typed, count, or string form
+- editor validation messages before deploy
+
+## Next Pages
+
+- [Supported PLC Registers](./SUPPORTED_REGISTERS.md)
+- [Latest Communication Verification](./LATEST_COMMUNICATION_VERIFICATION.md)
+- [User Guide](./USER_GUIDE.md)

package/docsrc/user/LATEST_COMMUNICATION_VERIFICATION.md

@@ -0,0 +1,28 @@
+# Latest Communication Verification
+
+This page keeps the current public summary only. Older detailed notes are not kept in the public documentation set.
+
+## Current Retained Summary
+
+- verified PLC models: `FX5UC-32MT/D`, `Q06UDVCPU`, `R08CPU`
+- verified transports: `TCP`, `UDP`
+- verified public nodes: `slmp-connection`, `slmp-read`, `slmp-write`
+- retained first-run smoke path: `slmp-basic-read-write.json`
+
+## Confirmed Public Register Scope
+
+- bit devices: `SM`, `X`, `Y`, `M`, `L`, `F`, `V`, `B`, `TS`, `TC`, `STS`, `STC`, `CS`, `CC`, `SB`, `DX`, `DY`
+- word devices: `SD`, `D`, `W`, `TN`, `LTN`, `STN`, `LSTN`, `CN`, `LCN`, `SW`, `Z`, `R`, `ZR`, `RD`
+- typed forms: `:S`, `:D`, `:L`, `:F`
+- high-level special forms: `.bit`, `,count`, `:STR`, `DSTR`
+
+## Practical Cautions
+
+- set `PLC series` and `frame type` explicitly for every connection
+- start with `D` reads before using typed, counted, or string forms
+- keep `slmp-device-matrix.json` for later verification, not for the first smoke test
+- `.bit,count` is not part of the current public high-level surface
+
+## Where Older Evidence Went
+
+Public historical report clutter was removed. Maintainer-only retained evidence now belongs under `internal_docs/`.

package/docsrc/user/SUPPORTED_REGISTERS.md

@@ -0,0 +1,81 @@
+# Supported PLC Registers
+
+This page is the canonical public register/device table for the Node-RED high-level nodes.
+
+## Supported Bit Devices
+
+| Family | Kind | Example | Numbering |
+| --- | --- | --- | --- |
+| `SM` | bit | `SM400` | decimal |
+| `X` | bit | `X20` | hexadecimal |
+| `Y` | bit | `Y20` | hexadecimal |
+| `M` | bit | `M1000` | decimal |
+| `L` | bit | `L100` | decimal |
+| `F` | bit | `F10` | decimal |
+| `V` | bit | `V10` | decimal |
+| `B` | bit | `B20` | hexadecimal |
+| `TS` | bit | `TS10` | decimal |
+| `TC` | bit | `TC10` | decimal |
+| `STS` | bit | `STS10` | decimal |
+| `STC` | bit | `STC10` | decimal |
+| `CS` | bit | `CS10` | decimal |
+| `CC` | bit | `CC10` | decimal |
+| `SB` | bit | `SB20` | hexadecimal |
+| `DX` | bit | `DX20` | hexadecimal |
+| `DY` | bit | `DY20` | hexadecimal |
+
+## Supported Word Devices
+
+| Family | Kind | Example | Numbering |
+| --- | --- | --- | --- |
+| `SD` | word | `SD100` | decimal |
+| `D` | word | `D100` | decimal |
+| `W` | word | `W20` | hexadecimal |
+| `TN` | word | `TN10` | decimal |
+| `LTN` | word | `LTN10` | decimal |
+| `STN` | word | `STN10` | decimal |
+| `LSTN` | word | `LSTN10` | decimal |
+| `CN` | word | `CN10` | decimal |
+| `LCN` | word | `LCN10` | decimal |
+| `SW` | word | `SW20` | hexadecimal |
+| `Z` | word | `Z10` | decimal |
+| `R` | word | `R100` | decimal |
+| `ZR` | word | `ZR100` | decimal |
+| `RD` | word | `RD100` | decimal |
+
+## High-Level Address Forms
+
+| Form | Example | Meaning |
+| --- | --- | --- |
+| plain word | `D100` | unsigned 16-bit word |
+| signed view | `D100:S` | signed 16-bit value |
+| dword view | `D200:D` | unsigned 32-bit value |
+| long view | `D300:L` | signed 32-bit value |
+| float view | `D200:F` | float32 value |
+| bit in word | `D50.3` | one bit inside a word |
+| counted word read | `D100,10` | 10 consecutive values |
+| counted bit read | `M1000,8` | 8 consecutive bits |
+| string view | `D100:STR,10` | UTF-8 string packed into words |
+| compatibility alias | `DSTR100,10` | alias for `D100:STR,10` |
+
+## Addressing Notes
+
+- Start with `D` for the first smoke test.
+- `X`, `Y`, `B`, `W`, `SB`, `SW`, `DX`, and `DY` use hexadecimal device numbers.
+- Most other families use decimal numbers.
+- `.bit` is valid only on word devices such as `D50.3`.
+- `LTN`, `LSTN`, and `LCN` default to 32-bit current-value access in the public high-level nodes.
+
+## Not Currently in the Public Surface
+
+- `LTS`
+- `LTC`
+- `LSTS`
+- `LSTC`
+- `LCS`
+- `LCC`
+- `LZ`
+- `G`
+- `HG`
+
+If a family is not listed above, do not treat it as publicly supported by the current Node-RED package.

package/docsrc/user/USER_GUIDE.md

@@ -31,6 +31,14 @@ If you are starting from the example flows in this repository, import these in t
 - [`slmp-control-error.json`](../../examples/flows/slmp-control-error.json)
 - [`slmp-udp-read-write.json`](../../examples/flows/slmp-udp-read-write.json)
 
+Optional local runtime smoke test from the repository root:
+
+```bash
+npm run smoke:editor
+```
+
+The smoke script installs the local package into an isolated temporary userDir, starts a temporary Node-RED runtime, imports `slmp-basic-read-write.json`, checks that the flow starts, and then shuts the runtime down again.
+
 ## Available nodes
 
 - `slmp-connection`
@@ -113,6 +121,7 @@ Rules:
 - `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
+- helper exports also include `normalizeAddress()`, `formatParsedAddress()`, and `normalizeAddressList()` for canonical address handling outside the editor UI
 
 ## Dynamic inputs
 
@@ -234,5 +243,6 @@ Recommended first import:
 - `.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
+- the read and write nodes keep the caller-visible logical request shape and do not silently switch to a different fallback split behavior
 - 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

@@ -1,2 +1,8 @@
-- name: User Guide
-  href: USER_GUIDE.md
+ - name: Getting Started
+   href: GETTING_STARTED.md
+ - name: Supported PLC Registers
+   href: SUPPORTED_REGISTERS.md
+ - name: Latest Communication Verification
+   href: LATEST_COMMUNICATION_VERIFICATION.md
+ - name: User Guide
+   href: USER_GUIDE.md

package/examples/flows/README.md

@@ -15,6 +15,16 @@ Start here:
 - [`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
 
+Optional local runtime smoke test from the repository root:
+
+```bash
+npm run smoke:editor
+```
+
+This imports `slmp-basic-read-write.json` into an isolated temporary userDir and verifies that the temporary Node-RED runtime reaches `Started flows`.
+
+Available flows:
+
 - [`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`
@@ -22,3 +32,7 @@ Start here:
 - [`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
+
+Notes:
+
+- The flow nodes keep the caller-visible logical request shape and do not silently switch to a different fallback split behavior.