# aiocamedomotic

> Async Python library for interacting with CAME Domotic home automation systems. Provides automatic session management and device control.

Key facts:

- Install with `pip install aiocamedomotic`. Requires Python 3.12, 3.13, or 3.14.
- Built on asyncio and aiohttp; every public method is async and prefixed
  with `async_`.
- Entry point: `CameDomoticAPI.async_create(host, username, password)`, used
  as an async context manager.
- Authentication is lazy: login happens on the first server call, not at
  client creation. Sessions are kept alive and renewed automatically.
- Supported device types: lights (on/off, dimmable, RGB), openings (covers),
  scenarios, thermoregulation zones, analog sensors, digital inputs, analog
  inputs, relays, timers, energy meters, loads control, and map pages.
  Server users can be managed too.
- Real-time device updates are available via long polling
  (`api.async_get_updates()`) with typed update classes.
- All exceptions inherit from `CameDomoticError`:
  `CameDomoticServerNotFoundError` (host unreachable), `CameDomoticAuthError`
  (bad credentials), `CameDomoticServerError` (other server errors).
- Unofficial library, not affiliated with or endorsed by CAME.
  Apache 2.0 license.

## Quickstart

```python
import asyncio

from aiocamedomotic import CameDomoticAPI
from aiocamedomotic.models import LightStatus

async def main():
    async with await CameDomoticAPI.async_create(
        "192.168.x.x", "username", "password"
    ) as api:
        lights = await api.async_get_lights()
        lamp = next((l for l in lights if l.name == "Kitchen lamp"), None)
        if lamp:
            await lamp.async_set_status(LightStatus.ON)

asyncio.run(main())
```

## Docs

- [Full documentation (llms-full.txt)](https://aiocamedomotic.readthedocs.io/latest/llms-full.txt): the
  complete documentation in a single Markdown file (~50k
  tokens) — getting started, usage examples for every device type, and the
  full API reference
- [Getting started](https://aiocamedomotic.readthedocs.io/latest/getting_started.html): installation and
  a step-by-step first example
- [Usage examples](https://aiocamedomotic.readthedocs.io/latest/usage_examples.html): task-oriented
  examples for every supported device type and feature
- [API reference](https://aiocamedomotic.readthedocs.io/latest/api_reference.html): reference for all
  public classes and methods

## Optional

- [Source repository](https://github.com/camedomotic-unofficial/aiocamedomotic): GitHub repository, issues, and releases
- [Development roadmap](https://github.com/camedomotic-unofficial/aiocamedomotic/blob/main/ROADMAP.md): planned features
- [Security policy](https://github.com/camedomotic-unofficial/aiocamedomotic/blob/main/SECURITY.md): how to report
  vulnerabilities
- [Contributing guide](https://github.com/camedomotic-unofficial/aiocamedomotic/blob/main/CONTRIBUTING.md): how to
  contribute to the project