py-bragerone Documentation

py-bragerone is an async Python library for integrating with the BragerOne heating system API. It provides REST and WebSocket clients, real-time parameter updates, and everything you need to build Home Assistant integrations or custom automation solutions.

Important

Status: Alpha - APIs may still evolve

Requirements: Python 3.13.2+ (aligned with Home Assistant 2025)

Quick Example

import asyncio

from pybragerone.gateway import BragerOneGateway


async def main() -> None:
   gateway = await BragerOneGateway.from_credentials(
      email="user@example.com",
      password="password",
      object_id=12345,
      modules=["ABC123", "DEF456"],
   )
   await gateway.start()
   try:
      async for event in gateway.bus.subscribe():
         print(f"Update: {event.pool}.{event.chan}{event.idx} = {event.value}")
   finally:
      await gateway.stop()


asyncio.run(main())

Key Features

🔌 Async REST Client

Built on httpx with automatic token refresh and HTTP caching

⚡ Real-time WebSocket

Socket.IO client with automatic reconnection and event streaming

📊 ParamStore

Runtime-light storage for live values (use ParamResolver for asset-driven discovery/metadata)

🏠 Home Assistant Ready

Designed from the ground up for HA integration patterns

🎯 Type Safe

Full Pydantic models with mypy strict mode compliance