Source code for powersensor_local.plug_api

"""Interface abstraction for Powersensor plugs."""
import sys

from logging import Logger

from .async_event_emitter import AsyncEventEmitter
from .plug_listener_tcp import PlugListenerTcp
from .plug_listener_udp import PlugListenerUdp
from .xlatemsg import translate_raw_message, Event, Message

[docs] class PlugApi(AsyncEventEmitter): """ The primary interface to access the interpreted event stream from a plug. The plug may be relaying messages from one or more sensors, in addition to its own reports. Acts as an AsyncEventEmitter. Events which can be registered for are documented in xlatemsg.translate_raw_message. """ def __init__(self, mac: str, ip: str, port: int = 49476, proto: str = 'udp', logger: Logger | None = None): """Create a :class:`PlugApi` instance for a single plug. Parameters ---------- mac : str MAC address of the plug (usually found in the ``id`` field of mDNS/ZeroConf discovery). ip : str IP address assigned to the plug. port : int, optional Port number of the plug’s API service. Defaults to ``49476``. proto : {'udp', 'tcp'}, optional Protocol used for communication. ``'udp'`` selects :class:`PlugListenerUdp`, while ``'tcp'`` selects :class:`PlugListenerTcp`. Any other value raises a :class:`ValueError`. logger : Logger, optional If provided, enables the logging of escaped exceptions from callbacks. Raises ------ ValueError If *proto* is not ``'udp'`` or ``'tcp'``. """ super().__init__(logger) self._mac: str = mac self._listener: PlugListenerUdp | PlugListenerTcp if proto == 'udp': self._listener = PlugListenerUdp(ip, port, logger) elif proto == 'tcp': self._listener = PlugListenerTcp(ip, port, logger) else: raise ValueError(f'Unsupported proto: {proto}') self._listener.subscribe('message', self._on_message) self._seen: set[str] = set()
[docs] def connect(self) -> None: """ Initiates a connection to the plug. Will automatically retry on failure or if the connection is lost, until such a time disconnect() is called. """ self._listener.connect()
[docs] async def disconnect(self) -> None: """Disconnects from the plug and stops further connection attempts.""" await self._listener.disconnect()
[docs] def forget_relayed(self, mac: str) -> None: """Forget having relayed messages for the given device. The next message relayed for it synthesizes 'now_relaying_for' again, as if this plug had never relayed for it before. """ self._seen.discard(mac)
async def _on_message(self, _: str, message: Message) -> None: """Translates the raw message and emits the resulting messages, if any. Also synthesizes 'now_relaying_for' messages as needed. """ try: evs = translate_raw_message(message, self._mac) except KeyError: # Ignore malformed messages return msgmac = message.get('mac') if msgmac is not None and msgmac != self._mac and msgmac not in self._seen: self._seen.add(str(msgmac)) # We want to emit this prior to events with data ev: Event = { 'mac': msgmac, } dev = message.get('device') if dev is not None: ev['device_type'] = dev role = message.get('role') if role is not None: ev['role'] = role await self.emit('now_relaying_for', ev) for name, ev in evs.items(): await self.emit(name, ev) @property def ip_address(self) -> str: """ Return the IP address provided on construction. Returns ------- str The IP address configured for the listener. """ return self._listener.ip @property def port(self) -> int: """ Return the port number provided on construction. Returns ------- int The TCP/UDP port configured for the listener. """ return self._listener.port