Package: cozify
Unofficial Python3 API bindings for the (unpublished) Cozify API.
Includes high-level helpers for easier use of the APIs,
for example an automatic authentication flow, and low-level 1:1 API functions.InstallationBasic usageread devices by capability, print temperature dataonly authenticateauthenticate with a non-default state storageOn CapabilitiesKeeping authentication validWorking RemotelyUsing Multiple HubsEnconding PitfallsSample projectsDevelopmentTestsRoadmap, aka. Current LimitationsInstallationPython3.8 is the current minimum supported version of Python.
For example Ubuntu 20.04 LTS is still supported out of the box, older versions may need a manual Python upgrade or PPA.The recommended way is to install from PyPi:sudo -H pip3 install cozifyTo benefit from new features you’ll need to update the library (pip does not auto-update):sudo -H pip3 install -U cozifyor if developing, clone the main branch of this repo (main stays at current release) and:curl -sSL https://install.python-poetry.org | python -
poetry installTo develop python-cozify clone the devel branch and submit pull requests against the devel branch.
New releases are cut from the devel branch as needed.Basic usageThese are merely some simple examples, for the full documentation see:http://python-cozify.readthedocs.io/en/latest/read devices by capability, print temperature datafromcozifyimporthubdevices=hub.devices(capabilities=hub.capability.TEMPERATURE)forid,devindevices.items():print('{0}:{1}C'.format(dev['name'],dev['state']['temperature']))only authenticatefromcozifyimportcloudcloud.authenticate()# authenticate() is interactive and usually triggered automatically# authentication data is stored in ~/.config/python-cozify/python-cozify.cfgauthenticate with a non-default state storagefromcozifyimportcloud,configconfig.setStatePath('/tmp/testing-state.cfg')cloud.authenticate()# authentication and other useful data is now stored in the defined location instead of ~/.config/python-cozify/python-cozify.cfg# you could also use the environment variable XDG_CONFIG_HOME to override where config files are storedOn CapabilitiesThe most practical way to “find” devices for operating on is currently to filter the devices list by their capabilties. The
most up to date list of recognized capabilities can be seen atcozify/hub.pyIf the capability you need is not yet supported, open a bug to get it added. One way to compare your live hub device’s capabilities
to those implemented is running the util/capabilities_list.py tool. It will list implemented and gathered capabilities from your live environment.
To get all of your previously unknown capabilities implemented, just copy-paste the full output of the utility into a new bug.In short capabilities are tags assigned to devices by Cozify that mostly guarantee the data related to that capability will be in the same format and structure.
For example the capabilities based example code in this document filters all the devices that claim to support temperature and reads their name and temperature state.
Multiple capabilities can be given in a filter by providing a list of capabilities. By default any capability in the list can match (OR filter) but it can be flipped to AND mode
where every capability must be present on a device for it to qualify. For example, if you only want multi-sensors that support both temperature and humidity monitoring you could define a filter as:devices=hub.devices(capabilities=[hub.capability.TEMPERATURE,hub.capability.HUMIDITY],and_filter=True)Keeping authentication validIf the cloud token expires, the only option to get a new one is an interactive prompt for an OTP.
Since most applications will want to avoid that as much as possible there are a few tips to keep a valid token alive.
At the time of writing tokens are valid for 28 days during which they can be seamlessly refreshed.In most cases it isn’t necessary to directly call cloud.refresh() if you’re already using cloud.ping() to test token validity.
cloud.ping() will also perform a refresh check after a successful ping unless explicitly told not to do so.To refresh a token you can call as often as you want:cloud.refresh()By default keys older than a day will be re-requested and otherwise no refresh is performed. The refresh can be forced:cloud.refresh(force=True)And the expiry duration can be altered (also when calling cloud.ping()):cloud.refresh(expiry=datetime.timedelta(days=20))# orcloud.ping(autorefresh=True,expiry=datetime.timedelta(days=20))Working RemotelyBy default queries to the hub are attempted via local LAN. Also by default “remoteness” autodetection is on and thus
if it is determined during cloud.authentication() or a hub.ping() call that you seem to not be in the same network, the state is flipped.
Both the remote state and autodetection can be overriden in most if not all funcions by the boolean keyword arguments ‘remote’ and ‘autoremote’. They can also be queried or permanently changed by the hub.remote() and hub.autoremote() functions.Using Multiple HubsEverything has been designed to support multiple hubs registered to the same Cozify Cloud account. All hub operations can be targeted by setting the keyword argument ‘hub_id’ or ‘hub_name’. The developers do not as of yet have access to multiple hubs so proper testing of multi functionality has not been performed. If you run into trouble, please open bugs so things can be improved.The remote state of hubs is kept separately so there should be no issues calling your home hub locally but operating on a summer cottage hub remotely at the same time.Enconding PitfallsThe hub provides data encoded as a utf-8 json string. Python-cozify transforms this into a Python dictionary
where string values are kept as unicode strings. Normally this isn’t an issue, as long as your system supports utf-8.
If not, you will run into trouble printing for example device names with non-ascii characters:UnicodeEncodeError: ‘ascii’ codec can’t encode character ‘xe4’ in position 34: ordinal not in range(128)The solution is to change your system locale to support utf-8. How this is done is however system dependant.
As a first test try temporarily overriding your locale:LC_ALL='en_US.utf8' python3 program.pySample projectsgithub.com/Artanicus/cozify-temp- Store Multisensor data into InfluxDBTake a look at the util/ directory for some crude small tools using the library that have been useful during development.File an issue to get your project added hereDevelopmentTo develop python-cozify clone the devel branch and submit pull requests against the devel branch.
New releases are cut from the devel branch as needed.Testspytest is used for unit tests.Certain tests are marked as “live” tests and require an active authentication state and a real hub to query against. Live tests are non-destructive, i.e. they will not change device state.Some tests are marked as “destructive” and will cause changes such as a light being turned on or tokens getting invalidated on purpose. Every effort is made to return devices to their original state and to perform saved state manipulation on copies of the live state.A few tests are marked as “remote” and are only expected to succeed when testing remotely, i.e. outside the LAN of the hub.A few tests are marked as “mbtest” and will only work if a MonteBank server is available. If a non-local instance is desired, provide a .env file with MBTEST_HOST set. The easiest way to get a local instance is to use Docker:docker run –rm –network host bbyars/mountebank:latest mb startMost tests are marked as “logic” and do not require anything external. If no set is defined, only logic tests are run.During development you can run the test suite right from the source directory:pytest # or: poetry run pytest#orrunonlylivetests:pytest -m live#runeverythingexceptdestructive*MonteBanktests:pytest -m "not destructive and not mbtest"To run the test suite on an already installed python-cozify (defining a set is mandatory, otherwise ALL sets are run including destructive):pytest -v -m logic --pyargs cozifyRoadmap, aka. Current LimitationsAuthentication flow has been improved quite a bit but it would benefit a lot from real-world feedback.Read call coverage is decent and support for most light interaction is done. If there’s something specific you want to use sooner than later file an issue so it can get prioritized!Device model is not object oriented yet and instead relies on capability filtering and device id’s.