pyisyox.runtime.variable module

Runtime Variable — typed wrapper for IoX controller variables.

The IoX controller exposes two variable types — integer ("1") and state ("2"); each carries a current value, an init/restore-on- startup value, decimal precision, a user-assigned name, and a last- change timestamp. The wrapper surfaces those as read-only properties plus three mutation coroutines (set_value / set_init / rename) that route through the controller’s POST /api/variables/{type}/{id} endpoint.

Sourced from the parsed VariableRecord in pyisyox.client. Each Variable instance shares the underlying record with the controller’s loaded state — local mutations update the record in place, and WS variable-change frames (the <var> payload on _1 action 6/7 events) likewise update the record so reads always reflect the latest value.

class Variable(record, client)

Bases: object

User-facing handle for one controller variable.

Parameters:

• record (VariableRecord)

• client (IoXClient)

classmethod from_record(record, client)

Construct a Variable from a parsed record.

Parameters:

• record (VariableRecord)

• client (IoXClient)

Return type:

Variable

property type_id: str

Variable type — "1" (integer) or "2" (state).

property id: str

Variable id within its type (string for ergonomic joins).

property address: str

Composite "{type_id}.{id}" identifier.

property name: str

User-assigned label.

property value: int | float

Current value (wire field val).

Reads reflect the latest write — mutations via set_value() update the underlying record in place after a successful POST.

Type is int | float: most variables read back as int from the wire (/api/variables/{type} parses "val" as int), but a controller may surface float on a fresh write that posted a non-integer (the modern POST /api/variables/{type}/{id} endpoint accepts floats and the wrapper stores whatever was sent on success).

property init: int | float

Restore-on-startup value. Same int-or-float surface as value.

property precision: int

Decimal precision. displayed = raw / 10**precision.

property ts: str

Last-change timestamp as the controller emits it.

ISO 8601 UTC string when present, "" when the controller doesn’t stamp the entry (e.g. freshly created variables before the first change).

async set_value(value)

Set the current value of this variable.

Wire shape: POST /api/variables/{type}/{id} with body {"value": <number>}. The modern endpoint accepts both int and float — for a precision > 0 variable, send the displayed float (e.g. 51.5) and the controller applies the * 10**precision scale on store. Sending an int on the same variable means the controller stores it verbatim (no scale applied), which produces a mismatch between consumer-displayed and controller-internal values — so callers driving displayed-unit UIs should send floats.

Strings are tolerated for legacy callers (parsed as float if they contain a decimal point, else int).

Updates the underlying record on success so subsequent reads of value reflect the new state without waiting for a WS frame.

Parameters:

value (float)

Return type:

None

async set_init(init)

Set the init / restore-on-startup value.

Wire shape: POST /api/variables/{type}/{id} with {"init": <number>}. Same int-or-float semantics as set_value().

Parameters:

init (float)

Return type:

None

async rename(name)

Rename this variable on the controller.

Wire shape: POST /api/variables/{type}/{id} with {"name": "<str>"}.

Parameters:

name (str)

Return type:

None

async set_precision(prec)

Set decimal precision (displayed = raw / 10**precision).

Wire shape: POST /api/variables/{type}/{id} with {"prec": <int>}.

A precision change fires _1/9 (VARIABLE_TABLE_CHANGED) on the WebSocket — not the per-value 6/7 frames — so consumers that only listen on value/init updates won’t see the new precision until they refresh. The pyisyox.Controller auto-refreshes the affected type on this event when its dispatcher is wired.

Parameters:

prec (int)

Return type:

None

async delete()

Delete this variable on the controller.

Wire shape: DELETE /api/variables/{type}/{id}. Fires a VARIABLE_TABLE_CHANGED frame so an auto-refresh listener can drop the entry from the registry; the wrapper itself becomes inert (subsequent mutations would 404 — the wrapper carries no flag for this; consumers should drop their reference).

Return type:

None

to_dict()

Flatten this variable to a JSON-compatible dict.

Return type:

dict[str, Any]