Package: xs1-api-client
xs1-api-clientA python 3.5+ library for accessing actuator and sensor data on the the
EZcontrol® XS1 Gateway using its HTTP API.Build StatusMasterBetaDevHome AssistantThe initial goal of this library was to be able to integrate the EZcontrol® XS1 Gateway withHome Assistant.
You can find the related integration documentation here:XS1 Home Assistant component documentationNote:
xs1-api-client was designed to have reusable device objects, meaning device objects can be updated.
When a user changes the order of devices within the XS1 gateway, their ids don’t change but their numbers (orders) do.
This causes the “device object” <-> device id association to get messed up. Since there is no way for us to know
about this change, it’s impossible for us to tell that the device number we use for an already created device object
does not correspond to the correct device anymore without fetching all devices again, which requires the recreation
of all device objects.TL;DR:Do not change the order of the devices in the XS1 Gatewayif you can avoid it, and if you do,
restart the service that relies on xs1-api-client to force a re-fetch of all devices.How to useInstallationpip installxs1-api-clientUsageFor 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.Basic ExampleCreate the API ObjectThe basic way of creating an API object is by providing connection info
directly when creating it:fromxs1_api_clientimportapiasxs1apifromxs1_api_clientimportapi_constants# Create an api object with private configurationapi=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.DevicesAll devices that you have configured in your XS1 are implemented using
theXS1Devicebase class which can be found at/device/__init__.py.
This class provides basic functionality for every device like getting
theid,name,typeand other values.Retrieve ActuatorsTo retrieve a list of all 64 actuators use the following call:actuators=api.get_all_actuators()This will return a list ofXS1Actuatorobjects which is another base
class for all actuators. You can use something like this to print all
your actuators:foractuatorinactuators: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:foractuatorinactuators:print(actuator)You can also filter the elements byenabledanddisabledstate using:enabled_actuators=api.get_all_actuators(True)Retrieve a single actuator simply by using:actuator_1=api.get_actuator(1)Retrieve an Actuator ValueTo retrieve the current value of an actuator just call:current_value=actuator.value()Set a new Actuator valueTo set a new value to this actuator use:actuator.set_value(100)This will send the required request to the XS1 and set thenew_valueproperty to your value. Most of the time this value is set
instantaneously is in sync with thevalueproperty. However if this
value is different from the standardvaluethe 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 InformationCurrently there isno callbackwhen the value is finally updated soyou have to update the device information manuallyif you want to
get an update on its current state:actuator.update()After that the usual methods likeactuator.value()will respond with
the updated state.Executing Actuator FunctionsIf 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:forfunctioninfunctions: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 SensorsTo 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 byenabledanddisabledstate using:enabled_sensors=api.get_all_sensors(True)This will return a list ofXS1Sensorobjects which is the base
class for all sensors.You can print basic information about them like this:forsensorinsensors:print("Sensor "+str(sensor.id())+": "+sensor.name()+" ("+str(sensor.value())+")")Just like mentioned above you can also use:forsensorinsensors:print(sensor)or:sensor_1=api.get_sensor(1)to retrieve a specific sensor.Updating Sensor InformationJust 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 DevicesThe 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 configurationSince version 2.0 it is possible to get and set device configurations on the XS1 using this library.Please have a look at theexample_config.pyfile to get an idea of how to retrieve a device configuration.Modify a device configurationBefore you proceedEvery 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 configurationThere is a very detailed example in this project calledexample_config_copy_actuator.pythat 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.ContributingGithub is for social coding: if you want to write code, I encourage contributions through pull requests from forks
of this repository. Create Github tickets for bugs and new features and comment on the ones that you are interested in.Licensexs1-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/>.