kv-hostlink 0.1.11

Python library for KEYENCE KV series Host Link (Upper Link) communication.

KV Host Link Protocol for Python

High-performance Python library for KEYENCE KV series PLCs using the Host Link (Upper Link) protocol.

This README intentionally covers the recommended high-level helper API only:

• HostLinkConnectionOptions
• open_and_connect
• parse_address
• try_parse_address
• format_address
• normalize_address
• read_typed
• read_timer_counter / read_timer / read_counter
• write_typed
• read_comments
• write_bit_in_word
• read_named
• poll
• read_words_single_request
• read_dwords_single_request
• read_words_chunked
• read_dwords_chunked
• read_expansion_unit_buffer
• write_expansion_unit_buffer

Installation

pip install kv-hostlink

Published metadata lives at https://pypi.org/project/kv-hostlink/, where wheel and tarball downloads are also available.

Quick Start

import asyncio

from hostlink import HostLinkConnectionOptions, open_and_connect, read_named, read_typed, write_typed


async def main() -> None:
    options = HostLinkConnectionOptions(
        host="192.168.250.100",
        port=8501,
        transport="tcp",
        timeout=3.0,
    )
    async with await open_and_connect(options) as client:
        dm0 = await read_typed(client, "DM0", "U")
        await write_typed(client, "DM10", "U", dm0)

        snapshot = await read_named(
            client,
            ["DM0", "DM1:S", "DM2:D", "DM4:F", "DM10.0", "DM20:COMMENT"],
        )
        print(snapshot)


if __name__ == "__main__":
    asyncio.run(main())

Supported PLC Registers

Start with these public high-level families first:

• word devices: DM, EM, FM, W, ZF, TM, Z
• bit devices: R, MR, LR, CR, X, Y, M, L
• typed forms: DM100:S, DM100:D, DM100:L, DM100:F
• comment form: DM100:COMMENT
• bit-in-word forms: DM100.3, DM100.A
• timer/counter scalar forms: T10:D, C10:D
• digital trimmer scalar forms on supported PLCs: AT0:D / default AT0

read_typed(client, "T10", "D") and read_named(client, ["T10"]) return the timer/counter preset value for compatibility. Use read_timer_counter(client, "T10") when the Host Link composite fields are needed: status, current, and preset.

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

T / C 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.

See the full public table in Supported PLC Registers. For model-specific published ranges, call client.read_device_range_catalog() or device_range_catalog_for_model("KV-8000").

Public Documentation

• Getting Started
• Supported PLC Registers
• Latest Communication Verification
• User Guide
• API Reference
• Troubleshooting
• Performance Guide
• Samples

Maintainer-only notes and retained evidence live under internal_docs/.

Samples

• high_level_async.py
• high_level_sync.py
• basic_high_level_rw.py
• named_snapshot.py
• polling_monitor.py

Common Workflows

Address normalization:

from hostlink import format_address, normalize_address, parse_address

print(normalize_address("dm100"))    # DM100
print(normalize_address("dm100.a"))  # DM100.A

parsed = parse_address("dm100.a")
print(parsed.base_device, parsed.bit_index)  # DM100 10
print(format_address(parsed))                # DM100.A

Typed block reads:

words = await read_words_single_request(client, "DM100", 10)
dwords = await read_dwords_single_request(client, "DM200", 4)

Bit-in-word update:

await write_bit_in_word(client, "DM50", bit_index=3, value=True)

Expansion unit buffer access:

from hostlink import read_expansion_unit_buffer, write_expansion_unit_buffer

buffer_words = await read_expansion_unit_buffer(client, 1, 100, 2, data_format="U")
await write_expansion_unit_buffer(client, 1, 200, buffer_words, data_format="U")

Comment read:

comment = await read_comments(client, "DM100")

XYM aliases are also accepted for comment reads, for example D10, E20, F30, M100, L200, X100, and Y100.

Verified Hardware

• CPU: KV-7500
• CPU: KV-X500
• Ethernet: built-in Ethernet port and KV-XLE02
• Transport: TCP and UDP

Development and Release Checks

run_ci.bat
release_check.bat

License

Distributed under the MIT License.