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

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.10
• 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 Older Flow Library Entries

If your Node-RED Flow Library entry or an existing project is still on 0.2.0, check these changes before updating a 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, normalizeAddressList, readTimerCounter, readTimer, and readCounter for canonical address handling and timer/counter composite reads
• the low-level HostLinkClient export includes expansion unit buffer helpers: readExpansionUnitBuffer() and writeExpansionUnitBuffer()
• the low-level HostLinkClient export includes switchBank() for PLC models that support the Host Link BE bank-switch command; KV-X500 targets do not use this command
• 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 also rejects spans that cross the common Host Link device-family bounds before a request is sent, including 32-bit reads that would run past the end of a word device area. It does not check PLC model-specific device ranges because the Node-RED connection profile does not select a PLC model. If an address is valid for the common Host Link family but 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
• AT digital trimmer values, treated as 32-bit (.D) device points on supported PLC families
• CM, VM
• D, E, F

AT is not listed in the WR/WRS device table, so write helpers reject AT before sending.

Supported high-level timer and counter scalar forms:

• Tn:D
• Cn:D

The high-level helper readNamed(["T10"]) keeps returning the preset value for compatibility. Use the exported JS helpers readTimerCounter(client, "T10"), readTimer(client, "T10"), or readCounter(client, "C10") when the Host Link composite fields are needed: status, current, and preset.

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. Timer/counter preset writes use Host Link WS / WSS only on KV-8000/7000-series CPU units. Manuals state that other CPU units do not support those commands and return abnormal response E1 when they are executed. 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 is not present on KV-X500. On KV-7500, AT0.D / AT7.D read and default AT0 high-level read were verified. AT is not listed in the WR/WRS device table, so write helpers reject AT before sending; a raw WR probe returned PLC E1.
• 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