Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

SmartCocoon Python API

GitHub Release GitHub Activity License

pre-commit Black

Project Maintenance BuyMeCoffee

logo

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

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 returns False for every other failure.
  • RequestError: network failures, timeouts and server errors, after up to three attempts with backoff. Rate limiting honours Retry-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

License

MIT. See LICENSE.md.

Metadata

Release files for pysmartcocoon 1.7.0b0

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

Source distribution (sdist)

Source distribution for pysmartcocoon 1.7.0b0
File Size Uploaded Provenance Actions
pysmartcocoon-1.7.0b0.tar.gz 39.6 kB With provenance Details for pysmartcocoon-1.7.0b0.tar.gz

Built distribution (wheel)

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

Total release size: 65.2 kB

Release files / pysmartcocoon-1.7.0b0.tar.gz

Download URL pysmartcocoon-1.7.0b0.tar.gz
Size 39.6 kB
Tags Source
SHA-256 checksum
How to use checksums
91825c4aee613da341b8abc51c1194dc376e0d17f86222a27cdeda281882c1ef
BLAKE2b-256 checksum
How to use checksums
86a505c5d76103b5a94846f51d1bf6467b0fb7413d08214d25351b0514ce49bd
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 16, 2026.

Transparency log

Release files / pysmartcocoon-1.7.0b0-py3-none-any.whl

Download URL pysmartcocoon-1.7.0b0-py3-none-any.whl
Size 25.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a8f04237bdd8bce4fb6217df4023b9f21d886df96ef0a0cd44cd38cfbb2db69
BLAKE2b-256 checksum
How to use checksums
5050357184bf9bf05c8045f3f5e1d297e4cdbb339d27aaa681cfbf714a0ae5b3
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 16, 2026.

Transparency log

Security for pysmartcocoon 1.7.0b0

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.

Select from 2 files

Attestation for pysmartcocoon-1.7.0b0.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 16, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release
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