python-cybro

Asynchronous Python client for the Cybrotech scgi server. Use it to read and write variables of Cybro / HIQ PLCs through the scgi server's HTTP interface.

Requirements

• Python 3.11 or newer
• A running Cybrotech scgi server v3.2.6 or newer (tested with v3.2.6 and v3.3.1; earlier versions are not supported). You can install the server natively, or run it as a Docker container:

Installation

pip install cybro

Usage

import asyncio

from cybro import Cybro


async def main() -> None:
    nad = 10000  # network address (NAD) of the PLC
    prefix = f"c{nad}."

    async with Cybro("192.168.1.100", port=4000, nad=nad) as cybro:
        # The first update reads server and PLC information.
        # It must run before variables can be added, read or written.
        device = await cybro.update()
        print("Server version:", device.server_info.server_version)
        print("Controllers:", device.server_info.nad_list)
        print("PLC status:", device.plc_info.plc_status)

        # Register variables that every following update() should refresh.
        cybro.add_var(f"{prefix}scan_time")
        cybro.add_var(f"{prefix}sys.response_time")

        device = await cybro.update()
        for name in device.user_vars:
            print(name, "->", device.vars[name].value)

        # Read and write single variables.
        print(await cybro.read_var(f"{prefix}lc00_qx00"))
        await cybro.write_var(f"{prefix}lc00_qx00", "1")


asyncio.run(main())

A longer example lives in examples/control.py.

Connecting

Cybro(host_str, port=4000, nad=0, session=None)

• host_str can be a plain host name or IP address, or a URL with a path, e.g. http://example.com/scgi. The scheme is ignored; requests always use HTTP.
• nad is the network address of the PLC. It is needed for PLC information and for add_var(). With nad=0 (the default), only server information is read. See Server only (nad=0).
• session lets you pass your own aiohttp.ClientSession; you stay responsible for closing it. Otherwise one is created on the first request and closed when leaving async with Cybro(...) or calling await cybro.disconnect().

Reading data

await cybro.update(full_update=False, plc_nad=0, device_type=0) returns a Device:

• The first call (or full_update=True) reads server and PLC information. Later calls only refresh the variables registered with add_var().
• Set device_type=1 for HIQ controllers to also read their HIQ-specific variables.
• plc_nad sets the PLC address if none was given to Cybro(). It only takes effect on the very first update() call.

Server only (nad=0)

Without a NAD, update() reads only the server information. Use this to check that the server is reachable, or to list the controllers it knows (device.server_info.nad_list). In this mode:

• device.plc_info is None.
• cybro.add_var(name) only accepts system variables (c<nad>.sys.*). Pass allow_all=True to register other variables.
• read_var() and write_var() work with full variable names, e.g. c10000.scan_time.

To work with a PLC, create the Cybro object with its NAD.

Variables

• cybro.add_var(name) registers a variable for update(). Only variables listed in the PLC's ALC file and system variables (c<nad>.sys.*) are accepted; pass allow_all=True to add any name.
• cybro.remove_var(name) removes it again.
• await cybro.read_var(name) and await cybro.write_var(name, value) read or write a single variable immediately.

Values are returned as strings. Each Var in device.vars has helpers to convert them: value_int(), value_float() and value_bool().

Errors

All exceptions derive from CybroError, so catching it is enough:

Connection errors, timeouts and server errors (HTTP 5xx) are retried up to three times before an exception is raised. Client errors (HTTP 4xx) are raised immediately. Writes are retried too, so after a timeout a write may reach the PLC twice.

Development

The project uses Poetry. A ready-to-use dev container is included for VS Code.

poetry install
poetry run pytest
poetry run pre-commit install  # run Ruff, prettier and the tests before every commit

Contributing

Contributions are welcome! Please read the contribution guidelines first.

License

MIT