hapbeat-helper 0.1.2__py3-none-any.whl

hapbeat_helper/__init__.py

@@ -0,0 +1,10 @@
+"""hapbeat-helper — local daemon bridging Studio (web) to Hapbeat devices."""
+
+try:
+    # Generated by scripts/gen_version.py (gitignored).
+    # Present in local dev installs; absent in PyPI releases.
+    from hapbeat_helper._version import __version__
+except ImportError:
+    # Fallback: release version embedded at publish time.
+    # Keep this in sync with pyproject.toml [project] version.
+    __version__ = "0.1.2"

hapbeat_helper/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m hapbeat_helper` to invoke the CLI."""
+
+from hapbeat_helper.cli import main
+
+if __name__ == "__main__":
+    main()

hapbeat_helper/cli.py

@@ -0,0 +1,328 @@
+"""Command-line entry for ``hapbeat-helper``.
+
+Subcommands:
+
+- ``start [--port 7703]``                 start the daemon (foreground)
+- ``status``                              probe ws://localhost:7703
+- ``version``                             print version
+- ``stop``                                stop the auto-started helper
+- ``logs [-f] [-n N]``                    show log file + tail recent lines
+- ``install-service``                     register as OS auto-start service (Task Scheduler on Windows / launchd on macOS)
+- ``uninstall-service``                   remove the OS service registration
+- ``service-status``                      show OS service registration state
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import socket
+import sys
+from pathlib import Path
+
+from hapbeat_helper import __version__
+from hapbeat_helper.server import HelperServer, WS_PORT
+
+logger = logging.getLogger("hapbeat-helper")
+
+
+def _config_dir() -> Path:
+    if sys.platform == "win32":
+        import os
+        base = Path(os.environ.get("APPDATA", str(Path.home())))
+        return base / "hapbeat-helper"
+    return Path.home() / ".config" / "hapbeat-helper"
+
+
+def _setup_logging(verbose: bool) -> None:
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    _setup_logging(args.verbose)
+    server = HelperServer(port=args.port)
+    print(f"hapbeat-helper {__version__} starting on ws://localhost:{args.port}")
+    print("Press Ctrl+C to stop.")
+    try:
+        asyncio.run(server.run())
+    except KeyboardInterrupt:
+        print("\nshutting down…")
+        return 0
+    except RuntimeError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    """TCP-probe the WebSocket port. Cheap reachability check."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(0.5)
+    try:
+        sock.connect(("127.0.0.1", args.port))
+        print(f"hapbeat-helper: reachable on ws://localhost:{args.port}")
+        return 0
+    except OSError:
+        print(
+            f"hapbeat-helper: not running (no listener on {args.port})",
+            file=sys.stderr,
+        )
+        return 1
+    finally:
+        sock.close()
+
+
+def _cmd_version(_args: argparse.Namespace) -> int:
+    print(f"hapbeat-helper {__version__}")
+    return 0
+
+
+def _cmd_stop(_args: argparse.Namespace) -> int:
+    try:
+        from hapbeat_helper.service import get_service_manager
+        mgr = get_service_manager()
+        if hasattr(mgr, "stop"):
+            mgr.stop()
+            return 0
+    except NotImplementedError:
+        pass
+    print(
+        "stop: no auto-started instance found. "
+        "If you launched in foreground, press Ctrl+C there.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _cmd_logs(args: argparse.Namespace) -> int:
+    """Print the log file path and tail recent lines.
+
+    With --follow / -f, stream new lines until Ctrl+C.
+    """
+    try:
+        from hapbeat_helper.service import get_service_manager
+        mgr = get_service_manager()
+    except NotImplementedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if not hasattr(mgr, "log_path"):
+        print(
+            "logs: this platform does not redirect stdout to a file. "
+            "Run `hapbeat-helper start` to see logs in the "
+            "current terminal.",
+            file=sys.stderr,
+        )
+        return 1
+    log = mgr.log_path()
+    print(f"# {log}")
+    if not log.exists():
+        print(
+            "(log file does not exist yet — has the service been started?)",
+            file=sys.stderr,
+        )
+        return 1
+
+    # Print last N lines.
+    try:
+        with log.open("r", encoding="utf-8", errors="replace") as f:
+            lines = f.readlines()
+        for line in lines[-args.lines:]:
+            sys.stdout.write(line)
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if not args.follow:
+        return 0
+
+    # Tail mode (cross-platform): poll for new bytes.
+    import time
+    sys.stdout.flush()
+    try:
+        with log.open("r", encoding="utf-8", errors="replace") as f:
+            f.seek(0, 2)  # to EOF
+            while True:
+                chunk = f.read()
+                if chunk:
+                    sys.stdout.write(chunk)
+                    sys.stdout.flush()
+                else:
+                    time.sleep(0.5)
+    except KeyboardInterrupt:
+        return 0
+
+
+def _cmd_install_service(_args: argparse.Namespace) -> int:
+    try:
+        from hapbeat_helper.service import get_service_manager
+        mgr = get_service_manager()
+        mgr.install()
+        return 0
+    except NotImplementedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _cmd_uninstall_service(_args: argparse.Namespace) -> int:
+    try:
+        from hapbeat_helper.service import get_service_manager
+        mgr = get_service_manager()
+        mgr.uninstall()
+        return 0
+    except NotImplementedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _cmd_service_status(_args: argparse.Namespace) -> int:
+    try:
+        from hapbeat_helper.service import get_service_manager
+        mgr = get_service_manager()
+        state = mgr.status()
+        labels = {
+            "not_registered": "not registered",
+            "stopped": "registered, stopped",
+            "running": "registered, running",
+        }
+        print(f"hapbeat-helper service: {labels.get(state, state)}")
+        return 0 if state == "running" else 1
+    except NotImplementedError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _cmd_config_show(_args: argparse.Namespace) -> int:
+    cfg = _config_dir()
+    print(f"config dir: {cfg}")
+    cfg_file = cfg / "config.toml"
+    if cfg_file.exists():
+        print(cfg_file.read_text(encoding="utf-8"))
+    else:
+        print("(no config file yet — defaults are in use)")
+    return 0
+
+
+def _add_verbose(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--verbose", "-v", action="store_true", help="debug logging",
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="hapbeat-helper",
+        description=(
+            "Local daemon that bridges Hapbeat Studio (web) to "
+            "Hapbeat devices on the local network."
+        ),
+        epilog=(
+            "commands:\n"
+            "  start            start in foreground (Ctrl+C to stop)\n"
+            "  stop             stop the running helper\n"
+            "                   macOS: unloads launchd job (restarts at next login)\n"
+            "                   Windows: kills process (task remains registered)\n"
+            "  status           check ws://localhost:7703 reachability\n"
+            "  version          show installed version\n"
+            "  logs             show/follow the auto-start log file\n"
+            "  install-service  register & start at OS login\n"
+            "  uninstall-service  remove registration and stop\n"
+            "  service-status   show registration state\n"
+            "  config show      show config file path and contents\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    _add_verbose(p)
+    sub = p.add_subparsers(dest="cmd")
+
+    p_start = sub.add_parser(
+        "start",
+        help="start the daemon in the foreground (Ctrl+C to stop)",
+    )
+    _add_verbose(p_start)
+    p_start.add_argument(
+        "--port", type=int, default=WS_PORT,
+        help=f"WebSocket port (default: {WS_PORT})",
+    )
+    p_start.set_defaults(func=_cmd_start)
+
+    p_status = sub.add_parser("status", help="check whether helper is running")
+    _add_verbose(p_status)
+    p_status.add_argument("--port", type=int, default=WS_PORT)
+    p_status.set_defaults(func=_cmd_status)
+
+    p_version = sub.add_parser("version", help="print version")
+    p_version.set_defaults(func=_cmd_version)
+
+    p_stop = sub.add_parser(
+        "stop",
+        help="stop the running helper (macOS: bootout; Windows: taskkill)",
+    )
+    p_stop.set_defaults(func=_cmd_stop)
+
+    p_logs = sub.add_parser(
+        "logs",
+        help="show log file path + tail recent lines (-f to follow)",
+    )
+    p_logs.add_argument(
+        "-n", "--lines", type=int, default=50,
+        help="number of lines to show from the end (default: 50)",
+    )
+    p_logs.add_argument(
+        "-f", "--follow", action="store_true",
+        help="stream new log lines until Ctrl+C",
+    )
+    p_logs.set_defaults(func=_cmd_logs)
+
+    p_install = sub.add_parser(
+        "install-service",
+        help="register hapbeat-helper as an OS auto-start service (launchd on macOS / Startup-folder VBS shim on Windows); starts immediately",
+    )
+    p_install.set_defaults(func=_cmd_install_service)
+
+    p_uninstall = sub.add_parser(
+        "uninstall-service",
+        help="remove the OS service registration",
+    )
+    p_uninstall.set_defaults(func=_cmd_uninstall_service)
+
+    p_svc_status = sub.add_parser(
+        "service-status",
+        help="show OS service registration state (not_registered / stopped / running)",
+    )
+    p_svc_status.set_defaults(func=_cmd_service_status)
+
+    p_config = sub.add_parser("config", help="config subcommands (try: config show)")
+    sub_cfg = p_config.add_subparsers(dest="config_cmd")
+    p_show = sub_cfg.add_parser("show", help="show config path / contents")
+    p_show.set_defaults(func=_cmd_config_show)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 1
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hapbeat_helper/device_registry.py

@@ -0,0 +1,131 @@
+"""Central device registry — single source of truth for device state.
+
+Helper edition: no Qt, no serial. USB serial setup happens in Studio
+(via Web Serial API) and is not surfaced here.
+
+Listeners register a callable that is invoked synchronously after every
+mutation; thread-safety is the listener's responsibility (the helper
+WebSocket layer marshals calls onto the asyncio loop).
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+# Liveness window. Scan loop pings every 2s (see server._scan_loop),
+# so a device is treated as offline after ~2 missed PONGs (5s window).
+# Manager parity: Manager uses 2s scan / 8s threshold; we run a touch
+# tighter so power-off shows up in the Studio UI within ~5s instead
+# of the 12s the previous "5s/12s" pair allowed.
+_OFFLINE_THRESHOLD = 5.0
+
+
+@dataclass
+class HapbeatDevice:
+    ip: str = ""
+    name: str = ""
+    mac: str = ""
+    address: str = ""  # path-based address e.g. "player_1/chest"
+    firmware: str = ""
+
+    last_seen: float = 0.0  # time.monotonic()
+    discovered_via: str = ""  # "mdns", "udp_broadcast"
+
+    volume_level: Optional[int] = None
+    volume_wiper: Optional[int] = None
+    volume_steps: Optional[int] = None
+
+    @property
+    def is_online(self) -> bool:
+        if self.last_seen == 0.0:
+            return False
+        return (time.monotonic() - self.last_seen) < _OFFLINE_THRESHOLD
+
+
+class DeviceRegistry:
+    """Thread-safe registry of known Hapbeat devices."""
+
+    def __init__(self) -> None:
+        self._devices: dict[str, HapbeatDevice] = {}
+        self._lock = threading.Lock()
+        self._listeners: list[Callable[[], None]] = []
+
+    # ── Listener API ─────────────────────────────────────────
+
+    def add_change_listener(self, callback: Callable[[], None]) -> None:
+        """Register a callback fired after any device-state mutation.
+
+        The callback runs on whatever thread caused the mutation, so the
+        callback itself must be safe to invoke from background threads.
+        """
+        self._listeners.append(callback)
+
+    def _notify(self) -> None:
+        for cb in list(self._listeners):
+            try:
+                cb()
+            except Exception:  # noqa: BLE001
+                logger.exception("device_registry listener failed")
+
+    # ── Mutation API ─────────────────────────────────────────
+
+    def upsert_device(self, info: dict) -> None:
+        """Add or update a device from discovery info."""
+        ip = info.get("ip", "")
+        if not ip:
+            return
+
+        with self._lock:
+            dev = self._devices.get(ip)
+            if dev is None:
+                dev = HapbeatDevice(ip=ip)
+                self._devices[ip] = dev
+            dev.name = info.get("name", dev.name) or dev.name
+            dev.mac = info.get("mac", dev.mac) or dev.mac
+            dev.address = info.get("address", dev.address) or dev.address
+            dev.firmware = info.get("firmware", dev.firmware) or dev.firmware
+            dev.last_seen = time.monotonic()
+            dev.discovered_via = info.get("discovered_via", dev.discovered_via)
+
+            # Optional volume fields (PONG carries these from 2026-04-12+)
+            for key in ("volume_level", "volume_wiper", "volume_steps"):
+                if key in info and info[key] is not None:
+                    setattr(dev, key, info[key])
+
+        self._notify()
+
+    def update_volume(
+        self, ip: str, level: Optional[int], wiper: Optional[int],
+        steps: Optional[int],
+    ) -> None:
+        with self._lock:
+            dev = self._devices.get(ip)
+            if dev is None:
+                return
+            if level is not None:
+                dev.volume_level = level
+            if wiper is not None:
+                dev.volume_wiper = wiper
+            if steps is not None:
+                dev.volume_steps = steps
+        self._notify()
+
+    # ── Query API ────────────────────────────────────────────
+
+    def get_all_devices(self) -> dict[str, HapbeatDevice]:
+        with self._lock:
+            return dict(self._devices)
+
+    def get_device(self, ip: str) -> Optional[HapbeatDevice]:
+        with self._lock:
+            return self._devices.get(ip)
+
+    def get_all_ips(self) -> list[str]:
+        with self._lock:
+            return list(self._devices.keys())

hapbeat_helper/mdns_scanner.py

@@ -0,0 +1,147 @@
+"""mDNS device discovery for Hapbeat devices.
+
+Browses ``_hapbeat._udp.local.`` via zeroconf and forwards discovered
+devices to the registered callbacks. The companion :class:`UdpListener`
+handles all UDP/PONG traffic, so this module is mDNS-only.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Callable, Optional
+
+from zeroconf import (
+    ServiceBrowser, ServiceInfo, ServiceStateChange, Zeroconf,
+)
+
+logger = logging.getLogger(__name__)
+
+HAPBEAT_SERVICE_TYPE = "_hapbeat._udp.local."
+
+DeviceCallback = Callable[[dict], None]
+RemovedCallback = Callable[[str], None]
+
+
+class MdnsScanner:
+    """Continuously browses for Hapbeat services via mDNS."""
+
+    def __init__(self) -> None:
+        self._zeroconf: Optional[Zeroconf] = None
+        self._browser: Optional[ServiceBrowser] = None
+        self._known: dict[str, dict] = {}  # ip -> info
+        self._lock = threading.Lock()
+        self._found_callbacks: list[DeviceCallback] = []
+        self._removed_callbacks: list[RemovedCallback] = []
+
+    # ── Listener API ─────────────────────────────────────────
+
+    def add_found_listener(self, cb: DeviceCallback) -> None:
+        self._found_callbacks.append(cb)
+
+    def add_removed_listener(self, cb: RemovedCallback) -> None:
+        self._removed_callbacks.append(cb)
+
+    # ── Lifecycle ────────────────────────────────────────────
+
+    def start(self) -> None:
+        if self._zeroconf is not None:
+            return
+        self._zeroconf = Zeroconf()
+        self._browser = ServiceBrowser(
+            self._zeroconf,
+            HAPBEAT_SERVICE_TYPE,
+            handlers=[self._on_state_change],
+        )
+        logger.info("mDNS browsing started for %s", HAPBEAT_SERVICE_TYPE)
+
+    def stop(self) -> None:
+        if self._browser is not None:
+            self._browser.cancel()
+            self._browser = None
+        if self._zeroconf is not None:
+            self._zeroconf.close()
+            self._zeroconf = None
+
+    # ── Query ────────────────────────────────────────────────
+
+    def get_devices(self) -> dict[str, dict]:
+        with self._lock:
+            return dict(self._known)
+
+    # ── Internal ─────────────────────────────────────────────
+
+    def _on_state_change(
+        self,
+        zeroconf: Zeroconf,
+        service_type: str,
+        name: str,
+        state_change: ServiceStateChange,
+    ) -> None:
+        if state_change == ServiceStateChange.Added:
+            info = zeroconf.get_service_info(service_type, name)
+            if info is not None:
+                self._handle_added(info)
+        elif state_change == ServiceStateChange.Removed:
+            self._handle_removed(name)
+
+    def _handle_added(self, info: ServiceInfo) -> None:
+        addresses = info.parsed_addresses()
+        if not addresses:
+            return
+        ip = addresses[0]
+
+        txt: dict[str, str] = {}
+        if info.properties:
+            for key_bytes, val_bytes in info.properties.items():
+                key = (
+                    key_bytes.decode("utf-8", errors="replace")
+                    if isinstance(key_bytes, bytes) else str(key_bytes)
+                )
+                val = (
+                    val_bytes.decode("utf-8", errors="replace")
+                    if isinstance(val_bytes, bytes)
+                    else str(val_bytes) if val_bytes is not None else ""
+                )
+                txt[key] = val
+
+        device_info: dict = {
+            "ip": ip,
+            "port": info.port,
+            "name": txt.get("name", info.name),
+            "group": int(txt.get("group", "0") or "0"),
+            "firmware": txt.get("fw", ""),
+            "mac": txt.get("mac", ""),
+            "discovered_via": "mdns",
+        }
+        with self._lock:
+            self._known[ip] = device_info
+
+        logger.info(
+            "mDNS: %s @ %s", device_info["name"] or "(unnamed)", ip,
+        )
+        for cb in list(self._found_callbacks):
+            try:
+                cb(device_info)
+            except Exception:  # noqa: BLE001
+                logger.exception("mdns found listener failed")
+
+    def _handle_removed(self, name: str) -> None:
+        removed_ip: Optional[str] = None
+        with self._lock:
+            for ip, dev in self._known.items():
+                if dev.get("name") == name or name.startswith(
+                    dev.get("name", "\x00"),
+                ):
+                    removed_ip = ip
+                    break
+            if removed_ip is not None:
+                del self._known[removed_ip]
+
+        if removed_ip is not None:
+            logger.info("mDNS removed: %s", name)
+            for cb in list(self._removed_callbacks):
+                try:
+                    cb(removed_ip)
+                except Exception:  # noqa: BLE001
+                    logger.exception("mdns removed listener failed")