Home Assistant Integration ========================== The typical integration flow has two distinct phases: Configuration Phase ------------------- During config flow, use asset-aware mode to discover entities. .. code-block:: python # 1. Login via REST await api_client.ensure_auth(email, password) # 2. Select object and modules objects = await api_client.get_objects() object_id = objects[0].id modules_resp = await api_client.get_modules(object_id=object_id) module_ids = [str(m.devid or m.id) for m in modules_resp if (m.devid or m.id) is not None] # 3. Enable asset-aware resolution param_store = ParamStore() resolver = ParamResolver.from_api(api=api_client, store=param_store, lang="en") # 4. Prime parameters via REST snapshot status, payload = await api_client.modules_parameters_prime(module_ids, return_data=True) if status in (200, 204) and isinstance(payload, dict): param_store.ingest_prime_payload(payload) # 5. Build entity descriptors with metadata from assets # Pick module permissions + menu id (deviceMenu) from one module; you can merge across modules if needed. first = modules_resp[0] device_menu = int(first.deviceMenu) permissions = list(getattr(first, "permissions", []) or []) symbols = await resolver.merge_assets_with_permissions(permissions=permissions, device_menu=device_menu) descriptors = [] for symbol, desc in symbols.items(): descriptors.append({ "symbol": symbol, "label": desc.get("label"), "unit": desc.get("unit"), }) .. note:: No WebSocket connection needed during config flow! Runtime Phase ------------- At runtime, use lightweight mode for best performance. .. code-block:: python # 1. Create gateway and lightweight ParamStore gateway = BragerOneGateway(api=api_client, object_id=object_id, modules=module_ids) param_store = ParamStore() # runtime-light (storage-only) # 2. Subscribe to updates async def handle_updates(): async for event in gateway.bus.subscribe(): if event.value is None: continue param_store.upsert( f"{event.pool}.{event.chan}{event.idx}", event.value, devid=event.devid, ) # Trigger HA entity updates # Per-module route visibility (multi-module): param_store.flatten_for_devid(devid) def on_alarm_quantity(event): if event.changed: ... # REST refresh alarm feed for event.devid gateway.on_alarm_quantity(on_alarm_quantity) # 3. Start gateway (connects WS, subscribes, primes) await gateway.start() Module connectivity ------------------- Two layers — do not conflate them: 1. **Module ↔ cloud** (SPA ``connectedAt``) — plant gateway reachability. Observe and wait when offline; the client cannot repair it. 2. **Library ↔ cloud** (Socket.IO client session) — must be **detectable** and **self-healing** (transport reset, reconnect, REST re-prime while down). Per-module cloud online/offline is **not** on the ParamUpdate EventBus (so existing ``bus.subscribe()`` loops stay typed and unbroken). Use the dedicated gateway API: .. code-block:: python from pybragerone.models.events import CloudSessionConnectivity, ModuleConnectivity def on_module(event: ModuleConnectivity) -> None: print(event.devid, "online" if event.online else "offline", event.source) def on_session(event: CloudSessionConnectivity) -> None: print("cloud session", "up" if event.up else "down", event.source) gateway.on_module_connectivity(on_module) gateway.on_cloud_session(on_session) # After start / refresh: # gateway.module_online(devid) -> True | False | None # gateway.module_connected_at(devid) -> int | None # REST connectedAt # gateway.ws_session_up() -> bool # library↔cloud Socket.IO # gateway.last_param_update_age_s() -> float | None The gateway primes from ``GET /v1/modules`` (``connectedAt != 0`` means online — same truthiness check as the SPA card/modal) and listens for the official Socket.IO push ``app:module:connection:status:changed`` (payload ``{devid: {connectedAt, gateway}}``, applied by Layout / ObjectsLayout in the web app). The client's own Socket.IO session is tracked separately and does **not** force modules offline (SPA parity). A background REST poll (default 60s; ``connectivity_poll_interval=0`` disables it) continues even while WS is down. Failed or empty ``get_modules`` responses never wipe every module to offline. Degraded rows (empty ``gateway``, null ``connectedAt``) parse as offline (``connectedAt == 0``) instead of being dropped from the listing. While the client's Socket.IO session is down, the same poll **REST-primes** parameters so Home Assistant entities keep receiving ``ParamUpdate`` events (WS deltas only resume after reconnect + resubscribe + prime). An Engine.IO abort that skips the Socket.IO disconnect callback still marks the session down before reconnect, so that REST-prime path can run. If the session still reports up but no **live** ``ParamUpdate`` is published for 180s (zombie transport), the poll REST-primes anyway; after two consecutive zombie primes it forces a hard Socket.IO restart (SPA parity: ``connect`` → ``ModulesService.connect`` + REST parameters), **awaiting** namespace join + ``resubscribe()`` so module binding completes. After repeated failed hard restarts it hard-resets the Socket.IO client, then rebuilds ``RealtimeManager``. Hard reconnect, transport recycle, and manager rebuild each attempt a fresh login before proceeding when credentials are available; token-only gateway clients (no ``creds_provider``) keep the existing access token instead of clearing it. Transport recycle and manager rebuild then apply an exponential recovery cooldown (REST primes continue). A **successful** hard reconnect does not arm cooldown; when hard reconnect aborts because forced re-login failed, cooldown **is** armed so the poll loop does not thrash. A subscribed module returning online while still zombie clears the cooldown and triggers recovery immediately (failed auth/resubscribe re-arms cooldown). Recovery is skipped while every subscribed module is known offline. Numeric event ``22`` (``SIGMA_NETWORK_EVENT_MODULE_MEMORY_UPDATED``) also triggers a per-module REST prime. ``BragerOneGateway.last_param_update_age_s()`` returns that gap for diagnostics. Connection **labels** are not hardcoded: resolve them from the live ``module`` i18n namespace (same keys the SPA uses): .. code-block:: python from pybragerone.models.i18n import I18nResolver labels = await I18nResolver(assets).resolve_module_connection_labels(lang="pl") # labels["serverConnection"], labels["connection.status"], # labels["connection.connected"], labels["connection.notConnected"], ... Stable grouping key for the HA connection child device: ``module.connection`` (i18n namespace path — **not** a menu-router route). .. important:: **After WebSocket reconnect:** Always re-fetch parameters via REST! .. code-block:: python # On reconnect, the gateway performs modules.connect + subscribe + prime again. # Make sure your ParamStore subscriber is active before starting the gateway. Entity Naming ------------- Route vs parameter visibility ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Everyday web-UI side-menu routes may be gated separately from individual parameters: - ``ParamResolver.route_visibility_diagnostics`` — static SPA route gates (installer denylist, ``isVisibleOnSideMenu``, ``displayDropdown`` leftovers). - ``ParamResolver.parameter_visibility_diagnostics`` — per-parameter status bits (``INVISIBLE``, ``DEVICE_AVAILABLE``). Static menu shells (e.g. ``MAINMENU_STREFY_CZASOWE`` / path ``timezones``) load parameter tokens from ``deviceMenu/static/.ts`` chunks referenced in ``index-*.js``. Use ``LiveAssetsCatalog.discover_static_route_tokens``, ``LiveAssetsCatalog.fetch_alarm_name_source`` (Alarms chunk / ``AlarmName`` enum), and pass ``static_route_symbols`` into ``build_panel_groups_from_menu`` (or call ``build_panel_groups`` with a primed ``ParamStore`` so overlays are resolved automatically). For activity feed display values use ``ParamResolver.resolve_raw_display_value(raw, unit_code=...)`` so numeric unit transforms match parameter entities. The Home Assistant integration caches entity descriptors in the config entry; after upgrading to a release that adds static-route overlays, users need a ``ha-bragerone`` release that bumps ``BOOTSTRAP_VERSION`` (the ``release/2026.9`` train uses version 14) **and** must reconfigure or reload the integration so bootstrap re-runs. Reloading on an integration build that still stores the previous bootstrap version leaves stale descriptor caches unchanged. Upgrading ``py-bragerone`` alone does not rewrite existing HA entity registries. ``build_panel_groups(..., web_ui_only=False)`` keeps permission/module-item based grouping and does **not** apply SPA ``displayDropdown`` gates; pass ``web_ui_only=True`` (and primed ``flat_values``) for everyday web-UI parity. ``build_panel_groups`` and ``panel_route_diagnostics`` accept ``use_store_flat_values=False`` to skip primed-store overlays and treat dropdown state as unprimed (structural route discovery). When ``flat_values`` is passed explicitly it always takes precedence over both the store and that switch. ``ParamStore.flatten_for_devid(devid)`` supplies module-scoped snapshots for multi-module setups; always forward ``ParamUpdate.devid`` on ``upsert``/``upsert_async``. .. code-block:: python # Recommended unique_id format for HA entities unique_id = f"bragerone_{device_id}_{pool}_{chan}{idx}" # For binary sensors from status bits unique_id = f"bragerone_{device_id}_{pool}_{chan}{idx}_bit{bit_index}" # Examples: # - bragerone_ABC123_P4_v1 # - bragerone_ABC123_P5_s40_bit3