pybricks-service 1.0.0b1__tar.gz

pybricks_service-1.0.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Pybricks Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pybricks_service-1.0.0b1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: pybricks-service
+Version: 1.0.0b1
+Summary: The Pybricks service: manages hub connections
+Keywords: pybricks,lego,micropython,bluetooth,robotics
+Author: The Pybricks Authors
+Author-email: The Pybricks Authors <dev@pybricks.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Typing :: Typed
+Requires-Dist: pybricks-core>=1.0.0b1
+Requires-Dist: anyio>=4.14
+Requires-Dist: bleak>=1.1.0
+Requires-Dist: packaging>=22
+Requires-Dist: serialx>=1.9
+Requires-Dist: aio-rfcomm>=1.1
+Requires-Dist: semver>=3
+Requires-Dist: typing-extensions>=4.15
+Maintainer: David Lechner
+Maintainer-email: David Lechner <david@pybricks.com>
+Requires-Python: >=3.11
+Project-URL: homepage, https://pybricks.com
+Project-URL: repository, https://github.com/pybricks/pybricks-tools
+Project-URL: documentation, https://pybricks.com/pybricks-tools/design/
+Project-URL: Changelog, https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-service/CHANGELOG.md
+Project-URL: Support, https://github.com/pybricks/support/discussions
+Project-URL: Issues, https://github.com/pybricks/support/issues
+Description-Content-Type: text/markdown
+
+# pybricks-service
+
+The background service behind the [Pybricks](https://pybricks.com) tools. It
+owns the Bluetooth connection to a hub and outlives any single command, which
+is what lets one `pb run` follow another without waiting to reconnect.
+
+It also fans a hub's output out to several clients at once, so an interactive
+session and a program watching the same hub do not get in each other's way.
+
+**You do not install this yourself.** It comes with `pybricks-cli`, and it
+starts when something needs it and stops when nothing has for a while.
+
+> **Status:** beta. Commands and APIs may still change before 1.0.0.

pybricks_service-1.0.0b1/README.md

@@ -0,0 +1,13 @@
+# pybricks-service
+
+The background service behind the [Pybricks](https://pybricks.com) tools. It
+owns the Bluetooth connection to a hub and outlives any single command, which
+is what lets one `pb run` follow another without waiting to reconnect.
+
+It also fans a hub's output out to several clients at once, so an interactive
+session and a program watching the same hub do not get in each other's way.
+
+**You do not install this yourself.** It comes with `pybricks-cli`, and it
+starts when something needs it and stops when nothing has for a while.
+
+> **Status:** beta. Commands and APIs may still change before 1.0.0.

pybricks_service-1.0.0b1/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "pybricks-service"
+version = "1.0.0b1"
+description = "The Pybricks service: manages hub connections"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "pybricks",
+    "lego",
+    "micropython",
+    "bluetooth",
+    "robotics",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Embedded Systems",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pybricks-core>=1.0.0b1",
+    "anyio>=4.14",
+    "bleak>=1.1.0",
+    "packaging>=22",
+    "serialx>=1.9",
+    "aio-rfcomm>=1.1",
+    "semver>=3",
+    "typing-extensions>=4.15",
+]
+
+[[project.authors]]
+name = "The Pybricks Authors"
+email = "dev@pybricks.com"
+
+[[project.maintainers]]
+name = "David Lechner"
+email = "david@pybricks.com"
+
+[project.scripts]
+pb-service = "pb_service.cli:main"
+
+[project.urls]
+homepage = "https://pybricks.com"
+repository = "https://github.com/pybricks/pybricks-tools"
+documentation = "https://pybricks.com/pybricks-tools/design/"
+Changelog = "https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-service/CHANGELOG.md"
+Support = "https://github.com/pybricks/support/discussions"
+Issues = "https://github.com/pybricks/support/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pb_service"
+
+[tool.uv.sources.pybricks-core]
+workspace = true

pybricks_service-1.0.0b1/pyproject.toml.orig

@@ -0,0 +1,51 @@
+[project]
+name = "pybricks-service"
+version = "1.0.0b1"
+description = "The Pybricks service: manages hub connections"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "The Pybricks Authors", email = "dev@pybricks.com" }]
+maintainers = [{ name = "David Lechner", email = "david@pybricks.com" }]
+requires-python = ">=3.11"
+keywords = ["pybricks", "lego", "micropython", "bluetooth", "robotics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Embedded Systems",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pybricks-core>=1.0.0b1",
+    "anyio>=4.14",
+    "bleak>=1.1.0",
+    "packaging>=22",
+    "serialx>=1.9",
+    "aio-rfcomm>=1.1",
+    "semver>=3",
+    "typing-extensions>=4.15",
+]
+
+[project.scripts]
+pb-service = "pb_service.cli:main"
+
+[project.urls]
+homepage = "https://pybricks.com"
+repository = "https://github.com/pybricks/pybricks-tools"
+documentation = "https://pybricks.com/pybricks-tools/design/"
+"Changelog" = "https://github.com/pybricks/pybricks-tools/blob/main/packages/pb-service/CHANGELOG.md"
+"Support" = "https://github.com/pybricks/support/discussions"
+"Issues" = "https://github.com/pybricks/support/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "pb_service"
+
+[tool.uv.sources]
+pybricks-core = { workspace = true }

pybricks_service-1.0.0b1/src/pb_service/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The Pybricks service.
+
+Owns every hub connection and outlives any single CLI invocation, so a hub
+stays connected between commands and several clients can talk to one hub at
+once.
+"""
+
+__version__ = "1.0.0b1"
+
+__all__ = ["__version__"]

pybricks_service-1.0.0b1/src/pb_service/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+from pb_service.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pybricks_service-1.0.0b1/src/pb_service/backend.py

@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""Choosing how the service reaches hubs.
+
+Imported lazily so that a service running against the simulated backend, as the
+tests and CI do, never loads the Bluetooth stack at all.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, cast
+
+import anyio
+
+from pb_service.hub.transport import HubTransport
+
+if TYPE_CHECKING:
+    from aio_rfcomm import Bluetooth
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "HUB_BACKEND_ENV_VAR",
+    "PERMISSION_NAME",
+    "get_hub_transport",
+    "open_hub_transport",
+]
+
+HUB_BACKEND_ENV_VAR = "PB_HUB_BACKEND"
+"""Selects the transport.
+
+Left alone, the service uses every transport together, which is what lets a hub
+be found whichever way it happens to be reachable. Set it to ``usb``, ``ble`` or
+``rfcomm`` to use only one, or to ``fake`` for a simulated hub.
+"""
+
+
+PERMISSION_NAME = "Pybricks RFCOMM Service"
+"""What macOS calls this service when it asks about Bluetooth.
+
+Shown in the permission dialog and under Privacy & Security, and what the
+answer is remembered against, so changing it asks every user again. pb-cli
+repeats it in what it tells the user, and a test holds the two together.
+
+Not plain "Pybricks": among the other entries in Privacy & Security that
+reads as the Pybricks app or Pybricks Code, and says nothing about what is
+asking or why. This is the part of pb-service that reaches EV3 and NXT hubs
+over Bluetooth Classic, and only that part is asked about: BLE is bleak's,
+inside the service itself.
+"""
+
+
+def _usb() -> HubTransport:
+    from pb_service.hub.usb import UsbHubTransport
+
+    return UsbHubTransport()
+
+
+def _ble() -> HubTransport:
+    from pb_service.hub.ble import BleHubTransport
+
+    return BleHubTransport()
+
+
+def _rfcomm(bluetooth: Bluetooth | None) -> tuple[HubTransport, ...]:
+    if bluetooth is None:
+        return ()
+
+    from pb_service.hub.rfcomm import RfcommHubTransport
+
+    return (RfcommHubTransport(bluetooth),)
+
+
+def _backend() -> str:
+    return os.environ.get(HUB_BACKEND_ENV_VAR, "").lower()
+
+
+def get_hub_transport(bluetooth: Bluetooth | None = None) -> HubTransport:
+    """Return the transport this service should use.
+
+    Every import here is inside the branch that needs it, so a service running
+    against the simulated backend loads neither the Bluetooth stack nor the
+    serial one, and a machine using only one of the real transports does not
+    pay for the other.
+
+    Returns:
+        Always a :class:`~pb_service.hub.combined.CombinedTransport`, holding
+        USB and Bluetooth or whichever single transport ``PB_HUB_BACKEND``
+        names. Always, even for one transport, so that choosing between
+        transports and honouring a request for a particular one are implemented
+        in exactly one place rather than once per backend. The simulated backend
+        is what lets the whole service be exercised on a CI runner with no radio
+        and nothing plugged in.
+
+    Args:
+        bluetooth: Bluetooth Classic, already open, or None to leave RFCOMM
+            out. :func:`open_hub_transport` opens it when it is wanted.
+    """
+    from pb_service.hub.combined import CombinedTransport
+
+    backend = _backend()
+
+    if backend == "fake":
+        from pb_service.hub.fake import FakeHub, FakeHubTransport
+
+        logger.warning("using the simulated hub backend; no real hub will be found")
+        return CombinedTransport(
+            FakeHubTransport(
+                FakeHub(name="Pybricks Hub", address="00:11:22:33:44:55"),
+                FakeHub(name="Spare Hub", address="66:77:88:99:AA:BB"),
+            )
+        )
+
+    if backend == "usb":
+        return CombinedTransport(_usb())
+
+    if backend == "ble":
+        return CombinedTransport(_ble())
+
+    if backend == "rfcomm":
+        return CombinedTransport(*_rfcomm(bluetooth))
+
+    if backend:
+        logger.warning(
+            "unknown %s=%r; using every transport", HUB_BACKEND_ENV_VAR, backend
+        )
+
+    # In TRANSPORT_PREFERENCE order, which is what makes USB the one chosen when
+    # a hub is reachable both ways. A test holds the two together.
+    return CombinedTransport(_usb(), _ble(), *_rfcomm(bluetooth))
+
+
+@asynccontextmanager
+async def open_hub_transport() -> AsyncGenerator[HubTransport, None]:
+    """Open the transport this service should use, for as long as the block lasts.
+
+    Bluetooth Classic is held open in this scope when RFCOMM is in use, and
+    nowhere else: aio-rfcomm allows it open once per process, and everything
+    opened through it stops working when its block ends, so it has to outlive
+    every hub. It is opened the first time RFCOMM needs it, not here, so the
+    service never waits on it to start (see
+    :mod:`pb_service.hub.rfcomm.lazy`). If it cannot be opened, RFCOMM
+    reports Bluetooth as unusable and the other transports carry on.
+
+    Yields:
+        What :func:`get_hub_transport` returns.
+    """
+    backend = _backend()
+
+    if backend in ("fake", "usb", "ble"):
+        yield get_hub_transport()
+        return
+
+    import aio_rfcomm.macos
+
+    from pb_service.hub.rfcomm.lazy import LazyBluetooth
+
+    # macOS asks the responsible process for Bluetooth permission, and a
+    # service started from a command line has no application to speak for it,
+    # so without this it is refused rather than asked. The answer is
+    # remembered under the name, so changing it asks the user again.
+    aio_rfcomm.macos.prompt_under_name(
+        name=PERMISSION_NAME, reason="to connect to LEGO hubs over Bluetooth"
+    )
+
+    async with anyio.create_task_group() as tg:
+        # Cast: it offers only the calls the RFCOMM transport makes.
+        bluetooth = cast("Bluetooth", LazyBluetooth(tg))
+
+        try:
+            yield get_hub_transport(bluetooth)
+        finally:
+            tg.cancel_scope.cancel()

pybricks_service-1.0.0b1/src/pb_service/cli.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 The Pybricks Authors
+
+"""The service's command line.
+
+Plain argparse rather than the CLI framework used by ``pb``: the service must not
+depend on the presentation layer, and it is not a program people interact with
+directly.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import signal
+import sys
+from typing import Any
+
+import anyio
+
+# Imported for the side effect: importing a method module registers its RPCs,
+# so nothing here reads the names. Said on each line, because a comment is
+# not something a linter can read.
+import pb_service.methods.hub  # pyright: ignore[reportUnusedImport]
+import pb_service.methods.program  # pyright: ignore[reportUnusedImport]
+import pb_service.methods.service  # pyright: ignore[reportUnusedImport]
+import pb_service.methods.stdio  # noqa: F401 # pyright: ignore[reportUnusedImport]
+from pb_core import ipc, lock
+from pb_core.ipc import AddressInUseError
+from pb_core.logging import setup_logging
+from pb_core.paths import log_file
+from pb_service import __version__
+from pb_service import service as service_module
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["main"]
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_ALREADY_RUNNING = 3
+
+_LEVELS = {
+    "trace": 5,
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+}
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pb-service",
+        description="The Pybricks service. Normally started automatically.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"pb-service {__version__}"
+    )
+    parser.add_argument(
+        "--endpoint",
+        help="Where to listen, for example tcp://127.0.0.1:47823. "
+        "Defaults to the platform's socket or named pipe.",
+    )
+    parser.add_argument(
+        "--foreground",
+        action="store_true",
+        help="Log to stderr instead of only to the log file.",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=sorted(_LEVELS),
+        default="info",
+        help="Verbosity (default: info).",
+    )
+    parser.add_argument(
+        "--idle-timeout",
+        type=float,
+        default=service_module.DEFAULT_IDLE_TIMEOUT,
+        help="Seconds with no clients and no hubs before exiting. "
+        "Use 0 to run until stopped.",
+    )
+    return parser
+
+
+async def _watch_signals(service: service_module.Service) -> None:
+    """Turn termination signals into an orderly shutdown.
+
+    On Windows ``anyio.open_signal_receiver`` is unavailable, because the
+    proactor loop has no ``add_signal_handler``. A plain handler that pokes the
+    loop is used instead, and it needs nothing else to make it prompt: asyncio
+    sets the signal wakeup socket, so the byte written by the C-level handler
+    -- from the thread Windows spawns to deliver a console control event --
+    completes the loop's own overlapped read and the wait returns at once.
+    Measured on Windows 11 against a loop parked in ``sleep_forever``: the
+    handler ran 0.7 ms after the event was sent, with nothing else waking the
+    loop.
+    """
+
+    if sys.platform == "win32":
+        import asyncio
+
+        loop = asyncio.get_running_loop()
+        event = anyio.Event()
+
+        def handler(signum: int, frame: Any) -> None:
+            loop.call_soon_threadsafe(event.set)
+
+        previous = [
+            (sig, signal.signal(sig, handler))
+            for sig in (signal.SIGINT, signal.SIGBREAK)
+        ]
+
+        try:
+            await event.wait()
+            service.request_shutdown("signal")
+        finally:
+            for sig, old in previous:
+                signal.signal(sig, old)
+
+        return
+
+    with anyio.open_signal_receiver(signal.SIGINT, signal.SIGTERM) as signals:
+        async for _ in signals:
+            service.request_shutdown("signal")
+            return
+
+
+async def _serve(args: argparse.Namespace) -> int:
+    endpoint = ipc.resolve(args.endpoint)
+    service_module.log_banner(endpoint, __version__)
+
+    try:
+        async with service_module.run_service(
+            endpoint, idle_timeout=args.idle_timeout
+        ) as service:
+            async with anyio.create_task_group() as tg:
+                tg.start_soon(_watch_signals, service)
+                await service.wait_for_shutdown()
+                tg.cancel_scope.cancel()
+
+            logger.info("shutting down: %s", service.shutdown_reason)
+    except AddressInUseError:
+        # The common case is two clients racing to start a service. One wins,
+        # and both clients then connect to it, so this is not an error.
+        logger.info("another service is already listening on %s", endpoint)
+        return EXIT_ALREADY_RUNNING
+
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the service.
+
+    Args:
+        argv: Command line arguments, defaulting to ``sys.argv``.
+
+    Returns:
+        The process exit code.
+    """
+    args = _parser().parse_args(argv)
+    level = _LEVELS[args.log_level]
+
+    setup_logging(
+        level=level,
+        style="plain" if args.foreground else "file",
+        log_file=None if args.foreground else log_file(),
+    )
+
+    # The first thing written, before anything that could fail or block.
+    # A process that gets no further than here still leaves evidence that
+    # it existed, which is exactly what a leftover service with nothing in
+    # the log did not.
+    logger.info(
+        "pb-service starting (pid=%d, argv=%s)",
+        os.getpid(),
+        argv if argv is not None else sys.argv[1:],
+    )
+
+    try:
+        with lock.single_instance():
+            return anyio.run(_serve, args, backend="asyncio")
+    except lock.AlreadyRunningError:
+        logger.info("another service already holds the lock; exiting")
+        return EXIT_ALREADY_RUNNING
+    except Exception:
+        logger.exception("service failed")
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())