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.