xs1-api-client 2.3.5

Create the API Object

The basic way of creating an API object is by providing connection info directly when creating it:

from xs1_api_client import api as xs1api
from xs1_api_client import api_constants

# Create an api object with private configuration
api = xs1api.XS1(host='192.168.2.20', user="Username", password="Password")

This will automatically try to connect to the gateway with the given credentials and retrieve basic gateway information which you can output like this:

print("Gateway Hostname: " + api.get_gateway_name())
print("Gateway MAC: " + api.get_gateway_mac())
print("Gateway Hardware Version: " + api.get_gateway_hardware_version())
print("Gateway Bootloader Version: " + api.get_gateway_bootloader_version())
print("Gateway Firmware Version: " + api.get_gateway_firmware_version())
print("Gateway uptime: " + str(api.get_gateway_uptime()) + " seconds")

You can also specify a custom port and enable SSL:

api = xs1api.XS1(host='192.168.2.20', port=1234, ssl=True, user="Username", password="Password")

Now that you have a connection to your gateway we can retrieve its configuration and set or retrieve values of configured actuators and sensors or even modify their configuration.

Devices

All devices that you have configured in your XS1 are implemented using the XS1Device base class which can be found at /device/__init__.py. This class provides basic functionality for every device like getting the id, name, type and other values.

Retrieve Actuators

To retrieve a list of all 64 actuators use the following call:

actuators = api.get_all_actuators()

This will return a list of XS1Actuator objects which is another base class for all actuators. You can use something like this to print all your actuators:

for actuator in actuators:
    print("Actuator " + str(actuator.id()) + ": " + actuator.name() + " (" + str(actuator.type()) + ")")

There is also an integrated __str__ method to print out most of the useful properties just like this:

for actuator in actuators:
    print(actuator)

You can also filter the elements by enabled and disabled state using:

enabled_actuators = api.get_all_actuators(True)

Retrieve a single actuator simply by using:

actuator_1 = api.get_actuator(1)

Retrieve an Actuator Value

To retrieve the current value of an actuator just call:

current_value = actuator.value()

Set a new Actuator value

To set a new value to this actuator use:

actuator.set_value(100)

This will send the required request to the XS1 and set the new_value property to your value. Most of the time this value is set instantaneously is in sync with the value property. However if this value is different from the standard value the XS1 gateway is still trying to update the value on the remote device. For some devices this can take up to a couple of minutes (f.ex. FHT 80B heating).

Updating Actuator Information

Currently there is no callback when the value is finally updated so you have to update the device information manually if you want to get an update on its current state:

actuator.update()

After that the usual methods like actuator.value() will respond with the updated state.

Executing Actuator Functions

If you have defined function presets for a device you can get a list of all functions using:

functions = actuator.get_functions()

and print them like this:

for function in functions:
    print(function)

to execute one of the functions type:

function.execute()

This will (like set_value) update the device state immediately with the gateways response. Remember though that there can be a delay for sending this value to the actual remote device like mentioned above.

Retrieve a List of Sensors

To retrieve a list of all 64 sensors use the following call:

sensors = api.get_all_sensors()

Just like with actuators you can filter the elements by enabled and disabled state using:

enabled_sensors = api.get_all_sensors(True)

for sensor in sensors:
    print("Sensor " + str(sensor.id()) + ": " + sensor.name() + " (" + str(sensor.value()) + ")")

Just like mentioned above you can also use:

for sensor in sensors:
    print(sensor)

or:

sensor_1 = api.get_sensor(1)

to retrieve a specific sensor.

Updating Sensor Information

Just like with actuators there is no automatic updates for sensors either. To get a state update from the XS1 gateway for your sensor object call:

sensor.update()

After that the complete state of this sensor is updated.

Disabled Devices

The XS1 allows up to 64 actuator and 64 sensor configurations. These 128 device configurations are accessible via the HTTP API at any time - even when there is nothing configured for a specific device id/number.

To check if a device has been configured (and enabled) in the XS1 web interface call:

device.enabled()

for both actuators and sensors alike.

Get a device configuration

Since version 2.0 it is possible to get and set device configurations on the XS1 using this library.

Please have a look at the example_config.py file to get an idea of how to retrieve a device configuration.

Modify a device configuration

Before you proceed

Every configuration change will write to the internal flash memory of the XS1. Please keep in mind that that the use flash memory can and will probably degrade when written too often.

Copy a device configuration

There is a very detailed example in this project called example_config_copy_actuator.py that will show you how to copy a device configuration and also explains most of the important configuration parameters you will have to use to set a custom configuration. Keep in mind though that the configuration parameters can vary between device types and systems.