# GeckoLib
Library to interface with Gecko Alliance spa pack systems via in.touch2
Written from the ground up using info gleaned from Wireshark captures to sniff
the conversation between the iOS app and the inTouch2 home transmitter.
Designed to be used by home automation systems such as Home Assistant or openHAB
_This library is currently in Alpha, meaning that there may be large changes
in library shape, class definitions, behaviours etc as I client it in my ongoing
Home Assistant integration. This has now been released, in preview, and can be
found at https://github.com/gazoodle/gecko-home-assistant, or from HACS by adding
a new integration and seaching for Gecko_
# Async support
The core of the library has been rewritten to be async based. This is for several
reasons;
1. Home Assistant, my main client of the library prefers this pattern. I'd like to
get away from the "can't connect", "not supported" pattern and have the spa
connect immediately to the facade (which will do the handshake to the actual spa
asynchronously so that connection state can be shown in the UI if required).
This will improve HA startup performance and allow me to control
the retry connection pattern in the library without having to burden the HA
integration with this (HA doesn't like protocol in integrations)
2. I've done loads of multi-threaded programming in my life and think I'm familiar
with almost all kinds of problems this brings, but ... why bother when this isn't
necessary
3. While trying to implement a feature that supports occasionally disconnected
spas without generating reams of logging, I realized that I was fighting against
the previous architecture, so it's time to refactor that.
4. Every day is a school day. I've not seriously explored Python's async support :-)
Currently this isn't a breaking change, the sync library still has the functionality
that it always had (albeit with some major refactoring). There is a completely parallel
API and class set to support async clients.
I'll update the HA integration to use the async version as it's much faster to start
and it has more functionality. I know there are other automation clients using this
library, so the sync API and classes will stay here for a while until those clients have
had a chance to use the new async code, but I will deprecate them at some point,
probably when the library goes to v1.0.0
# Installation
This library is hosted on PyPI and can be installed with the following command-line
`pip install geckolib`
# GeckoShell usage
Once the library is installed, you should be able to start a Python interpreter session
by using the command `python3`, then executing the following commands
```python
>>> from geckolib import GeckoShell
>>> GeckoShell.run()
<Disclaimer>
:
<snip/>
:
</Disclaimer>
Starting discovery process...Found 1 spas
Connecting to spa `Spa` at 10.1.2.3 ... connected!
Heater: Temperature 39.0°C, SetPoint 39.0°C, Operation Idle
Pump 1: OFF
Pump 2: OFF
Blower: OFF
Lights: OFF
WaterCare: Standard
Welcome to the Gecko shell. Type help or ? to list commands.
Spa$
```
This ought to find your spa on your local network. If it doesn't, please open an issue, you can
exercise some of your spa features using the commands below
```
Spa$ P1 HI
Spa$ P1 OFF
Spa$ LI ON
Spa$ LI OFF
```
You can get help on the GeckoShell module
```
Spa$ help
Documented commands (type help <topic>):
========================================
BL P2 discover get list refresh snapshot watercare
LI about download help live set state
P1 config exit license manage setpoint version
Spa$ help watercare
Set the active watercare mode to one of ['Away From Home', 'Standard', 'Energy Saving', 'Super Energy Saving', 'Weekender'] : WATERCARE <mode>
Spa$ watercare Weekender
```
If you have more than one spa/device detected, you can use the `list` and `manage` commands
```
Starting discovery process...Found 2 spas
Welcome to the Gecko shell. Type help or ? to list commands.
(Gecko) list
1. Spa
2. Dummy Spa
(Gecko) manage 1
Connecting to spa `Spa` at 10.1.2.3 ... connected!
Heater: Temperature 39.0°C, SetPoint 39.0°C, Operation Idle
P1: OFF
P2: OFF
BL: OFF
LI: OFF
WaterCare: Standard
Spa$
```
If you want to get some diagnostics you can enable file logging at the start of the session
```python
>>> from geckolib import GeckoShell
>>> GeckoShell.run(["logfile client.log"])
:
:
```
or it can be used later after you've connected to your spa with the `logfile` command
```
Spa$ logfile client.log
```
The file `client.log` will contain diagnostic information that may be useful
for tracking down issues
If you want to start the client and point it at a specific IP address (maybe you have your SPA on a different subnet), you can issue the discovery command as part of the launch parameters
```python
>>> from geckolib import GeckoShell
>>> GeckoShell.run(["logfile client.log", "discover 192.168.1.2"])
:
:
```
# Simulator Usage
It's best if you download the repo for using the simulator. Once you've done that,
open a terminal to your repo test folder (./tests)
`python3 simulator.py`
You should see a prompt
```
Welcome to the Gecko simulator. Type help or ? to list commands.
(GeckoSim)
```
You should load the default snapshot at this point
```
(GeckoSim) load snapshots/default.snapshot
(GeckoSim)
```
Now you can run the client program, or indeed your iOS or Android app and then
attempt to connect to the simulator. At present it only supports loading another
snapshot to change the state. If the changes are too great, for example, if you've
loaded a completly different spa then the iOS and Android apps may be confused.
Best to click on the account icon and then reselect the test spa to get it to
reconnect from the start.
Also, at present the simulator doesn't respond to any commands issued from the
iOS and Android applications.
# Async API Usage
```python
""" Sample client demonstrating async use of geckolib """
import asyncio
import logging
from geckolib import GeckoAsyncSpaMan, GeckoSpaEvent # type: ignore
# Replace with your own UUID, see https://www.uuidgenerator.net/>
CLIENT_ID = "a2d936db-4e95-4e4d-82bc-b4225fa99739"
# Replace with your spa IP address if on a sub-net
SPA_ADDRESS = None
class SampleSpaMan(GeckoAsyncSpaMan):
"""Sample spa man implementation"""
async def handle_event(self, event: GeckoSpaEvent, **kwargs) -> None:
# Uncomment this line to see events generated
# print(f"{event}: {kwargs}")
pass
async def main() -> None:
async with SampleSpaMan(CLIENT_ID, spa_address=SPA_ADDRESS) as spaman:
print("Looking for spas on your network ...")
# Wait for descriptors to be available
await spaman.wait_for_descriptors()
if len(spaman.spa_descriptors) == 0:
print("**** There were no spas found on your network.")
return
spa_descriptor = spaman.spa_descriptors[0]
print(f"Connecting to {spa_descriptor.name} at {spa_descriptor.ipaddress} ...")
await spaman.async_set_spa_info(
spa_descriptor.ipaddress,
spa_descriptor.identifier_as_string,
spa_descriptor.name,
)
# Wait for the facade to be ready
await spaman.wait_for_facade()
print(spaman.facade.water_heater)
print("Turning pump 1 on")
await spaman.facade.pumps[0].async_set_mode("HI")
await asyncio.sleep(5)
print("Turning pump 1 off")
await spaman.facade.pumps[0].async_set_mode("OFF")
await asyncio.sleep(5)
if __name__ == "__main__":
# Install logging
stream_logger = logging.StreamHandler()
stream_logger.setLevel(logging.DEBUG)
stream_logger.setFormatter(
logging.Formatter("%(asctime)s> %(levelname)s %(message)s")
)
logging.getLogger().addHandler(stream_logger)
logging.getLogger().setLevel(logging.INFO)
asyncio.run(main())
```
This should output something like this
```
Looking for spas on your network ...
2022-03-16 07:05:12,842> INFO Found 1 spas ... [My Spa(SPA00:01:02:03:04:05)]
Connecting to My Spa at 10.0.0.123 ...
Heater: Temperature 36.0°C, SetPoint 36.0°C, Real SetPoint 36.0°C, Operation Idle
Turning pump 1 on
2022-03-16 07:05:19,292> INFO Value for UdP2 changed from OFF to HI
2022-03-16 07:05:19,479> INFO Value for P2 changed from OFF to HIGH
2022-03-16 07:05:19,480> INFO Value for UdPumpTime changed from 0 to 45
Turning pump 1 off
2022-03-16 07:05:25,049> INFO Value for UdP2 changed from HI to OFF
2022-03-16 07:05:25,236> INFO Value for P2 changed from HIGH to OFF
2022-03-16 07:05:25,236> INFO Value for UdPumpTime changed from 45 to 0
```
# Complete sample
There is also a complete async sample which can be found in the repo under
the /sample folder. This can be run using `python3 complete.py`. Full path
https://github.com/gazoodle/geckolib/tree/main/sample
# Home Assistant integration
The best example of use is in the Home Assistant integration which can be
found here https://github.com/gazoodle/gecko-home-assistant
# Sync API Usage
**WARNING** Sync functionality will be removed in a future release,
examples removed from README
# Acknowledgements
- Inspired by https://github.com/chicago6061/in.touch2.
- Thanks to the folk at Gecko for building this system as a local device rather than mandating a cloud solution.
- Wireshark is an awesome tool for sniffing out what is going on on your network. Take a look one day, you might be horrified :-)
# License
https://www.gnu.org/licenses/gpl-3.0.html
# Todo
- Spa state (errors)
- Error handling (ongoing)
- Pythonize where possible
- APIs to support integration into automation systems (Ongoing)
- Warnings/Errors
- Diagnostics
- More unit tests
- Handle other device types such as Waterfall
- Handle inMix for lighting control
- Add API documentation
- Merge reminders branch from @kalinrow
- List property for User demands in pack classes
- List property for errors in pack classes
- Tidy up support files. One class per file
- Full sweep for typing hints - Ongoing
- Add sensor for errors
- Add switch for winterizing
- Add ability to set hours so we can implement a crude clock sync mechanism
- Think about a way to provide access to behaviour refresh frequencies so that
it can be customised
- Look into getting shell & simulator using async API so that there are no
internal dependencies on the sync code any longer
- Move to pytest unit test framework
- Use snapshots to generate some specific tests
- Build some documentation
- Add coverage to GitHub package workflow
- There is a lock issue when a command is being retried as the protocol lock
is busy and the CUI won't exit until the timeout has been reached (this can
be reproduced by making the simulator stop responding to watercare requests)
## Done/Fixed in 0.4.8
- Split radio strength & channel into two separate sensors
- Added some extra debugging around protocol sync lock
- Some unit_of_measurement values were the string "None" instead of the python keyword None
- Aggregate SpaPack error properties into a single text sensor
- Rebuild pack accessors from SpaStructPack.xml v36.1
## Done/Fixed in 0.4.7
- Merged fix for negative watercare values (thanks @EiNSTeiN-)
- Demote out-of-range spapack struct enum values to DEBUG and return "Unknown"
- Demote "No handler for xxxx" to DEBUG to declutter log files
## Done/Fixed in 0.4.6
- Going back to basics and watching the protocol from the iOS app, I noticed that
the commands sent from the app don't use the same sequence numbers as the ones
that are sent during connection, they run a loop around from 192-255 whereas the
protocol ones go from 1-191 ... so replicate that behaviour in case it's confusing
something in the system and adding to the instability of connections
- Moved protocol retry constants to GeckoConfig class
- Added 2 second pause between protocol retries to allow intouch2 EN module to settle
- Increased default timeout from 2 to 4 seconds
- Added radio channel and signal strength sensor
## Done/Fixed in 0.4.5
- Config change code could attempt to set result on a future that was already
set leading to an unhandled exception that could result in the partial status
update task being cancelled
- Disconnected facades now cleared out of the system correctly
- Added some more diagnostics to chase sporadic disconnects
## Done/Fixed in 0.4.4
- Moved config settings out of const class into their own class
- Added idle/active config settings and task loop for library to switch between
idle and active config settings. An idle spa is one that is currently not processing
any user demands, an active spa is one that has received a client request such as to
change temp or turn on a pump. Active mode will stay on while any user demand is
currently live.
- Replaced asyncio.sleep in various places with config_sleep which is aware of when
the configuration values have changed which means that the loops currently waiting on
these values stop waiting and can collect the new values.
## Done/Fixed in 0.4.2
- Fixed processor getting pegged at 100% but not using asyncio.sleep(0)
- Fixed simulator to respect names compatible with Windows
- Renamed some snapshots
## Done/Fixed in 0.4.1
- Updated README with simple async example
- Pull in reminders PR from @kalinrow - Thanks!
- Add unit tests for reminders
- Add async version of reminders - slightly different API as sync version returns
time as first reminder
- Updated various clients to use reminders
## Done/Fixed in 0.4.0
- Supports both sync and async clients. The sync clients ought to be backward
compatible but there has been a huge chunk of refactoring to get the async
built and even though I've run all the tests and clients, it's possible there
are issues
- Sensor for connection status is available early in facade lifetime
- Ping sensor available after spa begins connection sequence
- Re-added readline library to simulator as it was doing auto-complete for snapshot
loading and was useful when testing, but added it inside a try/catch block so
it won't upset Windows clients
- Manage ping failure and RF errors with retry mechanism
- Watercare regular refresh from facade
- Create Spa manager class to run the connection logic so that clients get cleanup
opportunity when reconnections are needed
- Handle disconnected spas, ping failures, RF errors and so on
- Simulator can get/set accessors for experimentation
## Done/Fixed in 0.3.24
- Fix error found by Github workflow
- Added extra logging into to find out more about issue #28
- Removed readline library as it isn't supported on Windows and it wasn't really doing anything
- Added some extra doc for issue #18
- Added RFERR handler to client and simulator to start investigations
- Handle Watercare index out of range
- Accessors can now deal with Time type entries
- Added diag.py to aid tracking issue#27
- Added eco mode control to facade and shell
- Temperature accessor in new generator as it doesn't need to be handled at runtime
- Removed decorators.py
## Done/Fixed in 0.3.23
- Demoted some INFO logging to DEBUG to reduce HA log file clutter
## Done/Fixed in 0.3.22
- Increase connection timeout to help with laggy tubs and busy networks
- Watercare setting updated locally rather than wait for tub response to
improve HA UI responsiveness
- Fast locator for static IP
## Done/Fixed in 0.3.21
- Demoted some benign debugging data that clutters log files
- Replaced "config" and "live" with "accessors" commands in shell to reduce direct access to XML
- Added "monitor" command in shell to give a live view of changes from other sources e.g. control panel or app
- Removed runtime reliance on SpaPackStruct.xml, this is replaced by the python code in driver/pack/\*
- Accessor can handle byte, word, bool value updates if provided as a string (i.e. GeckoShell set command)
## Done/Fixed in 0.3.20
- Merge changes for variable speed pumps. Thanks https://github.com/los93sol
- Prevent new "pump" command showing in help UI
## Done/Fixed in 0.3.19
- Ensure STATP changes are cleared after processing rather than accumulating for-all-time! Thanks https://github.com/maegibbons
## Done/Fixed in 0.3.18
- Added some more snapshots
- Attempt to handle spas that return unsupported config/log versions
- Add ability to provide an IP address to the library
## Done/Fixed in 0.3.17
- Attempt to fix urllib3 requirement in pip install. It was in the wrong place
## Done/Fixed in 0.3.16
- More robust to missed packets during spa connection
- Mechanism to access raw pack values from the facade, e.g. facade.pumps[0].state_sensor.accessor.raw_value
- Add API to facade to get device by key, e.g. facade.get_device("P1") will return the first pump.
- Add property to facade to get all device keys; facade.devices
## Done/Fixed in 0.3.15
- Trying out Github publish actions
## Done/Fixed in 0.3.14
- Added SmartWinterMode sensors
- Added Filter Clean/Purge sensors
## Done/Fixed in 0.3.13
- Move MrSteam handling on so that we can get a proper structure dump
## Done/Fixed in 0.3.12
- UnicodeEncodeError: 'latin-1' codec can't encode character '\u0101' in position 108: ordinal not in range(256)
- Massive refactor of protocol handlers to make building a simulator easier
- Changes to allow library to be more suitable for async clients
- Ping frequency returned to 15 seconds
- Simulator added to allow investigation using snapshots sent in from other folk
- Heating state fixed to show heating/cooling as appropriate
- Issue #1 Waterfall now recognised and responding to button press
- Issue #3 P1 Twice - deduped the device list
- Issue #8 The library should be able to provide temp and heater usage stats now
- Issue #9 Water Heater current operation should now be working correctly
## Done/Fixed in 0.3.11
- Ping frequency set to 45 seconds
- Reset method to GeckoReponse class to handle retries in GeckoGetStatus class
- Add mechanism to locate a spa in the locator class based on it's identifier
- Set worker threads to daemon mode
- Re-structure for better lifetime management and easier clienting
- Merged PR from dukey32123 supplying waterfall constants ... need to find keypad code too.
- flake8 and black formatting and tidy-up
- Observable added to propagate change notification so we can be cliented as a
local-push integration in Home Assistant
- Moved all the functionality out of client.py and put it into GeckoShell class
## Done/Fixed in 0.3.10
- Try upload to PiPY
## Done/Fixed in 0.3.9
- Message encoding -> latin1 from utf-8 to avoid mangling raw bytes. This fixes
the turning pump 2 off when turning pump 1 on using `set UdP2=HI` then
`set UdP1=HI`. There must be a better way to do this without switching between
strings and bytes ...
- Major source restructure to get ready for PyPI package
- Moved to pyproject.toml/setup.cfg for modern Python library
- Updated README.md with better examples
## Done/Fixed in 0.3.8
- Restructure code to be in line with Python library style
- Code auto formatted with Black
- Most pylint warnings/issues fixed
- Unit tests added for GeckoStructAccessor
- Watercare handled
- Client.py program restructured to use python Cmd class
## Done/Fixed in 0.3.7
- Deal with unhandled devices
## Done/Fixed in 0.3.6
- Limit buttons & devices to those available based on configuration (i.e. don't show P3 if not installed)
- Dump state block & intro sequence so we can build a simulator
- Deal with temp decorators that might not be present on different modules
- Automation interface added
- Timeout retry of command to make it more robust on busy networks
# Version
Using Semantic versioning https://semver.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/gazoodle/geckolib",
"name": "geckolib",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Gecko Alliance,in.touch2,library,Home Automation",
"author": "Gazoodle",
"author_email": "gazoodle@hash.fyi",
"download_url": "https://files.pythonhosted.org/packages/6d/29/e2c74fcb4f14b0cca39d0b235f3b5a85d2c7bbb7df90aa7c9e063ce9ff44/geckolib-0.4.8.tar.gz",
"platform": null,
"description": "# GeckoLib\n\nLibrary to interface with Gecko Alliance spa pack systems via in.touch2\n\nWritten from the ground up using info gleaned from Wireshark captures to sniff\nthe conversation between the iOS app and the inTouch2 home transmitter.\n\nDesigned to be used by home automation systems such as Home Assistant or openHAB\n\n_This library is currently in Alpha, meaning that there may be large changes\nin library shape, class definitions, behaviours etc as I client it in my ongoing\nHome Assistant integration. This has now been released, in preview, and can be\nfound at https://github.com/gazoodle/gecko-home-assistant, or from HACS by adding\na new integration and seaching for Gecko_\n\n# Async support\n\nThe core of the library has been rewritten to be async based. This is for several\nreasons;\n\n1. Home Assistant, my main client of the library prefers this pattern. I'd like to\n get away from the \"can't connect\", \"not supported\" pattern and have the spa\n connect immediately to the facade (which will do the handshake to the actual spa\n asynchronously so that connection state can be shown in the UI if required).\n This will improve HA startup performance and allow me to control\n the retry connection pattern in the library without having to burden the HA\n integration with this (HA doesn't like protocol in integrations)\n2. I've done loads of multi-threaded programming in my life and think I'm familiar\n with almost all kinds of problems this brings, but ... why bother when this isn't\n necessary\n3. While trying to implement a feature that supports occasionally disconnected\n spas without generating reams of logging, I realized that I was fighting against\n the previous architecture, so it's time to refactor that.\n4. Every day is a school day. I've not seriously explored Python's async support :-)\n\nCurrently this isn't a breaking change, the sync library still has the functionality\nthat it always had (albeit with some major refactoring). There is a completely parallel\nAPI and class set to support async clients.\n\nI'll update the HA integration to use the async version as it's much faster to start\nand it has more functionality. I know there are other automation clients using this\nlibrary, so the sync API and classes will stay here for a while until those clients have\nhad a chance to use the new async code, but I will deprecate them at some point,\nprobably when the library goes to v1.0.0\n\n# Installation\n\nThis library is hosted on PyPI and can be installed with the following command-line\n\n`pip install geckolib`\n\n# GeckoShell usage\n\nOnce the library is installed, you should be able to start a Python interpreter session\nby using the command `python3`, then executing the following commands\n\n```python\n>>> from geckolib import GeckoShell\n>>> GeckoShell.run()\n\n\n <Disclaimer>\n :\n <snip/>\n :\n </Disclaimer>\n\nStarting discovery process...Found 1 spas\nConnecting to spa `Spa` at 10.1.2.3 ... connected!\nHeater: Temperature 39.0\u00b0C, SetPoint 39.0\u00b0C, Operation Idle\nPump 1: OFF\nPump 2: OFF\nBlower: OFF\nLights: OFF\nWaterCare: Standard\nWelcome to the Gecko shell. Type help or ? to list commands.\n\nSpa$\n\n```\n\nThis ought to find your spa on your local network. If it doesn't, please open an issue, you can\nexercise some of your spa features using the commands below\n\n```\n\nSpa$ P1 HI\nSpa$ P1 OFF\n\nSpa$ LI ON\nSpa$ LI OFF\n```\n\nYou can get help on the GeckoShell module\n\n```\n\nSpa$ help\n\nDocumented commands (type help <topic>):\n========================================\nBL P2 discover get list refresh snapshot watercare\nLI about download help live set state\nP1 config exit license manage setpoint version\n\nSpa$ help watercare\nSet the active watercare mode to one of ['Away From Home', 'Standard', 'Energy Saving', 'Super Energy Saving', 'Weekender'] : WATERCARE <mode>\nSpa$ watercare Weekender\n\n```\n\nIf you have more than one spa/device detected, you can use the `list` and `manage` commands\n\n```\n\nStarting discovery process...Found 2 spas\nWelcome to the Gecko shell. Type help or ? to list commands.\n\n(Gecko) list\n1. Spa\n2. Dummy Spa\n(Gecko) manage 1\nConnecting to spa `Spa` at 10.1.2.3 ... connected!\nHeater: Temperature 39.0\u00b0C, SetPoint 39.0\u00b0C, Operation Idle\nP1: OFF\nP2: OFF\nBL: OFF\nLI: OFF\nWaterCare: Standard\nSpa$\n\n```\n\nIf you want to get some diagnostics you can enable file logging at the start of the session\n\n```python\n>>> from geckolib import GeckoShell\n>>> GeckoShell.run([\"logfile client.log\"])\n\n :\n :\n\n```\n\nor it can be used later after you've connected to your spa with the `logfile` command\n\n```\n\nSpa$ logfile client.log\n\n```\n\nThe file `client.log` will contain diagnostic information that may be useful\nfor tracking down issues\n\nIf you want to start the client and point it at a specific IP address (maybe you have your SPA on a different subnet), you can issue the discovery command as part of the launch parameters\n\n```python\n>>> from geckolib import GeckoShell\n>>> GeckoShell.run([\"logfile client.log\", \"discover 192.168.1.2\"])\n\n :\n :\n\n```\n\n# Simulator Usage\n\nIt's best if you download the repo for using the simulator. Once you've done that,\nopen a terminal to your repo test folder (./tests)\n\n`python3 simulator.py`\n\nYou should see a prompt\n\n```\nWelcome to the Gecko simulator. Type help or ? to list commands.\n\n(GeckoSim)\n```\n\nYou should load the default snapshot at this point\n\n```\n(GeckoSim) load snapshots/default.snapshot\n(GeckoSim)\n```\n\nNow you can run the client program, or indeed your iOS or Android app and then\nattempt to connect to the simulator. At present it only supports loading another\nsnapshot to change the state. If the changes are too great, for example, if you've\nloaded a completly different spa then the iOS and Android apps may be confused.\n\nBest to click on the account icon and then reselect the test spa to get it to\nreconnect from the start.\n\nAlso, at present the simulator doesn't respond to any commands issued from the\niOS and Android applications.\n\n# Async API Usage\n\n```python\n\"\"\" Sample client demonstrating async use of geckolib \"\"\"\n\nimport asyncio\nimport logging\n\nfrom geckolib import GeckoAsyncSpaMan, GeckoSpaEvent # type: ignore\n\n# Replace with your own UUID, see https://www.uuidgenerator.net/>\nCLIENT_ID = \"a2d936db-4e95-4e4d-82bc-b4225fa99739\"\n# Replace with your spa IP address if on a sub-net\nSPA_ADDRESS = None\n\n\nclass SampleSpaMan(GeckoAsyncSpaMan):\n \"\"\"Sample spa man implementation\"\"\"\n\n async def handle_event(self, event: GeckoSpaEvent, **kwargs) -> None:\n # Uncomment this line to see events generated\n # print(f\"{event}: {kwargs}\")\n pass\n\n\nasync def main() -> None:\n\n async with SampleSpaMan(CLIENT_ID, spa_address=SPA_ADDRESS) as spaman:\n print(\"Looking for spas on your network ...\")\n\n # Wait for descriptors to be available\n await spaman.wait_for_descriptors()\n\n if len(spaman.spa_descriptors) == 0:\n print(\"**** There were no spas found on your network.\")\n return\n\n spa_descriptor = spaman.spa_descriptors[0]\n print(f\"Connecting to {spa_descriptor.name} at {spa_descriptor.ipaddress} ...\")\n await spaman.async_set_spa_info(\n spa_descriptor.ipaddress,\n spa_descriptor.identifier_as_string,\n spa_descriptor.name,\n )\n\n # Wait for the facade to be ready\n await spaman.wait_for_facade()\n\n print(spaman.facade.water_heater)\n\n print(\"Turning pump 1 on\")\n await spaman.facade.pumps[0].async_set_mode(\"HI\")\n\n await asyncio.sleep(5)\n\n print(\"Turning pump 1 off\")\n await spaman.facade.pumps[0].async_set_mode(\"OFF\")\n\n await asyncio.sleep(5)\n\n\nif __name__ == \"__main__\":\n # Install logging\n stream_logger = logging.StreamHandler()\n stream_logger.setLevel(logging.DEBUG)\n stream_logger.setFormatter(\n logging.Formatter(\"%(asctime)s> %(levelname)s %(message)s\")\n )\n logging.getLogger().addHandler(stream_logger)\n logging.getLogger().setLevel(logging.INFO)\n\n asyncio.run(main())\n```\n\nThis should output something like this\n\n```\nLooking for spas on your network ...\n2022-03-16 07:05:12,842> INFO Found 1 spas ... [My Spa(SPA00:01:02:03:04:05)]\nConnecting to My Spa at 10.0.0.123 ...\nHeater: Temperature 36.0\u00b0C, SetPoint 36.0\u00b0C, Real SetPoint 36.0\u00b0C, Operation Idle\nTurning pump 1 on\n2022-03-16 07:05:19,292> INFO Value for UdP2 changed from OFF to HI\n2022-03-16 07:05:19,479> INFO Value for P2 changed from OFF to HIGH\n2022-03-16 07:05:19,480> INFO Value for UdPumpTime changed from 0 to 45\nTurning pump 1 off\n2022-03-16 07:05:25,049> INFO Value for UdP2 changed from HI to OFF\n2022-03-16 07:05:25,236> INFO Value for P2 changed from HIGH to OFF\n2022-03-16 07:05:25,236> INFO Value for UdPumpTime changed from 45 to 0\n\n```\n\n# Complete sample\n\nThere is also a complete async sample which can be found in the repo under\nthe /sample folder. This can be run using `python3 complete.py`. Full path\nhttps://github.com/gazoodle/geckolib/tree/main/sample\n\n# Home Assistant integration\n\nThe best example of use is in the Home Assistant integration which can be\nfound here https://github.com/gazoodle/gecko-home-assistant\n\n# Sync API Usage\n\n**WARNING** Sync functionality will be removed in a future release,\nexamples removed from README\n\n# Acknowledgements\n\n- Inspired by https://github.com/chicago6061/in.touch2.\n- Thanks to the folk at Gecko for building this system as a local device rather than mandating a cloud solution.\n- Wireshark is an awesome tool for sniffing out what is going on on your network. Take a look one day, you might be horrified :-)\n\n# License\n\nhttps://www.gnu.org/licenses/gpl-3.0.html\n\n# Todo\n\n- Spa state (errors)\n- Error handling (ongoing)\n- Pythonize where possible\n- APIs to support integration into automation systems (Ongoing)\n - Warnings/Errors\n - Diagnostics\n- More unit tests\n- Handle other device types such as Waterfall\n- Handle inMix for lighting control\n- Add API documentation\n- Merge reminders branch from @kalinrow\n- List property for User demands in pack classes\n- List property for errors in pack classes\n- Tidy up support files. One class per file\n- Full sweep for typing hints - Ongoing\n- Add sensor for errors\n- Add switch for winterizing\n- Add ability to set hours so we can implement a crude clock sync mechanism\n- Think about a way to provide access to behaviour refresh frequencies so that\n it can be customised\n- Look into getting shell & simulator using async API so that there are no\n internal dependencies on the sync code any longer\n- Move to pytest unit test framework\n- Use snapshots to generate some specific tests\n- Build some documentation\n- Add coverage to GitHub package workflow\n- There is a lock issue when a command is being retried as the protocol lock\n is busy and the CUI won't exit until the timeout has been reached (this can\n be reproduced by making the simulator stop responding to watercare requests)\n\n## Done/Fixed in 0.4.8\n\n- Split radio strength & channel into two separate sensors\n- Added some extra debugging around protocol sync lock\n- Some unit_of_measurement values were the string \"None\" instead of the python keyword None\n- Aggregate SpaPack error properties into a single text sensor\n- Rebuild pack accessors from SpaStructPack.xml v36.1\n\n## Done/Fixed in 0.4.7\n\n- Merged fix for negative watercare values (thanks @EiNSTeiN-)\n- Demote out-of-range spapack struct enum values to DEBUG and return \"Unknown\"\n- Demote \"No handler for xxxx\" to DEBUG to declutter log files\n\n## Done/Fixed in 0.4.6\n\n- Going back to basics and watching the protocol from the iOS app, I noticed that\n the commands sent from the app don't use the same sequence numbers as the ones\n that are sent during connection, they run a loop around from 192-255 whereas the\n protocol ones go from 1-191 ... so replicate that behaviour in case it's confusing\n something in the system and adding to the instability of connections\n- Moved protocol retry constants to GeckoConfig class\n- Added 2 second pause between protocol retries to allow intouch2 EN module to settle\n- Increased default timeout from 2 to 4 seconds\n- Added radio channel and signal strength sensor\n\n## Done/Fixed in 0.4.5\n\n- Config change code could attempt to set result on a future that was already\n set leading to an unhandled exception that could result in the partial status\n update task being cancelled\n- Disconnected facades now cleared out of the system correctly\n- Added some more diagnostics to chase sporadic disconnects\n\n## Done/Fixed in 0.4.4\n\n- Moved config settings out of const class into their own class\n- Added idle/active config settings and task loop for library to switch between\n idle and active config settings. An idle spa is one that is currently not processing\n any user demands, an active spa is one that has received a client request such as to\n change temp or turn on a pump. Active mode will stay on while any user demand is\n currently live.\n- Replaced asyncio.sleep in various places with config_sleep which is aware of when\n the configuration values have changed which means that the loops currently waiting on\n these values stop waiting and can collect the new values.\n\n## Done/Fixed in 0.4.2\n\n- Fixed processor getting pegged at 100% but not using asyncio.sleep(0)\n- Fixed simulator to respect names compatible with Windows\n- Renamed some snapshots\n\n## Done/Fixed in 0.4.1\n\n- Updated README with simple async example\n- Pull in reminders PR from @kalinrow - Thanks!\n- Add unit tests for reminders\n- Add async version of reminders - slightly different API as sync version returns\n time as first reminder\n- Updated various clients to use reminders\n\n## Done/Fixed in 0.4.0\n\n- Supports both sync and async clients. The sync clients ought to be backward\n compatible but there has been a huge chunk of refactoring to get the async\n built and even though I've run all the tests and clients, it's possible there\n are issues\n- Sensor for connection status is available early in facade lifetime\n- Ping sensor available after spa begins connection sequence\n- Re-added readline library to simulator as it was doing auto-complete for snapshot\n loading and was useful when testing, but added it inside a try/catch block so\n it won't upset Windows clients\n- Manage ping failure and RF errors with retry mechanism\n- Watercare regular refresh from facade\n- Create Spa manager class to run the connection logic so that clients get cleanup\n opportunity when reconnections are needed\n- Handle disconnected spas, ping failures, RF errors and so on\n- Simulator can get/set accessors for experimentation\n\n## Done/Fixed in 0.3.24\n\n- Fix error found by Github workflow\n- Added extra logging into to find out more about issue #28\n- Removed readline library as it isn't supported on Windows and it wasn't really doing anything\n- Added some extra doc for issue #18\n- Added RFERR handler to client and simulator to start investigations\n- Handle Watercare index out of range\n- Accessors can now deal with Time type entries\n- Added diag.py to aid tracking issue#27\n- Added eco mode control to facade and shell\n- Temperature accessor in new generator as it doesn't need to be handled at runtime\n- Removed decorators.py\n\n## Done/Fixed in 0.3.23\n\n- Demoted some INFO logging to DEBUG to reduce HA log file clutter\n\n## Done/Fixed in 0.3.22\n\n- Increase connection timeout to help with laggy tubs and busy networks\n- Watercare setting updated locally rather than wait for tub response to\n improve HA UI responsiveness\n- Fast locator for static IP\n\n## Done/Fixed in 0.3.21\n\n- Demoted some benign debugging data that clutters log files\n- Replaced \"config\" and \"live\" with \"accessors\" commands in shell to reduce direct access to XML\n- Added \"monitor\" command in shell to give a live view of changes from other sources e.g. control panel or app\n- Removed runtime reliance on SpaPackStruct.xml, this is replaced by the python code in driver/pack/\\*\n- Accessor can handle byte, word, bool value updates if provided as a string (i.e. GeckoShell set command)\n\n## Done/Fixed in 0.3.20\n\n- Merge changes for variable speed pumps. Thanks https://github.com/los93sol\n- Prevent new \"pump\" command showing in help UI\n\n## Done/Fixed in 0.3.19\n\n- Ensure STATP changes are cleared after processing rather than accumulating for-all-time! Thanks https://github.com/maegibbons\n\n## Done/Fixed in 0.3.18\n\n- Added some more snapshots\n- Attempt to handle spas that return unsupported config/log versions\n- Add ability to provide an IP address to the library\n\n## Done/Fixed in 0.3.17\n\n- Attempt to fix urllib3 requirement in pip install. It was in the wrong place\n\n## Done/Fixed in 0.3.16\n\n- More robust to missed packets during spa connection\n- Mechanism to access raw pack values from the facade, e.g. facade.pumps[0].state_sensor.accessor.raw_value\n- Add API to facade to get device by key, e.g. facade.get_device(\"P1\") will return the first pump.\n- Add property to facade to get all device keys; facade.devices\n\n## Done/Fixed in 0.3.15\n\n- Trying out Github publish actions\n\n## Done/Fixed in 0.3.14\n\n- Added SmartWinterMode sensors\n- Added Filter Clean/Purge sensors\n\n## Done/Fixed in 0.3.13\n\n- Move MrSteam handling on so that we can get a proper structure dump\n\n## Done/Fixed in 0.3.12\n\n- UnicodeEncodeError: 'latin-1' codec can't encode character '\\u0101' in position 108: ordinal not in range(256)\n- Massive refactor of protocol handlers to make building a simulator easier\n- Changes to allow library to be more suitable for async clients\n- Ping frequency returned to 15 seconds\n- Simulator added to allow investigation using snapshots sent in from other folk\n- Heating state fixed to show heating/cooling as appropriate\n- Issue #1 Waterfall now recognised and responding to button press\n- Issue #3 P1 Twice - deduped the device list\n- Issue #8 The library should be able to provide temp and heater usage stats now\n- Issue #9 Water Heater current operation should now be working correctly\n\n## Done/Fixed in 0.3.11\n\n- Ping frequency set to 45 seconds\n- Reset method to GeckoReponse class to handle retries in GeckoGetStatus class\n- Add mechanism to locate a spa in the locator class based on it's identifier\n- Set worker threads to daemon mode\n- Re-structure for better lifetime management and easier clienting\n- Merged PR from dukey32123 supplying waterfall constants ... need to find keypad code too.\n- flake8 and black formatting and tidy-up\n- Observable added to propagate change notification so we can be cliented as a\n local-push integration in Home Assistant\n- Moved all the functionality out of client.py and put it into GeckoShell class\n\n## Done/Fixed in 0.3.10\n\n- Try upload to PiPY\n\n## Done/Fixed in 0.3.9\n\n- Message encoding -> latin1 from utf-8 to avoid mangling raw bytes. This fixes\n the turning pump 2 off when turning pump 1 on using `set UdP2=HI` then\n `set UdP1=HI`. There must be a better way to do this without switching between\n strings and bytes ...\n- Major source restructure to get ready for PyPI package\n- Moved to pyproject.toml/setup.cfg for modern Python library\n- Updated README.md with better examples\n\n## Done/Fixed in 0.3.8\n\n- Restructure code to be in line with Python library style\n- Code auto formatted with Black\n- Most pylint warnings/issues fixed\n- Unit tests added for GeckoStructAccessor\n- Watercare handled\n- Client.py program restructured to use python Cmd class\n\n## Done/Fixed in 0.3.7\n\n- Deal with unhandled devices\n\n## Done/Fixed in 0.3.6\n\n- Limit buttons & devices to those available based on configuration (i.e. don't show P3 if not installed)\n- Dump state block & intro sequence so we can build a simulator\n- Deal with temp decorators that might not be present on different modules\n- Automation interface added\n- Timeout retry of command to make it more robust on busy networks\n\n# Version\n\nUsing Semantic versioning https://semver.org/\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A library to interface with Gecko Alliance products using in.touch2",
"version": "0.4.8",
"split_keywords": [
"gecko alliance",
"in.touch2",
"library",
"home automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "95b56b1293493ddbcef8c576a68adf05cdcc40b9387619507179d3b4607beabd",
"md5": "3b5ce9b374d7b64aa3d17ac8cf666866",
"sha256": "f97eb5374f9bc922287b56d75b0074e339c4e73c98a7ad93863563f8e482b97a"
},
"downloads": -1,
"filename": "geckolib-0.4.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b5ce9b374d7b64aa3d17ac8cf666866",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1150840,
"upload_time": "2023-02-06T20:03:24",
"upload_time_iso_8601": "2023-02-06T20:03:24.886553Z",
"url": "https://files.pythonhosted.org/packages/95/b5/6b1293493ddbcef8c576a68adf05cdcc40b9387619507179d3b4607beabd/geckolib-0.4.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d29e2c74fcb4f14b0cca39d0b235f3b5a85d2c7bbb7df90aa7c9e063ce9ff44",
"md5": "1c1e5994a63a7c8cf344b83243900ccf",
"sha256": "8aa1f57a745dd978d085bc7b5483a2a74c6b37f4b54fffa56c9f4715b4aecc67"
},
"downloads": -1,
"filename": "geckolib-0.4.8.tar.gz",
"has_sig": false,
"md5_digest": "1c1e5994a63a7c8cf344b83243900ccf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 947198,
"upload_time": "2023-02-06T20:03:26",
"upload_time_iso_8601": "2023-02-06T20:03:26.909267Z",
"url": "https://files.pythonhosted.org/packages/6d/29/e2c74fcb4f14b0cca39d0b235f3b5a85d2c7bbb7df90aa7c9e063ce9ff44/geckolib-0.4.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-06 20:03:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "gazoodle",
"github_project": "geckolib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "geckolib"
}
JSON
