Metadata-Version: 2.5
Name: connectlife
Version: 0.14.0
Summary: A Python library for communicating with the ConnectLife API
Project-URL: Homepage, https://github.com/oyvindwe/connectlife
Project-URL: Issues, https://github.com/oyvindwe/connectlife/issues
Author-email: Øyvind Matheson Wergeland <oyvind@wergeland.org>
License-File: LICENSE
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.5
Requires-Dist: cryptography>=42.0.0
Description-Content-Type: text/markdown

# Python library for ConnectLife API 

Used by devices from Hisense, Gorenje, ASKO & ATAG and ETNA Connect.

The goal of this library is to support a native [Home Assistant](https://www.home-assistant.io/) integration for devices
that uses the ConnectLife API.

The code is based on [Connectlife API proxy / MQTT Home Assistant integration](https://github.com/bilan/connectlife-api-connector)
([MIT license](https://github.com/bilan/connectlife-api-connector/blob/51c6b8e4562205e1c343d0cba19354f411bd5e77/composer.json#L2-L6)).

Software is provided as is - use at your own risk. There is probably no way to harm your physical devices, but
there is no guarantee that you don't experience other problems, for instance locking your ConnectLife account. 

Licensed under [GPLv3](LICENSE).

## Dumping your appliances

To test out the library (users in Russia/CIS may need to pass the `--trir` option):
```bash
pip install connectlife
python -m connectlife.dump --username <username> [--password '<password>'] [--trir]
```
Omit password to be prompted for it instead. Make sure to always use single quotes around
passwords with special characters.

This will log in to the ConnectLife API using the provided username and password, and write a JSON
file with all returned fields for each appliance that is registered with the account. Pass
`--format dd` to instead write a mapping file YAML skeleton to be used with
[connectlife-ha](https://github.com/oyvindwe/connectlife-ha).

> **Note:** the property set a device reports is not authoritative. A device may report properties it
> does not actually support (and may omit ones its feature code defines), so two units with the same
> device type/feature code can report different properties. Treat dumps as a starting point for a
> mapping, not ground truth — cross-check controls against the device or the ConnectLife app.

Pass `--query` to dump something else. Each query writes one file per appliance, except
`property-list`. The per-device queries redact the puid, wifi_id and device_id that the responses
echo, but the responses are undocumented and may contain other identifiers, so review each file
before sharing.

### Energy statistics

```bash
python -m connectlife.dump --username <username> --query energy
```
Writes `<type>-<feature>-energy.json` with the responses from both energy endpoints
(`air_duct_energy` and `energyConsumptionCurve`).

### Static data

```bash
python -m connectlife.dump --username <username> --query static
```
Writes `<type>-<feature>-static.json` with the `query_static_data` response: the settings and values
the device supports, and its firmware versions. It's per device, so it can differ between two
models that report the same device type/feature code.

### System data

```bash
python -m connectlife.dump --username <username> --query system
```
Writes `<type>-<feature>-system.json` with the `query_system_data` response. For a dishwasher it
lists the programs with their position, duration and which options each allows.

### Self-check

```bash
python -m connectlife.dump --username <username> --query self-check
```
Writes `<type>-<feature>-self-check.json` with the faults the device can report (e.g. `Error-F11`,
with the value that means a fault and a description) and the current ones.

### Property list

```bash
python -m connectlife.dump --username <username> \
    --query property-list --device-type-code <type-code> --device-feature-code <feature-code>
```
Writes `<type>-<feature>-property-list.json` with the property list for a device type and feature
code (any code, not just ones on your account).

### Hourly power

There is no dump query for this, but the library has `get_hour_power(puid, date)` for the hourly
energy use of a day. Non-AC devices reply with zeros.

## OAuth (browser sign-in)

`OAuthConnectLifeApi` uses tokens from the browser sign-in on `oauth.hijuconn.com`, which also
supports Google, Apple, Facebook and Microsoft accounts and accepting updated terms. The caller
runs the authorization code flow and refreshes the tokens (in Home Assistant, the OAuth2 config
flow), and passes a callback returning a valid access token:

```python
from connectlife.oauth import (
    OAUTH2_AUTHORIZE_URL,
    OAUTH2_CLIENT_ID,
    OAUTH2_CLIENT_SECRET,
    OAUTH2_TOKEN_URL,
    OAuthConnectLifeApi,
    generate_source_id,
)

api = OAuthConnectLifeApi(get_access_token, source_id=stored_source_id)
appliances = await api.get_appliances()
```

The client ID and secret are Hisense's client for Home Assistant. Requests go to Hisense's
third-party API (`juapi-3rd.hijuconn.com`), except energy statistics, which it doesn't have; those
go to the app gateway with the same token. If the API rejects the token twice,
`LifeConnectAuthError` is raised and the sign-in should be repeated. Persist the `source_id`.

## Test server

To use the test server to support developing the Home Assistant integration, clone this repo and see
[DEVELOPMENT.md](DEVELOPMENT.md#test-server).
