@fa_yoshinobu/node-red-contrib-plc-comm-kvhostlink 0.2.8

Node-RED nodes for KEYENCE KV Host Link communication over TCP/UDP.

npm install @fa_yoshinobu/node-red-contrib-plc-comm-kvhostlink

Node-RED KV Host Link Nodes for KEYENCE PLCs

Node-RED nodes for KEYENCE KV series PLC communication over KV Host Link (Upper Link), using the same high-level read/write model as the existing Python and .NET libraries.

Quick start

1. Install the package into your Node-RED user directory and restart Node-RED.
2. Add one kvhostlink-connection config node and set host, port, transport, and timeout.
3. Import kvhostlink-basic-read-write.json for the first smoke test.
4. When scalar read/write works, move to kvhostlink-typed-read-write.json and kvhostlink-array-read-write.json.
5. Use kvhostlink-device-matrix.json only after the basics are stable.

Release information

• package name: @fa_yoshinobu/node-red-contrib-plc-comm-kvhostlink
• package version: 0.2.8
• npm package: https://www.npmjs.com/package/@fa_yoshinobu/node-red-contrib-plc-comm-kvhostlink
• Node-RED requirement: >=3.0.0
• Node.js requirement: >=18
• changelog: https://github.com/fa-yoshinobu/node-red-contrib-plc-comm-kvhostlink/blob/main/CHANGELOG.md

Install from npm:

cd ~/.node-red
npm install @fa_yoshinobu/node-red-contrib-plc-comm-kvhostlink

Install from this repository:

cd ~/.node-red
npm install /path/to/node-red-contrib-plc-comm-kvhostlink

Optional local editor smoke test from the repository root:

npm run smoke:editor

This command installs the local package into an isolated temporary userDir, starts a temporary Node-RED runtime, imports kvhostlink-basic-read-write.json, verifies the flow starts, and then shuts the runtime down again.

Changes Since Flow Library 0.2.0

The Node-RED Flow Library currently shows 0.2.0 as the published baseline for this scoped package. Check these changes before updating an existing flow:

• Host Link command framing is fixed to CR termination. If an old flow had an Append LF connection option, remove that assumption.
• The connection node now exposes an explicit timeout setting.
• Read/write nodes now expose metadata modes, connection control messages, comment reads, and canonical address helper exports.
• kvhostlink-device-matrix.json now includes one-click run-all read/write buttons, an auto-run status lamp, timeout tracking, non-overlapping button layout, and JSONL logging.
• The matrix write sequence skips entries marked writable: false; timer/counter T and C samples are circuit-dependent and not safe generic write targets.

Documentation

• User Guide
• Example Flows
• Future Device Support
• Maintainer Notes
• Validation Reports Directory
• Documentation Index

Current scope

• TCP and UDP transport
• Reusable kvhostlink-connection config node
• explicit connection options for host, port, transport, and timeout
• kvhostlink-read powered by the high-level helper API
• kvhostlink-write powered by the high-level helper API
• high-level scalar, signed, dword, long, float, bit-in-word, and ,count forms
• comment read helper and :COMMENT snapshot form
• metadata emission modes for msg.kvhostlink: full / minimal / off
• connection control via connect / disconnect / reinitialize messages
• matrix-style debug flow with one-click run-all read/write, status lamp feedback, timeout tracking, and JSONL result logging
• beginner-oriented sample flows for scalar, typed, and array patterns
• local tests for protocol parsing and high-level helper behavior
• helper exports also include normalizeAddress, formatParsedAddress, and normalizeAddressList for canonical address handling
• optional local runtime smoke validation via npm run smoke:editor

Supported high-level address forms include:

• DM100
• DM110:S
• DM120:D
• DM130:L
• DM140:F
• DM145:COMMENT
• DM150.3
• DM160,4
• R200,4
• T10:D
• C10:D

Supported devices

Input validation checks address syntax, device code support, suffix forms, bit notation, count syntax, and Host Link command constraints. It does not check PLC model-specific device ranges. If an address is outside the connected PLC's actual range, the PLC response is returned as the runtime error.

Supported bit devices:

• R, B, MR, LR, CR, VB
• X, Y, M, L

Supported word devices:

• DM, EM, FM, ZF, W, TM, Z
• TC, TS, CC, CS
• CM, VM
• D, E, F

Supported high-level timer and counter scalar forms:

• Tn:D
• Cn:D

Tn:D and Cn:D depend on a corresponding timer or counter circuit existing in the PLC program. If the circuit is not present, a PLC error or timeout is an expected validation result rather than a device parser failure. Use TC / TS / CC / CS when checking the timer/counter current/contact device families directly.

Example flows

• kvhostlink-basic-read-write.json First-step scalar read/write flow.
• kvhostlink-typed-read-write.json Signed, dword, long, float, and bit-in-word examples.
• kvhostlink-array-read-write.json ,count read/write examples for words and bits.
• kvhostlink-device-matrix.json High-level matrix-style verification flow with one-by-one controls, run-all read/write buttons, status lamp feedback, and JSONL logging. Completed results are appended to logs/kvhostlink-device-matrix-<session>.jsonl under your Node-RED user directory.

Connection and runtime behavior

Connection settings on kvhostlink-connection:

• host
• port
• transport: tcp or udp
• timeout in milliseconds
• command framing is fixed to Host Link CR termination

Read and write nodes support:

• full or minimal msg.kvhostlink metadata, or leaving it unchanged
• msg.connect, msg.disconnect, and msg.reinitialize
• msg.topic = "connect" | "disconnect" | "reinitialize"

The read and write nodes keep the caller-visible logical request shape and do not silently retry one logical request as a different fallback split operation.

Comment reads use the Host Link RDC command and return strings in the same payload shapes as other read values.

XYM aliases are also accepted for comment reads, so forms such as D10:COMMENT, M20:COMMENT, and X100:COMMENT are valid.

Known limitations

• AT remains pending support and is tracked in TODO.md.
• The package now has beginner flows, but the validation coverage and example breadth are still narrower than node-red-contrib-plc-comm-slmp.

Latest Matrix Verification

Latest retained KV Host Link Node-RED matrix result:

• date: 2026-05-02
• target class: KV-5000
• catalog samples: 35
• completed JSONL records: 157
• result: all records OK
• log shape: each record includes protocol, requestId, sessionId, logPath, operation, deviceCode, sampleLabel, address, status, and timing fields