scirodev 0.1.0__py3-none-any.whl

sciro/__init__.py

@@ -0,0 +1,6 @@
+"""sciro -- PeakHub extensions to the Pybricks API.
+
+These are typing stubs (like the `pybricks` package): the real modules are frozen
+into the PeakHub firmware. Import from `sciro.parameters`, `sciro.iodevices` and
+`sciro.floorpro`.
+"""

sciro/_common.py

@@ -0,0 +1,31 @@
+"""Typing helpers for the sciro stubs, in the style of ``pybricks._common``:
+a value that is returned directly, or awaitable under multitasking. The
+upstream ``MaybeAwaitableTuple[T]`` is a 1-tuple, so fixed-shape results get
+their own classes here.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Tuple
+
+if TYPE_CHECKING:
+    from typing import Awaitable
+
+    _Line = Tuple[float, float, float, float, int, bool]
+    _Ints = Tuple[int, ...]
+    _IRCalib = Tuple[Tuple[int, ...], Tuple[int, ...], int, int]
+    _RGBC = Tuple[int, int, int, int, int]
+    _Euler = Tuple[float, float, float, int]
+    _StateData = Tuple[bytes, bytes]
+
+    class MaybeAwaitableLine(_Line, Awaitable[_Line]): ...
+
+    class MaybeAwaitableInts(_Ints, Awaitable[_Ints]): ...
+
+    class MaybeAwaitableIRCalib(_IRCalib, Awaitable[_IRCalib]): ...
+
+    class MaybeAwaitableRGBC(_RGBC, Awaitable[_RGBC]): ...
+
+    class MaybeAwaitableEuler(_Euler, Awaitable[_Euler]): ...
+
+    class MaybeAwaitableStateData(_StateData, Awaitable[_StateData]): ...

sciro/floorpro.py

@@ -0,0 +1,148 @@
+"""sciro.floorpro -- the LP-FloorPro line sensor over PUMP (PeakHub).
+
+Stub for the frozen module of the same name. Every reading method returns the
+value directly, or an awaitable under multitasking.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Tuple
+
+if TYPE_CHECKING:
+    from pybricks._common import MaybeAwaitable, MaybeAwaitableFloat
+
+    from ._common import (
+        MaybeAwaitableEuler,
+        MaybeAwaitableInts,
+        MaybeAwaitableIRCalib,
+        MaybeAwaitableLine,
+        MaybeAwaitableRGBC,
+    )
+
+from .iodevices import PUMPDevice, StreamInfo
+from .parameters import Port as _Port
+
+
+class _Stream:
+    dev: PUMPDevice
+    id: int
+
+    def subscribe(self, mode: int, rate: int = 0) -> MaybeAwaitable:
+        """subscribe(mode, rate=0)  -- see :meth:`PUMPDevice.subscribe`."""
+
+    def state(self) -> Optional[bytes]:
+        """state() -> bytes | None  -- the stream's current state prefix."""
+
+
+class Line(_Stream):
+    """IR array derived data (default: every sample, 400 Hz)."""
+
+    def read(self) -> MaybeAwaitableLine:
+        """read() -> Tuple
+
+        Returns ``(cog_dark, cog_bright, brightness, darkness, mask, calibrating)``:
+        centre of gravity of the dark / bright pixels in sensor pitches from the
+        middle sensor (-7 .. +7), overall brightness / darkness (0 .. 1), a
+        15-bit bright-pixel mask (bit i = sensor i), and whether calibration is
+        active.
+        """
+
+    def calibrate(self, enable: bool = True) -> MaybeAwaitable:
+        """calibrate(enable=True)  -- start/stop min-max calibration of the array."""
+
+
+class IRRaw(_Stream):
+    """15 raw 12-bit ADC readings. Off by default: use :meth:`oneshot` or subscribe."""
+
+    def read(self) -> MaybeAwaitableInts:
+        """read() -> Tuple[int, ...]  -- 15 values, 0 .. 4095, sensor 0 first."""
+
+    def oneshot(self) -> MaybeAwaitableInts:
+        """oneshot() -> Tuple[int, ...]  -- request one frame and return it."""
+
+
+class IRCalib(_Stream):
+    """Calibration table of the IR array. Off by default."""
+
+    def read(self) -> MaybeAwaitableIRCalib:
+        """read() -> Tuple
+
+        Returns ``(min, max, min_visited_mask, max_visited_mask)`` with ``min`` and
+        ``max`` tuples of 15 raw counts.
+        """
+
+    def oneshot(self) -> MaybeAwaitableIRCalib:
+        """oneshot() -> Tuple  -- request the table once and return it."""
+
+
+class ColorSensor(_Stream):
+    """TCS3400 on an extension port: raw R, G, B, C at device resolution.
+
+    Every sample is tagged with the settings it was measured under, so a read
+    after a settings change waits for the first sample taken with the new
+    settings.
+    """
+
+    def read(self) -> MaybeAwaitableRGBC:
+        """read() -> Tuple[int, int, int, int, int]  -- (red, green, blue, clear, status)."""
+
+    def settings(self) -> Tuple[int, int, int]:
+        """settings() -> Tuple[int, int, int]  -- (led_percent, gain_x, atime) in effect."""
+
+    def set_light(self, percent: int) -> MaybeAwaitable:
+        """set_light(percent)  -- illumination LED duty, 0 .. 100."""
+
+    def set_gain(self, gain_x: int) -> MaybeAwaitable:
+        """set_gain(gain_x)  -- analog gain: 1, 4, 16 or 64."""
+
+    def set_integration(self, atime: int) -> MaybeAwaitable:
+        """set_integration(atime)  -- TCS3400 ATIME register 0 .. 255: (256 - atime) * 2.78 ms."""
+
+
+class IMU(_Stream):
+    """BNO086 on an extension port: roll, pitch, yaw in degrees.
+
+    The heading offset lives on the hub: :meth:`reset_heading` makes the current
+    yaw read as the given angle.
+    """
+
+    def read(self) -> MaybeAwaitableEuler:
+        """read() -> Tuple  -- (roll, pitch, yaw, status), degrees; yaw includes the offset."""
+
+    def heading(self) -> MaybeAwaitableFloat:
+        """heading() -> float  -- yaw in degrees (-180 .. 180], with the offset applied."""
+
+    def reset_heading(self, angle: float = 0) -> MaybeAwaitable:
+        """reset_heading(angle=0)  -- make the current heading read as ``angle``."""
+
+
+class FloorPro:
+    """LP-FloorPro connected to a PeakHub port, speaking PUMP."""
+
+    dev: PUMPDevice
+    """The underlying generic device."""
+    serial: str
+    """The device's 8-character short ID."""
+    line: Line
+    ir_raw: IRRaw
+    ir_calib: IRCalib
+
+    def __init__(self, port: _Port):
+        """FloorPro(port)
+
+        Arguments:
+            port (Port): Port the sensor is connected to. Raises ``OSError`` if
+                no device is there or it is not a FloorPro.
+        """
+
+    def color_sensor(self, ext_port: int = 1) -> ColorSensor:
+        """color_sensor(ext_port=1) -> ColorSensor
+
+        The TCS3400 on extension port 1 or 2; raises ``OSError`` if none.
+        """
+
+    def imu(self, ext_port: int = 2) -> IMU:
+        """imu(ext_port=2) -> IMU  -- the BNO086 on extension port 1 or 2; raises ``OSError`` if none."""
+
+    def streams(self) -> Tuple[StreamInfo, ...]:
+        """streams() -> Tuple  -- the enumerated streams ``(id, url, ext_port, state_len)``."""

sciro/iodevices.py

@@ -0,0 +1,79 @@
+"""sciro.iodevices -- PeakHub-only device classes (re-exported from
+``pybricks.iodevices`` on the hub; declared here for the IDE).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, Optional, Tuple, Union
+
+if TYPE_CHECKING:
+    from pybricks._common import MaybeAwaitable
+
+    from ._common import MaybeAwaitableStateData
+
+from .parameters import Port as _Port
+
+# (stream id, url, ext_port, state length)
+StreamInfo = Tuple[int, str, int, int]
+
+
+class PUMPDevice:
+    """Generic access to a PUMP device (Power UART Multiplex Protocol) on a
+    PeakHub port. Streams are addressed by id (1..N); state and data are raw
+    ``bytes`` decoded by the user or a convenience class such as
+    :class:`sciro.floorpro.FloorPro`. Spec: ``PUMP-Protocol.md``.
+    """
+
+    OFF: int = 0
+    """Stream-control mode: stream is silent."""
+    ONESHOT: int = 1
+    """Stream-control mode: one frame, then the mode self-clears to OFF."""
+    ON_CHANGE: int = 2
+    """Stream-control mode: a frame whenever a new sample differs."""
+    PERIODIC: int = 3
+    """Stream-control mode: every sample (rate 0) or at the given rate."""
+
+    def __init__(self, port: _Port):
+        """PUMPDevice(port)
+
+        Arguments:
+            port (Port): Port the device is connected to. Raises ``OSError``
+                (``ENODEV``) if no PUMP device has completed its handshake there
+                within a few seconds.
+        """
+
+    def info(self) -> Dict[str, Union[str, Tuple[StreamInfo, ...]]]:
+        """info() -> Dict
+
+        Returns:
+            ``{"url": str, "serial": str, "streams": ((id, url, ext_port, state_len), ...)}``
+        """
+
+    def state(self, stream: int) -> Optional[bytes]:
+        """state(stream) -> bytes | None
+
+        The last state prefix echoed by the stream (first two bytes are the
+        stream-control word: mode, rate), or ``None`` if none was received yet.
+        """
+
+    def read(self, stream: int) -> MaybeAwaitableStateData:
+        """read(stream) -> Tuple[bytes, bytes]
+
+        Waits for a frame measured under the currently requested settings and
+        returns ``(state, data)``. Awaitable under multitasking.
+        """
+
+    def change_state(self, stream: int, state: bytes) -> MaybeAwaitable:
+        """change_state(stream, state)
+
+        Sets the stream's whole state prefix (must be exactly its length) and
+        waits until the device echoes it. Raises ``OSError`` (``ETIMEDOUT``) if
+        the device never acknowledges.
+        """
+
+    def subscribe(self, stream: int, mode: int, rate: int = 0) -> MaybeAwaitable:
+        """subscribe(stream, mode, rate=0)
+
+        Changes only the stream-control word (keeps the device-specific state
+        bytes). ``rate`` is in units of 10 Hz, 0 = every sample.
+        """

sciro/parameters.py

@@ -0,0 +1,30 @@
+"""sciro.parameters -- the Pybricks parameter types, with the PeakHub port set.
+
+On the hub this module re-exports ``pybricks.parameters`` unchanged (the firmware
+has always had ``Port.G`` and ``Port.H``); this stub exists because the upstream
+stubs declare ``Port.A`` .. ``Port.F`` only.
+"""
+
+from pybricks.parameters import (  # noqa: F401  (re-exports)
+    Axis as Axis,
+    Button as Button,
+    Color as Color,
+    Direction as Direction,
+    Icon as Icon,
+    Side as Side,
+    Stop as Stop,
+)
+from pybricks.parameters import _PybricksEnum
+
+
+class Port(_PybricksEnum):
+    """Port on the PeakHub. Eight LPF2/PUP ports, A .. H."""
+
+    A: Port = ord("A")
+    B: Port = ord("B")
+    C: Port = ord("C")
+    D: Port = ord("D")
+    E: Port = ord("E")
+    F: Port = ord("F")
+    G: Port = ord("G")
+    H: Port = ord("H")

scirodev/__init__.py

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

scirodev/cli.py

@@ -0,0 +1,17 @@
+"""`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()

scirodev-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: scirodev
+Version: 0.1.0
+Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
+Author: Thomas Schank
+License: MIT
+Project-URL: Homepage, https://github.com/sciurus-robotics/scirodev
+Project-URL: Repository, https://github.com/sciurus-robotics/scirodev
+Keywords: pybricks,lego,peakhub,micropython,stubs
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pybricksdev>=2.3
+Requires-Dist: pybricks>=3.6
+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`).
+
+```
+pip install scirodev                                    # from PyPI
+pip install "scirodev @ git+https://github.com/sciurus-robotics/scirodev.git@v0.1.0"
+pipx install scirodev                                   # just the CLI, in its own venv
+```
+
+Hacking on it:
+
+```
+pip install -e .
+```
+
+Then your IDE/type checker knows these, which the upstream `pybricks` stubs don't:
+
+```python
+from sciro.parameters import Port          # Port.A .. Port.H (PeakHub has 8 ports)
+from sciro.iodevices import PUMPDevice     # generic PUMP device access
+from sciro.floorpro import FloorPro        # LP-FloorPro convenience class
+
+fp = FloorPro(Port.G)
+cog_dark, cog_bright, brightness, darkness, mask, calibrating = fp.line.read()
+```
+
+On the hub these modules are frozen into the PeakHub firmware:
+`sciro.parameters` and `sciro.iodevices` re-export the same runtime objects as
+their `pybricks.*` counterparts, so `sciro.parameters.Port is
+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.
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, commit, tag `vX.Y.Z` and push the tag. The
+GitHub workflow builds, type-checks and publishes to PyPI via Trusted Publishing
+(configured on pypi.org: owner `sciurus-robotics`, repo `scirodev`, workflow
+`publish.yml`, environment `pypi`).

scirodev-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sciro/__init__.py,sha256=auvDdSvjOd3FXLu8XV0mOGyahF06zkmfkGEj7US783o,238
+sciro/_common.py,sha256=g2e5p1jEZ4Z1s2EtyL2sOY6cau1r4xbtZI1RKXQDTZk,1046
+sciro/floorpro.py,sha256=fRj6IycPNEzYCp2BlYJ2rdZipKUGjO8n-9wdEXUOlo8,5005
+sciro/iodevices.py,sha256=H_iE44JkJwzYR41BVylG8wJ8mR4a72pcQKBdbAbJp7g,2787
+sciro/parameters.py,sha256=POB0G5i5bsmXDLoKkjZ_M14xLT_3GyaidpzRQrhHLqk,821
+sciro/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scirodev/__init__.py,sha256=PigYDhaDY9FpENpagsmRhOKNt7suuiLz__kHrf-WHJw,107
+scirodev/cli.py,sha256=EedyRghlMPpNQ4qA0E9pIDK_tNBdfwf7sRBIiaNuO1s,405
+scirodev-0.1.0.dist-info/licenses/LICENSE,sha256=5eMIVXEq0VbDVA3Y9p3IXJemflDENP4sQA2eSx_PNgI,1088
+scirodev-0.1.0.dist-info/METADATA,sha256=q1Ox66tdgnC05FpLNsqclwWRclZpKtLWojNqHhRM_4A,2407
+scirodev-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+scirodev-0.1.0.dist-info/entry_points.txt,sha256=G0501dWnjtPC7Bjp0jzKPlNXKS63Q1rD8acTcrw-AGI,47
+scirodev-0.1.0.dist-info/top_level.txt,sha256=jwUBs_F6VA_ZrXFXxuZGG4rKLSaGoTUjsHZejBvrY8U,15
+scirodev-0.1.0.dist-info/RECORD,,

scirodev-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scirodev-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scirodev = scirodev.cli:main

scirodev-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sciurus Robotics, Thomas Schank
+
+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.

scirodev-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+sciro
+scirodev