API Reference¶

class drok_xyt01.DrokXYT01(config: DrokXYT01Config)¶

Bases: object

XY-T01 controller driver with asynchronous reader and synchronous acks.

This class manages the serial port, a background reader thread that demultiplexes measurements and command responses, and a simple command API.

Thread safety: one command may be in flight at a time. A dedicated TX lock serializes writes. The reader thread safely hands response lines to the active waiter, if any.

Parameters:: config – Serial and timing configuration.

connect(on_measurement: Callable[[str, float], None] | None = None) → bool¶

Open the serial port and start the reader thread.

A safe configuration sequence is issued: stop, off, short delay, start to enable streaming. This is the safe-state sequence.

Parameters:: on_measurement – Optional callback (mode: str, temp_c: float) that receives asynchronous measurement updates. mode is one of {"CL", "OP", "OFF"}. Must return quickly or risk blocking additional reads.
Returns:: True if connected and reader started; otherwise False.

disconnect() → None¶: Stop the reader, close the serial port, and leave the controller OFF.

enable_logging(verbose: bool = False) → None¶

Configure module logging with a simple formatter.

Parameters:: verbose – If True, use DEBUG level; otherwise INFO.

property is_connected: bool¶

Whether the serial port is open.

Returns:: True if the serial device is open.

off() → bool¶

Turn controller output OFF.

Returns:: True on expected ack, else False.

on() → bool¶

Turn controller output ON.

Returns:: True on expected ack, else False.

query_state() → DrokXYT01State¶

Return structured device state.

This issues a read and parses the result into a DrokXYT01State.

Returns:: Parsed DrokXYT01State.

read_settings() → tuple[str, str, str]¶

Read the three settings/state lines from the controller.

Returns:: Tuple of three raw lines (L1, L2, L3). Empty strings on timeout.

reset() → None¶

Reset the controller and reconnect.

The sequence is: stop, off, wait ~2 s, clear buffers, disconnect, connect. The existing measurement callback is preserved.

set_alarm(temp_c: float) → bool¶

Set the controller alarm threshold.

Parameters:: temp_c – Alarm in °C (-50..110).
Returns:: True if an expected state (DOWN or UP) is received.

set_setpoint(temp_c: float) → bool¶

Set the controller setpoint.

Parameters:: temp_c – Setpoint in °C (-50..110).
Returns:: True on expected ack, else False.

start() → bool¶

Start streaming measurements.

Returns:: True on expected ack, else False.

stop() → bool¶

Stop streaming measurements.

Returns:: True on expected ack, else False.

drok_xyt01.DrokXYT01Cli() → None¶: Simple CLI for manual interaction and demonstration.

class drok_xyt01.DrokXYT01Config(port: str = '/dev/serial1', baudrate: int = 9600, read_timeout_s: float = 2.0, write_timeout_s: float = 1.0, crlf: str = '\n', ack_timeout_s: float = 3.0, txrx_delay_s: float = 1.0)¶

Bases: object

Serial and timing configuration for DrokXYT01.

Parameters:

port – Serial device path.
baudrate – UART baud rate.
read_timeout_s – Serial readline timeout (seconds).
write_timeout_s – Serial write timeout (seconds).
crlf – Line terminator appended to transmitted commands.
ack_timeout_s – Maximum time to wait for a command’s response lines.
txrx_delay_s – Inter-command delay between TX and the first RX wait.

ack_timeout_s: float = 3.0¶

baudrate: int = 9600¶

crlf: str = '\n'¶

port: str = '/dev/serial1'¶

read_timeout_s: float = 2.0¶

txrx_delay_s: float = 1.0¶

write_timeout_s: float = 1.0¶

Bases: object

Structured state returned by DrokXYT01.query_state().

Variables:

mode – "heat" or "cool" (derived from H/C), or None if unknown.
setpoint_c – Setpoint temperature in °C, if available.
hysteresis_c – Hysteresis in °C, if available.
alarm_c – Alarm threshold in °C, if available.
start_delay_min – Output start delay (OPH) in minutes, if available.
calibration_bias_c – Calibration offset (OFE) in °C, if available.

alarm_c: float | None¶

calibration_bias_c: float | None¶

hysteresis_c: float | None¶

mode: str | None¶

setpoint_c: float | None¶

start_delay_min: int | None¶