espspapy 1.0.0__py3-none-any.whl

espspapy/__init__.py

@@ -0,0 +1,37 @@
+"""Local control of connected spas."""
+
+from .discovery import async_discover
+from .esptouch import async_pair
+from .exceptions import (
+    CommandError,
+    InvalidFrameError,
+    PairingError,
+    SpaConnectionError,
+    SpaException,
+    SpaNotRespondingError,
+    TimeoutExceededError,
+)
+from .helpers import get_local_ip
+from .models import Device, PairingResult, SpaInfo, SpaStatus
+from .spa import Spa
+from .timers import TimerSlot, build_timer_frame
+
+__all__ = [
+    "CommandError",
+    "Device",
+    "InvalidFrameError",
+    "PairingError",
+    "PairingResult",
+    "Spa",
+    "SpaConnectionError",
+    "SpaException",
+    "SpaInfo",
+    "SpaNotRespondingError",
+    "SpaStatus",
+    "TimeoutExceededError",
+    "TimerSlot",
+    "async_discover",
+    "async_pair",
+    "build_timer_frame",
+    "get_local_ip",
+]

espspapy/__main__.py

@@ -0,0 +1,7 @@
+"""Run ``python -m espspapy``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

espspapy/cli.py

@@ -0,0 +1,164 @@
+"""Command line interface: ``espspapy``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from dataclasses import asdict
+import getpass
+import json
+import logging
+import sys
+import time
+
+from .discovery import async_discover
+from .esptouch import async_pair
+from .exceptions import SpaException
+from .helpers import get_local_ip
+from .models import Device, SpaInfo, SpaStatus
+from .spa import Spa
+
+STATES = {"on": True, "off": False}
+
+
+def _format_status(status: SpaStatus) -> str:
+    unit = "°F" if status.fahrenheit else "°C"
+
+    def state(value: bool, hours: float | None = None) -> str:
+        timer = f" (timer {hours:g} h)" if hours is not None else ""
+        return ("on" if value else "off") + timer
+
+    def temperature(value: int | None) -> str:
+        return f"{value} {unit}" if value is not None else "?"
+
+    lines = [
+        f"Power        : {state(status.power)}",
+        f"Filter       : {state(status.filter, status.filter_hours)}",
+        f"Heater       : {state(status.heater, status.heater_hours)}",
+        f"Jets         : {state(status.jets)}",
+        f"Bubbles      : {state(status.bubbles)}",
+        f"Sanitizer    : {state(status.sanitizer, status.sanitizer_hours)}",
+        f"Temperature  : {temperature(status.current_temperature)}",
+        f"Target       : {temperature(status.target_temperature)}",
+    ]
+    if status.error_code:
+        lines.append(f"Error        : {status.error_code}")
+    return "\n".join(lines)
+
+
+def _print(value: SpaStatus | SpaInfo, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(asdict(value), ensure_ascii=False))
+    elif isinstance(value, SpaStatus):
+        print(_format_status(value))
+    else:
+        print(f"uid={value.uid} ip={value.ip} dtype={value.dtype}")
+
+
+async def _run(args: argparse.Namespace) -> int:
+    if args.command == "discover":
+        spas = await async_discover(args.timeout)
+        for info in spas:
+            _print(info, args.json)
+        return 0 if spas else 1
+
+    if args.command == "pair":
+        password = args.password
+        if password is None:
+            password = getpass.getpass(f"Wi-Fi password for {args.ssid}: ")
+        local_ip = args.local_ip or get_local_ip()
+        print(f"Pairing {args.ssid} from {local_ip}…", file=sys.stderr)
+        result = await async_pair(args.ssid, password, local_ip, bssid=args.bssid)
+        print(f"Spa module {result.mac} joined with IP {result.ip}", file=sys.stderr)
+        args.host = result.ip
+
+    async with Spa(args.host) as spa:
+        if args.command in ("pair", "identify"):
+            _print(await spa.async_identify(), args.json)
+        elif args.command == "status":
+            _print(await spa.async_get_status(), args.json)
+        elif args.command == "monitor":
+            previous = None
+            while True:
+                status = await spa.async_get_status()
+                if status.raw != previous:
+                    previous = status.raw
+                    if not args.json:
+                        print(f"--- {time.strftime('%Y-%m-%d %H:%M:%S')}")
+                    _print(status, args.json)
+                    sys.stdout.flush()
+                await asyncio.sleep(args.interval)
+        elif args.command == "temp":
+            _print(await spa.async_set_temperature(args.value), args.json)
+        elif args.command == "raw":
+            _print(await spa.async_send_frame(args.frame), args.json)
+        else:
+            device = Device[args.command.upper()]
+            if args.state == "toggle":
+                status = await spa.async_toggle(device)
+            else:
+                status = await spa.async_set_device(device, STATES[args.state])
+            _print(status, args.json)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser."""
+    parser = argparse.ArgumentParser(prog="espspapy", description="Control spas.")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    parser.add_argument("-v", "--verbose", action="store_true", help="debug logs")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    discover = sub.add_parser("discover", help="find the spas of the LAN")
+    discover.add_argument("--timeout", type=float, default=3.0)
+
+    pair = sub.add_parser("pair", help="connect a spa to the Wi-Fi (ESP-Touch)")
+    pair.add_argument("--ssid", required=True, help="2.4 GHz network")
+    pair.add_argument("--bssid", help="access point MAC address (optional)")
+    pair.add_argument("--password", help="Wi-Fi password (prompted if omitted)")
+    pair.add_argument("--local-ip", help="IP address of this host")
+
+    for name, help_text in (
+        ("identify", "show the spa identity"),
+        ("status", "show the spa status"),
+    ):
+        sub.add_parser(name, help=help_text).add_argument("host")
+
+    monitor = sub.add_parser("monitor", help="follow the status (Ctrl+C to stop)")
+    monitor.add_argument("host")
+    monitor.add_argument("--interval", type=float, default=30.0)
+
+    for device in Device:
+        name = device.name.lower()
+        command = sub.add_parser(name, help=f"switch {name}")
+        command.add_argument("host")
+        command.add_argument("state", choices=("on", "off", "toggle"))
+
+    temp = sub.add_parser("temp", help="set the target temperature")
+    temp.add_argument("host")
+    temp.add_argument("value", type=int)
+
+    raw = sub.add_parser("raw", help="send a hex frame (checksum added)")
+    raw.add_argument("host")
+    raw.add_argument("frame")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line interface."""
+    args = build_parser().parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.WARNING,
+        format="%(levelname)s %(name)s %(message)s",
+    )
+    try:
+        return asyncio.run(_run(args))
+    except (SpaException, ValueError) as err:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 0 if args.command == "monitor" else 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

espspapy/const.py

@@ -0,0 +1,60 @@
+"""Constants of the spa protocol."""
+
+from __future__ import annotations
+
+SPA_TCP_PORT = 8990
+
+MSG_TYPE_HEARTBEAT = 0
+MSG_TYPE_COMMAND = 1
+MSG_TYPE_REPORT = 2
+MSG_TYPE_IDENTIFY = 3
+
+RESULT_OK = "ok"
+
+DEFAULT_TIMEOUT = 15.0
+DEFAULT_RETRIES = 3
+RETRY_DELAY = 2.0
+HEARTBEAT_INTERVAL = 50.0
+
+# Frames without checksum, from command set 1/3.
+FRAME_STATUS = "8888060FEE0F01"
+FRAME_SET_TEMPERATURE = "8888050F0C"
+
+# Timer frames: prefix + device (09 filter, 0A heater, 0B sanitizer) + list.
+TIMER_FRAME_PREFIX = "8888280F"
+TIMER_LIST_MARKER = 0x55
+TIMER_LIST_CLEAR = 0x00
+TIMER_LIST_LEN = 36
+TIMER_MAX_SLOTS = 7
+TIMER_MAX_DURATION = 48
+TIMER_WINDOW_HOURS = 168
+
+TEMP_RANGE_CELSIUS = (10, 40)
+TEMP_RANGE_FAHRENHEIT = (50, 104)
+ERROR_CODE_MIN = 180
+ERROR_CODE_END = 200
+# Heater on, target temperature maintained.
+HEATER_STANDBY_BIT = 6
+
+BROADCAST_ADDR = "255.255.255.255"
+
+# LAN discovery
+DISCOVERY_SEND_PORT = 10549
+DISCOVERY_RECEIVE_PORT = 10500
+DISCOVERY_REQUEST = b"spa_request"
+DISCOVERY_TIMEOUT = 3.0
+
+# ESP-Touch v1 (Espressif SDK, EsptouchTaskParameter)
+ESPTOUCH_TARGET_PORT = 7001
+ESPTOUCH_LISTEN_PORT = 18266
+ESPTOUCH_PACKET_INTERVAL = 0.008
+ESPTOUCH_GUIDE_DURATION = 2.0
+ESPTOUCH_DATA_DURATION = 4.0
+ESPTOUCH_SEND_TIMEOUT = 45.0
+ESPTOUCH_RECEIVE_TIMEOUT = 15.0
+ESPTOUCH_RESULT_LEN = 11
+ESPTOUCH_GUIDE_CODES = (515, 514, 513, 512)
+ESPTOUCH_DATA_OFFSET = 40
+ESPTOUCH_MAX_INDEX = 127
+ESPTOUCH_PAYLOAD_BYTE = b"1"
+ESPTOUCH_UNKNOWN_BSSID = bytes(6)

espspapy/discovery.py

@@ -0,0 +1,81 @@
+"""Discovery of the spas of the local network (UDP broadcast)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import socket
+
+from .const import (
+    BROADCAST_ADDR,
+    DISCOVERY_RECEIVE_PORT,
+    DISCOVERY_REQUEST,
+    DISCOVERY_SEND_PORT,
+    DISCOVERY_TIMEOUT,
+)
+from .exceptions import InvalidFrameError
+from .models import SpaInfo
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def parse_discovery_answer(data: bytes, sender_ip: str) -> SpaInfo | None:
+    """Decode a discovery answer (JSON, NUL padded)."""
+    text = data.split(b"\x00", 1)[0].decode("utf-8", errors="replace")
+    if "{" not in text:
+        return None
+    try:
+        info = SpaInfo.from_dict(json.loads(text))
+    except (ValueError, InvalidFrameError) as err:
+        _LOGGER.debug("Ignored answer from %s: %s", sender_ip, err)
+        return None
+    if info.ip is None:
+        return SpaInfo(uid=info.uid, ip=sender_ip, dtype=info.dtype)
+    return info
+
+
+class _DiscoveryProtocol(asyncio.DatagramProtocol):
+    def __init__(self) -> None:
+        self.found: dict[str, SpaInfo] = {}
+
+    def datagram_received(self, data: bytes, addr: tuple[str | int, int]) -> None:
+        _LOGGER.debug("Discovery answer from %s: %s", addr, data)
+        if info := parse_discovery_answer(data, str(addr[0])):
+            self.found[info.uid] = info
+
+
+def _udp_socket(port: int) -> socket.socket:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    sock.setblocking(False)
+    sock.bind(("", port))
+    return sock
+
+
+async def async_discover(
+    timeout: float = DISCOVERY_TIMEOUT,
+    *,
+    broadcast_address: str = BROADCAST_ADDR,
+    send_port: int = DISCOVERY_SEND_PORT,
+    receive_port: int = DISCOVERY_RECEIVE_PORT,
+) -> list[SpaInfo]:
+    """Broadcast ``spa_request`` and return the spas that answered.
+
+    The spas answer on ``receive_port`` (10500), whatever the source port.
+    """
+    loop = asyncio.get_running_loop()
+    transport, protocol = await loop.create_datagram_endpoint(
+        _DiscoveryProtocol, sock=_udp_socket(receive_port)
+    )
+    sender = _udp_socket(send_port)
+    try:
+        await loop.sock_sendto(
+            sender, DISCOVERY_REQUEST, (broadcast_address, send_port)
+        )
+        await asyncio.sleep(timeout)
+    finally:
+        sender.close()
+        transport.close()
+    return list(protocol.found.values())

espspapy/esptouch.py

@@ -0,0 +1,215 @@
+"""Wi-Fi pairing of a spa with ESP-Touch v1.
+
+The Wi-Fi module of the spa is an Espressif chip. Before joining a network it
+sniffs the air and decodes SSID, BSSID and password from the *length* of UDP
+broadcast packets (``com.espressif.iot.esptouch``). Once connected, it answers
+with its MAC and IP address on UDP port 18266.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+import ipaddress
+import logging
+import socket
+
+from .const import (
+    BROADCAST_ADDR,
+    ESPTOUCH_DATA_DURATION,
+    ESPTOUCH_DATA_OFFSET,
+    ESPTOUCH_GUIDE_CODES,
+    ESPTOUCH_GUIDE_DURATION,
+    ESPTOUCH_LISTEN_PORT,
+    ESPTOUCH_MAX_INDEX,
+    ESPTOUCH_PACKET_INTERVAL,
+    ESPTOUCH_PAYLOAD_BYTE,
+    ESPTOUCH_RECEIVE_TIMEOUT,
+    ESPTOUCH_RESULT_LEN,
+    ESPTOUCH_SEND_TIMEOUT,
+    ESPTOUCH_TARGET_PORT,
+    ESPTOUCH_UNKNOWN_BSSID,
+)
+from .exceptions import PairingError
+from .helpers import get_local_ip, parse_bssid
+from .models import PairingResult
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _build_crc8_table() -> tuple[int, ...]:
+    table = []
+    for value in range(256):
+        crc = value
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0x8C if crc & 1 else crc >> 1
+        table.append(crc)
+    return tuple(table)
+
+
+_CRC8_TABLE = _build_crc8_table()
+
+
+def crc8(data: bytes) -> int:
+    """Return the CRC8 Dallas/Maxim (reflected polynomial 0x8C, ``CRC8``)."""
+    crc = 0
+    for byte in data:
+        crc = _CRC8_TABLE[(byte ^ crc) & 0xFF]
+    return crc
+
+
+def _data_code(value: int, index: int) -> tuple[int, int, int]:
+    """Encode a byte and its index into three 9-bit words (``DataCode``)."""
+    if index > ESPTOUCH_MAX_INDEX:
+        raise ValueError("SSID and password too long for ESP-Touch")
+    crc = crc8(bytes((value, index)))
+    return (
+        (crc & 0xF0) | (value >> 4),
+        0x100 | index,
+        ((crc & 0x0F) << 4) | (value & 0x0F),
+    )
+
+
+def build_datum_lengths(
+    ssid: bytes, bssid: bytes, password: bytes, local_ip: bytes
+) -> list[int]:
+    """Return the packet lengths of the data code (``DatumCode``)."""
+    total_len = 5 + len(local_ip) + len(password) + len(ssid)
+    ssid_crc = crc8(ssid)
+    bssid_crc = crc8(bssid)
+
+    entries = [(total_len, 0), (len(password), 1), (ssid_crc, 2), (bssid_crc, 3)]
+    checksum = total_len ^ len(password) ^ ssid_crc ^ bssid_crc
+    for offset, byte in enumerate(local_ip + password + ssid):
+        checksum ^= byte
+        entries.append((byte, 5 + offset))
+    entries.insert(4, (checksum, 4))
+
+    # BSSID bytes are interleaved every 4 entries.
+    position = 5
+    for offset, byte in enumerate(bssid):
+        entries.insert(min(position, len(entries)), (byte, total_len + offset))
+        position += 4
+
+    return [
+        word + ESPTOUCH_DATA_OFFSET
+        for value, index in entries
+        for word in _data_code(value, index)
+    ]
+
+
+def build_packets(
+    ssid: str, password: str, local_ip: str, bssid: str | None = None
+) -> tuple[list[bytes], list[bytes]]:
+    """Return the guide and data packets to broadcast."""
+    parsed_bssid = parse_bssid(bssid) if bssid else ESPTOUCH_UNKNOWN_BSSID
+    guide = [ESPTOUCH_PAYLOAD_BYTE * length for length in ESPTOUCH_GUIDE_CODES]
+    datum = [
+        ESPTOUCH_PAYLOAD_BYTE * length
+        for length in build_datum_lengths(
+            ssid.encode(),
+            parsed_bssid,
+            password.encode(),
+            ipaddress.IPv4Address(local_ip).packed,
+        )
+    ]
+    return guide, datum
+
+
+def expected_answer_marker(ssid: str, password: str) -> int:
+    """Return the first byte of the module answer."""
+    return (len(ssid.encode()) + len(password.encode()) + 9) & 0xFF
+
+
+def parse_pairing_answer(data: bytes, marker: int) -> PairingResult | None:
+    """Decode the module answer: marker, MAC (6 bytes), IP (4 bytes)."""
+    if len(data) < ESPTOUCH_RESULT_LEN or data[0] != marker:
+        return None
+    return PairingResult(
+        mac=data[1:7].hex(":"), ip=str(ipaddress.IPv4Address(data[7:11]))
+    )
+
+
+class _AnswerProtocol(asyncio.DatagramProtocol):
+    def __init__(self, marker: int, answer: asyncio.Future[PairingResult]) -> None:
+        self._marker = marker
+        self._answer = answer
+
+    def datagram_received(self, data: bytes, addr: tuple[str | int, int]) -> None:
+        _LOGGER.debug("ESP-Touch answer from %s: %s", addr, data.hex())
+        result = parse_pairing_answer(data, self._marker)
+        if result and not self._answer.done():
+            self._answer.set_result(result)
+
+
+async def async_pair(
+    ssid: str,
+    password: str,
+    local_ip: str | None = None,
+    *,
+    bssid: str | None = None,
+    send_timeout: float = ESPTOUCH_SEND_TIMEOUT,
+    receive_timeout: float = ESPTOUCH_RECEIVE_TIMEOUT,
+    target: tuple[str, int] = (BROADCAST_ADDR, ESPTOUCH_TARGET_PORT),
+    listen_port: int = ESPTOUCH_LISTEN_PORT,
+) -> PairingResult:
+    """Send the Wi-Fi credentials to a spa in pairing mode.
+
+    ``local_ip`` is the address of this host on that network (sent to the spa
+    so that it can answer), detected when omitted. ``bssid``, the MAC address of the 2.4 GHz access
+    point, is optional: a zero BSSID is sent when it is unknown.
+    Raises :class:`PairingError` without answer.
+    """
+    if local_ip is None:
+        local_ip = get_local_ip()
+    guide, datum = build_packets(ssid, password, local_ip, bssid)
+    marker = expected_answer_marker(ssid, password)
+    loop = asyncio.get_running_loop()
+    answer: asyncio.Future[PairingResult] = loop.create_future()
+
+    listener = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    listener.setblocking(False)
+    listener.bind(("", listen_port))
+    transport, _ = await loop.create_datagram_endpoint(
+        lambda: _AnswerProtocol(marker, answer), sock=listener
+    )
+    sender = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    sender.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+    sender.setblocking(False)
+
+    async def _send(packet: bytes) -> None:
+        await loop.sock_sendto(sender, packet, target)
+        await asyncio.sleep(ESPTOUCH_PACKET_INTERVAL)
+
+    async def _broadcast() -> None:
+        try:
+            sender.bind((local_ip, 0))
+            start = loop.time()
+            index = 0
+            while loop.time() - start < send_timeout:
+                phase_end = loop.time() + ESPTOUCH_GUIDE_DURATION
+                while loop.time() < phase_end:
+                    for packet in guide:
+                        await _send(packet)
+                phase_end = loop.time() + ESPTOUCH_DATA_DURATION
+                while loop.time() < phase_end:
+                    for packet in datum[index : index + 3]:
+                        await _send(packet)
+                    index = (index + 3) % len(datum)
+        except OSError as err:
+            if not answer.done():
+                answer.set_exception(PairingError(f"Broadcast failed: {err}"))
+
+    broadcast = asyncio.create_task(_broadcast(), name="espspapy-esptouch")
+    try:
+        async with asyncio.timeout(send_timeout + receive_timeout):
+            return await answer
+    except TimeoutError as err:
+        raise PairingError("No answer from the spa") from err
+    finally:
+        broadcast.cancel()
+        with suppress(asyncio.CancelledError):
+            await broadcast
+        sender.close()
+        transport.close()

espspapy/exceptions.py

@@ -0,0 +1,29 @@
+"""Exceptions for espspapy."""
+
+
+class SpaException(Exception):
+    """General exception."""
+
+
+class SpaConnectionError(SpaException):
+    """The spa cannot be reached or closed the connection."""
+
+
+class TimeoutExceededError(SpaException):
+    """The spa did not answer in time."""
+
+
+class SpaNotRespondingError(SpaException):
+    """The Wi-Fi module answered but the spa control board did not."""
+
+
+class InvalidFrameError(SpaException):
+    """The spa sent an unexpected answer."""
+
+
+class CommandError(SpaException):
+    """The command cannot be executed in the current spa state."""
+
+
+class PairingError(SpaException):
+    """ESP-Touch pairing failed."""

espspapy/helpers.py

@@ -0,0 +1,45 @@
+"""Helpers for the spa protocol."""
+
+from __future__ import annotations
+
+import socket
+
+
+def checksum(frame: str) -> str:
+    """Return the checksum of a hex frame: ``255 - sum(bytes) % 255``."""
+    return f"{255 - sum(bytes.fromhex(frame)) % 255:02X}"
+
+
+def with_checksum(frame: str) -> str:
+    """Return the hex frame followed by its checksum."""
+    frame = frame.upper()
+    return frame + checksum(frame)
+
+
+def work_hours(value: int) -> float | None:
+    """Decode a timer byte.
+
+    Bit 7 means active, bits 0-6 count half hours. The spa sends ``0x80``
+    when no timer is programmed.
+    """
+    half_hours = value & 0x7F
+    return half_hours / 2 if value & 0x80 and half_hours else None
+
+
+def parse_bssid(value: str) -> bytes:
+    """Parse ``aa:bb:cc:dd:ee:ff`` (any separator) into 6 bytes."""
+    cleaned = "".join(char for char in value if char in "0123456789abcdefABCDEF")
+    if len(cleaned) != 12:
+        raise ValueError(f"Invalid BSSID: {value}")
+    return bytes.fromhex(cleaned)
+
+
+def get_local_ip() -> str:
+    """Return the IP address of this host on the LAN (nothing is sent).
+
+    Connecting a UDP socket sends no packet: it only asks the OS which
+    interface (and so which local address) would be used for that route.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+        sock.connect(("10.255.255.255", 1))
+        return str(sock.getsockname()[0])