From ba6828d2822619006b4ead400ff323dd50554a92 Mon Sep 17 00:00:00 2001 From: Sathya Laufer Date: Tue, 29 May 2018 22:12:57 +0200 Subject: [PATCH] README --- Example.py | 17 ++++++++++--- README.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++----- setup.py | 4 +-- 3 files changed, 81 insertions(+), 12 deletions(-) diff --git a/Example.py b/Example.py index fd86710..bdf38da 100644 --- a/Example.py +++ b/Example.py @@ -5,14 +5,23 @@ def eventHandler(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(peerId, channel, variableName, value); + print("Event handler called with arguments: peerId: " + str(peerId) + "; channel: " + str(channel) + "; variable name: " + variableName + "; value: " + str(value)); -hg = Homegear("/var/run/homegear/homegearIPC.sock", eventHandler); +hg = Homegear("/var/lib/homegear/homegearIPC.sock", eventHandler); # hg waits until the connection is established (but for a maximum of 2 seonds). -print(hg.logLevel()); -print(hg.listDevices()); +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); \ No newline at end of file diff --git a/README.md b/README.md index 0c577d4..31ec6d8 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ libhomegear-python is a python extension to connect to Homegear over Unix Domain The extension requires `libhomegear-ipc` to be installed. To install it, add the Homegear APT repository for your distribution (see https://homegear.eu/downloads.html) and execute -``` +```bash apt install libhomegear-ipc ``` @@ -15,7 +15,7 @@ apt install libhomegear-ipc To compile and install the extension manually, execute -``` +```bash sudo python3 setup.py install ``` @@ -23,18 +23,47 @@ sudo python3 setup.py install There is only one object available: `Homegear`. It takes two parameters in it's constructor: The path to the Homegear IPC socket (`/var/run/homegear/homegearIPC.sock` by default) 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. +## 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: -``` +```python from homegear import Homegear # This callback method is called on Homegear variable changes def eventHandler(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(peerId, channel, variableName, value); + print("Event handler called with arguments: peerId: " + str(peerId) + "; channel: " + str(channel) + "; variable name: " + variableName + "; value: " + str(value)); hg = Homegear("/var/run/homegear/homegearIPC.sock", eventHandler); ``` @@ -43,15 +72,46 @@ Please note that the callback method is called from a different thread. Please u To execute a RPC method, just type `hg.`. For example to set the system variable "TEST" to "6" and retrieve it again: -``` +```python hg.setSystemVariable("TEST", 6); print(hg.getSystemVariable("TEST")); ``` -See Examply.py for a full example. +A full example: + +```python +import time +from homegear import Homegear + +# This callback method is called on Homegear variable changes +def eventHandler(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: 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 +* [GitHub Project](https://github.com/Homegear/libhomegear-python) * [Homegear Website](https://homegear.eu) * [Homegear Reference](https://ref.homegear.eu) * [Homegear Documentation](https://doc.homegear.eu) \ No newline at end of file diff --git a/setup.py b/setup.py index 642a77c..6a70fdc 100644 --- a/setup.py +++ b/setup.py @@ -6,14 +6,14 @@ setuptools.setup( name="homegear", - version="1.0.3", + version="1.0.4", description = 'Extension to connect to a local Homegear service.', long_description=long_description, long_description_content_type="text/markdown", author="Homegear GmbH", author_email="contact@homegear.email", url="https://github.com/Homegear/libhomegear-python", - download_url = 'https://github.com/Homegear/libhomegear-python/archive/1.0.3.tar.gz', + download_url = 'https://github.com/Homegear/libhomegear-python/archive/1.0.4.tar.gz', keywords = ['homegear', 'smart home'], ext_modules=[ Extension("homegear", ["homegear.cpp", "IpcClient.cpp", "PythonVariableConverter.cpp"],