pyatccala 0.1.0

Async client for the ATC Cala / Grupo Ferroli WiFi radiator cloud API

pyatccala

Async Python client for the ATC Cala / Grupo Ferroli WiFi radiator cloud API (gateway.grupoferroli.es). It powers a companion ATC Cala Home Assistant integration but has no Home Assistant dependency and can be used standalone.

The reverse-engineered protocol is documented in the companion integration repo's API.md.

Install

pip install pyatccala

Usage

import asyncio
from pyatccala import AtcCalaClient

async def main():
    async with AtcCalaClient("[e-mail]", "password") as client:
        await client.login()                      # OAuth password grant
        installations = await client.get_installations()
        inst = installations[0]

        for radiator in await client.get_radiators(inst.id_installation):
            print(radiator.name, radiator.mode, radiator.current_temperature)

        # Change the Comfort setpoint on one radiator (values sent as strings automatically).
        await client.put_radiator_changes(
            heaters=[radiator.id_radiator],
            cambios=[("TempComfort", 21.5)],
        )

        # Start a 60-minute boost to 22°C (expiry computed from the server clock).
        await client.async_start_boost(inst.id_installation, [radiator.id_radiator], 22.0, 60)

asyncio.run(main())

Auth handling

AtcCalaClient manages the OAuth token transparently:

• The access token lasts ~20 minutes. async_ensure_token() refreshes it before expiry using the refresh grant, falling back to a full password login if the refresh is rejected.
• Any 401 from a data call triggers one automatic re-auth and retry.
• Errors are typed: AtcCalaAuthError (re-login required) vs AtcCalaConnectionError (transient).

Pass your own aiohttp.ClientSession via session= (recommended inside a larger app), or let the client create and own one. api_base= can point at a mock/proxy for testing.

Development

pip install -e .[test]
pytest -p no:homeassistant   # (the flag only matters if HA test plugins share the venv)