xs1-api-client

A python library for accessing actuator and sensor data on the the EZcontrol® XS1 Gateway using their HTTP API.

How to use

Installation

pip install xs1-api-client

Usage

For a basic example have a look at the example.py file. If you need more info have a look at the documentation which should help.

License

xs1-api-client by Markus Ressel
Copyright (C) 2017  Markus Ressel

This program 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.

This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

Content:

API

xs1_api_client package

Subpackages

xs1_api_client.device package

Subpackages

xs1_api_client.device.actuator package

Submodules

xs1_api_client.device.actuator.base module

class xs1_api_client.device.actuator.base.XS1Actuator(state, api_interface)

Bases: xs1_api_client.device.base.XS1Device

Represents a basic XS1 Actuator, there may be special variants for some types.

call_function(function)

Calls the specified function by id and saves the api response as the new state

Parameters:function – XS1Function object

get_functions()

Returns:a list of functions that can be executed using the call_function() method

set_value(value)

Sets a new value for this actuator

Parameters:value – new value to set

update()

Updates the state of this actuator

class xs1_api_client.device.actuator.base.XS1Function(actuator, id, type, description)

Bases: object

Represents a function of a XS1Actuator.

description()

Returns:a description for this function

execute()

Executes this function and sets the response as the new actuator value

id()

Returns:the id of this function (note that this id is only unique for a single actuator!)

type()

Returns:the type of this function

xs1_api_client.device.actuator.switch module

class xs1_api_client.device.actuator.switch.XS1Switch(state, api_interface)

Bases: xs1_api_client.device.actuator.base.XS1Actuator

Represents a XS1 Switch.

turn_off()

Turns off the switch.

turn_on()

Turns on the switch.

xs1_api_client.device.actuator.thermostat module

class xs1_api_client.device.actuator.thermostat.XS1Thermostat(state, api_interface)

Bases: xs1_api_client.device.actuator.base.XS1Actuator

Represents a basic XS1 Actuator, there may be special variants for some types.

set_temperature(temp)

Sets the new target temperature of this thermostat

Parameters:temp – double value

Module contents

xs1_api_client.device.sensor package

Submodules

xs1_api_client.device.sensor.base module

class xs1_api_client.device.sensor.base.XS1Sensor(state, api_interface)

Bases: xs1_api_client.device.base.XS1Device

Represents a XS1 Sensor

set_value(value)

Sets a value for this sensor This should only be used for debugging purpose! :param value: new value to set

update()

Updates the state of this sensor

Module contents

Submodules

xs1_api_client.device.base module

class xs1_api_client.device.base.XS1Device(state: dict, api_interface)

Bases: object

This is a generic XS1 device, all other objetcs inherit from this.

enabled()

Returns:Returns if this device is enabled.

id()

Returns:id of this device

last_update()

Returns:the time when this device’s value was updated last

name()

Returns:the name of this device

new_value()

Returns the new value to set for this device. If this value differs from the currrent value the gateway is still trying to update the value on the device. If it does not differ the value has already been set.

Returns:the new value to set for this device

set_state(new_state: dict)

Sets a new state for this device. If there is an existing state, new and old values will be merged to retain any information that was missing from api responses.

Parameters:new_state – new representation of this device (api response)

set_value(value)

Sets a new value for this device. This method should be implemented by inheriting classes.

Parameters:value – the new value to set

type()

Returns:the type of this device

unit()

Returns:the unit that is used for the value

update()

Updates the current value of this device. This method should be implemented by inheriting classes.

value()

Returns:the current value of this device

Module contents

Submodules

xs1_api_client.api module

This is the main xs1_api_client api which contains the XS1 object to interact with the gateway.

Example usage can be found in the example.py file

class xs1_api_client.api.XS1(host: str = None, user: str = None, password: str = None)

Bases: object

This class is the main api interface that handles all communication with the XS1 gateway.

call_actuator_function(actuator_id, function)

Executes a function on the specified actuator and sets the response on the passed in actuator.

Parameters:

• actuator_id – actuator id to execute the function on and set response value
• function – id of the function to execute

Returns:

the api response

get_all_actuators()

Requests the list of enabled actuators from the gateway.

Returns:a list of XS1Actuator objects

get_all_sensors()

Requests the list of enabled sensors from the gateway.

Returns:list of XS1Sensor objects

get_gateway_bootloader_version()

Returns:the bootloader version number of the gateway

get_gateway_firmware_version()

Returns:the firmware version number of the gateway

get_gateway_hardware_version()

Returns:the hardware version number of the gateway

get_gateway_mac()

Returns:the mac address of the gateway

get_gateway_name()

Returns:the hostname of the gateway

get_gateway_uptime()

Returns:the uptime of the gateway in seconds

get_protocol_info()

Retrieves the protocol version that is used by the gateway

Returns:protocol version number

get_state_actuator(actuator_id)

Gets the current state of the specified actuator.

Parameters:actuator_id – actuator id Returns:the api response as a dict

get_state_sensor(sensor_id)

Gets the current state of the specified sensor.

Parameters:sensor_id – sensor id Returns:the api response as a dict

send_request(command, *parameters)

Sends a GET request to the XS1 Gateway and returns the response as a JSON object.

Parameters:

• command – command parameter for the URL (see api_constants)
• parameters – additional parameters needed for the specified command like ‘number=3’ (without any ‘&’ symbol)

Returns:

the api response as a json object

set_actuator_value(actuator_id, value)

Sets a new value for the specified actuator.

Parameters:

• actuator_id – actuator id to set the new value on
• value – the new value to set on the specified actuator

Returns:

the api response

set_connection_info(host, user, password)

Sets private connection info for this XS1 instance. This XS1 instance will also immediately use this connection info.

Parameters:

• host – host address the gateway can be found at
• user – username for authentication
• password – password for authentication

static set_global_connection_info(host, user, password)

Sets the global connection info. This initialization is valid for all XS1 instances that do not have a specific connection configuration upon instantiation or using the set_connection_info() method. If you want a XS1 instance to use the global info instead of private use the use_global_connection_info() method.

Parameters:

• host – host address the gateway can be found at
• user – username for authentication
• password – password for authentication

set_sensor_value(sensor_id, value)

Sets a new value for the specified sensor. WARNING: Only use this for “virtual” sensors or for debugging!

Parameters:

• sensor_id – sensor id to set the new value on
• value – the new value to set on the specified sensor

Returns:

the api response

update_config_info()

Retrieves gateway specific (and immutable) configuration data

use_global_connection_info()

Enables the use of global configuration data

xs1_api_client.api_constants module

XS1 HTTP Web API constants used to create GET request URLs and parse the JSON answer.

xs1_api_client.api_constants.COMMAND_GET_CONFIG_INFO = 'get_config_info'

Command to get (final) configuration information about the gateway

xs1_api_client.api_constants.COMMAND_GET_LIST_ACTUATORS = 'get_list_actuators'

Command to get a list of all actuators

xs1_api_client.api_constants.COMMAND_GET_LIST_SENSORS = 'get_list_sensors'

Command to get a list of all sensors

xs1_api_client.api_constants.COMMAND_GET_PROTOCOL_INFO = 'get_protocol_info'

Command to get information about the protocol version used by the gateway

xs1_api_client.api_constants.COMMAND_GET_STATE_ACTUATOR = 'get_state_actuator'

Command to get the state of a specific actuator

xs1_api_client.api_constants.COMMAND_GET_STATE_SENSOR = 'get_state_sensor'

Command to get the state of a specific sensor

xs1_api_client.api_constants.COMMAND_SET_STATE_ACTUATOR = 'set_state_actuator'

Command to set a new value on an actuator

xs1_api_client.api_constants.COMMAND_SET_STATE_SENSOR = 'set_state_sensor'

Command to set a new value on a sensor (for debugging)

xs1_api_client.api_constants.ERROR_CODES = {'09': 'type not virtual', '05': 'invalid system', '01': 'invalid command', '06': 'invalid function', '02': 'cmd type missing', '12': 'protocol version mismatch', '10': 'syntax error', '08': 'object not found', '11': 'error time range', '04': 'duplicate name', '07': 'invalid date/time', '03': 'number/name not found'}

Dictionary with description values for each error code

xs1_api_client.api_constants.ERROR_CODE_CMD_TYPE_MISSING = '02'

Error code for ‘cmd type missing’

xs1_api_client.api_constants.ERROR_CODE_DUPLICATE = '04'

Error code for ‘duplicate name’

xs1_api_client.api_constants.ERROR_CODE_INVALID_COMMAND = '01'

Error code for ‘invalid command’

xs1_api_client.api_constants.ERROR_CODE_INVALID_DATE_TIME = '07'

Error code for ‘invalid date/time’

xs1_api_client.api_constants.ERROR_CODE_INVALID_FUNCTION = '06'

Error code for ‘invalid function’

xs1_api_client.api_constants.ERROR_CODE_INVALID_SYSTEM = '05'

Error code for ‘invalid system’

xs1_api_client.api_constants.ERROR_CODE_INVALID_TIME_RANGE = '11'

Error code for ‘error time range’

xs1_api_client.api_constants.ERROR_CODE_NOT_FOUND = '03'

Error code for ‘number/name not found’

xs1_api_client.api_constants.ERROR_CODE_OBJECT_NOT_FOUND = '08'

Error code for ‘object not found’

xs1_api_client.api_constants.ERROR_CODE_PROTOCOL_VERSION_MISMATCH = '12'

Error code for ‘protocol version mismatch’

xs1_api_client.api_constants.ERROR_CODE_SYNTAX_ERROR = '10'

Error code for ‘syntax error’

xs1_api_client.api_constants.ERROR_CODE_TYPE_NOT_VIRTUAL = '09'

Error code for ‘type not virtual’

xs1_api_client.api_constants.NODE_ACTUATOR = 'actuator'

Node with an array of actuators

xs1_api_client.api_constants.NODE_DEVICE_BOOTLOADER_VERSION = 'bootloader'

Bootloader version number

xs1_api_client.api_constants.NODE_DEVICE_FIRMWARE_VERSION = 'firmware'

Firmware version number

xs1_api_client.api_constants.NODE_DEVICE_HARDWARE_VERSION = 'hardware'

Hardware revision

xs1_api_client.api_constants.NODE_DEVICE_MAC = 'mac'

MAC address

xs1_api_client.api_constants.NODE_DEVICE_NAME = 'devicename'

Hostname

xs1_api_client.api_constants.NODE_DEVICE_UPTIME = 'uptime'

Uptime in seconds

xs1_api_client.api_constants.NODE_ERROR = 'error'

Node containing the error code

xs1_api_client.api_constants.NODE_INFO = 'info'

Node with gateway specific information

xs1_api_client.api_constants.NODE_PARAM_DESCRIPTION = 'dsc'

Device description

xs1_api_client.api_constants.NODE_PARAM_FUNCTION = 'function'

Array of functions

xs1_api_client.api_constants.NODE_PARAM_ID = 'id'

Device id (only unique within actuators/sensors)

xs1_api_client.api_constants.NODE_PARAM_NAME = 'name'

Device name

xs1_api_client.api_constants.NODE_PARAM_NEW_VALUE = 'newvalue'

New value to set for the device

xs1_api_client.api_constants.NODE_PARAM_NUMBER = 'number'

Alternative device id (only unique within actuators/sensors)

xs1_api_client.api_constants.NODE_PARAM_TYPE = 'type'

Device type

xs1_api_client.api_constants.NODE_PARAM_UNIT = 'unit'

Device value unit

xs1_api_client.api_constants.NODE_PARAM_UTIME = 'utime'

Time this device was last updated

xs1_api_client.api_constants.NODE_PARAM_VALUE = 'value'

Current device value

xs1_api_client.api_constants.NODE_SENSOR = 'sensor'

Node with an array of sensors

xs1_api_client.api_constants.NODE_VERSION = 'version'

Node with protocol version info

xs1_api_client.api_constants.UNIT_BOOLEAN = 'boolean'

Boolean unit type

xs1_api_client.api_constants.URL_PARAM_COMMAND = 'cmd='

command parameter that specifies the method the api is queried with

xs1_api_client.api_constants.URL_PARAM_FUNCTION = 'function='

parameter that specifies the function to execute (on an actuator)

xs1_api_client.api_constants.URL_PARAM_NUMBER = 'number='

number parameter that specifies the id of an actuator or sensor

xs1_api_client.api_constants.URL_PARAM_PASSWORD = 'pwd='

‘Password’ parameter

xs1_api_client.api_constants.URL_PARAM_USER = 'user='

‘User’ parameter

xs1_api_client.api_constants.URL_PARAM_VALUE = 'value='

‘value’ parameter that specifies the new value to set an actuator (or sensor) to

xs1_api_client.api_constants.VALUE_DISABLED = 'disabled'

‘Disabled’ type

xs1_api_client.test_XS1 module

class xs1_api_client.test_XS1.TestXS1(methodName='runTest')

Bases: unittest.case.TestCase

test_call_actuator_function()

test_get_all_actuators()

test_get_all_sensors()

test_get_state_actuator()

test_get_state_sensor()

test_set_actuator_value()

test_set_sensor_value()

Module contents