SmartCocoon Python API
A Python library for the SmartCocoon cloud API. It is the library behind the SmartCocoon integration for Home Assistant, and can be used on its own from any async Python code.
This is not an official SmartCocoon API. It talks to the same cloud service as the SmartCocoon app, which is undocumented and can change without notice.
Contents
- Installation
- Quick start
- What the library gives you
- Keeping state current
- Errors
- Debug logging
- Development
- Documentation
Installation
pip install pysmartcocoon
Requires Python 3.13.2 or later.
Quick start
import asyncio
import aiohttp
from pysmartcocoon import SmartCocoonManager
from pysmartcocoon.const import FanMode
async def main() -> None:
async with aiohttp.ClientSession() as session:
manager = SmartCocoonManager(session)
# Logs in and loads locations, thermostats, rooms and fans.
if not await manager.async_start_services("you@example.com", "password"):
raise SystemExit("Login failed")
for fan_id, fan in manager.fans.items():
print(fan_id, fan.room_name, fan.mode, f"{fan.speed_pct}%")
fan_id = next(iter(manager.fans))
# Every control method returns False if SmartCocoon did not accept it.
if not await manager.async_set_fan_speed(fan_id, 50):
print("Speed change was not accepted")
await manager.async_set_fan_modes(fan_id, FanMode.ECO, 50)
asyncio.run(main())
Pass your own aiohttp.ClientSession when you have one. The library never closes a
session it did not create, because Home Assistant shares one session across every
integration. If you pass none, the library creates its own.
What the library gives you
SmartCocoonManager is the entry point. After async_start_services() it holds
locations, thermostats, rooms and fans, each a dict keyed by ID.
Controlling a fan: all of these take a fan_id and return bool:
| Method | Effect |
|---|---|
async_fan_turn_on(fan_id) |
Always on (FanMode.ON) |
async_fan_turn_off(fan_id) |
Always off (FanMode.OFF) |
async_set_fan_auto(fan_id) |
Auto mode, configured in the SmartCocoon app |
async_set_fan_eco(fan_id) |
Eco mode |
async_set_fan_speed(fan_id, pct) |
Speed, 0–100. Values outside that range are refused |
async_set_fan_modes(fan_id, mode, pct) |
Mode and speed together |
Reading a fan: the main Fan properties:
| Property | Meaning |
|---|---|
mode |
auto, eco, always_on or always_off |
fan_on |
Whether the fan is currently running |
speed_pct / power |
The manual speed setting, as a percentage / raw value (×100) |
speed_level |
The speed the fan is actually running at, 1–12. In eco and auto modes the cloud picks the speed itself, so this differs from speed_pct. The SmartCocoon app shows speed_level / 12 |
connected, last_connection |
Cloud connection state. A fan silent for more than 15 minutes is reported as disconnected even if the cloud still says connected |
predicted_room_temperature, is_room_estimating |
SmartCocoon's room temperature estimate |
room_id, room_name, firmware_version, thermostat_vendor |
Descriptive details |
The 1–12 range of speed_level is inferred from live data, not documented.
Keeping state current
The API does not push changes to clients, so poll. async_refresh_fans() refreshes
every fan in one request and returns whether it worked:
while True:
if not await manager.async_refresh_fans():
print("Refresh failed; fans keep their previous values")
await asyncio.sleep(60)
Home Assistant polls this way every 60 seconds. async_update_fans() does the same
refresh but returns the fan dict and swallows every failure, so you cannot tell fresh
data from stale with it.
Each fan also carries mqtt_username and mqtt_password. Do not connect to the
SmartCocoon broker with them. They are the fan's own identity: connecting with them
takes over the fan's session, and the real fan drops offline until it reconnects.
Errors
All errors derive from pysmartcocoon.errors.SmartCocoonError.
UnauthorizedError: SmartCocoon rejected the credentials. Expired sessions are handled for you: on a 401 the library logs in again once and retries the request. You only see this error when that fresh login is refused too, which normally means the password changed.async_refresh_fans()raises it so you can ask for a new password; it returnsFalsefor every other failure.RequestError: network failures, timeouts and server errors, after up to three attempts with backoff. Rate limiting honoursRetry-After.
Debug logging
Enable the pysmartcocoon logger at DEBUG to log every API request and response.
Passwords, tokens, MQTT credentials and your home address are masked before they are
logged, and email addresses are partly masked, so the output is safe to attach to an
issue. In Home Assistant:
logger:
logs:
pysmartcocoon: debug
To see every field the API sends, including ones the library doesn't read yet, run
scripts/dump_api_payloads.py. See the
Debug Guide for more.
Development
git clone https://github.com/davecpearce/pysmartcocoon.git
cd pysmartcocoon
pip install -r requirements_test.txt && pip install -e .
pytest -m "not integration" # integration tests use your real account
mypy pysmartcocoon
pre-commit run --all-files # the same lint gate CI runs
A VS Code dev container is included; see docs/DEVCONTAINER_README.md. Releases are published to PyPI automatically when a version tag is pushed; see docs/CONTRIBUTING.md.
Documentation
- CHANGELOG.md: what changed in each release
- Debug Guide: debug logging and troubleshooting
- Debugging fan connection status
- Contributing: code style, tests and releases
- Dev container
- Scripts
License
MIT. See LICENSE.md.
Metadata
Release files for pysmartcocoon 1.7.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 |
|---|---|---|---|---|
| pysmartcocoon-1.7.0.tar.gz | 39.6 kB | With provenance | Details for pysmartcocoon-1.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pysmartcocoon-1.7.0-py3-none-any.whl | Python 3 | none | any | Details for pysmartcocoon-1.7.0-py3-none-any.whl |
Total release size: 65.2 kB
Release files / pysmartcocoon-1.7.0.tar.gz
| Download URL | pysmartcocoon-1.7.0.tar.gz |
|---|---|
| Size | 39.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0e27bb706578785d5162c2053ecb87307b8aa5292bfcb6f4fac05ebd50d82d2e
|
|
BLAKE2b-256 checksum How to use checksums |
e334bb1975b587d2ff85c31d4865003b2ff97c4c21e3203afc94c4e4f80ebde6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / pysmartcocoon-1.7.0-py3-none-any.whl
| Download URL | pysmartcocoon-1.7.0-py3-none-any.whl |
|---|---|
| Size | 25.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ee16bea797b36a73fb241cddfd553606203ed917e5e29381d31c3ec0680ddaa2
|
|
BLAKE2b-256 checksum How to use checksums |
fcab184507b21964ebbf38e30d803994ee2528a57aea3d7d4efcc0440958a042
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for pysmartcocoon 1.7.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pysmartcocoon-1.7.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA 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.