SmartCocoon Python API
A Python library for controlling SmartCocoon smart vents with comprehensive debug logging and Home Assistant integration support.
Table of Contents
- Overview
- Installation
- Quick Start
- Features
- Usage Examples
- Home Assistant Integration
- Debug Logging
- Development
- Documentation
- Contributing
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
From PyPI (Recommended)
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 temperatureeco- Energy-efficient modealways_on- Always runningalways_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
- Copy the
custom_components/smartcocoonfolder to your Home Assistantcustom_componentsdirectory - Restart Home Assistant
- 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:
- Open the project in VS Code
- When prompted, reopen in container
- 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
- 📚 Complete Documentation - Comprehensive documentation index
- 🐛 Debug Guide - Debug logging and troubleshooting
- 🛠️ Development Guide - Development environment setup
- 🤝 Contributing Guide - How to contribute to the project
- 📜 Development Scripts - Utility scripts for development
Contributing
Contributions are welcome! Please see docs/CONTRIBUTING.md for guidelines.
Quick Contribution Checklist
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and code quality checks
- 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.
1 maintainer
Metadata
1 maintainer
Release files for pysmartcocoon 1.4.6
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 | |
|---|---|---|---|---|
| pysmartcocoon-1.4.6.tar.gz | 30.3 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pysmartcocoon-1.4.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 51.3 kB
Release files / pysmartcocoon-1.4.6.tar.gz
| Download URL | pysmartcocoon-1.4.6.tar.gz |
|---|---|
| Size | 30.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8eef077c021aa2403b860843e1cd8bfa2f5c3994f0383c5b5ce56db612cc6af5
|
|
BLAKE2b-256 checksum How to use checksums |
f750090f17652a68c3517c1f68fed4af50dbfffb64da4c7f8481152aac6b21dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 8, 2026.
Transparency logRelease files / pysmartcocoon-1.4.6-py3-none-any.whl
| Download URL | pysmartcocoon-1.4.6-py3-none-any.whl |
|---|---|
| Size | 21.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a58941a07e2408d2dec48ecb3c6d3a78a790e332ceadaad0629556655abce3c0
|
|
BLAKE2b-256 checksum How to use checksums |
b2b84f02d29244a4ebb3687385e98ab38b59fc40292af387dc00d5fca050520c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Aug 8, 2026.
Transparency logSecurity for pysmartcocoon 1.4.6
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
All 2 files in this release have been uploaded with provenance metadata.
Attestation for pysmartcocoon-1.4.6.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 Aug 8, 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.
