pyintelliclima
This is a Python module for communicating with IntelliClima ECOCOMFORT 2.0 and ECOCOMFORT 3 devices. Its main use is for my corresponding HomeAssistant IntelliClima integration.
ECOCOMFORT 3 support is community-contributed and is not tested by me - I own only the ECOCOMFORT 2.0. It can be extended to include other devices from IntelliClima in the future, but not without help from device owners. I've made a guide for adding new devices. If you own another device type, it's highly appreciated if you could take a look at the guide and see if you can add a PR for your device(s), or share the logs as described so I can add them.
This API was made by reverse engineering the cloud API, through the use of an android emulator and proxy to catch the Intelliclima+ app traffic. As such, no public API exists and the functionality of this module breaks if the API changes. This module is provided as-is, with no guarantees of correctness, stability, or continued functionality. Use it at your own risk.
Sensor values
All values are returned as strings, and every sensor has a "no reading" sentinel that has to be filtered out before it reaches a consumer - report those as unavailable rather than as a measurement:
| Field | Sentinel |
|---|---|
tamb |
327.67 |
rh |
143 |
voc_state, co2 |
65535 |
aqi |
143 |
Air-quality values
Read air quality from voc_state on both generations. It carries a different quantity on each,
so it needs a different device class:
| Field | ECOCOMFORT 2.0 | ECOCOMFORT 3 |
|---|---|---|
voc_state |
VOC, ppm | eCO2, ppm |
co2 |
no sensor | unreliable - do not use |
aqi |
no sensor | air-quality index, 1-5 |
| threshold field | voc_thrs |
co2_thrs |
For a Home Assistant sensor, both with UnitOfRatio.PARTS_PER_MILLION:
- ECOCOMFORT 2.0 -
SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS_PARTS - ECOCOMFORT 3 -
SensorDeviceClass.CO2
The ECOCOMFORT 3 eCO2 figure is VOC-derived rather than an NDIR measurement, so it responds to solvents and cooking as well as to occupancy.
Reading the sensor-mode thresholds
rh_thrs and voc_thrs/co2_thrs are not plain levels: the level sits in the low bits and the
"advanced control" flag in bit 7, so a threshold with that flag on reads back as 129-131.
Read the decoded properties instead, each None when the device reports no value:
| Property | Register | Type |
|---|---|---|
device.humidity_threshold |
rh_thrs |
ThresholdSetting |
device.voc_threshold (ECOCOMFORT 2.0 only) |
voc_thrs |
ThresholdSetting |
device.co2_threshold (ECOCOMFORT 3 only) |
co2_thrs |
ThresholdSetting |
device.luminosity_threshold |
lux_thrs |
ThresholdLevel |
A ThresholdSetting is a level plus an advanced flag. Luminosity is a bare level - it is the
one threshold with no advanced-control option on either generation.
The flag matters most on a write. The thresholds and the satellite rotation share one device
register, so changing one means resending the others - and resending a raw register as a level is
out of range, while resending the level alone clears a flag the user set in the app. Note this is
not FanState.advanced, which is a different bit reporting that an armed threshold is engaging
right now.
Note that threshold writes were not observed to persist reliably - see
IntelliClimaEcocomfort2API.set_advanced_settings.
Reading the calibration offsets
offset_temp and offset_hum are in hundredths - -230 is -2.3 degrees - while
set_temperature_and_humidity_offsets() takes degrees and percent. Read
device.temperature_offset and device.humidity_offset, each None when the device
reports no value, so the two ends agree on units.
This matters because both offsets share one device register and must be written together: changing one means resending the other, and resending the raw field writes a hundredfold offset.
Reading the current mode and speed
mode_set and speed_set hold the last commanded values, which is not necessarily what the
unit is doing - the vendor app never displays them. Read device.fan_state instead, which
decodes the reported mode_state/speed_state registers into the running direction, speed,
preset, and the boost/night/profiled/advanced flags.
One exception: when a write needs to preserve "the current speed", keep reading speed_set.
The running speed may be a boost or night-profile override, and commanding that back would
make a temporary override permanent. FanSpeedState.boost has no FanSpeed counterpart at
all - boost is device-driven and lasts three minutes.
Credits
This was highly inspired by: https://github.com/ruizmarc/homebridge-intelliclima
Partial credit for the reverse engineering process of the API goes to them.
ECOCOMFORT 3 support, and the observation that the IntelliClima+ app ships as plain JavaScript and can therefore be read directly, are thanks to @rbressers.
Project Docs
For how to install uv and Python, see installation.md.
For development workflows, see development.md.
This project was built from simple-modern-uv.
Metadata
Release files for pyintelliclima 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyintelliclima-0.5.0.tar.gz | 144.0 kB | Without provenance | Details for pyintelliclima-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyintelliclima-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for pyintelliclima-0.5.0-py3-none-any.whl |
Total release size: 164.7 kB
Release files / pyintelliclima-0.5.0.tar.gz
| Download URL | pyintelliclima-0.5.0.tar.gz |
|---|---|
| Size | 144.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
27bb12fe7a4292e9db078e11d914902478eb52c0753c1474dfd4ca91e20c1cf4
|
|
BLAKE2b-256 checksum How to use checksums |
eabc8a7a6d5803c8eb691f948e77858117e06029c4957f097b6a40d75ddba096
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.5
|
Release files / pyintelliclima-0.5.0-py3-none-any.whl
| Download URL | pyintelliclima-0.5.0-py3-none-any.whl |
|---|---|
| Size | 20.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c7387f886a8a7b96c308d5faa7b142e635f824a4c24447571051da15c5981558
|
|
BLAKE2b-256 checksum How to use checksums |
ba8b1cec0ff0fa2b15f48be2e6d30f9475edd7667bcc76faa95b79491d913086
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.5
|
Security for pyintelliclima 0.5.0
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.