Skip to content

Latest commit

 

History

History
136 lines (96 loc) · 4.72 KB

README.md

File metadata and controls

136 lines (96 loc) · 4.72 KB
Raw

python3-homegear

python3-homegear is a python extension to connect to Homegear over Unix Domain Sockets. It supports all of Homegear's RPC methods and live event reception.

Prerequisites

The extension requires libhomegear-ipc to be installed and it needs at least Python version 3. To install it, add the Homegear APT repository for your distribution (see https://homegear.eu/downloads.html) and execute

apt install libhomegear-ipc

Alternatively on non Debian-like systems you can compile libhomegear-ipc manually:

git clone https://github.com/Homegear/libhomegear-ipc
cd libhomegear-ipc
./makeRelease.sh

Setup

if you have pip, just do:

sudo python3 -m pip install homegear

To compile and install the extension manually, download it from GibHut and execute

sudo python3 setup.py install

Methods

There is only one object available: Homegear. It takes two parameters in it's constructor: The path to the Homegear IPC socket (normally /var/run/homegear/homegearIPC.sock) and a callback method. The callback method is executed when a device variable is updated in Homegear. On instantiation the class waits until it is connected succesfully to Homegear. After 2 seconds it returns even if there is no connection. To check, if the object is still connected, you can call connected(). Apart from this method, you can call all RPC methods available in Homegear (see ref.homegear.eu).

Behaviour on no connection

When there is no connection to Homegear, the constructor returns after 2 seconds. It indefinitely tries to reconnect until it is able to establish a connection. The same happens on connection loss. To check if the module is connected, call connected(). Even when there is no connection, you can still call all RPC methods without exception. The return value will be None.

Type conversion

Python variable to Homegear variable

Python Homegear
None Void
Bool Boolean
Long Integer
Float Float
Unicode String
Bytes Binary
List Array
Tuple Array
Dict Struct

Homegear variable to Python variable

Homegear Python
Void None
Boolean Bool
Integer Long
Float Float
String Unicode
Binary Bytes
Array List
Struct Dict

Usage example

A minimal example:

from homegear import Homegear

# This callback method is called on Homegear variable changes
def eventHandler(eventSource, peerId, channel, variableName, value):
	# Note that the event handler is called by a different thread than the main thread. I. e. thread synchronization is
	# needed when you access non local variables.
	print("Event handler called with arguments: source: " + eventSource + " peerId: " + str(peerId) + "; channel: " + str(channel) + "; variable name: " + variableName + "; value: " + str(value));

hg = Homegear("/var/run/homegear/homegearIPC.sock", eventHandler);

Please note that the callback method is called from a different thread. Please use thread synchronization when accessing shared variables.

To execute a RPC method, just type hg.<method name>. For example to set the system variable "TEST" to "6" and retrieve it again:

hg.setSystemVariable("TEST", 6);
print(hg.getSystemVariable("TEST"));

A full example:

import time
from homegear import Homegear

# This callback method is called on Homegear variable changes
def eventHandler(eventSource, peerId, channel, variableName, value):
	# Note that the event handler is called by a different thread than the main thread. I. e. thread synchronization is
	# needed when you access non local variables.
	print("Event handler called with arguments: source: " + eventSource + " peerId: " + str(peerId) + "; channel: " + str(channel) + "; variable name: " + variableName + "; value: " + str(value));

hg = Homegear("/var/run/homegear/homegearIPC.sock", eventHandler);

# hg waits until the connection is established (but for a maximum of 2 seonds).

hg.setSystemVariable("TEST", 6);
print("getSystemVariable(\"TEST\") after setting \"TEST\" to 6: ", hg.getSystemVariable("TEST"));

hg.setSystemVariable("TEST", ["One", 2, 3.3]);
print("getSystemVariable(\"TEST\") after setting \"TEST\" to an array: ", hg.getSystemVariable("TEST"));

hg.setSystemVariable("TEST", {"One": 1, 2: "Two", 3: [3, 3, 3]});
print("getSystemVariable(\"TEST\") after setting \"TEST\" to a struct: ", hg.getSystemVariable("TEST"));

counter = 0;
while(hg.connected()):
	time.sleep(1);
	counter += 1;
	hg.setSystemVariable("TEST", counter);

Links