From a934c79a9b146048b70e9f056ee131cec977cc5b Mon Sep 17 00:00:00 2001 From: jkerdreu <jkerdreu@b32b6428-25c9-4566-ad07-03861ab6144f> Date: Tue, 16 Jul 2024 12:49:24 +0000 Subject: [PATCH] Added a bunch of docs git-svn-id: https://redmine.imt-atlantique.fr/svn/xaal/code/Python/branches/0.7@3205 b32b6428-25c9-4566-ad07-03861ab6144f --- devices/loggers/warp10/README.rst | 57 ++++++++++++++----- devices/loggers/warp10/pyproject.toml | 12 ++-- devices/protocols/HomeKit/README.rst | 36 ++---------- devices/protocols/HomeKit/pyproject.toml | 12 ++-- devices/protocols/Meross/README.rst | 5 ++ devices/protocols/Meross/pyproject.toml | 12 ++-- devices/protocols/SensFloor/README.rst | 10 +++- devices/protocols/SensFloor/pyproject.toml | 12 ++-- devices/protocols/Tuya/README.rst | 21 +++---- devices/protocols/Tuya/pyproject.toml | 12 ++-- devices/protocols/Yeelight/README.rst | 14 +++++ devices/protocols/Yeelight/pyproject.toml | 12 ++-- devices/protocols/ZWave/README.rst | 18 +++--- devices/protocols/ZWave/pyproject.toml | 12 ++-- devices/tests/dummy/README.rst | 33 +++++++++++ devices/tests/dummy/pyproject.toml | 14 +++-- devices/tests/fakeinput/README.rst | 16 ++++++ devices/tests/fakeinput/pyproject.toml | 22 +++++-- devices/weather/OpenWeatherMap/README.rst | 17 ++++++ devices/weather/OpenWeatherMap/pyproject.toml | 12 ++-- 20 files changed, 251 insertions(+), 108 deletions(-) diff --git a/devices/loggers/warp10/README.rst b/devices/loggers/warp10/README.rst index 060c2258..34f3d778 100644 --- a/devices/loggers/warp10/README.rst +++ b/devices/loggers/warp10/README.rst @@ -1,17 +1,48 @@ +xaal.warp10 +=========== +This provide a warp10 (https://www.warp10.io/) logger for xAAL. It will log all xAAL messages to a warp10 instance. +Install & Run +------------- +You can install it using pip : + +.. code-block:: bash + + $ pip install xaal.warp10 + +Then you can run it : + +.. code-block:: bash + + $ python -m xaal.warp10 + # or + $ xaal-pkgrun warp10 + + +Config +------ + +.. code-block:: ini + + [config] + url = http://warp10:8080/api/v0/update + topic = xaal-lab + token = nI6H6KKxy3QSTxmfe0_lQyaBI0aV3gR4r5niVAKlaUb32cxIemlU7Vpb8AYhOkgZMz.bi... + Grafana -======= -You can use Grafana to display warp10 series, for example : - - -[ - 'xxxxxxxx_key_xxxxx' - '~xaal-home.thermometer.basic.temperature' - { 'devid' '2f31c921-01b2-4097-bfae-5753dde2cd42' } - $startISO $endISO -] -FETCH -'salon ' RENAME -{ 'devid' '' '.app' '' } RELABEL \ No newline at end of file +------- +You can use Grafana to display warp10 series, for example : + +.. code-block:: + + [ + 'xxxxxxxx_key_xxxxx' + '~xaal-home.thermometer.basic.temperature' + { 'devid' '2f31c921-01b2-4097-bfae-5753dde2cd42' } + $startISO $endISO + ] + FETCH + 'salon ' RENAME + { 'devid' '' '.app' '' } RELABEL diff --git a/devices/loggers/warp10/pyproject.toml b/devices/loggers/warp10/pyproject.toml index f205c8c4..75c1f214 100644 --- a/devices/loggers/warp10/pyproject.toml +++ b/devices/loggers/warp10/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.warp10" version = "0.1" description = "xAAL logger for warp10" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "warp10"] dependencies = ["xaal.lib", "urllib3"] diff --git a/devices/protocols/HomeKit/README.rst b/devices/protocols/HomeKit/README.rst index 5fd80c7b..e4645fb3 100644 --- a/devices/protocols/HomeKit/README.rst +++ b/devices/protocols/HomeKit/README.rst @@ -1,32 +1,4 @@ -xAAL Aqara Gateway -================== - - -Install & Config ----------------- -- Install with python setup.py develop or install. -- Enable local network on the Aqara Gateway with the Mi Home - Android or iOS app. You can follow this manual: - https://www.domoticz.com/wiki/Xiaomi_Gateway_(Aqara) - store the secret key somewhere. -- Run the xAAL gateway with: python -m xaal.aqara. The gateway - should detect all Aqara devices on your local network. -- To enable quick discovery and control devices (switches, leds..) - edit the config file ~/.xaal/xaal.aqara.ini and add the key - like this: - - [devices] - [[xxxxxxxxxxxx]] - base_addr = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx - model = gateway - secret = ydt5xis45x7k5x1x - - -Notes ------ -- xAAL gateway supports more than one Aqara Gateway (hub) on the - network make sure to set a secret key to each hub. -- xAAL gateway supports most Aqara devices, feel free to edit (and - submit) xaal/aqara/devices.py if you own a unsupported device. - - +xaal.homekit +============ +This package provides a HomeKit / xAAL Gateway. This is a preliminary version. We are looking for feedbacks and contributions. +The gateway loose the connection with the HomeKit bridge after a while. diff --git a/devices/protocols/HomeKit/pyproject.toml b/devices/protocols/HomeKit/pyproject.toml index 485bc062..3360d80c 100644 --- a/devices/protocols/HomeKit/pyproject.toml +++ b/devices/protocols/HomeKit/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.homekit" version = "0.1" description = "xAAL devices for Homekit" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "homekit"] dependencies = ["xaal.lib", "aiohomekit"] diff --git a/devices/protocols/Meross/README.rst b/devices/protocols/Meross/README.rst index e69de29b..a5e5f1da 100644 --- a/devices/protocols/Meross/README.rst +++ b/devices/protocols/Meross/README.rst @@ -0,0 +1,5 @@ +xaal.meross +=========== +This package allows you to control your Meross devices from xAAL. +Tested only w/ M340 RGB light. It should be easy to add support for other devices. +Feel free to contribute. diff --git a/devices/protocols/Meross/pyproject.toml b/devices/protocols/Meross/pyproject.toml index 911711e2..1d84c0a8 100644 --- a/devices/protocols/Meross/pyproject.toml +++ b/devices/protocols/Meross/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.meross" version = "0.1" description = "xAAL gateway for Meross devices" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "meross"] dependencies = ["xaal.lib", "xaal.schemas", "meross_iot==0.4.4.4"] diff --git a/devices/protocols/SensFloor/README.rst b/devices/protocols/SensFloor/README.rst index 71335583..1086ec86 100644 --- a/devices/protocols/SensFloor/README.rst +++ b/devices/protocols/SensFloor/README.rst @@ -1,10 +1,14 @@ -Websocket client for Future Shape Sensfloor. +xaal.sensfloor +============== +This is a gateway for Future Shape Sensfloor to xAAL. It use the websocket API provided by the Sensfloor. + +https://future-shape.com/en/system/ + WARNINGs -======== +-------- - Sensfloor is only compliant w/ socketio 5.0.0 (won't work on 5.5.*) - Due to mess in engineio signal handler, the GW is unable to call eng.shutdown() => This is enought for me right now, but still be carefull. => This bug raise a RuntineError on exit.. but not on console/self.shutdown() - \ No newline at end of file diff --git a/devices/protocols/SensFloor/pyproject.toml b/devices/protocols/SensFloor/pyproject.toml index 2c8a44c3..d663ddf9 100644 --- a/devices/protocols/SensFloor/pyproject.toml +++ b/devices/protocols/SensFloor/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.sensfloor" version = "0.1" description = "xAAL devices for Future Shape SensFloor" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "Sense Floor"] dependencies = ["xaal.lib", "xaal.schemas", "python-socketio==5.0.0", "aiohttp"] diff --git a/devices/protocols/Tuya/README.rst b/devices/protocols/Tuya/README.rst index 1de5d9c6..bd5a3c40 100644 --- a/devices/protocols/Tuya/README.rst +++ b/devices/protocols/Tuya/README.rst @@ -1,5 +1,6 @@ -xAAL gateway for Tuya devices -============================= +xaal.tuya +========= +This package provides a gateway to control Tuya devices from xAAL network. Tuya protocol is the common protocol used in cheap chinese outlets, smart plugs, and RGB lamps. It use the cloud base "Smart Life" mobile application (Android/IOS). @@ -7,24 +8,24 @@ and RGB lamps. It use the cloud base "Smart Life" mobile application (Android/IO This protocol isn't really reliable. If you can, avoid the use of Smart Life APP when this gateway is running. This should be ok, but attributes can be out of sync. The gateway polls devices state every 45 seconds but due to socket error, -this can be a little longuer. +this can be a little longuer. -The complete guide to extract keys is there: +The complete guide to extract keys is there: https://github.com/codetheweb/tuyapi/blob/master/docs/SETUP.md Notes : The main issue is that tuya devices close every connection after 10 seconds. Supported devices -================= +----------------- The gateway supports: PowerRelays (from 1 to x relais), SmartPlugs (same as relais but with a single power-meter), lamps and RGB lamps Configuration samples -===================== +--------------------- -- Dimmer Lamp / LSC Smart filament +- Dimmer Lamp / LSC Smart filament .. code-block:: @@ -35,7 +36,7 @@ Configuration samples white_temp = 1800, 2700 # for LSC addr = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -- RGB Lamp / LSC RGB1 +- RGB Lamp / LSC RGB1 .. code-block:: @@ -46,8 +47,8 @@ Configuration samples white_temp = 1800, 2700 # for LSC white_temp = 3000, 6500 # for Utorch LE7 addr = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - -- Alphawise dumb single outlet + +- Alphawise dumb single outlet .. code-block:: diff --git a/devices/protocols/Tuya/pyproject.toml b/devices/protocols/Tuya/pyproject.toml index 49a09c2e..35a637be 100644 --- a/devices/protocols/Tuya/pyproject.toml +++ b/devices/protocols/Tuya/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.tuya" version = "0.1" description = "xAAL support for Tuya protocol / Smart Life App" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "tuya"] dependencies = ["xaal.lib", "gevent", "decorator", "tuyaface"] diff --git a/devices/protocols/Yeelight/README.rst b/devices/protocols/Yeelight/README.rst index e69de29b..dd695265 100644 --- a/devices/protocols/Yeelight/README.rst +++ b/devices/protocols/Yeelight/README.rst @@ -0,0 +1,14 @@ +xaal.yeelight +============= +This package provides a xAAL gateway for Yeelight lights. It support most of the Yeelight lights and bulbs. +You have to enable local control on your Yeelight device to use this package. You can do this by enabling +the "LAN Control" option in the Yeelight app. + +The gateway detects the Yeelight devices on the network and creates a xAAL device for each of them. Check +*yeelight.ini* after the first run to see the devices created. + + +Notes +----- +This gateway doesn't use the asyncio API provides by the Yeelight library. Instead, it use gevent. This code +is a bit old, and need some refactoring to use the asyncio API. But it works well for now. diff --git a/devices/protocols/Yeelight/pyproject.toml b/devices/protocols/Yeelight/pyproject.toml index 18cc40c4..a1033ecb 100644 --- a/devices/protocols/Yeelight/pyproject.toml +++ b/devices/protocols/Yeelight/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.yeelight" version = "0.1" description = "xAAL devices for Xiaomi / Aqara" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "aqara"] dependencies = ["xaal.lib", "gevent", "yeelight", "decorator"] diff --git a/devices/protocols/ZWave/README.rst b/devices/protocols/ZWave/README.rst index f89279c5..09dbee55 100644 --- a/devices/protocols/ZWave/README.rst +++ b/devices/protocols/ZWave/README.rst @@ -1,12 +1,18 @@ -xAAL Zwave Gateway -================== + +xaal.zwave +========== +This package provides a gateway to connect Zwave devices to the xAAL. +It uses the openzwave library to communicate with the Zstick. +As the openzwave library is outdated, it is recommended to use an old +version of Python (tested w/ 3.8.12) to run this gateway. + Install & Config ---------------- -- Install the gateway as usual, python setup.py develop (or install) +- Install the gateway as usual, *pip install xaal.zwave* - Plug the Zstick -- Run the gateway w/ python -m xaal.zwave -- Change the serial port in the config file xaal.zwave.ini if needed. +- Run the gateway w/ *python -m xaal.zwave* +- Change the serial port in the config file *zwave.ini* if needed. - The gateway will detect all paired products with the Zstick so, no addtionnal config is needed @@ -14,5 +20,3 @@ Products -------- - Supported products are in products/, feel free to add (and submit) your own devices. - - diff --git a/devices/protocols/ZWave/pyproject.toml b/devices/protocols/ZWave/pyproject.toml index 9527a126..b6d08385 100644 --- a/devices/protocols/ZWave/pyproject.toml +++ b/devices/protocols/ZWave/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.zwave" version = "0.1" description = "xAAL devices for Zwave" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "zwave"] dependencies = ["xaal.lib", "python_openzwave", "prettytable"] diff --git a/devices/tests/dummy/README.rst b/devices/tests/dummy/README.rst index e69de29b..df8f3fac 100644 --- a/devices/tests/dummy/README.rst +++ b/devices/tests/dummy/README.rst @@ -0,0 +1,33 @@ +xaal.dummy +========== +This package provides some dummy (fake) devices for the xAAL Project. It is intended to be used for testing purposes. + +Usage +----- +Run the module to see the available devices and how to run them. + + .. code:: bash + + python -m xaal.dummy + ================= xAAL dummy devices ================= + + This package contains some fake lamps, power_relay, and bots: + - lamp: a simple lamp implementation + - lamp_minimal: a simple lamp using schema devices + - power_relay: a power relay + - temperature: a fake temperature sensor + - autobot: a bot than send turn_on/off and set_brightness + - asyncbot: same as autobot with asyncio + + + To run a module simply call: python -m xaal.dummy.module + Example: python -m xaal.dummy.lamp 8e1495cc-b98b-11eb-8432-d6bd5fe18736 + + All modules accept their address (uuid) as argument. Autobot uuid is the + lamp's address to switch. + +Here a simple example to run a lamp: + + .. code:: bash + + python -m xaal.dummy.lamp 8e1495cc-b98b-11eb-8432-d6bd5fe18736 diff --git a/devices/tests/dummy/pyproject.toml b/devices/tests/dummy/pyproject.toml index b81ed092..64d1b01b 100644 --- a/devices/tests/dummy/pyproject.toml +++ b/devices/tests/dummy/pyproject.toml @@ -1,12 +1,16 @@ [project] name = "xaal.dummy" -version = "0.1" +version = "0.2" description = "xAAL dummy devices" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal"] dependencies = ["xaal.lib"] diff --git a/devices/tests/fakeinput/README.rst b/devices/tests/fakeinput/README.rst index e69de29b..589c63db 100644 --- a/devices/tests/fakeinput/README.rst +++ b/devices/tests/fakeinput/README.rst @@ -0,0 +1,16 @@ +xaal.fakeinput +============== +This package provides some dummy (fake) input devices for the xAAL Project. It come with a web interface to control the devices. +We use this package to fake the lab inputs for testing purpose. + +Usage +----- +Just edit the 'fakeinput.ini' file to fit your needs and run the package. + +.. code-block:: bash + + $ python -m xaal.fakeinput + # or + $ xaal-pkgrun fakeinput + +Open the web interface to control the devices (http://localhost:8081). diff --git a/devices/tests/fakeinput/pyproject.toml b/devices/tests/fakeinput/pyproject.toml index eefc51c1..e3206c9c 100644 --- a/devices/tests/fakeinput/pyproject.toml +++ b/devices/tests/fakeinput/pyproject.toml @@ -1,14 +1,24 @@ [project] name = "xaal.fakeinput" -version = "0.2" +version = "0.3" description = "xAAL fake switch, buttons, contact devices " readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "json"] -dependencies = ["xaal.lib", "xaal.schemas", "bottle", "gevent", "gevent-websocket"] +dependencies = [ + "xaal.lib", + "xaal.schemas", + "bottle", + "gevent", + "gevent-websocket", +] [tool.setuptools.packages.find] diff --git a/devices/weather/OpenWeatherMap/README.rst b/devices/weather/OpenWeatherMap/README.rst index e69de29b..9ec81467 100644 --- a/devices/weather/OpenWeatherMap/README.rst +++ b/devices/weather/OpenWeatherMap/README.rst @@ -0,0 +1,17 @@ +xaal.owm +======== +This package is a OpenWeatherMap gateway for xAAL. It provides a way to get weather information from OpenWeatherMap and send it to xAAL network. + + +Config & Run +------------ +Edit the configuration file `owm.ini` to set your OpenWeatherMap API key and the city you want to get weather information from. + +.. code-block:: ini + + [config] + api_key = xxxx + place = "Brest,FR" + temperature = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + humidity = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx + pressure = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx diff --git a/devices/weather/OpenWeatherMap/pyproject.toml b/devices/weather/OpenWeatherMap/pyproject.toml index 897cc89f..20e459ae 100644 --- a/devices/weather/OpenWeatherMap/pyproject.toml +++ b/devices/weather/OpenWeatherMap/pyproject.toml @@ -3,10 +3,14 @@ name = "xaal.owm" version = "0.2" description = "xAAL devices for OpenWeather Map" readme = "README.rst" -authors = [ { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" } ] -license = { text = "GPL License"} -classifiers = ["Programming Language :: Python", -"Topic :: Software Development :: Libraries :: Python Modules"] +authors = [ + { name = "Jerome Kerdreux", email = "Jerome.Kerdreux@imt-atlantique.fr" }, +] +license = { text = "GPL License" } +classifiers = [ + "Programming Language :: Python", + "Topic :: Software Development :: Libraries :: Python Modules", +] keywords = ["xaal", "own", "weather"] dependencies = ["xaal.lib", "xaal.schemas", "pyowm==2.10.0"] -- GitLab