Skip to main content

Python client for Unisenza Plus

Unisenza Plus is a product line that connects smart thermostats and other devices manufactured by Purmo to a cloud service via the Unisenza Plus Gateway. pyupgw is a python client for that cloud service.

Currently, only the smart thermostats are supported.

Installation

Install the library using pip or your favorite package management tool:

$ pip install pyupgw

Usage

The following sample program illustrates how to use the client

import asyncio
from pyupgw import create_client, Client, Device, DeviceType

def report_changes(device: Device, changes: dict):
    print(f"{device.get_name()} has new changes:")
    for key, value in changes.items():
        print(f"- {key}: {value}")

 async def main():
     async with create_client("username", "password") as client:

         # Refresh the device state from the server.
         # The coroutine completes when the new state is available.
         await client.refresh_all_devices()

         print("Gateways:")
         for gateway in client.get_gateways():
             print(f"- {gateway.get_name()}")

         print("Devices:")
         for gateway, device in client.get_devices():
             if device.get_type() == DeviceType.HVAC:
                 print(
                     f"- {device.get_name()},",
                     f"target temperature: {device.get_target_temperature()},",
                     f"current temperature: {device.get_current_temperature()}",
                 )

         device = client.get_gateways()[0].get_children()[0]

         # Send the updated temperature to the server.
         # The coroutine completes when the server accepts the change,
         # but hasn't necessarily applied it yet.
         # You can subscribe to get notified when the change is eventually applied.
         device.subscribe(report_changes)
         await device.update_target_temperature(20.0)
         await asyncio.sleep(10)

 if __name__ == "__main__":
     asyncio.run(main())

The underlying API is based on MQTT and totally asynchronous. The library automatically synchronizes when fetching fresh state for the devices, but the same is not true for the update_X() calls. The server may not even report some updates, for instance when setting the target temperature to the same value it already has.

The sample program naively uses asyncio.sleep() to ensure it has time to receive the notification about the newly applied temperature value. An actual program would do something more efficient, like update GUI elements or dispatch messages to an event loop in response to the callbacks.

Command-line interface

The package contains a command-line interface. To install the dependencies, include the cli extras:

$ pip install pyupgw[cli]
$ pyupgw --help

Goals

The main reason for this project was to develop a client library for a Home Assistant integration for Unisenza Plus.

The client library is intended to give a robust and simplified interface to the most important functionality of the smart thermostats. By hiding complexity it trades off some degree of control.

The library only supports a subset of features of the devices. New features may be added on a case-by-case basis.

Non-goals

The author of the library is in no way affiliated with the company Purmo, and not working using official API documentation. The code is based on experimentation with the equipment at hand, and will likely never cover all the possible features of the products.

The Unisenza Plus service is based on the UleEco IoT platform. Hence, the package might work with some modifications with other solutions based on the platform. However, since the author does not have official documentation, this is not guaranteed and a universal UleEco client is not in the scope of this project for the time being.

The intended use of the library is developing scripts and other automation for the Purmo thermostats. The underlying API contains data specifically intended to be consumed by the official Unisenza Plus app (related to presentation and notifications, for instance). There is no intention to support those features in this library.

Contributing

This project is still in its early stages. Please open an issue or PR in the Github repository if you want to get in touch with questions or contributions.

The integration has been developed with no access to the official documentation and only supports the devices that the author and contributors have available. To help inspect messages between the client and the cloud service, use the logging capabilities of the pyupgw command-line interface.

Metadata

Release files for pyupgw 0.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyupgw 0.14
File Size Uploaded Provenance Actions
pyupgw-0.14.tar.gz 21.8 kB Without provenance Details for pyupgw-0.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyupgw 0.14
File Interpreter ABI Platform Actions
pyupgw-0.14-py3-none-any.whl Python 3 none any Details for pyupgw-0.14-py3-none-any.whl

Total release size: 45.3 kB

Release files / pyupgw-0.14.tar.gz

Download URL pyupgw-0.14.tar.gz
Size 21.8 kB
Tags Source
SHA-256 checksum
How to use checksums
30ef5a385a63f84c2f7014c028fdca16324739cde65654cef4499b71b31545ae
BLAKE2b-256 checksum
How to use checksums
3b9dd7c4810ce5ccf478a904e9bd28fbb0f2976eb4081a5c40af43cb1e9263bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.34.2

Release files / pyupgw-0.14-py3-none-any.whl

Download URL pyupgw-0.14-py3-none-any.whl
Size 23.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ab1058d67c41967117060553349d6bba576d78de52d6635435f1f6cd99cf58cd
BLAKE2b-256 checksum
How to use checksums
d57957b4478ae46cdf791f185a6a20b42c30a96f98d9d8d46af727a3b697b1da
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.34.2

Security for pyupgw 0.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page