{"id":47669250,"url":"https://github.com/fa-yoshinobu/plc-comm-hostlink-python","last_synced_at":"2026-06-12T05:01:01.045Z","repository":{"id":345331596,"uuid":"1180035143","full_name":"fa-yoshinobu/plc-comm-hostlink-python","owner":"fa-yoshinobu","description":"Reliable Python client for KEYENCE KV series PLCs using the Host Link (Upper Link) protocol. Supports KV-8000, KV-7500, and KV-5500.","archived":false,"fork":false,"pushed_at":"2026-06-11T19:57:16.000Z","size":1566,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T21:21:01.598Z","etag":null,"topics":["automation","hostlink","industrial-iot","keyence","plc","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fa-yoshinobu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T16:24:38.000Z","updated_at":"2026-06-11T19:56:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fa-yoshinobu/plc-comm-hostlink-python","commit_stats":null,"previous_names":["fa-yoshinobu/plc-comm-hostlink-python"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/fa-yoshinobu/plc-comm-hostlink-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa-yoshinobu%2Fplc-comm-hostlink-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa-yoshinobu%2Fplc-comm-hostlink-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa-yoshinobu%2Fplc-comm-hostlink-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa-yoshinobu%2Fplc-comm-hostlink-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fa-yoshinobu","download_url":"https://codeload.github.com/fa-yoshinobu/plc-comm-hostlink-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fa-yoshinobu%2Fplc-comm-hostlink-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34229624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","hostlink","industrial-iot","keyence","plc","python"],"created_at":"2026-04-02T12:22:54.432Z","updated_at":"2026-06-12T05:01:01.039Z","avatar_url":"https://github.com/fa-yoshinobu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KV Host Link Protocol for Python\n\n[![CI](https://github.com/fa-yoshinobu/plc-comm-hostlink-python/actions/workflows/test.yml/badge.svg)](https://github.com/fa-yoshinobu/plc-comm-hostlink-python/actions/workflows/test.yml)\n[![Release](https://github.com/fa-yoshinobu/plc-comm-hostlink-python/actions/workflows/release.yml/badge.svg)](https://github.com/fa-yoshinobu/plc-comm-hostlink-python/actions/workflows/release.yml)\n[![PyPI](https://img.shields.io/pypi/v/kv-hostlink.svg)](https://pypi.org/project/kv-hostlink/)\n[![Documentation](https://img.shields.io/badge/docs-GitHub_Pages-blue.svg)](https://fa-yoshinobu.github.io/plc-comm-hostlink-python/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Static Analysis: Ruff](https://img.shields.io/badge/Lint-Ruff-black.svg)](https://github.com/astral-sh/ruff)\n[![Type Checked: Mypy](https://img.shields.io/badge/Types-Mypy-blue.svg)](http://mypy-lang.org/)\n\n![Illustration](https://raw.githubusercontent.com/fa-yoshinobu/plc-comm-hostlink-python/main/docsrc/assets/kv.png)\n\nHigh-performance Python library for KEYENCE KV series PLCs using the Host Link (Upper Link) protocol.\n\nThis README intentionally covers the recommended high-level helper API only:\n\n- `HostLinkConnectionOptions`\n- `open_and_connect`\n- `parse_address`\n- `try_parse_address`\n- `format_address`\n- `normalize_address`\n- `read_typed`\n- `read_timer_counter` / `read_timer` / `read_counter`\n- `write_typed`\n- `read_comments`\n- `write_bit_in_word`\n- `read_named`\n- `poll`\n- `read_words_single_request`\n- `read_dwords_single_request`\n- `read_words_chunked`\n- `read_dwords_chunked`\n- `read_expansion_unit_buffer`\n- `write_expansion_unit_buffer`\n\n## Installation\n\n```bash\npip install kv-hostlink\n```\n\nPublished metadata lives at \u003chttps://pypi.org/project/kv-hostlink/\u003e, where wheel and tarball downloads are also available.\n\n## Quick Start\n\n```python\nimport asyncio\n\nfrom hostlink import HostLinkConnectionOptions, open_and_connect, read_named, read_typed, write_typed\n\n\nasync def main() -\u003e None:\n    options = HostLinkConnectionOptions(\n        host=\"192.168.250.100\",\n        port=8501,\n        transport=\"tcp\",\n        timeout=3.0,\n    )\n    async with await open_and_connect(options) as client:\n        dm0 = await read_typed(client, \"DM0\", \"U\")\n        await write_typed(client, \"DM10\", \"U\", dm0)\n\n        snapshot = await read_named(\n            client,\n            [\"DM0\", \"DM1:S\", \"DM2:D\", \"DM4:F\", \"DM10.0\", \"DM20:COMMENT\"],\n        )\n        print(snapshot)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n## Supported PLC Registers\n\nStart with these public high-level families first:\n\n- word devices: `DM`, `EM`, `FM`, `W`, `ZF`, `TM`, `Z`\n- bit devices: `R`, `MR`, `LR`, `CR`, `X`, `Y`, `M`, `L`\n- typed forms: `DM100:S`, `DM100:D`, `DM100:L`, `DM100:F`\n- comment form: `DM100:COMMENT`\n- bit-in-word forms: `DM100.3`, `DM100.A`\n- timer/counter scalar forms: `T10:D`, `C10:D`\n- digital trimmer scalar forms on supported PLCs: `AT0:D` / default `AT0`\n\n`read_typed(client, \"T10\", \"D\")` and `read_named(client, [\"T10\"])` return the\ntimer/counter preset value for compatibility. Use\n`read_timer_counter(client, \"T10\")` when the Host Link composite fields are\nneeded: `status`, `current`, and `preset`.\n\n`AT` is not listed in the WR/WRS device table, so write helpers reject AT before\nsending.\n\n`T` / `C` preset writes use Host Link `WS` / `WSS` only on KV-8000/7000-series\nCPU units. Manuals state that other CPU units do not support those commands\nand return abnormal response `E1` when they are executed.\n\nSee the full public table in [Supported PLC Registers](docsrc/user/SUPPORTED_REGISTERS.md).\nFor model-specific published ranges, call `client.read_device_range_catalog()` or `device_range_catalog_for_model(\"KV-8000\")`.\n\n## Public Documentation\n\n- [Getting Started](docsrc/user/GETTING_STARTED.md)\n- [Supported PLC Registers](docsrc/user/SUPPORTED_REGISTERS.md)\n- [Latest Communication Verification](docsrc/user/LATEST_COMMUNICATION_VERIFICATION.md)\n- [User Guide](docsrc/user/USER_GUIDE.md)\n- [API Reference](docsrc/user/API_REFERENCE.md)\n- [Troubleshooting](docsrc/user/TROUBLESHOOTING.md)\n- [Performance Guide](docsrc/user/PERFORMANCE_GUIDE.md)\n- [Samples](samples/README.md)\n\nMaintainer-only notes and retained evidence live under `internal_docs/`.\n\n## Samples\n\n- [high_level_async.py](samples/high_level_async.py)\n- [high_level_sync.py](samples/high_level_sync.py)\n- [basic_high_level_rw.py](samples/basic_high_level_rw.py)\n- [named_snapshot.py](samples/named_snapshot.py)\n- [polling_monitor.py](samples/polling_monitor.py)\n\n## Common Workflows\n\nAddress normalization:\n\n```python\nfrom hostlink import format_address, normalize_address, parse_address\n\nprint(normalize_address(\"dm100\"))    # DM100\nprint(normalize_address(\"dm100.a\"))  # DM100.A\n\nparsed = parse_address(\"dm100.a\")\nprint(parsed.base_device, parsed.bit_index)  # DM100 10\nprint(format_address(parsed))                # DM100.A\n```\n\nTyped block reads:\n\n```python\nwords = await read_words_single_request(client, \"DM100\", 10)\ndwords = await read_dwords_single_request(client, \"DM200\", 4)\n```\n\nBit-in-word update:\n\n```python\nawait write_bit_in_word(client, \"DM50\", bit_index=3, value=True)\n```\n\nExpansion unit buffer access:\n\n```python\nfrom hostlink import read_expansion_unit_buffer, write_expansion_unit_buffer\n\nbuffer_words = await read_expansion_unit_buffer(client, 1, 100, 2, data_format=\"U\")\nawait write_expansion_unit_buffer(client, 1, 200, buffer_words, data_format=\"U\")\n```\n\nComment read:\n\n```python\ncomment = await read_comments(client, \"DM100\")\n```\n\nXYM aliases are also accepted for comment reads, for example `D10`, `E20`, `F30`, `M100`, `L200`, `X100`, and `Y100`.\n\n## Verified Hardware\n\n- CPU: `KV-7500`\n- CPU: `KV-X500`\n- Ethernet: built-in Ethernet port and `KV-XLE02`\n- Transport: `TCP` and `UDP`\n\n## Development and Release Checks\n\n```bash\nrun_ci.bat\nrelease_check.bat\n```\n\n## License\n\nDistributed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffa-yoshinobu%2Fplc-comm-hostlink-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffa-yoshinobu%2Fplc-comm-hostlink-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffa-yoshinobu%2Fplc-comm-hostlink-python/lists"}