Skip to content

Service API

Tier: Stable Core

Synchronous service wrapper and polling lifecycle APIs.

pyclickplc.ModbusService

Synchronous wrapper over ClickClient with background polling.

connect 

connect(
    host: str,
    port: int = 502,
    *,
    device_id: int = 1,
    timeout: int = 1,
) -> None

Connect to a CLICK PLC endpoint.

Parameters:

Name Type Description Default
host str

PLC hostname or IP address.

 required
port int

Modbus TCP port.

 502
device_id int

Modbus unit/device ID.

 1
timeout int

Client timeout in seconds.

 1

Raises:

Type Description
OSError

Connection attempt failed.
ValueError

Invalid connection arguments.

disconnect 

disconnect() -> None

Disconnect from the PLC and stop the service loop thread.

close 

close() -> None

Alias for :meth:disconnect.

set_poll_addresses 

set_poll_addresses(addresses: Iterable[str]) -> None

Replace the active polling address set.

Parameters:

Name Type Description Default
addresses Iterable[str]

Address strings to poll each cycle.

 required

Raises:

Type Description
ValueError

Any address is invalid.

clear_poll_addresses 

clear_poll_addresses() -> None

Clear the active polling address set.

stop_polling 

stop_polling() -> None

Pause polling while keeping the current configured address set.

read 

read(addresses: Iterable[str]) -> ModbusResponse[PlcValue]

Synchronously read one or more addresses.

Parameters:

Name Type Description Default
addresses Iterable[str]

Address strings to read.

 required

Returns:

Type Description
ModbusResponse[PlcValue]

ModbusResponse keyed by canonical normalized addresses.

Raises:

Type Description
ValueError

Any address is invalid.
OSError

Not connected or transport/protocol read failure.

write 

write(
    values: Mapping[str, PlcValue]
    | Iterable[tuple[str, PlcValue]],
) -> list[WriteResult]

Synchronously write one or more address values.

Parameters:

Name Type Description Default
values Mapping[str, PlcValue] | Iterable[tuple[str, PlcValue]]

Mapping or iterable of (address, value) pairs.

 required

Returns:

Type Description
list[WriteResult]

Per-item write outcomes preserving input order.
list[WriteResult]

Validation and write failures are reported in each WriteResult.

pyclickplc.ReconnectConfig dataclass

ClickClient reconnect behavior used by ModbusService.

pyclickplc.ConnectionState

Bases: Enum

Connection state notifications emitted by ModbusService.

pyclickplc.WriteResult

Bases: TypedDict

Per-address write outcome.