Controller documentation¶
The controller is the node of your adaptater. You can use it to retrieve informations on it : library, statistics, …
- 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.controller.
ZWaveController
(controller_id, network, options=None)¶ The controller manager.
Allows to retrieve informations about the library, statistics, … Also used to send commands to the controller
Commands :
- Driver::ControllerCommand_AddController : Add a new secondary controller to the Z-Wave network.
- Driver::ControllerCommand_AddDevice : Add a new device (but not a controller) to the Z-Wave network.
- Driver::ControllerCommand_CreateNewPrimary : (Not yet implemented)
- Driver::ControllerCommand_ReceiveConfiguration :
- Driver::ControllerCommand_RemoveController : remove a controller from the Z-Wave network.
- Driver::ControllerCommand_RemoveDevice : remove a device (but not a controller) from the Z-Wave network.
- Driver::ControllerCommand_RemoveFailedNode : move a node to the controller’s list of failed nodes. The node must actually
- have failed or have been disabled since the command will fail if it responds. A node must be in the controller’s failed nodes list or ControllerCommand_ReplaceFailedNode to work.
- Driver::ControllerCommand_HasNodeFailed : Check whether a node is in the controller’s failed nodes list.
- Driver::ControllerCommand_ReplaceFailedNode : replace a failed device with another. If the node is not in
- the controller’s failed nodes list, or the node responds, this command will fail.
- Driver:: ControllerCommand_TransferPrimaryRole : (Not yet implemented) - Add a new controller to the network and
- make it the primary. The existing primary will become a secondary controller.
- Driver::ControllerCommand_RequestNetworkUpdate : Update the controller with network information from the SUC/SIS.
- Driver::ControllerCommand_RequestNodeNeighborUpdate : Get a node to rebuild its neighbour list. This method also does ControllerCommand_RequestNodeNeighbors afterwards.
- Driver::ControllerCommand_AssignReturnRoute : Assign a network return route to a device.
- Driver::ControllerCommand_DeleteAllReturnRoutes : Delete all network return routes from a device.
- Driver::ControllerCommand_CreateButton : Create a handheld button id.
- Driver::ControllerCommand_DeleteButton : Delete a handheld button id.
Callbacks :
- Driver::ControllerState_Waiting : The controller is waiting for a user action. A notice should be displayed
- to the user at this point, telling them what to do next. For the add, remove, replace and transfer primary role commands, the user needs to be told to press the inclusion button on the device that is going to be added or removed. For ControllerCommand_ReceiveConfiguration, they must set their other controller to send its data, and for ControllerCommand_CreateNewPrimary, set the other controller to learn new data.
- Driver::ControllerState_InProgress : the controller is in the process of adding or removing the chosen node. It is now too late to cancel the command.
- Driver::ControllerState_Complete : the controller has finished adding or removing the node, and the command is complete.
- Driver::ControllerState_Failed : will be sent if the command fails for any reason.
-
add_node
(doSecurity=False)¶ Start the Inclusion Process to add a Node to the Network.
The Status of the Node Inclusion is communicated via Notifications. Specifically, you should monitor ControllerCommand Notifications.
Results of the AddNode Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: doSecurity (bool) – Whether to initialize the Network Key on the device if it supports the Security CC Returns: True if the request was sent successfully. Return type: bool
-
assign_return_route
(nodeid)¶ Ask a Node to update its update its Return Route to the Controller
This command will ask a Node to update its Return Route to the Controller
Results of the AssignReturnRoute Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
begin_command_add_device
(**kwargs)¶ Add a new device to the Z-Wave network.
Parameters: high_power (bool) – Used only with the AddDevice, AddController, RemoveDevice and RemoveController commands. Usually when adding or removing devices, the controller operates at low power so that the controller must be physically close to the device for security reasons. If _highPower is true, the controller will operate at normal power levels instead. Defaults to false. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_assign_return_route
(**kwargs)¶ Assign a network return route from a node to another one.
Parameters: - from_node_id (int) – The node that we will use the route.
- to_node_id (int) – The node that we will change the route
Returns: True if the command was accepted and has started.
Return type: bool
Create a handheld button id
Parameters: - node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced.
- arg (int) –
Returns: True if the command was accepted and has started.
Return type: bool
-
begin_command_create_new_primary
(**kwargs)¶ Add a new controller to the Z-Wave network. Used when old primary fails. Requires SUC.
Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_delete_all_return_routes
(**kwargs)¶ Delete all network return routes from a device.
Parameters: node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced. Returns: True if the command was accepted and has started. Return type: bool
Delete a handheld button id.
Parameters: - node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced.
- arg (int) –
Returns: True if the command was accepted and has started.
Return type: bool
-
begin_command_has_node_failed
(**kwargs)¶ Check whether a node is in the controller’s failed nodes list.
Parameters: node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_receive_configuration
(**kwargs)¶ Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_remove_device
(**kwargs)¶ Remove a device from the Z-Wave network.
Parameters: high_power (bool) – Used only with the AddDevice, AddController, RemoveDevice and RemoveController commands. Usually when adding or removing devices, the controller operates at low power so that the controller must be physically close to the device for security reasons. If _highPower is true, the controller will operate at normal power levels instead. Defaults to false. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_remove_failed_node
(**kwargs)¶ Move a node to the controller’s list of failed nodes. The node must actually have failed or have been disabled since the command will fail if it responds. A node must be in the controller’s failed nodes list for ControllerCommand_ReplaceFailedNode to work.
Parameters: node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_replace_failed_node
(**kwargs)¶ Replace a failed device with another. If the node is not in the controller’s failed nodes list, or the node responds, this command will fail.
Parameters: node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_replication_send
(**kwargs)¶ Send information from primary to secondary.
Parameters: high_power (bool) – Usually when adding or removing devices, the controller operates at low power so that the controller must be physically close to the device for security reasons. If _highPower is true, the controller will operate at normal power levels instead. Defaults to false. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_request_network_update
(**kwargs)¶ Update the controller with network information from the SUC/SIS.
Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_request_node_neigbhor_update
(**kwargs)¶ Get a node to rebuild its neighbors list. This method also does ControllerCommand_RequestNodeNeighbors afterwards.
Parameters: node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_send_node_information
(**kwargs)¶ Send a node information frame.
Parameters: node_id (int) – Used only with the ReplaceFailedNode command, to specify the node that is going to be replaced. Returns: True if the command was accepted and has started. Return type: bool
-
begin_command_transfer_primary_role
(**kwargs)¶ Make a different controller the primary. The existing primary will become a secondary controller.
Parameters: high_power (bool) – Used only with the AddDevice, AddController, RemoveDevice and RemoveController commands. Usually when adding or removing devices, the controller operates at low power so that the controller must be physically close to the device for security reasons. If _highPower is true, the controller will operate at normal power levels instead. Defaults to false. Returns: True if the command was accepted and has started. Return type: bool
-
cancel_command
()¶ Cancels any in-progress command running on a controller.
-
capabilities
¶ The capabilities of the controller.
Returns: The capabilities of the controller Return type: set
Create a handheld button id.
Only intended for Bridge Firmware Controllers.
Results of the CreateButton Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: - nodeId (int) – The ID of the node to query.
- buttonid (int) – the ID of the Button to query.
Returns: True if the request was sent successfully.
Return type: bool
-
create_new_primary
()¶ Create a new primary controller when old primary fails. Requires SUC.
This command creates a new Primary Controller when the Old Primary has Failed. Requires a SUC on the network to function.
Results of the CreateNewPrimary Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Returns: True if the request was sent successfully. Return type: bool
-
delete_all_return_routes
(nodeid)¶ Ask a Node to delete all Return Route.
This command will ask a Node to delete all its return routes, and will rediscover when needed.
Results of the DeleteAllReturnRoutes Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
Delete a handheld button id.
Only intended for Bridge Firmware Controllers.
Results of the CreateButton Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: - nodeId (int) – The ID of the node to query.
- buttonid (int) – the ID of the Button to query.
Returns: True if the request was sent successfully.
Return type: bool
-
device
¶ The device path.
Returns: The device (ie /dev/zwave) Return type: str
-
do_poll_statistics
()¶ Timer based polling system for statistics
-
get_stats_label
(stat)¶ Retrieve label of the statistic from driver.
Parameters: stat – The code of the stat label to retrieve. Returns: The label or the stat. Return type: str
-
hard_reset
()¶ Hard Reset a PC Z-Wave Controller. Resets a controller and erases its network configuration settings. The controller becomes a primary controller ready to add devices to a new network.
This command fires a lot of louie signals. Louie’s clients must disconnect from nodes and values signals
dispatcher.send(self._network.SIGNAL_NETWORK_RESETTED, **{'network': self._network})
-
has_node_failed
(nodeid)¶ Check if the Controller Believes a Node has Failed.
This is different from the IsNodeFailed call in that we test the Controllers Failed Node List, whereas the IsNodeFailed is testing our list of Failed Nodes, which might be different.
The Results will be communicated via Notifications. Specifically, you should monitor the ControllerCommand notifications
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
is_bridge_controller
¶ Is this controller using the bridge controller library.
Return type: bool
-
is_locked
¶ Check if the controller is locked or not. Should not be used. Listen to notifications and use request_controller_status to retrieve the status of the controller
-
is_primary_controller
¶ Is this node a primary controller of the network.
Return type: bool
-
is_static_update_controller
¶ Is this controller a static update controller (SUC).
Return type: bool
-
kill_command
()¶ Cancels any in-progress command running on a controller and release the lock.
-
library_config_path
¶ The library Config path.
Returns: The library config directory Return type: str
-
library_description
¶ The description of the library.
Returns: The library description (name and version) Return type: str
-
library_type_name
¶ The name of the library.
Returns: The cpp library name Return type: str
-
library_user_path
¶ The library User path.
Returns: The user directory to store user configuration Return type: str
-
library_version
¶ The version of the library.
Returns: The cpp library version Return type: str
-
name
¶ The node name of the controller on the network.
Returns: The node’s name of the controller on the network Return type: str
-
node
¶ The node controller on the network.
Returns: The node controller on the network Return type: ZWaveNode
-
node_id
¶ The node Id of the controller on the network.
Returns: The node id of the controller on the network Return type: int
-
options
¶ The starting options of the manager.
Returns: The options used to start the manager Return type: ZWaveOption
-
ozw_library_version
¶ The version of the openzwave library.
Returns: The openzwave library version Return type: str
-
poll_stats
¶ The interval for polling statistics
Returns: The interval in seconds Return type: float
-
python_library_config_version
¶ The version of the config for python library.
Returns: The python library config version Return type: str
-
python_library_flavor
¶ The flavor of the python library.
Returns: The python library flavor Return type: str
-
python_library_version
¶ The version of the python library.
Returns: The python library version Return type: str
-
receive_configuration
()¶ Receive network configuration information from primary controller. Requires secondary.
This command prepares the controller to recieve Network Configuration from a Secondary Controller.
Results of the ReceiveConfiguration Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Returns: True if the request was sent successfully. Return type: bool
-
remove_failed_node
(nodeid)¶ Remove a Failed Device from the Z-Wave Network
This Command will remove a failed node from the network. The Node should be on the Controllers Failed Node List, otherwise this command will fail. You can use the HasNodeFailed function below to test if the Controller believes the Node has Failed.
The Status of the Node Removal is communicated via Notifications. Specifically, you should monitor ControllerCommand Notifications.
Results of the RemoveFailedNode Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
remove_node
()¶ Remove a Device from the Z-Wave Network
The Status of the Node Removal is communicated via Notifications. Specifically, you should monitor ControllerCommand Notifications.
Results of the RemoveNode Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: doSecurity (bool) – Whether to initialize the Network Key on the device if it supports the Security CC Returns: True if the request was sent successfully. Return type: bool
-
replace_failed_node
(nodeid)¶ Replace a failed device with another.
If the node is not in the controller’s failed nodes list, or the node responds, this command will fail.
You can check if a Node is in the Controllers Failed node list by using the HasNodeFailed method.
Results of the ReplaceFailedNode Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
replication_send
(nodeid)¶ Send information from primary to secondary
Results of the ReplicationSend Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommandParameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
request_controller_status
()¶ Generate a notification with the current status of the controller. You can check the lock in your code using something like this:
- if controllerState in network.controller.STATES_UNLOCKED:
- hide_cancel_button() show_command_buttons()
- else:
- show_cancel_button() hide_command_buttons()
-
request_network_update
(nodeid)¶ Update the controller with network information from the SUC/SIS.
Results of the RequestNetworkUpdate Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
request_node_neighbor_update
(nodeid)¶ Ask a Node to update its Neighbor Tables
This command will ask a Node to update its Neighbor Tables.
Results of the RequestNodeNeighborUpdate Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
send_node_information
(nodeid)¶ Send a NIF frame from the Controller to a Node. This command send a NIF frame from the Controller to a Node
Results of the SendNodeInformation Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Parameters: nodeId (int) – The ID of the node to query. Returns: True if the request was sent successfully. Return type: bool
-
send_queue_count
¶ Get count of messages in the outgoing send queue.
Returns: The count of messages in the outgoing send queue. Return type: int
-
soft_reset
()¶ Soft Reset a PC Z-Wave Controller. Resets a controller without erasing its network configuration settings.
-
stats
¶ Retrieve statistics from driver.
Statistics:
- s_SOFCnt : Number of SOF bytes received
- s_ACKWaiting : Number of unsolicited messages while waiting for an ACK
- s_readAborts : Number of times read were aborted due to timeouts
- s_badChecksum : Number of bad checksums
- s_readCnt : Number of messages successfully read
- s_writeCnt : Number of messages successfully sent
- s_CANCnt : Number of CAN bytes received
- s_NAKCnt : Number of NAK bytes received
- s_ACKCnt : Number of ACK bytes received
- s_OOFCnt : Number of bytes out of framing
- s_dropped : Number of messages dropped & not delivered
- s_retries : Number of messages retransmitted
- s_controllerReadCnt : Number of controller messages read
- s_controllerWriteCnt : Number of controller messages sent
Returns: Statistics of the controller Return type: dict()
-
stop
()¶ Stop the controller and all this threads.
-
to_dict
(extras=['all'])¶ Return a dict representation of the controller.
Parameters: extras ([]) – The extra inforamtions to add Returns: A dict Return type: dict()
-
transfer_primary_role
()¶ Add a new controller to the network and make it the primary.
The existing primary will become a secondary controller.
Results of the TransferPrimaryRole Command will be send as a Notification with the Notification type as Notification::Type_ControllerCommand
Returns: True if the request was sent successfully. Return type: bool
-
update_ozw_config
()¶ Update the openzwave config from github. Not available for shared flavor as we don’t want to update the config of the precompiled config.
-
zwcallback
(**kwargs)¶ The Callback Handler used when sendig commands to the controller. Dispatch a louie message.
To do : add node in signal when necessary
Parameters: args (dict()) – A dict containing informations about the state of the controller