kv-hostlink 0.1.9

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
• 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

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
• 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.