scirodev 0.5.5__tar.gz → 0.7.3__tar.gz

{scirodev-0.5.5/scirodev.egg-info → scirodev-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.5.5
+Version: 0.7.3
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -23,9 +23,14 @@ Dynamic: license-file
 
 # scirodev
 
-Host-side companion to the PeakHub firmware: **typed API stubs** for the `sciro`
-namespace that PeakHub programs import, plus the hub tooling (it depends on
-`pybricksdev`, so `scirodev run ble prog.py` works exactly like `pybricksdev`).
+Host-side companion to Sciurus Robotics hubs (PeakHub so far): **typed API
+stubs** for the `sciro` namespace that PeakHub programs import, plus the
+`scirodev` command line tool.
+
+The tool is built on `pybricksdev`. It offers pybricksdev's own tools
+unchanged (`scirodev run ble prog.py` works exactly like `pybricksdev run`),
+and adds tools that only exist for sciro hubs, such as `scirodev rename`.
+`scirodev -h` lists both and marks which is which.
 
 ```
 pip install scirodev                                    # from PyPI
@@ -46,6 +51,7 @@ from sciro.parameters import Port          # Port.A .. Port.H (PeakHub has 8 por
 from sciro.iodevices import PUMPDevice     # generic PUMP device access
 from sciro.pump import FloorPro        # PUMP devices (LP-FloorPro, ...)
 from sciro.hubs import PeakHub             # hub class incl. display.device()
+from sciro.canbus import CAN               # beta: raw classic-CAN frames on connector 1/2
 from sciro.tools import RingBuffer         # experimental: RAM recorder -> CSV file via the console
 from sciro.robotics import PIDController   # experimental: PID with optional logging
 
@@ -92,6 +98,30 @@ pybricks.parameters.Port` — the stubs only add what the IDE is missing. The
 stub files here mirror the frozen modules; a release of this package matches
 the PeakHub firmware of the same date.
 
+## Hub names
+
+Every PeakHub advertises under its own name, `Peak-XXXX` out of the box (the
+first four characters of its board ID), so several hubs on one table can be
+told apart:
+
+```
+scirodev run ble --name Peak-BYN9 prog.py
+```
+
+Give a hub a name of your choice (1 to 16 printable ASCII characters); it is
+stored on the hub and survives power cycles and firmware updates:
+
+```
+scirodev rename usb MyRobot               # over USB: applied at once
+scirodev rename ble MyRobot -n Peak-BYN9  # over Bluetooth: confirm on the hub
+scirodev rename usb --default             # back to Peak-XXXX
+```
+
+Over Bluetooth the hub spells the new name on its display, then shows `?`.
+Press the centre button to accept; any other button, or 10 seconds without
+one, rejects. This keeps somebody else in radio range from renaming your hub.
+`hub.system.name()` returns the name.
+
 ## API reference (HTML)
 
 The stubs double as the source of the API reference, built with Sphinx the way

{scirodev-0.5.5 → scirodev-0.7.3}/README.md

@@ -1,8 +1,13 @@
 # scirodev
 
-Host-side companion to the PeakHub firmware: **typed API stubs** for the `sciro`
-namespace that PeakHub programs import, plus the hub tooling (it depends on
-`pybricksdev`, so `scirodev run ble prog.py` works exactly like `pybricksdev`).
+Host-side companion to Sciurus Robotics hubs (PeakHub so far): **typed API
+stubs** for the `sciro` namespace that PeakHub programs import, plus the
+`scirodev` command line tool.
+
+The tool is built on `pybricksdev`. It offers pybricksdev's own tools
+unchanged (`scirodev run ble prog.py` works exactly like `pybricksdev run`),
+and adds tools that only exist for sciro hubs, such as `scirodev rename`.
+`scirodev -h` lists both and marks which is which.
 
 ```
 pip install scirodev                                    # from PyPI
@@ -23,6 +28,7 @@ from sciro.parameters import Port          # Port.A .. Port.H (PeakHub has 8 por
 from sciro.iodevices import PUMPDevice     # generic PUMP device access
 from sciro.pump import FloorPro        # PUMP devices (LP-FloorPro, ...)
 from sciro.hubs import PeakHub             # hub class incl. display.device()
+from sciro.canbus import CAN               # beta: raw classic-CAN frames on connector 1/2
 from sciro.tools import RingBuffer         # experimental: RAM recorder -> CSV file via the console
 from sciro.robotics import PIDController   # experimental: PID with optional logging
 
@@ -69,6 +75,30 @@ pybricks.parameters.Port` — the stubs only add what the IDE is missing. The
 stub files here mirror the frozen modules; a release of this package matches
 the PeakHub firmware of the same date.
 
+## Hub names
+
+Every PeakHub advertises under its own name, `Peak-XXXX` out of the box (the
+first four characters of its board ID), so several hubs on one table can be
+told apart:
+
+```
+scirodev run ble --name Peak-BYN9 prog.py
+```
+
+Give a hub a name of your choice (1 to 16 printable ASCII characters); it is
+stored on the hub and survives power cycles and firmware updates:
+
+```
+scirodev rename usb MyRobot               # over USB: applied at once
+scirodev rename ble MyRobot -n Peak-BYN9  # over Bluetooth: confirm on the hub
+scirodev rename usb --default             # back to Peak-XXXX
+```
+
+Over Bluetooth the hub spells the new name on its display, then shows `?`.
+Press the centre button to accept; any other button, or 10 seconds without
+one, rejects. This keeps somebody else in radio range from renaming your hub.
+`hub.system.name()` returns the name.
+
 ## API reference (HTML)
 
 The stubs double as the source of the API reference, built with Sphinx the way

{scirodev-0.5.5 → scirodev-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scirodev"
-version = "0.5.5"
+version = "0.7.3"
 description = "PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev"
 readme = "README.md"
 requires-python = ">=3.10"

{scirodev-0.5.5 → scirodev-0.7.3}/sciro/_common.py

@@ -21,6 +21,7 @@ if TYPE_CHECKING:
     _Calibration = Tuple[Tuple[int, int, int, int], Tuple[int, int, int, int], Tuple[int, int, int], bool, bool, int]
     _Pixels = Tuple[_RGB, ...]
     _Bools = Tuple[bool, ...]
+    _Frame = Tuple[int, bytes, bool]
 
     class MaybeAwaitableLine(_Line, Awaitable[_Line]): ...
 
@@ -43,3 +44,5 @@ if TYPE_CHECKING:
     class MaybeAwaitableStr(str, Awaitable[str]): ...
 
     class MaybeAwaitableBools(_Bools, Awaitable[_Bools]): ...
+
+    class MaybeAwaitableFrame(_Frame, Awaitable[_Frame]): ...

scirodev-0.7.3/sciro/canbus.py

@@ -0,0 +1,86 @@
+"""sciro.canbus -- the PeakHub CAN connectors (beta).
+
+Classic CAN (11/29-bit identifiers, up to 8 data bytes) on CAN connector 1 or 2.
+Both transceivers are powered while a program holds a ``CAN`` object and are
+switched off when the program ends.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
+
+if TYPE_CHECKING:
+    from pybricks._common import MaybeAwaitable
+
+    from ._common import MaybeAwaitableFrame
+
+Frame = Tuple[int, bytes, bool]
+"""A received frame: ``(id, data, extended)``."""
+
+
+class CAN:
+    """One of the hub's CAN connectors."""
+
+    def __init__(self, bus: int, bitrate: int = 500000):
+        """CAN(bus, bitrate=500000)
+
+        Arguments:
+            bus (int): Connector number, 1 or 2.
+            bitrate (int): Bits per second: 125000, 250000, 500000 or 1000000.
+                Raises ``OSError`` (``ENOTSUP``) on a board whose CAN
+                transceivers must stay off.
+        """
+
+    def bitrate(self, bitrate: Optional[int] = None) -> Optional[int]:
+        """bitrate() -> int
+        bitrate(bitrate)
+
+        Gets or sets the bit rate. Setting it restarts the controller: frames
+        waiting to be sent are dropped, received frames are kept.
+        """
+
+    def send(self, id: int, data: bytes = b"", extended: bool = False, timeout: Optional[int] = 100) -> MaybeAwaitable:
+        """send(id, data=b"", extended=False, timeout=100)
+
+        Queues one frame. Waits up to ``timeout`` ms for room in the transmit
+        queue (it only fills when nobody on the bus acknowledges) and raises
+        ``OSError`` (``ETIMEDOUT``) after that.
+
+        Arguments:
+            id (int): Identifier, 11 bits or 29 bits with ``extended=True``.
+            data (bytes): 0 to 8 bytes.
+            extended (bool): Use a 29-bit identifier.
+            timeout (int): Milliseconds, ``None`` to wait forever.
+        """
+
+    def recv(self, timeout: Optional[int] = 1000) -> Optional[MaybeAwaitableFrame]:
+        """recv(timeout=1000) -> Tuple[int, bytes, bool] | None
+
+        Takes the oldest received frame as ``(id, data, extended)``, or ``None``
+        when nothing arrived within ``timeout`` ms (``None`` = wait forever,
+        ``0`` = just poll). Under multitasking ``await`` the result; it is then
+        never ``None`` at the call site, so narrow the type (e.g. ``assert``).
+        """
+
+    def pending(self) -> int:
+        """pending() -> int
+
+        Number of received frames waiting (up to 32 are queued; beyond that,
+        frames are counted as lost).
+        """
+
+    def clear(self) -> None:
+        """clear()
+
+        Drops the queued received frames and zeroes the counters.
+        """
+
+    def stats(self) -> Dict[str, Union[int, bool]]:
+        """stats() -> Dict
+
+        Counters and controller state: ``tx_queued``, ``tx_done`` (acknowledged
+        on the bus), ``rx``, ``rx_lost``, ``bus_off_count``, ``tec``, ``rec``
+        (CAN error counters), ``lec`` (last error code, 0 none, 1 stuff, 2 form,
+        3 ack, 4 bit1, 5 bit0, 6 crc, 7 unchanged), ``warning``, ``passive``,
+        ``bus_off``.
+        """

{scirodev-0.5.5 → scirodev-0.7.3}/sciro/hubs.py

@@ -1,12 +1,13 @@
 """sciro.hubs -- the PeakHub.
 
 On the hub this module re-exports ``pybricks.hubs`` unchanged; the stub adds what
-the upstream stubs lack: the ``PeakHub`` class and its ``display.device()``.
+the upstream stubs lack: the ``PeakHub`` class, its ``display.device()``, and the
+``ThisHub`` alias.
 """
 
 from __future__ import annotations
 
-from typing import Any, Optional, Protocol, Tuple
+from typing import Any, Dict, Optional, Protocol, Tuple, Union
 
 from pybricks import _common
 from pybricks.hubs import PrimeHub as PrimeHub  # noqa: F401  (re-export)
@@ -121,6 +122,68 @@ class Battery(_common.Battery):
         """
 
 
+class UsbPd:
+    """**Experimental.** The hub's USB-PD input.
+
+    Reached as :attr:`PeakHub.usb_pd`. Lets a program read the measured input
+    voltage and ask the USB-PD sink to renegotiate to a different one.
+    """
+
+    def voltage(self, volts: Optional[int] = None) -> Optional[int]:
+        """voltage(volts=None) -> int
+
+        Without an argument, returns the **measured** USB-PD input voltage in
+        millivolts. The sense sits before the ideal diode, so it reads the
+        supply itself and is not masked by a connected battery. Returns 0 if
+        the ADC has not sampled yet (only in the first few ms after boot).
+
+        With an argument, asks the sink to renegotiate to that voltage.
+
+        Arguments:
+            volts (int): 5, 9, 12 or 15. Any other value raises ``ValueError``.
+
+        Returns:
+            The measured voltage in mV when called with no argument,
+            otherwise ``None``.
+
+        .. warning::
+
+            **Experimental, and it is a request rather than a command.**
+
+            A supply that does not offer the requested voltage simply refuses.
+            Nothing is raised in that case and the hub stays where it was, so
+            **read the voltage back** to see what actually happened rather than
+            assuming the call took effect.
+
+            Higher PD gears (20 V, 28 V) are deliberately unreachable: the
+            hub's voltage sense saturates at 18.81 V, so the firmware could not
+            even measure what it had asked for.
+
+        Renegotiating itself is well behaved in practice: measured working even
+        while driving motors on a small (2x18650-class) power bank, and on a
+        bench supply switching 9 V to 12 V and back with the hub up throughout.
+
+        Some power banks that were already switched on when the cable went
+        in feed plain 5 V first and then cycle VBUS by themselves a few seconds
+        later to start PD; a hub running from USB alone restarts at 9 V then.
+        That is the bank's doing, not the request's. Switching such a bank off
+        and on before pressing PWR avoids it.
+        """
+
+    def status(self) -> Dict[str, Union[bool, int]]:
+        """status() -> Dict
+
+        What the USB-PD sink negotiated with the supply:
+        ``{"pd": bool, "bc": bool, "qc2": bool, "qc3": bool, "epr": bool,
+        "max_ma": int, "raw": int, "mv": int}``. ``pd`` is ``True`` under a PD
+        contract (the normal 9 V case). ``max_ma`` is the contract's current
+        limit (0 without PD), ``raw`` the sink's status register, ``mv`` the
+        measured input voltage.
+
+        Diagnostic: lets a program see whether a contract exists at all.
+        """
+
+
 class PeakHub:
     """LEGO-compatible hub by Sciurus Robotics: 8 ports, 5x5 RGB matrix, IMU."""
 
@@ -134,6 +197,7 @@ class PeakHub:
     imu = _common.IMU()
     speaker = _common.Speaker()
     system = System()
+    usb_pd = UsbPd()
 
     def __init__(
         self,
@@ -150,3 +214,32 @@ class PeakHub:
             broadcast_channel: Channel for broadcasting data (0 .. 255).
             observe_channels: Channels to observe.
         """
+
+
+#: The hub this program is running on.
+#:
+#: Every Pybricks firmware compiles in exactly one hub class and exports it
+#: under several names: the generic ``ThisHub``, the hub's own name, and any
+#: aliases. On PeakHub firmware ``ThisHub``, :class:`PeakHub`, ``PrimeHub`` and
+#: ``InventorHub`` are therefore all the *same* class object -- this is resolved
+#: when the firmware is built, not by detecting anything at run time.
+#:
+#: Use it for code that should run unchanged on whichever hub is in front of
+#: you, which is mostly bench and test scripts::
+#:
+#:     from sciro.hubs import ThisHub
+#:
+#:     hub = ThisHub()
+#:     print(hub.imu.heading(), hub.imu.tilt())
+#:
+#: Prefer :class:`PeakHub` when a program is specific to this hub anyway: it
+#: says so, and it reads better than a generic name.
+#:
+#: Note the difference between the REPL and a downloaded program. The REPL is
+#: started with everything auto-imported and with a ready-made ``hub`` instance
+#: already created, so there ``hub.imu.heading()`` just works. A downloaded
+#: program gets neither: it must import what it uses and construct the hub, as
+#: above, and ``print(hub)`` there raises ``NameError``. (In the firmware this
+#: is ``pb_package_pybricks_init(true)`` for the REPL versus ``false`` for
+#: everything else.)
+ThisHub = PeakHub

scirodev-0.7.3/scirodev/__init__.py

@@ -0,0 +1,8 @@
+"""scirodev -- tooling for Sciurus Robotics hubs on top of pybricksdev, and the `sciro` API stubs."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("scirodev")
+except PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0+unknown"

scirodev-0.7.3/scirodev/cli.py

@@ -0,0 +1,146 @@
+"""`scirodev` command line.
+
+One tool for Sciurus Robotics hubs (PeakHub so far). It is built on
+pybricksdev: pybricksdev's own tools (run, compile, flash, ...) are offered
+unchanged, next to the tools that only exist for sciro hubs (rename).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from . import __version__
+
+DESCRIPTION = """\
+Command line tool for Sciurus Robotics hubs (PeakHub).
+
+Built on pybricksdev. Tools marked [pybricksdev] are pybricksdev's own,
+unchanged, and work with any hub running Pybricks firmware. The other tools
+are extensions for sciro hubs.
+"""
+
+EPILOG = """\
+Run `%(prog)s <tool> --help` for tool-specific arguments.
+
+Examples:
+  %(prog)s run ble --name Peak-BYN9 program.py
+  %(prog)s rename ble MyRobot --name Peak-BYN9
+"""
+
+# pybricksdev tools to offer, by class name. Looked up by name so a pybricksdev
+# release that adds or drops one does not break us.
+PYBRICKSDEV_TOOLS = ("Compile", "Run", "Flash", "DFU", "OAD", "LWP3", "Udev")
+
+
+def _pybricksdev_version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("pybricksdev")
+    except PackageNotFoundError:
+        return "?"
+
+
+def build_parser() -> tuple[argparse.ArgumentParser, argparse._SubParsersAction]:
+    import pybricksdev.cli as pbcli
+
+    from .rename import Rename
+
+    parser = argparse.ArgumentParser(
+        prog="scirodev",
+        description=DESCRIPTION,
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"scirodev v{__version__} (pybricksdev v{_pybricksdev_version()})",
+    )
+    parser.add_argument("-d", "--debug", action="store_true", help="enable debug logging")
+
+    subparsers = parser.add_subparsers(metavar="<tool>", dest="tool", help="the tool to use")
+
+    # Our own tools first.
+    for tool in (Rename(),):
+        tool.add_parser(subparsers)
+    own = len(subparsers._choices_actions)
+
+    for name in PYBRICKSDEV_TOOLS:
+        cls = getattr(pbcli, name, None)
+        if cls is not None:
+            cls().add_parser(subparsers)
+
+    # Mark what comes from pybricksdev in the tool list.
+    for action in subparsers._choices_actions[own:]:
+        action.help = f"{action.help or ''} [pybricksdev]".strip()
+
+    return parser, subparsers
+
+
+def pairing_hint(error: str) -> str | None:
+    """Plain words for the Bluetooth errors a PIN-protected hub can cause."""
+    e = error.lower()
+    if "peer removed pairing information" in e:
+        return (
+            "This computer was paired with the hub, but the hub no longer knows it\n"
+            "(its PIN was set or changed). Make the computer forget the hub in its\n"
+            "Bluetooth settings, then run the command again and enter the hub's PIN."
+        )
+    if "authentication" in e or "encryption is insufficient" in e or "pairing" in e:
+        return (
+            "The hub is protected with a PIN. Enter it in the dialog of your operating\n"
+            "system when it appears; if the command gave up meanwhile, run it again.\n"
+            "After 3 wrong PINs the hub refuses new computers until its Bluetooth\n"
+            "button is switched off and on."
+        )
+    return None
+
+
+def main() -> None:
+    if sys.platform == "win32":
+        # Same workaround as pybricksdev: bad side effects of pythoncom.
+        try:
+            from bleak_winrt._winrt import MTA, init_apartment
+        except ImportError:
+            from winrt._winrt import MTA, init_apartment
+
+        init_apartment(MTA)
+
+    parser, subparsers = build_parser()
+
+    try:
+        import argcomplete
+
+        argcomplete.autocomplete(parser)
+    except ImportError:
+        pass
+
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        format="%(asctime)s: %(levelname)s: %(name)s: %(message)s",
+        level=logging.DEBUG if args.debug else logging.WARNING,
+    )
+
+    if not args.tool:
+        parser.error(f'Missing name of tool: {"|".join(subparsers.choices.keys())}')
+
+    try:
+        result = asyncio.run(subparsers.choices[args.tool].tool.run(args))
+    except Exception as e:
+        hint = pairing_hint(str(e))
+        if hint is None or args.debug:
+            raise
+        print(f"error: {e}\n\n{hint}", file=sys.stderr)
+        sys.exit(1)
+    if isinstance(result, int) and result:
+        sys.exit(result)
+
+
+if __name__ == "__main__":
+    main()

scirodev-0.7.3/scirodev/rename.py

@@ -0,0 +1,112 @@
+"""`scirodev rename`: give a PeakHub a name of its own (see DESCRIPTION)."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+# PeakHub extension of the Pybricks command set (PBIO_PYBRICKS_COMMAND_SET_HUB_NAME).
+SET_HUB_NAME = 0xA0
+NAME_MAX = 16
+
+
+def check_name(name: str) -> str:
+    if name == "":
+        return name
+    if len(name) > NAME_MAX:
+        raise argparse.ArgumentTypeError(f"at most {NAME_MAX} characters")
+    if any(not (0x20 <= ord(c) <= 0x7E) for c in name):
+        raise argparse.ArgumentTypeError("printable ASCII characters only")
+    if name != name.strip():
+        raise argparse.ArgumentTypeError("no leading or trailing spaces")
+    return name
+
+
+DESCRIPTION = """\
+Give a PeakHub a name of its own.
+
+The name is what the hub advertises over Bluetooth (so `scirodev run ble
+--name <name>` finds exactly this hub) and what hub.system.name() returns. It
+is stored on the hub across power cycles and firmware updates.
+
+Over USB the hub takes the name at once. Over Bluetooth, where anybody in
+range could send the command, the hub spells the new name on its display,
+shows `?` and applies it only when the centre button is pressed (any other
+button, or 10 s without one, rejects it). The hub must be idle: no program
+running, not in power-save.
+"""
+
+
+class Rename:
+    """The `rename` tool (same shape as pybricksdev's Tool classes)."""
+
+    def add_parser(self, subparsers: argparse._SubParsersAction) -> None:
+        p = subparsers.add_parser(
+            "rename",
+            help="set the name a PeakHub advertises under",
+            description=DESCRIPTION,
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        p.tool = self
+        self.parser = p
+        p.add_argument("conntype", choices=["ble", "usb"], help="how to reach the hub")
+        p.add_argument(
+            "new_name",
+            type=check_name,
+            nargs="?",
+            help=f"the new name: 1 to {NAME_MAX} printable ASCII characters",
+        )
+        p.add_argument("--default", action="store_true", help="go back to the default name (Peak-XXXX)")
+        p.add_argument("-n", "--name", help="current name of the hub to rename (ble; default: first hub found)")
+
+    async def run(self, args: argparse.Namespace) -> int:
+        if args.default == (args.new_name is not None):
+            self.parser.error("give either a new name or --default")
+        if args.default:
+            args.new_name = ""
+        elif args.new_name == "":
+            self.parser.error("the name must not be empty (use --default for the default name)")
+        return await rename(args)
+
+
+async def rename(args: argparse.Namespace) -> int:
+    from pybricksdev.ble.pybricks import PYBRICKS_COMMAND_EVENT_UUID
+
+    if args.conntype == "ble":
+        from pybricksdev.ble import find_device
+        from pybricksdev.connections.pybricks import PybricksHubBLE
+
+        print(f"Searching for {args.name or 'any hub with Pybricks service'}...")
+        hub = PybricksHubBLE(await find_device(args.name))
+    else:
+        from usb.core import find as find_usb
+
+        from pybricksdev.connections.pybricks import PybricksHubUSB
+        from pybricksdev.usb import LEGO_USB_VID
+
+        device = find_usb(custom_match=lambda d: d.idVendor == LEGO_USB_VID and d.product.endswith("Pybricks"))
+        if device is None:
+            print("Pybricks Hub not found.", file=sys.stderr)
+            return 1
+        hub = PybricksHubUSB(device)
+
+    shown = args.new_name or "the default name"
+    await hub.connect()
+    try:
+        await hub.write_gatt_char(
+            PYBRICKS_COMMAND_EVENT_UUID,
+            bytes([SET_HUB_NAME]) + args.new_name.encode("ascii"),
+            True,
+        )
+        if args.conntype == "ble":
+            print(f"The hub now shows the new name ({shown}) and then '?'.")
+            print("Press the centre button on the hub to accept. Any other button, or 10 s, rejects.")
+            # Stay connected while the user decides, so nobody else can slip in.
+            await asyncio.sleep(len(args.new_name) * 0.6 + 10.5)
+            print("Done. If accepted, the hub advertises under the new name from the next connection on.")
+        else:
+            print(f"Renamed to {shown}.")
+    finally:
+        await hub.disconnect()
+    return 0

{scirodev-0.5.5 → scirodev-0.7.3/scirodev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.5.5
+Version: 0.7.3
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -23,9 +23,14 @@ Dynamic: license-file
 
 # scirodev
 
-Host-side companion to the PeakHub firmware: **typed API stubs** for the `sciro`
-namespace that PeakHub programs import, plus the hub tooling (it depends on
-`pybricksdev`, so `scirodev run ble prog.py` works exactly like `pybricksdev`).
+Host-side companion to Sciurus Robotics hubs (PeakHub so far): **typed API
+stubs** for the `sciro` namespace that PeakHub programs import, plus the
+`scirodev` command line tool.
+
+The tool is built on `pybricksdev`. It offers pybricksdev's own tools
+unchanged (`scirodev run ble prog.py` works exactly like `pybricksdev run`),
+and adds tools that only exist for sciro hubs, such as `scirodev rename`.
+`scirodev -h` lists both and marks which is which.
 
 ```
 pip install scirodev                                    # from PyPI
@@ -46,6 +51,7 @@ from sciro.parameters import Port          # Port.A .. Port.H (PeakHub has 8 por
 from sciro.iodevices import PUMPDevice     # generic PUMP device access
 from sciro.pump import FloorPro        # PUMP devices (LP-FloorPro, ...)
 from sciro.hubs import PeakHub             # hub class incl. display.device()
+from sciro.canbus import CAN               # beta: raw classic-CAN frames on connector 1/2
 from sciro.tools import RingBuffer         # experimental: RAM recorder -> CSV file via the console
 from sciro.robotics import PIDController   # experimental: PID with optional logging
 
@@ -92,6 +98,30 @@ pybricks.parameters.Port` — the stubs only add what the IDE is missing. The
 stub files here mirror the frozen modules; a release of this package matches
 the PeakHub firmware of the same date.
 
+## Hub names
+
+Every PeakHub advertises under its own name, `Peak-XXXX` out of the box (the
+first four characters of its board ID), so several hubs on one table can be
+told apart:
+
+```
+scirodev run ble --name Peak-BYN9 prog.py
+```
+
+Give a hub a name of your choice (1 to 16 printable ASCII characters); it is
+stored on the hub and survives power cycles and firmware updates:
+
+```
+scirodev rename usb MyRobot               # over USB: applied at once
+scirodev rename ble MyRobot -n Peak-BYN9  # over Bluetooth: confirm on the hub
+scirodev rename usb --default             # back to Peak-XXXX
+```
+
+Over Bluetooth the hub spells the new name on its display, then shows `?`.
+Press the centre button to accept; any other button, or 10 seconds without
+one, rejects. This keeps somebody else in radio range from renaming your hub.
+`hub.system.name()` returns the name.
+
 ## API reference (HTML)
 
 The stubs double as the source of the API reference, built with Sphinx the way

{scirodev-0.5.5 → scirodev-0.7.3}/scirodev.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 sciro/__init__.py
 sciro/_common.py
+sciro/canbus.py
 sciro/floorpro.py
 sciro/hubs.py
 sciro/iodevices.py
@@ -13,6 +14,7 @@ sciro/robotics.py
 sciro/tools.py
 scirodev/__init__.py
 scirodev/cli.py
+scirodev/rename.py
 scirodev.egg-info/PKG-INFO
 scirodev.egg-info/SOURCES.txt
 scirodev.egg-info/dependency_links.txt

scirodev-0.5.5/scirodev/__init__.py

@@ -1,3 +0,0 @@
-"""scirodev -- PeakHub tooling on top of pybricksdev, and the `sciro` API stubs."""
-
-__version__ = "0.1.0"

scirodev-0.5.5/scirodev/cli.py

@@ -1,17 +0,0 @@
-"""`scirodev` command line: pybricksdev's CLI (run, download, flash, ...) under
-our name, so one tool covers PeakHub as well. PeakHub-specific commands can be
-added here later; everything else is forwarded unchanged.
-"""
-
-import sys
-
-
-def main() -> None:
-    from pybricksdev.cli import main as pybricksdev_main
-
-    sys.argv[0] = "scirodev"
-    pybricksdev_main()
-
-
-if __name__ == "__main__":
-    main()