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 http://code.google.com/p/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 for 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.

begin_command_add_device(high_power=False)

Add a new device to the Z-Wave network.

Parameters:high_power – 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. :type high_power: bool :return: True if the command was accepted and has started. :rtype: bool

begin_command_assign_return_route(from_node_id, to_node_id)

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

begin_command_create_button(node_id, arg=0)

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()

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(node_id)

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
begin_command_delete_button(node_id, arg=0)

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(node_id)

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()
Returns:True if the command was accepted and has started.
Return type:bool
begin_command_remove_device(high_power=False)

Remove a device from the Z-Wave network.

Parameters:high_power – 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. :type high_power: bool :return: True if the command was accepted and has started. :rtype: bool

begin_command_remove_failed_node(node_id)

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(node_id)

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(high_power=False)

Send information from primary to secondary.

Parameters:high_power – 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. :type high_power: bool :return: True if the command was accepted and has started. :rtype: bool

begin_command_request_network_update()

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(node_id)

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(node_id)

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(high_power=False)

Make a different controller the primary. The existing primary will become a secondary controller.

Parameters:high_power – 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. :type high_power: bool :return: True if the command was accepted and has started. :rtype: 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
device

The device path.

Returns:The device (ie /dev/zwave)
Return type:str
get_stats_label(stat)

Retrieve abel 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})

is_bridge_controller

Is this controller using the bridge controller library.

Return type:bool
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
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
python_library_version

The version of the python library.

Returns:The python library version
Return type:str
send_queue_count

Get count of messages in the outgoing send queue.

Returns:Thr 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()
zwcallback(args)

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

Previous topic

Network documentation

Next topic

Option documentation

This Page