PyISY Library Reference

ISY Class

class pyisy.isy.ISY(address, port, username, password, use_https=False, tls_ver=1.1, webroot='', websession=None, use_websocket=False)

This is the main class that handles interaction with the ISY device.

address: String of the IP address of the ISY device

port: String of the port over which the ISY is serving its API

username: String of the administrator username for the ISY

password: String of the administrator password for the ISY

use_https: [optional] Boolean of whether secured HTTP should be used

tls_ver: [optional] Number indicating the version of TLS encryption to use. Valid options are 1.1 or 1.2.

Variables

• auto_reconnect – Boolean value that indicates if the class should auto-reconnect to the event stream if the connection is lost.

• auto_update – Boolean value that controls the class’s subscription to the event stream that allows node, program values to be updated automatically.

• connected – Read only boolean value indicating if the class is connected to the controller.

• nodes – pyisy.nodes.Nodes manager that interacts with Insteon nodes and groups.

• programs – Program manager that interacts with ISY programs and i folders.

• variables – Variable manager that interacts with ISY variables.

property auto_update

Return the auto_update property.

property connected

Return the status of the connection.

property hostname

Return the hostname.

async initialize()

Initialize the connection with the ISY.

async query(address=None)

Query all the nodes or a specific node if an address is provided .

Args:

address (string, optional): Node Address to query. Defaults to None.

Returns:

boolean: Returns True on successful command, False on error.

async send_x10_cmd(address, cmd)

Send an X10 command.

address: String of X10 device address (Ex: A10) cmd: String of command to execute. Any key of x10_commands can be used

async shutdown()

Cleanup connections and prepare for exit.

Node Manager Class

class pyisy.nodes.Nodes(isy, root=None, addresses=None, nnames=None, nparents=None, nobjs=None, ntypes=None, xml=None)

This class handles the ISY nodes.

This class can be used as a dictionary to navigate through the controller’s structure to objects of type pyisy.nodes.Node and pyisy.nodes.Group that represent objects on the controller.

isy: ISY class

root: [optional] String representing the current navigation level’s ID

addresses: [optional] list of node ids

nnames: [optional] list of node names

nparents: [optional] list of node parents

nobjs: [optional] list of node objects

ntypes: [optional] list of node types

xml: [optional] String of xml data containing the configuration data

Variables

• all_lower_nodes – Return all nodes beneath current level

• children – A list of the object’s children.

• has_children – Indicates if object has children

• name – The name of the current folder in navigation.

__getitem__(val)

Navigate through the node tree. Can take names or IDs.

__init__(isy, root=None, addresses=None, nnames=None, nparents=None, nobjs=None, ntypes=None, xml=None)

Initialize the Nodes ISY Node Manager class.

__iter__()

Return an iterator for each node below the current nav level.

__repr__()

Create a pretty representation of the nodes/folders/groups.

__repr_folders__(folders)

Return a representation of the folder structure.

__repr_groups__(groups)

Return a representation of the groups structure.

__repr_nodes__(nodes)

Return a representation of the nodes structure.

__reversed__()

Return the iterator in reverse order.

__setitem__(item, value)

Set item value.

__str__()

Return string representation of the nodes/folders/groups.

__weakref__

list of weak references to the object (if defined)

property all_lower_nodes

Return all nodes below the current root.

property children

Return the children of the class.

control_message_received(xmldoc)

Pass Control events from an event stream message to nodes.

Used for sending out to subscribers.

get_by_id(address)

Get object with the given ID.

address: Integer representing node/group/folder id.

get_by_index(i)

Return the object at the given index in the list.

i: Integer representing index of node/group/folder.

get_by_name(val)

Get child object with the given name.

val: String representing name to look for.

get_children(ident=None)

Return the children of the class.

get_folder(address)

Return the folder of a given node address.

property has_children

Return if the root has children.

insert(address, nname, nparent, nobj, ntype)

Insert a new node into the lists.

address: node id

nname: node name

nparent: node parent

nobj: node object

ntype: node type

property name

Return the name of the root.

node_changed_received(xmldoc)

Handle Node Change/Update events from an event stream message.

parse(xml)

Parse the xml data.

xml: String of the xml data

async update(wait_time=0, xml=None)

Update the status and properties of the nodes in the class.

This calls the “/rest/status” endpoint.

wait_time: [optional] Amount of seconds to wait before updating

async update_nodes(wait_time=0)

Update the contents of the class.

This calls the “/rest/nodes” endpoint.

wait_time: [optional] Amount of seconds to wait before updating

update_received(xmldoc)

Update nodes from event stream message.

Node Base Class

class pyisy.nodes.nodebase.NodeBase(nodes, address, name, status, family_id=None, aux_properties=None, pnode=None)

Base Object for Nodes and Groups/Scenes.

__init__(nodes, address, name, status, family_id=None, aux_properties=None, pnode=None)

Initialize a Node Base class.

__str__()

Return a string representation of the node.

__weakref__

list of weak references to the object (if defined)

property address

Return the Node ID.

property aux_properties

Return the aux properties that were in the Node Definition.

async beep()

Identify physical device by sound (if supported).

async brighten()

Increase brightness of a device by ~3%.

property description

Return the description of the node from it’s notes.

async dim()

Decrease brightness of a device by ~3%.

async disable()

Send command to the node to disable it.

async enable()

Send command to the node to enable it.

async fade_down()

Begin fading down (dim) a device.

async fade_stop()

Stop fading a device.

async fade_up()

Begin fading up (dim) a device.

property family

Return the ISY Family category.

async fast_off()

Start manually brightening a device.

async fast_on()

Start manually brightening a device.

property folder

Return the folder of the current node as a property.

async get_notes()

Retrieve and parse the notes for a given node.

Notes are not retrieved unless explicitly requested by a call to this function.

property is_load

Return the isLoad property of the node from it’s notes.

property last_changed

Return the UTC Time of the last status change for this node.

property last_update

Return the UTC Time of the last update for this node.

property location

Return the location of the node from it’s notes.

property name

Return the name of the Node.

property primary_node

Return just the parent/primary node address.

This is similar to Node.parent_node but does not return the whole Node class, and will return itself if it is the primary node/group.

async query()

Request the ISY query this node.

async rename(new_name)

Rename the node or group in the ISY.

Note: Feature was added in ISY v5.2.0, this will fail on earlier versions.

async send_cmd(cmd, val=None, uom=None, query=None)

Send a command to the device.

property spoken

Return the text of the Spoken property inside the group notes.

property status

Return the current node state.

property status_feedback

Return information for a status change event.

async turn_off()

Turn off the nodes/group in the ISY.

async turn_on(val=None)

Turn the node on.

[optional] val: The value brightness value (0-255) for the node.

update(event=None, wait_time=0, xmldoc=None)

Update the group with values from the controller.

update_last_changed(timestamp=None)

Set the UTC Time of the last status change for this node.

update_last_update(timestamp=None)

Set the UTC Time of the last update for this node.

update_property(prop)

Update an aux property for the node when received.

Node Class

class pyisy.nodes.Node(nodes, address, name, state, aux_properties=None, zwave_props=None, node_def_id=None, pnode=None, device_type=None, enabled=None, node_server=None, protocol=None, family_id=None)

This class handles ISY nodes.

parent: The node manager object.

address: The Node ID.

value: The current Node value.

name: The node name.

spoken: The string of the Notes Spoken field.

notes: Notes from the ISY

uom: Unit of Measure returned by the ISY

prec: Precision of the Node (10^-prec)

aux_properties: Additional Properties for the node

zwave_props: Z-Wave Properties from the devtype tag (used for Z-Wave Nodes.)

node_def_id: Node Definition ID (used for ISY firmwares >=v5)

pnode: Node ID of the primary node

device_type: device type.

node_server: the parent node server slot used

protocol: the device protocol used (z-wave, zigbee, insteon, node server)

Variables

• status – A watched property that indicates the current status of the node.

• has_children – Property indicating that there are no more children.

__init__(nodes, address, name, state, aux_properties=None, zwave_props=None, node_def_id=None, pnode=None, device_type=None, enabled=None, node_server=None, protocol=None, family_id=None)

Initialize a Node class.

property dimmable

Return the best guess if this is a dimmable node.

DEPRECIATED: USE is_dimmable INSTEAD. Will be removed in future release.

property enabled

Return if the device is enabled or not in the ISY.

property formatted

Return the formatted value with units, if provided.

get_command_value(uom, cmd)

Check against the list of UOM States if this is a valid command.

get_groups(controller=True, responder=True)

Return the groups (scenes) of which this node is a member.

If controller is True, then the scene it controls is added to the list If responder is True, then the scenes it is a responder of are added to the list.

get_property_uom(prop)

Get the Unit of Measurement for Z-Wave Climate Settings.

async get_zwave_parameter(parameter)

Retrieve a Z-Wave Parameter from the ISY.

property is_dimmable

Return the best guess if this is a dimmable node.

Check ISYv4 UOM, then Insteon and Z-Wave Types for dimmable types.

property is_lock

Determine if this device is a door lock type.

property is_thermostat

Determine if this device is a thermostat/climate control device.

property node_def_id

Return the node definition id (used for ISYv5).

property node_server

Return the node server parent slot (used for v5 Node Server devices).

property parent_node

Return the parent node object of this node.

Typically this is for devices that are represented as multiple nodes in the ISY, such as door and leak sensors. Return None if there is no parent.

property prec

Return the precision of the raw device value.

property protocol

Return the device standard used (Z-Wave, Zigbee, Insteon, Node Server).

async secure_lock()

Send a command to securely lock a lock device.

async secure_unlock()

Send a command to securely lock a lock device.

async set_climate_mode(cmd)

Send a command to the device to set the climate mode.

async set_climate_setpoint(val)

Send a command to the device to set the system setpoints.

async set_climate_setpoint_cool(val)

Send a command to the device to set the system heat setpoint.

async set_climate_setpoint_heat(val)

Send a command to the device to set the system heat setpoint.

async set_fan_mode(cmd)

Send a command to the device to set the fan mode setting.

async set_on_level(val)

Set the ON Level for a device.

async set_ramp_rate(val)

Set the Ramp Rate for a device.

async set_zwave_parameter(parameter, value, size)

Set a Z-Wave Parameter on an end device via the ISY.

async start_manual_dimming()

Begin manually dimming a device.

async stop_manual_dimming()

Stop manually dimming a device.

property type

Return the device typecode (Used for Insteon).

property uom

Return the unit of measurement for the device.

async update(event=None, wait_time=0, xmldoc=None)

Update the value of the node from the controller.

update_state(state)

Update the various state properties when received.

property zwave_props

Return the Z-Wave Properties (used for Z-Wave devices).

Group Class

class pyisy.nodes.Group(nodes, address, name, members=None, controllers=None, family_id='6', pnode=None)

Interact with ISY groups (scenes).

nodes: The node manager object.

address: The node ID.

name: The node name.

members: List of the members in this group.

controllers: List of the controllers in this group.

spoken: The string of the Notes Spoken field.

Variables

• has_children – Boolean value indicating that group has no children.

• members – List of the members of this group.

• controllers – List of the controllers of this group.

• name – The name of this group.

• status – Watched property indicating the status of the group.

• group_all_on – Watched property indicating if all devices in group are on.

__del__()

Cleanup event handlers before deleting.

__init__(nodes, address, name, members=None, controllers=None, family_id='6', pnode=None)

Initialize a Group class.

property controllers

Get the controller nodes of the scene/group.

property group_all_on

Return the current node state.

property members

Get the members of the scene/group.

property protocol

Return the protocol for this entity.

async update(event=None, wait_time=0, xmldoc=None)

Update the group with values from the controller.

update_callback(event=None)

Handle synchronous callbacks for subscriber events.

Program Manager Class

class pyisy.programs.Programs(isy, root=None, addresses=None, pnames=None, pparents=None, pobjs=None, ptypes=None, xml=None)

This class handles the ISY programs.

This class can be used as a dictionary to navigate through the controller’s structure to objects of type pyisy.programs.Program and pyisy.programs.Folder (when requested) that represent objects on the controller.

isy: The ISY device class

root: Program/Folder ID representing the current level of navigation.

addresses: List of program and folder IDs.

pnames: List of the program and folder names.

pparents: List of the program and folder parent IDs.

pobjs: List of program and folder objects.

ptypes: List of the program and folder types.

xml: XML string from the controller detailing the programs and folders.

Variables

• all_lower_programs – A list of all programs below the current navigation level. Does not return folders.

• children – A list of the children immediately below the current navigation level.

• leaf – The child object representing the current item in navigation. This is useful for getting a folder to act as a program.

• name – The name of the program at the current level of navigation.

__getitem__(val)

Navigate through the hierarchy using names or IDs.

val: Name or ID to navigate to.

__init__(isy, root=None, addresses=None, pnames=None, pparents=None, pobjs=None, ptypes=None, xml=None)

Initialize the Programs ISY programs manager class.

__iter__()

Return an iterator that iterates through all the programs.

Does not iterate folders. Only Programs that are beneath the current folder in navigation.

__repr__()

Return a string showing the hierarchy of the program manager.

__reversed__()

Return an iterator that goes in reverse order.

__setitem__(val, value)

Set the item value.

__str__()

Return a string representation of the program manager.

__weakref__

list of weak references to the object (if defined)

property all_lower_programs

Return all lower programs in a path.

property children

Return the children of the class.

get_by_id(address)

Get a program/folder with the given ID.

address: The program/folder ID to look for.

get_by_index(i)

Get the program/folder at the given index.

i: The program/folder index.

get_by_name(val)

Get a child program/folder with the given name.

val: The name of the child program/folder to look for.

insert(address, pname, pparent, pobj, ptype)

Insert a new program or folder into the manager.

address: The ID of the program or folder.

pname: The name of the program or folder.

pparent: The parent of the program or folder.

pobj: The object representing the program or folder.

ptype: The type of the item being added (program/folder).

property leaf

Return the leaf property.

property name

Return the name of the path.

parse(xml)

Parse the XML from the controller and updates the state of the manager.

xml: XML string from the controller.

async update(wait_time=0.5, address=None)

Update the status of the programs and folders.

wait_time: How long to wait before updating.

address: The program ID to update.

update_received(xmldoc)

Update programs from EventStream message.

Folder Class

class pyisy.programs.Folder(programs, address, pname, pstatus, plastup)

Object representing a program folder on the ISY device.

programs: The folder manager object.

address: The folder ID.

pname: The folder name.

pstatus: The current folder status.

Variables

• dtype – Returns the type of the object (folder).

• status – Watched property representing the current status of the folder.

__init__(programs, address, pname, pstatus, plastup)

Initialize the Folder class.

__str__()

Return a string representation of the node.

__weakref__

list of weak references to the object (if defined)

property address

Return the program or folder ID.

async disable()

Send command to the program/folder to enable it.

async enable()

Send command to the program/folder to enable it.

property last_changed

Return the last time the program was changed in this module.

property last_update

Return the last time the program was updated.

property leaf

Get the leaf property.

property name

Return the name of the Node.

property protocol

Return the protocol for this entity.

async run()

Send a run command to the program/folder.

async run_else()

Send a runElse command to the program/folder.

async run_then()

Send a runThen command to the program/folder.

async send_cmd(command)

Run the appropriate clause of the object.

property status

Return the current node state.

property status_feedback

Return information for a status change event.

async stop()

Send a stop command to the program/folder.

async update(wait_time=0.5, data=None)

Update the status of the program.

data: [optional] The data to update the folder with.

wait_time: [optional] Seconds to wait before updating.

Program Class

class pyisy.programs.Program(programs, address, pname, pstatus, plastup, plastrun, plastfin, penabled, pstartrun, prunning)

Class representing a program on the ISY controller.

programs: The program manager object.

address: The ID of the program.

pname: The name of the program.

pstatus: The current status of the program.

plastup: The last time the program was updated.

plastrun: The last time the program was run.

plastfin: The last time the program finished running.

penabled: Boolean value showing if the program is enabled on the controller.

pstartrun: Boolean value showing if the if the program runs on controller start up.

prunning: Boolean value showing if the current program is running on the controller.

__init__(programs, address, pname, pstatus, plastup, plastrun, plastfin, penabled, pstartrun, prunning)

Initialize a Program class.

__str__()

Return a string representation of the node.

__weakref__

list of weak references to the object (if defined)

property address

Return the program or folder ID.

async disable()

Send command to the program/folder to enable it.

async disable_run_at_startup()

Send command to the program to enable it to run at startup.

async enable()

Send command to the program/folder to enable it.

async enable_run_at_startup()

Send command to the program to enable it to run at startup.

property enabled

Return if the program is enabled on the controller.

property last_changed

Return the last time the program was changed in this module.

property last_finished

Return the last time the program finished running.

property last_run

Return the last time the program was run.

property last_update

Return the last time the program was updated.

property leaf

Get the leaf property.

property name

Return the name of the Node.

property protocol

Return the protocol for this entity.

property ran_else

Return the Ran Else property for this program.

property ran_then

Return the Ran Then property for this program.

async run()

Send a run command to the program/folder.

property run_at_startup

Return if the program runs on controller start up.

async run_else()

Send a runElse command to the program/folder.

async run_then()

Send a runThen command to the program/folder.

property running

Return if the current program is running on the controller.

async send_cmd(command)

Run the appropriate clause of the object.

property status

Return the current node state.

property status_feedback

Return information for a status change event.

async stop()

Send a stop command to the program/folder.

async update(wait_time=0.5, data=None)

Update the program with values on the controller.

wait_time: [optional] Seconds to wait before updating.

data: [optional] Data to update the object with.

Variable Manager Class

class pyisy.variables.Variables(isy, root=None, vids=None, vnames=None, vobjs=None, def_xml=None, var_xml=None)

This class handles the ISY variables.

This class can be used as a dictionary to navigate through the controller’s structure to objects of type pyisy.variables.Variable that represent objects on the controller.

isy: The ISY object.

root: The ID of the current level of navigation.

vids: List of variable IDs from the controller.

vnames: List of variable names form the controller.

vobjs: List of variable objects.

xml: XML string from the controller detailing the device’s variables.

Variables

children – List of the children below the current level of navigation.

__getitem__(val)

Navigate through the variables by ID or name.

val: Name or ID for navigation.

__init__(isy, root=None, vids=None, vnames=None, vobjs=None, def_xml=None, var_xml=None)

Initialize a Variables ISY Variable Manager class.

__repr__()

Return a string representing the children variables.

__setitem__(val, value)

Handle the setitem function for the Class.

__str__()

Return a string representation of the variable manager.

__weakref__

list of weak references to the object (if defined)

property children

Get the children of the class.

get_by_name(val)

Get a variable with the given name.

val: The name of the variable to look for.

parse(xml)

Parse XML from the controller with details about the variables.

parse_definitions(xmls)

Parse the XML Variable Definitions from the ISY.

async update(wait_time=0)

Update the variable objects with data from the controller.

wait_time: Seconds to wait before updating.

update_received(xmldoc)

Process an update received from the event stream.

Variable Class

class pyisy.variables.Variable(variables, vid, vtype, vname, init, status, ts, prec)

Object representing a variable on the controller.

variables: The variable manager object.

vid: List of variable IDs.

vtype: List of variable types.

init: List of values that variables initialize to when the controller starts.

val: The current variable value.

ts: The timestamp for the last time the variable was edited.

Variables

• init – Watched property that represents the value the variable initializes to when the controller boots.

• lastEdit – Watched property that indicates the last time the variable was edited.

• val – Watched property that represents the value of the variable.

__init__(variables, vid, vtype, vname, init, status, ts, prec)

Initialize a Variable class.

__repr__()

Return a string representation of the variable.

__str__()

Return a string representation of the variable.

__weakref__

list of weak references to the object (if defined)

property address

Return the formatted Variable Type and ID.

property init

Return the initial state.

property last_changed

Return the UTC Time of the last status change for this node.

property last_edited

Return the last edit time.

property last_update

Return the UTC Time of the last update for this node.

property name

Return the Variable Name.

property prec

Return the Variable Precision.

property protocol

Return the protocol for this entity.

async set_init(val)

Set the initial value for the variable after the controller boots.

val: The value to have the variable initialize to.

async set_value(val, init=False)

Set the value of the variable.

val: The value to set the variable to.

property status

Return the current node state.

property status_feedback

Return information for a status change event.

async update(wait_time=0)

Update the object with the variable’s parameters from the controller.

wait_time: Seconds to wait before updating.

property vid

Return the Variable ID.

Clock Class

class pyisy.clock.Clock(isy, xml=None)

ISY Clock class cobject.

DESCRIPTION:

This class handles the ISY clock/location info.

ATTRIBUTES:

isy: The ISY device class last_called: the time of the last call to /rest/time tz_offset: The Time Zone Offset of the ISY dst: Daylight Savings Time Enabled or not latitude: ISY Device Latitude longitude: ISY Device Longitude sunrise: ISY Calculated Sunrise sunset: ISY Calculated Sunset military: If the clock is military time or not.

__init__(isy, xml=None)

Initialize the network resources class.

isy: ISY class xml: String of xml data containing the configuration data

__repr__()

Return a long string showing all the clock values.

__str__()

Return a string representing the clock Class.

__weakref__

list of weak references to the object (if defined)

property dst

Confirm if DST is enabled or not on the ISY.

property last_called

Get the time of the last call to /rest/time in UTC.

property latitude

Provide the latitude information from the isy.

property longitude

Provide the longitude information from the isy.

property military

Confirm if military time is in use or not on the isy.

parse(xml)

Parse the xml data.

xml: String of the xml data

property sunrise

Provide the sunrise information from the isy (UTC).

property sunset

Provide the sunset information from the isy (UTC).

property tz_offset

Provide the Time Zone Offset from the isy in Hours.

async update(wait_time=0)

Update the contents of the networking class.

wait_time: [optional] Amount of seconds to wait before updating

async update_thread(interval)

Continually update the class until it is told to stop.

Should be run as a task in the event loop.

NetworkResources Class

class pyisy.networking.NetworkResources(isy, xml=None)

Network Resources class cobject.

DESCRIPTION:

This class handles the ISY networking module.

USAGE:

This object may be used in a similar way as a dictionary with the either networking command names or ids being used as keys and the ISY networking command class will be returned.

EXAMPLE:

# a = networking[‘test function’] # a.run()

ATTRIBUTES:

isy: The ISY device class addresses: List of net command ids nnames: List of net command names nobjs: List of net command objects

__getitem__(val)

Return the item from the collection.

__init__(isy, xml=None)

Initialize the network resources class.

isy: ISY class xml: String of xml data containing the configuration data

__setitem__(val, value)

Set the item value.

__weakref__

list of weak references to the object (if defined)

get_by_id(val)

Return command object being given a command id.

val: Integer representing command id

get_by_index(val)

Return command object being given a command index.

val: Integer representing command index in List

get_by_name(val)

Return command object being given a command name.

val: String representing command name

parse(xml)

Parse the xml data.

xml: String of the xml data

async update(wait_time=0)

Update the contents of the networking class.

wait_time: [optional] Amount of seconds to wait before updating

async update_threaded(interval)

Continually update the class until it is told to stop.

Should be run in a thread.

NetworkCommand Class

class pyisy.networking.NetworkCommand(network_resources, address)

Network Command Class.

DESCRIPTION:

This class handles individual networking commands.

ATTRIBUTES:

network_resources: The networkin resources class

__init__(network_resources, address)

Initialize network command class.

network_resources: NetworkResources class address: Integer of the command id

__weakref__

list of weak references to the object (if defined)

property address

Return the Resource ID for the Network Resource.

async run()

Execute the networking command.

Connection Class

class pyisy.connection.Connection(address, port, username, password, use_https=False, tls_ver=1.1, webroot='', websession=None)

Connection object to manage connection to and interaction with ISY.

__init__(address, port, username, password, use_https=False, tls_ver=1.1, webroot='', websession=None)

Initialize the Connection object.

__weakref__

list of weak references to the object (if defined)

async close()

Cleanup connections and prepare for exit.

compile_url(path, query=None)

Compile the URL to fetch from the ISY.

property connection_info

Return the connection info required to connect to the ISY.

async get_config(retries=0)

Fetch the configuration from the ISY.

async get_description()

Fetch the services description from the ISY.

async get_network()

Fetch the list of network resources from the ISY.

async get_nodes()

Fetch the list of nodes/groups/scenes from the ISY.

async get_programs(address=None)

Fetch the list of programs from the ISY.

async get_status()

Fetch the status of nodes/groups/scenes from the ISY.

async get_time()

Fetch the system time info from the ISY.

async get_variable_defs()

Fetch the list of variables from the ISY.

async get_variables()

Fetch the variable details from the ISY to update local copy.

async ping()

Test connection to the ISY and return True if alive.

async request(url, retries=0, ok404=False, delay=0)

Execute request to ISY REST interface.

async test_connection()

Test the connection and get the config for the ISY.