Network documentation

This is the central point. Everything is attached to a network.

This file is part of python-openzwave project https://github.com/OpenZWave/python-openzwave.

platform:Unix, Windows, MacOS X sinopsis:openzwave API

License : GPL(v3)

python-openzwave is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

python-openzwave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with python-openzwave. If not, see http://www.gnu.org/licenses.

class openzwave.network.ZWaveNetwork(options, log=None, autostart=True, kvals=True)

The network object = homeid. It contains a reference to the manager and the controller.

It dispatches the following louie signals :

• SIGNAL_NETWORK_FAILED = ‘NetworkFailed’
• SIGNAL_NETWORK_STARTED = ‘NetworkStarted’
• SIGNAL_NETWORK_READY = ‘NetworkReady’
• SIGNAL_NETWORK_STOPPED = ‘NetworkStopped’
• SIGNAL_NETWORK_RESETTED = ‘DriverResetted’
• SIGNAL_NETWORK_AWAKED = ‘DriverAwaked’
• SIGNAL_DRIVER_FAILED = ‘DriverFailed’
• SIGNAL_DRIVER_READY = ‘DriverReady’
• SIGNAL_DRIVER_RESET = ‘DriverReset’
• SIGNAL_DRIVER_REMOVED = ‘DriverRemoved’
• SIGNAL_NODE_ADDED = ‘NodeAdded’
• SIGNAL_NODE_EVENT = ‘NodeEvent’
• SIGNAL_NODE_NAMING = ‘NodeNaming’
• SIGNAL_NODE_NEW = ‘NodeNew’
• SIGNAL_NODE_PROTOCOL_INFO = ‘NodeProtocolInfo’
• SIGNAL_NODE_READY = ‘NodeReady’
• SIGNAL_NODE_REMOVED = ‘NodeRemoved’
• SIGNAL_SCENE_EVENT = ‘SceneEvent’
• SIGNAL_VALUE_ADDED = ‘ValueAdded’
• SIGNAL_VALUE_CHANGED = ‘ValueChanged’
• SIGNAL_VALUE_REFRESHED = ‘ValueRefreshed’
• SIGNAL_VALUE_REMOVED = ‘ValueRemoved’
• SIGNAL_POLLING_ENABLED = ‘PollingEnabled’
• SIGNAL_POLLING_DISABLED = ‘PollingDisabled’
• SIGNAL_CREATE_BUTTON = ‘CreateButton’
• SIGNAL_DELETE_BUTTON = ‘DeleteButton’
• SIGNAL_BUTTON_ON = ‘ButtonOn’
• SIGNAL_BUTTON_OFF = ‘ButtonOff’
• SIGNAL_ESSENTIAL_NODE_QUERIES_COMPLETE = ‘EssentialNodeQueriesComplete’
• SIGNAL_NODE_QUERIES_COMPLETE = ‘NodeQueriesComplete’
• SIGNAL_AWAKE_NODES_QUERIED = ‘AwakeNodesQueried’
• SIGNAL_ALL_NODES_QUERIED = ‘AllNodesQueried’
• SIGNAL_ALL_NODES_QUERIED_SOME_DEAD = ‘AllNodesQueriedSomeDead’
• SIGNAL_MSG_COMPLETE = ‘MsgComplete’
• SIGNAL_ERROR = ‘Error’
• SIGNAL_NOTIFICATION = ‘Notification’
• SIGNAL_CONTROLLER_COMMAND = ‘ControllerCommand’
• SIGNAL_CONTROLLER_WAITING = ‘ControllerWaiting’

The table presented below sets notifications in the order they might typically be received, and grouped into a few logically related categories. Of course, given the variety of ZWave controllers, devices and network configurations the actual sequence will vary (somewhat). The descriptions below the notification name (in square brackets) identify whether the notification is always sent (unless there’s a significant error in the network or software) or potentially sent during the execution sequence.

Driver Initialization Notification

The notification below is sent when OpenZWave has successfully connected to a physical ZWave controller.

• DriverReady

[always sent] Sent when the driver (representing a connection between OpenZWave and a Z-Wave controller attached to the specified serial (or HID) port) has been initialized. At the time this notification is sent, only certain information about the controller itself is known:

• Controller Z-Wave version
• Network HomeID
• Controller capabilities
• Controller Application Version & Manufacturer/Product ID
• Nodes included in the network

• DriverRemoved

[always sent (either due to Error or by request)] The Driver is being removed. Do Not Call Any Driver Related Methods after receiving this

Node Initialization Notifications

As OpenZWave starts, it identifies and reads information about each node in the network. The following notifications may be sent during the initialization process.

• NodeNew

[potentially sent] Sent when a new node has been identified as part of the Z-Wave network. It is not sent if the node was identified in a prior execution of the OpenZWave library and stored in the zwcfg*.xml file. At the time this notification is sent, very little is known about the node itself… only that it is new to OpenZWave. This message is sent once for each new node identified.

• NodeAdded

[always sent (for each node associated with the controller)] Sent when a node has been added to OpenZWave’s set of nodes. It can be triggered either as the zwcfg*.xml file is being read, when a new node is found on startup (see NodeNew notification above), or if a new node is included in the network while OpenZWave is running. As with NodeNew, very little is known about the node at the time the notification is sent…just the fact that a new node has been identified and its assigned NodeID.

• NodeProtocolInfo

[potentially sent] Sent after a node’s protocol information has been successfully read from the controller. At the time this notification is sent, only certain information about the node is known:

• Whether it is a “listening” or “sleeping” device
• Whether the node is capable of routing messages
• Maximum baud rate for communication
• Version number
• Security byte

NodeNaming

[potentially sent] Sent when a node’s name has been set or changed (although it may be “set” to “” or NULL).

• ValueAdded

[potentially sent] Sent when a new value has been associated with the node. At the time this notification is sent, the new value may or may not have “live” data associated with it. It may be populated, but it may alternatively just be a placeholder for a value that has not been read at the time the notification is sent.

• NodeQueriesComplete

[always sent (for each node associated with the controller that has been successfully queried)] Sent when a node’s values and attributes have been fully queried. At the time this notification is sent, the node’s information has been fully read at least once. So this notification might trigger “full” display of the node’s information, values, etc. If this notification is not sent, it indicates that there has been a problem initializing the device. The most common issue is that the node is a “sleeping” device. The NodeQueriesComplete notification will be sent when the node wakes up and the query process completes.

Initialization Complete Notifications

As indicated above, when OpenZWave starts it reads certain information from a file, from the controller and from the network. The following notifications identify when this initialization/querying process is complete.

• AwakeNodesQueried

[always sent] Sent when all “listening” -always-on-devices have been queried successfully. It also indicates, by implication, that there are some “sleeping” nodes that will not complete their queries until they wake up. This notification should be sent relatively quickly after start-up. (Of course, it depends on the number of devices on the ZWave network and whether there are any messages that “time out” without a proper response.)

• AllNodesQueried

[potentially sent] Sent when all nodes have been successfully queried.

This notification should be sent relatively quickly if there are no “sleeping” nodes. But it might be sent quite a while after start-up if there are sleeping nodes and at least one of these nodes has a long “wake-up” interval.

Other Notifications

In addition to the notifications described above, which are primarily “initialization” notifications that are sent during program start-up, the following notifications may be sent as a result of user actions, external program control, etc.

• ValueChanged : Sent when a value associated with a node has changed. Receipt of this notification indicates that it may be a good time to read the new value and display or otherwise process it accordingly.
• ValueRemoved : Sent when a value associated with a node has been removed.
• Group : Sent when a node’s group association has changed.
• NodeRemoved : Sent when a node has been removed from the ZWave network.
• NodeEvent : Sent when a node sends a Basic_Set command to the controller. This notification can be generated by certain sensors, for example, motion detectors, to indicate that an event has been sensed.
• PollingEnabled : Sent when node/value polling has been enabled.
• PollingDisabled : Sent when node/value polling has been disabled.
• DriverReset : Sent to indicate when a controller has been reset. This notification is intended to replace the potentially hundreds of notifications representing each value and node removed from the network.

About the use of louie signals : For network, python-openzwave send the following louie signal :

SIGNAL_NETWORK_FAILED : the driver has failed to start. SIGNAL_NETWORK_STARTED : the driver is ready, but network is not available. SIGNAL_NETWORK_AWAKED : all awake nodes are queried. Some sleeping nodes may be missing. SIGNAL_NETWORK_READY : all nodes are queried. Network is fully functionnal. SIGNAL_NETWORK_RESETTED : the network has been resetted. It will start again. SIGNAL_NETWORK_STOPPED : the network has been stopped.

Deprecated : SIGNAL_DRIVER_* shouldn’t be used anymore.

controller

The controller of the network.

Returns:The controller of the network Return type:ZWaveController

create_scene(label=None)

Create a new scene on the network. If label is set, also change the label of the scene

If you store your scenes on a local variable, get a new one to get the scene id

Parameters:label (str or None) – The new label Returns:return the id of scene on the network. Return 0 if fails Return type:int

destroy()

Destroy the netwok and all related stuff.

get_poll_interval()

Get the time period between polls of a nodes state

Returns:The number of milliseconds between polls Return type:int

get_scenes()

The scenes of the network.

Scenes are generated directly from the lib. There is no notification support to keep them up to date. So for a batch job, consider storing them in a local variable.

Returns:return a dict() (that can be empty) of scene object. Return None if betwork is not ready Return type:dict() or None

get_value(value_id)

Retrieve a value on the network.

Check every nodes to see if it holds the value

Parameters:value_id (int) – The id of the value to find Returns:The value or None Return type:ZWaveValue

get_value_from_id_on_network(id_on_network)

Retrieve a value on the network from it’s id_on_network.

Check every nodes to see if it holds the value

Parameters:id_on_network (str) – The id_on_network of the value to find Returns:The value or None Return type:ZWaveValue

heal(upNodeRoute=False)

Heal network by requesting nodes rediscover their neighbors. Sends a ControllerCommand_RequestNodeNeighborUpdate to every node. Can take a while on larger networks.

Parameters:upNodeRoute (bool) – Optional Whether to perform return routes initialization. (default = false). Returns:True is the ControllerCommand ins sent. False otherwise Return type:bool

home_id

The home_id of the network.

Return type:int

home_id_str

The home_id of the network as string.

Return type:str

id_separator

The separator in id representation.

Return type:char

is_ready

Says if the network is ready for operations.

Return type:bool

manager

The manager to use to communicate with the lib c++.

Return type:ZWaveManager

nodes

The nodes of the network.

Return type:dict()

nodes_count

The nodes count of the network.

Return type:int

nodes_to_dict(extras=['all'])

Return a dict representation of the network.

Parameters:extras ([]) – The extra inforamtions to add Returns:A dict Return type:dict()

remove_scene(scene_id)

Delete the scene on the network.

Parameters:scene_id (int) – The id of the scene to check Returns:True if the scene was removed. False in other cases Return type:bool

scene_exists(scene_id)

Check that the scene exists

Parameters:scene_id (int) – The id of the scene to check Returns:True if the scene exist. False in other cases Return type:bool

scenes_count

Return the number of scenes

Returns:The number of scenes Return type:int

scenes_to_dict(extras=['all'])

Return a JSONifiable dict representation of the scenes.

Parameters:extras ([]) – The extra inforamtions to add Returns:A dict Return type:dict()

set_poll_interval(milliseconds=500, bIntervalBetweenPolls=True)

Set the time period between polls of a nodes state.

Due to patent concerns, some devices do not report state changes automatically to the controller. These devices need to have their state polled at regular intervals. The length of the interval is the same for all devices. To even out the Z-Wave network traffic generated by polling, OpenZWave divides the polling interval by the number of devices that have polling enabled, and polls each in turn. It is recommended that if possible, the interval should not be set shorter than the number of polled devices in seconds (so that the network does not have to cope with more than one poll per second).

Parameters:

• milliseconds (int) – The length of the polling interval in milliseconds.
• bIntervalBetweenPolls (bool) – If set to true (via SetPollInterval), the pollInterval will be interspersed between each poll (so a much smaller m_pollInterval like 100, 500, or 1,000 may be appropriate). If false, the library attempts to complete all polls within m_pollInterval.

sleeping_nodes_count

The count of sleeping nodes on the network.

Return type:int

start()

Start the network object :

• add a watcher
• add a driver

state

The state of the network. Values may be changed in the future, only order is important. You can safely ask node information when state >= STATE_READY

• STATE_STOPPED = 0
• STATE_FAILED = 1
• STATE_RESETTED = 3
• STATE_STARTED = 5
• STATE_AWAKED = 7
• STATE_READY = 10

Return type:int

state_str

The state of the network. Values may be changed in the future, only order is important. You can safely ask node informations when state >= STATE_AWAKED

Return type:int

stop(fire=True)

Stop the network object.

• remove the watcher
• remove the driver
• clear the nodes

dispatcher.send(self.SIGNAL_NETWORK_STOPPED, **{'network': self})

switch_all(state)

Method for switching all devices on or off together. The devices must support the SwitchAll command class. The command is first broadcast to all nodes, and then followed up with individual commands to each node (because broadcasts are not routed, the message might not otherwise reach all the nodes).

Parameters:state (bool) – True to turn on the switches, False to turn them off

test(count=1)

Send a number of test messages to every node and record results.

Parameters:count (int) – The number of test messages to send.

to_dict(extras=['kvals'])

Return a dict representation of the network.

Parameters:extras ([]) – The extra inforamtions to add Returns:A dict Return type:dict()

write_config()

The last message that was sent is now complete.

zwcallback(args)

The Callback Handler used with the libopenzwave.

n[‘valueId’] = {

• ‘home_id’ : v.GetHomeId(),
• ‘node_id’ : v.GetNodeId(),
• ‘commandClass’ : PyManager.COMMAND_CLASS_DESC[v.GetCommandClassId()],
• ‘instance’ : v.GetInstance(),
• ‘index’ : v.GetIndex(),
• ‘id’ : v.GetId(),
• ‘genre’ : PyGenres[v.GetGenre()],
• ‘type’ : PyValueTypes[v.GetType()],
• #’value’ : value.c_str(),
• ‘value’ : getValueFromType(manager,v.GetId()),
• ‘label’ : label.c_str(),
• ‘units’ : units.c_str(),
• ‘readOnly’: manager.IsValueReadOnly(v)

}

Parameters:args (dict()) – A dict containing informations about the state of the controller