Skip to main content

SmartCocoon Python API

GitHub Release GitHub Activity License

pre-commit Black

Project Maintenance BuyMeCoffee

logo

A Python library for controlling SmartCocoon smart vents with comprehensive debug logging and Home Assistant integration support.

Table of Contents

Overview

This library provides a Python interface to the SmartCocoon cloud service, allowing you to control smart vents programmatically. It's designed primarily for Home Assistant integration but can be used independently for any Python project.

Status

This is not an official API from SmartCocoon and is in active development. The library is stable for basic operations but may have breaking changes as the API evolves.

Supported Devices

  • SmartCocoon Smart Vents (all models)

Installation

pip install pysmartcocoon

From Source

git clone https://github.com/davecpearce/pysmartcocoon.git
cd pysmartcocoon
pip install -e .

For Development

git clone https://github.com/davecpearce/pysmartcocoon.git
cd pysmartcocoon
pip install -e .[test]

Quick Start

import asyncio
from pysmartcocoon import SmartCocoonManager

async def main():
    # Initialize the manager
    manager = SmartCocoonManager()

    # Authenticate with your SmartCocoon account
    await manager.async_start_services(
        username="your_email@example.com",
        password="your_password"
    )

    # Update data from the API
    await manager.async_update_data()

    # Access your fans
    for fan_id, fan in manager.fans.items():
        print(f"Fan {fan_id}: {fan.name} - {fan.mode}")

        # Control the fan
        await fan.async_set_fan_mode("auto")
        await fan.async_set_fan_speed(50)  # 50% speed

    # Clean up
    await manager._api.close()

# Run the example
asyncio.run(main())

Features

Core Functionality

  • Cloud Integration: Connect to SmartCocoon cloud service
  • Device Discovery: Automatically discover and configure fans
  • Fan Control: Complete control over fan operations
  • Real-time Updates: Get current fan status and settings
  • Error Handling: Robust error handling and retry logic

Fan Control Capabilities

  • Power Control: Turn fans on/off
  • Speed Control: Set fan speed (0-100%)
  • Mode Control:
    • auto - Automatic mode based on temperature
    • eco - Energy-efficient mode
    • always_on - Always running
    • always_off - Always off
  • Status Monitoring: Real-time fan status and connection state

Advanced Features

  • Debug Logging: Comprehensive debug output for troubleshooting
  • Type Hints: Full type annotation support
  • Async Support: Built for async/await patterns
  • Home Assistant Ready: Designed for seamless HA integration

Usage Examples

Basic Fan Control

import asyncio
from pysmartcocoon import SmartCocoonManager

async def control_fan():
    manager = SmartCocoonManager()

    try:
        # Authenticate
        await manager.async_start_services("user@example.com", "password")

        # Get fan data
        await manager.async_update_data()

        # Find a specific fan
        fan = next(iter(manager.fans.values()))

        # Turn on and set to auto mode
        await fan.async_set_fan_mode("auto")
        await fan.async_set_fan_speed(75)

        print(f"Fan {fan.name} is now {fan.mode} at {fan.speed_pct}%")

    finally:
        await manager._api.close()

asyncio.run(control_fan())

Monitoring Fan Status

async def monitor_fans():
    manager = SmartCocoonManager()

    try:
        await manager.async_start_services("user@example.com", "password")

        while True:
            await manager.async_update_data()

            for fan_id, fan in manager.fans.items():
                status = "🟢 Connected" if fan.connected else "🔴 Disconnected"
                print(f"{fan.name}: {status} - {fan.mode} at {fan.speed_pct}%")

            await asyncio.sleep(30)  # Check every 30 seconds

    finally:
        await manager._api.close()

Home Assistant Integration

Installation

  1. Copy the custom_components/smartcocoon folder to your Home Assistant custom_components directory
  2. Restart Home Assistant
  3. Add the integration through the UI

Configuration

# configuration.yaml
smartcocoon:
  username: "your_email@example.com"
  password: "your_password"

Debug Logging in Home Assistant

Add to your configuration.yaml:

logger:
  logs:
    pysmartcocoon: debug

For detailed debug information, see the Debug Guide.

Debug Logging

The library includes comprehensive debug logging to help troubleshoot issues:

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Your code here - debug output will be shown

Debug output includes:

  • API requests and responses
  • Authentication details
  • Fan control operations
  • Error information

See the Debug Guide for complete documentation.

Development

Prerequisites

  • Python 3.13.2+
  • Git
  • Docker (for running GitHub Actions locally)

Development Environment

This project includes a complete development environment using VS Code Dev Containers:

  1. Open the project in VS Code
  2. When prompted, reopen in container
  3. The devcontainer will automatically set up all dependencies

See docs/DEVCONTAINER_README.md for detailed setup instructions.

Running Tests

# Run all tests
pytest

# Run with debug output
pytest -v -s

# Run integration tests (requires credentials)
export RUN_INTEGRATION=1
pytest tests/test_fan_control.py::test_integration_debug_logging -v -s

Code Quality

The project uses several tools to maintain code quality:

  • Black: Code formatting
  • isort: Import sorting
  • pylint: Code linting
  • mypy: Type checking
  • pre-commit: Git hooks

Run all checks:

pre-commit run --all-files

Documentation

Contributing

Contributions are welcome! Please see docs/CONTRIBUTING.md for guidelines.

Quick Contribution Checklist

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests and code quality checks
  5. Submit a pull request

Work to do

  • MQTT integration for real-time updates
  • Device discovery implementation
  • WebSocket support for live updates
  • Additional fan control features
  • Performance optimizations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Metadata

Release files for pysmartcocoon 1.4.2

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.4.2
File Size Uploaded Provenance Actions
pysmartcocoon-1.4.2.tar.gz 22.4 kB Without provenance Details for pysmartcocoon-1.4.2.tar.gz

Built distribution (wheel)

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

Total release size: 40.3 kB

Release files / pysmartcocoon-1.4.2.tar.gz

Download URL pysmartcocoon-1.4.2.tar.gz
Size 22.4 kB
Tags Source
SHA-256 checksum
How to use checksums
d9556eb66d0401b58057eb5857c5f4490c70340391655b1265a222cca8f24be1
BLAKE2b-256 checksum
How to use checksums
e608c9884cc14e96b132a10805bf8cae5f4bd7804eed51e657265e4753510736
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.2

Release files / pysmartcocoon-1.4.2-py3-none-any.whl

Download URL pysmartcocoon-1.4.2-py3-none-any.whl
Size 18.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2ea4bbd585617e877fb7f6cd14d7370a1b95bc531cfd00e6a77e00df08b34912
BLAKE2b-256 checksum
How to use checksums
6c917c9f0a60cef7295821d57dd128709578a5631b48c95b0f19e9308c122ddd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.2

Security for pysmartcocoon 1.4.2

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.

Release history Release notifications | RSS feed

This release

1.4.2 This release

2 release files No provenance

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