pyisyox.schema.nodedef module

Node definition dataclasses for IoX devices.

A NodeDef describes the static behaviour of a class of nodes: which properties exist, which commands are accepted/sent, and which links the node supports. The same shape applies to native Insteon/Z-Wave nodedefs and PG3 plugin nodedefs — there is no plugin-only field. The structural key into the lookup table is (nodedef_id, family_id, instance_id).

A live Property value (raw + formatted + uom) is reported by the controller via /api/nodes (for native nodes), /rest/status (the canonical full table), or WebSocket event frames; it is not part of the nodedef and is kept here only as a separate dataclass.

Source schema: /rest/profiles instance nodedefs[].

class Property(id, value, formatted='', uom='', prec=None, name='')[source]

Bases: object

A live property value reported by the controller for a node.

Variables:

  • id (str) – Property id (e.g. "ST", "GV1").

  • value (str) – Raw value as reported by the controller (string form keeps controller-emitted precision).

  • formatted (str) – Human-readable value (e.g. "0.6839 US gallons").

  • uom (str) – Unit-of-measure id reported alongside the value.

  • prec (int | None) – Decimal precision applied to value (None when not provided).

  • name (str) – Optional display name override (often empty — the nodedef-level NodeProperty.name is the authoritative label).

Parameters:
id: str
value: str
formatted: str
uom: str
prec: int | None
name: str
class NodeProperty(id, editor_id, name='', hide=False)[source]

Bases: object

A property slot defined on a nodedef.

Variables:

  • id (str) – Property id (e.g. "ST", "OL", "CLISPC", "GV1").

  • editor_id (str) – Reference to the editor governing this property’s display and (where applicable) write-side validation.

  • name (str) – Human-readable label, inline-resolved by the controller (e.g. "Current" for Flume’s GV1, "On Level" for Insteon’s OL). Authoritative source.

  • hide (bool) – Hint that the property should not be surfaced in default UIs.

Parameters:
id: str
editor_id: str
name: str
hide: bool
class NodeCommands(sends=<factory>, accepts=<factory>)[source]

Bases: object

Commands a nodedef sends and accepts.

Variables:

  • sends (list[pyisyox.schema.cmd.Command]) – Commands the node emits — useful as trigger sources (e.g. OnOffControl sends DON/DOF on physical press).

  • accepts (list[pyisyox.schema.cmd.Command]) – Commands the node receives — drive the node’s controllable HA platform (light/switch/climate/lock/cover/button).

Parameters:
sends: list[Command]
accepts: list[Command]

Bases: object

Control and response link references on a nodedef.

Parameters:
ctl: list[str]
rsp: list[str]
class NodeDef(id, family_id, instance_id, name='', properties=<factory>, cmds=<factory>, nls_key=None, links=<factory>)[source]

Bases: object

The static definition of a node class.

Variables:

  • id (str) – Nodedef identifier (e.g. "KeypadDimmer_ADV", "Thermostat", "flume2", "controller").

  • family_id (str) – Family id this nodedef belongs to ("1" for Insteon, "4" for Z-Wave, plugin slot id for PG3 nodedefs).

  • instance_id (str) – Instance id within the family (typically equal to family_id for built-in families and equal to the plugin slot for PG3 instances).

  • name (str) – Default display name (the NDN-<nls>-NAME NLS entry). Often empty — the live node carries a user-assigned name; this is just the discovery-time default. /rest/profiles families resolve it inline; for dynamic Z-Wave nodedefs pyisyox fills it from the family NLS table.

  • properties (dict[str, pyisyox.schema.nodedef.NodeProperty]) – Property slots, keyed by property id.

  • cmds (pyisyox.schema.nodedef.NodeCommands) – Sent and accepted commands.

  • nls_key (str | None) – Reference key into the NLS string table (e.g. "flume2"); pyisyox does not need to resolve this — every visible string is already inline-resolved in property/command name fields and in WS event frames.

  • links (pyisyox.schema.nodedef.NodeLinks) – Control and response link references.

Parameters:
id: str
family_id: str
instance_id: str
name: str
properties: dict[str, NodeProperty]
cmds: NodeCommands
nls_key: str | None
classmethod from_json(raw, family_id, instance_id)[source]

Build a NodeDef from a JSON object scoped to its family/instance.

Parameters:
Return type:

NodeDef

property lookup_key: tuple[str, str, str]

The (nodedef_id, family_id, instance_id) join key used to match a node from /api/nodes to its definition.