pybragerone.api.ws

WebSocket (Socket.IO) client for BragerOne realtime events.

Classes

EventDispatcher(*args, **kwargs)	Protocol for an event dispatcher used by the realtime manager.
RealtimeManager(token, *[, origin, referer, ...])	Thin Socket.IO wrapper for BragerOne realtime channel.

class pybragerone.api.ws.EventDispatcher(*args, **kwargs)

Bases: Protocol

Protocol for an event dispatcher used by the realtime manager.

class pybragerone.api.ws.RealtimeManager(token: str, *, origin: str = 'https://one.brager.pl', referer: str = 'https://one.brager.pl/', io_base: str = 'https://io.brager.pl', socket_path: str = '/socket.io', namespace: str = '/ws', token_provider: Callable[[], Awaitable[str]] | None = None, connect_timeout_s: float = 20.0)

Bases: object

Thin Socket.IO wrapper for BragerOne realtime channel.

The manager keeps a single AsyncClient connection, exposes the Engine.IO SID and the namespace SID, and forwards selected events to a user-provided callback (EventHandler). It does not interpret payloads; that is the gateway’s responsibility.

Notes

• Authentication is provided only via HTTP headers (Bearer token).

• We always connect to the :data:`~.constants.WS_NAMESPACE` namespace.

• We listen to: snapshot and the various *:parameters:change events.

• Subscriptions are emitted in a few payload variants (modules / devids) and optionally include group_id.

Parameters:

• token (str)

• origin (str)

• referer (str)

• io_base (str)

• socket_path (str)

• namespace (str)

• token_provider (Callable[[], Awaitable[str]] | None)

• connect_timeout_s (float)

add_on_connected(cb: Callable[[], Awaitable[None] | None])

Register a callback to be called when the connection is established.

Return type:

None

Parameters:

cb (Callable[[], Awaitable[None] | None])

add_on_disconnected(cb: Callable[[], Awaitable[None] | None])

Register a callback to be called when the Socket.IO session drops.

Return type:

None

Parameters:

cb (Callable[[], Awaitable[None] | None])

async connect()

Open a Socket.IO connection with appropriate headers and wait for join.

Return type:

None

async disconnect()

Close the Socket.IO connection if open.

Return type:

None

engine_sid()

Return the underlying Engine.IO SID (transport-level).

Return type:

str | None

async force_reconnect()

Tear down a still-“connected” Socket.IO session and reconnect.

Used when ParamUpdates go silent while the client still reports up (zombie Engine.IO that skipped disconnect callbacks). The SPA recovers via built-in Socket.IO reconnect then connect → ModulesService.connect + REST /modules/parameters; our supervisor only acts when connected looks down, so this forces that same path (on_connected → gateway resubscribe + prime).

Waits for the namespace join (same as connect()) so callers can safely sid() / modules.connect immediately afterwards.

Return type:

None

property group_id: int | None

Return the optional group_id included in subscription payloads.

async hard_reset()

Abandon the Socket.IO client and open a brand-new transport session.

Stronger than force_reconnect(): stops the supervisor, replaces the AsyncClient (handlers re-bound), then runs a full connect(). Used when disconnect/reconnect on the same client fails to restore live ParamUpdate traffic.

Return type:

None

last_disconnect_reason()

Return the most recent classified disconnect reason, if any.

Return type:

Optional[Literal['disconnect', 'stop', 'handshake_503', 'connect_error', 'empty_queue', 'server_stop', 'eio_close', 'reconnect_error', 'supervisor_stale', 'force_reconnect', 'hard_reset']]

on_event(handler: EventDispatcher)

Register a single event dispatcher (gateway attaches here).

Return type:

None

Parameters:

handler (EventDispatcher)

async resubscribe()

Re-emit subscription events after a reconnect.

Return type:

None

sid()

Return the namespace SID (/ws), if available.

Return type:

str | None

async subscribe(modules: list[str])

Emit listen events for the provided devices (devids/modules).

Return type:

None

Parameters:

modules (list[str])