Have access to all your GIRA home appliances. You can turn lights on and off, open blinds via cronjobs or using a webfrontend (not included) and open your garage when you come home (using flask + automate for Android).
Only works with Python 3!
There are 3 ways of installing the API Client. We recommend using pip for smaller projects and requirements.txt for bigger ones.
Install using pip (sometimes you have to use pip instead of pip3)
pip3 install git+https://github.com/leoyn/gira-homeserver-api.git
If you are using a requirements.txt
file you can add the URL as shown below:
# other packages here
git+https://github.com/leoyn/gira-homeserver-api.git
Then do your pip3 install -r requirements.txt
.
- Clone using git:
git clone [email protected]:leoyn/gira-homeserver-api.git
- Copy the
gira_homeserver_api
folder into your project folder
cp gira-homeserver-api/gira_homeserver_api my-home-project/gira_homeserver_api
import gira_homeserver_api as api
client = api.Client("127.0.0.1", 80, "username", "password")
# listener when client is ready, because connect() blocks thread
def onClientReady(sessionToken):
type = 1
id = 101
value = 1
# Turn device 101 on
client.setDeviceValue(type, id, value)
client.onClientReady(onClientReadyListener)
# connnect and block thread
client.connect()
For more in depth comments check out the quick_start.py in the examples directory.
What is this code doing?
It connects to your homeserver with the given credentials and turns on a lamp with id 101.
These are device types when you access your Gira Homeserver directly via the client. When you want to use the device object instead look for here. They use the same devices types of GIRA but asbtract the numerical types by providing appropiate functions.
Type | Description | Example devices |
---|---|---|
0 | Used to get a value from a device instead of setting one | All devices |
1 | Set device value | Lights, Blinds, Thermostats |
20 | Also set device value. The only type that works with a garage | Garage |
- Download your device list
import gira_homeserver_api as api
client = api.Client("127.0.0.1", 80, "username", "password")
def onClientReady(sessionToken):
# open file and download devices
file = open("my_devices.xml", "w")
file.write(client.getDevices())
file.close()
# close connection
client.close()
client.onClientReady(onClientReady)
client.connect()
- Open the file
my_devices.xml
with a text editor and search for devices. Example:
<device id="200" txt="House\Basement\Room\Socket" template="0-16_5" uhr="1000000010">
<connect slot="slot_bin" tag="1337" />
</device>
1337
IS the device id and NOT 200
. TAG = Device Id
- Control your socket by the api
import gira_homeserver_api as api
client = api.Client("127.0.0.1", 80, "username", "password")
def onClientReady(sessionToken):
# turns your socket with id 1337 on
client.setDeviceValue(1, 1337, 1)
client.onClientReady(onClientReady)
client.connect()
client = api.Client("127.0.0.1", 80, "username", "password")
client.setDeviceValue(1, 101, 1)
Please use setDeviceValue(deviceType, deviceId, value)
instead
Always returns a float value for device with given id.
Returns None
when device does not respond or device does not exist.
value = client.getDeviceValue(101)
Listens for all device value changes
def onDeviceValueListener(deviceId, value):
print(deviceId, value)
client.onDeviceValue(onDeviceValueListener)
Connect to homeserver.
Must be called after setting listeners and before get or setting values of devices.
client.connect()
Arguments:
asynchronous
: When setting toTrue
client won't block thread. Default:False
.reconnect
: automatically reconnect when connections drops. Default:True
.
It is recommended to execute sets and gets of device values after onClientReady listener received the ready event
def onClientReadyListener():
print("Client is ready")
client.setDeviceValue(1, 101, 1)
print("Device value is", client.getDeviceValue(101))
client.onClientReady(onClientReadyListener)
Listens for connection error
def onConnectionErrorListener():
print("Client connection aborted")
client.onConnectionError(onConnectionErrorListener)
Close connection
client.close()
Send raw text to server.
Please be aware that this might has negative side effects. Use with caution.
client.send("1|1|1")
You can find an example in the using_the_device_parser.py in the example directory.
devices = api.Parser.parse(client.getDevices(), client)
Note: client
(2nd argument) is optional. If you don't provide it, devices cannot be controlled.
All devices have the following methods:
getId()
: get gevice IDsetId(id)
: set device IDgetValue()
: get value of devicesetValue(id)
: set value of devicegetName()
: get name. e.g.floor\area\room\object
setName(id)
: set namegetClient()
: get client objectsetClient(client)
: set client object
Has only two states: on
or off
.
turnOn()
: turns device onturnOff()
: turns device offgetState()
: returnsTrue
= on orFalse
= off
Will set a device value on a scale from 0 to 1.
0 = 0%
1 = 100%
setValue(value)
: set device value between 0 and 1getValue()
: get device value
Acts as a normal device. However it has 20
as the internal device type.
Value devices take any arbitrary input you give it. Basically the same as sequence device with the internal device type 1
.