scirodev 0.2.1__tar.gz → 0.3.1__tar.gz

{scirodev-0.2.1/scirodev.egg-info → scirodev-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.2.1
+Version: 0.3.1
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -41,7 +41,7 @@ Then your IDE/type checker knows these, which the upstream `pybricks` stubs don'
 ```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
+from sciro.pump import FloorPro        # PUMP devices (LP-FloorPro, ...)
 from sciro.hubs import PeakHub             # hub class incl. display.device()
 
 hub = PeakHub()
@@ -50,6 +50,10 @@ cog_dark, cog_bright, brightness, darkness, mask, calibrating = fp.line.read()
 hub.display.device(fp, brightness=50)      # mirror the sensor's LED strip on the 5x5
 ```
 
+Full demo programs for the LP FloorPro (both for LEGO hubs and the PeakHub) live in
+[sciurus-robotics/FloorPro-CodeDemos](https://github.com/sciurus-robotics/FloorPro-CodeDemos);
+`examples/` here stays minimal.
+
 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

{scirodev-0.2.1 → scirodev-0.3.1}/README.md

@@ -21,7 +21,7 @@ Then your IDE/type checker knows these, which the upstream `pybricks` stubs don'
 ```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
+from sciro.pump import FloorPro        # PUMP devices (LP-FloorPro, ...)
 from sciro.hubs import PeakHub             # hub class incl. display.device()
 
 hub = PeakHub()
@@ -30,6 +30,10 @@ cog_dark, cog_bright, brightness, darkness, mask, calibrating = fp.line.read()
 hub.display.device(fp, brightness=50)      # mirror the sensor's LED strip on the 5x5
 ```
 
+Full demo programs for the LP FloorPro (both for LEGO hubs and the PeakHub) live in
+[sciurus-robotics/FloorPro-CodeDemos](https://github.com/sciurus-robotics/FloorPro-CodeDemos);
+`examples/` here stays minimal.
+
 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

{scirodev-0.2.1 → scirodev-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scirodev"
-version = "0.2.1"
+version = "0.3.1"
 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.2.1 → scirodev-0.3.1}/sciro/__init__.py

@@ -2,5 +2,5 @@
 
 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.pump`.
 """

scirodev-0.3.1/sciro/floorpro.py

@@ -0,0 +1,13 @@
+"""sciro.floorpro -- deprecated alias of :mod:`sciro.pump` (where the FloorPro
+class lives now). Kept so older programs keep type-checking.
+"""
+
+from .pump import (  # noqa: F401  (re-exports)
+    IMU as IMU,
+    ColorSensor as ColorSensor,
+    FloorPro as FloorPro,
+    IRCalib as IRCalib,
+    IRRaw as IRRaw,
+    Line as Line,
+    Pixels as Pixels,
+)

{scirodev-0.2.1 → scirodev-0.3.1}/sciro/hubs.py

@@ -38,7 +38,7 @@ class LightMatrix(_common.LightMatrix):
         the program ends.
 
         Arguments:
-            device (FloorPro): The device to mirror.
+            device (FloorPro): The device to mirror (any ``sciro.pump`` device with a display stream).
             brightness (Number, %): Brightness of the mirrored pixels, 0 .. 1000.
                 Above 100 the picture is amplified (clipping at full), since
                 the matrix is far dimmer than a sensor's own LED strip.

{scirodev-0.2.1 → scirodev-0.3.1}/sciro/iodevices.py

@@ -21,7 +21,7 @@ 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``.
+    :class:`sciro.pump.FloorPro`. Spec: ``PUMP-Protocol.md``.
     """
 
     OFF: int = 0
@@ -49,6 +49,15 @@ class PUMPDevice:
             ``{"url": str, "serial": str, "streams": ((id, url, ext_port, state_len), ...)}``
         """
 
+    def stats(self) -> Dict[str, Union[int, Tuple[Tuple[int, int, int], ...]]]:
+        """stats() -> Dict
+
+        Link counters since the session started, for load tests and diagnostics:
+        ``{"frames": good frames received, "crc_errors", "cobs_errors",
+        "short_frames", "overflows", "streams": ((id, frames, gaps), ...)}``
+        where ``gaps`` counts frames of that stream the hub never received.
+        """
+
     def state(self, stream: int) -> Optional[bytes]:
         """state(stream) -> bytes | None
 
@@ -75,5 +84,6 @@ class PUMPDevice:
         """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.
+        bytes). ``rate`` is in Hz (1 .. 255; higher values are clamped to 255),
+        0 = every sample.
         """

{scirodev-0.2.1 → scirodev-0.3.1}/sciro/parameters.py

@@ -28,3 +28,14 @@ class Port(_PybricksEnum):
     F: Port = ord("F")
     G: Port = ord("G")
     H: Port = ord("H")
+
+
+class ExtPort:
+    """Extension port of a PUMP device (1-based, as in its stream table)."""
+
+    EXT1: int = 1
+    EXT2: int = 2
+    EXT3: int = 3
+    EXT4: int = 4
+    EXT5: int = 5
+    EXT6: int = 6

scirodev-0.2.1/sciro/floorpro.py → scirodev-0.3.1/sciro/pump.py

@@ -1,4 +1,6 @@
-"""sciro.floorpro -- the LP-FloorPro line sensor over PUMP (PeakHub).
+"""sciro.pump -- PUMP devices on the PeakHub, the PUMP counterpart of
+``pybricks.pupdevices``: the generic :class:`PUMPDevice` plus one class per
+device (currently the LP-FloorPro line sensor).
 
 Stub for the frozen module of the same name. Every reading method returns the
 value directly, or an awaitable under multitasking.
@@ -6,10 +8,10 @@ value directly, or an awaitable under multitasking.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Optional, Tuple
+from typing import TYPE_CHECKING, Iterable, Optional, Tuple, Union
 
 if TYPE_CHECKING:
-    from pybricks._common import MaybeAwaitable, MaybeAwaitableFloat
+    from pybricks._common import MaybeAwaitable, MaybeAwaitableColor, MaybeAwaitableFloat
 
     from ._common import (
         MaybeAwaitableEuler,
@@ -20,7 +22,10 @@ if TYPE_CHECKING:
         MaybeAwaitableRGBC,
     )
 
-from .iodevices import PUMPDevice, StreamInfo
+from .iodevices import PUMPDevice as PUMPDevice  # noqa: F401  (re-export)
+from .iodevices import StreamInfo
+from pybricks.parameters import Color
+
 from .parameters import Port as _Port
 
 
@@ -29,7 +34,7 @@ class _Stream:
     id: int
 
     def subscribe(self, mode: int, rate: int = 0) -> MaybeAwaitable:
-        """subscribe(mode, rate=0)  -- see :meth:`PUMPDevice.subscribe`."""
+        """subscribe(mode, rate=0)  -- rate in Hz, 0 = every sample; see :meth:`PUMPDevice.subscribe`."""
 
     def state(self) -> Optional[bytes]:
         """state() -> bytes | None  -- the stream's current state prefix."""
@@ -80,7 +85,7 @@ class Pixels(_Stream):
     """The sensor's own LED strip picture, rendered on the device at full scale:
     18 ``(r, g, b)`` triplets = IR channels 0..14, EXT1, EXT2, battery. Off by
     default. A PeakHub mirrors it on its 5x5 matrix with
-    :meth:`sciro.hubs.PeakHub.display.device`.
+    :meth:`sciro.hubs.LightMatrix.device`.
     """
 
     def read(self) -> MaybeAwaitablePixels:
@@ -91,15 +96,49 @@ class Pixels(_Stream):
 
 
 class ColorSensor(_Stream):
-    """TCS3400 on an extension port: raw R, G, B, C at device resolution.
+    """TCS3400 colour sensor on an extension port of a PUMP device.
+
+    ``ColorSensor(port, ext_port)`` opens it directly; :meth:`FloorPro.color_sensor`
+    returns the same class. ``hsv()`` and ``color()`` follow
+    ``pybricks.pupdevices.ColorSensor``.
 
     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.
     """
 
+    ext_port: int
+
+    def __init__(self, port: Union[_Port, PUMPDevice], ext_port: int = 1):
+        """ColorSensor(port, ext_port=ExtPort.EXT1)
+
+        Arguments:
+            port (Port): Hub port of the PUMP device carrying the sensor (or the
+                opened ``PUMPDevice`` itself).
+            ext_port (ExtPort): Extension port the sensor is plugged into.
+                Raises ``OSError`` if there is no colour sensor there.
+        """
+
     def read(self) -> MaybeAwaitableRGBC:
-        """read() -> Tuple[int, int, int, int, int]  -- (red, green, blue, clear, status)."""
+        """read() -> Tuple[int, int, int, int, int]  -- raw (red, green, blue, clear, status) at device resolution."""
+
+    def hsv(self) -> MaybeAwaitableColor:
+        """hsv() -> Color
+
+        Hue (0 .. 359), saturation (0 .. 100) and value (0 .. 100) of the
+        surface, as a ``Color``. Standard HSV of the raw reading; value is
+        relative to the full scale of the current integration time.
+        """
+
+    def color(self) -> MaybeAwaitableColor:
+        """color() -> Color
+
+        The nearest of the detectable colours (default: red, yellow, green,
+        blue, white, none), matched like ``pybricks.pupdevices.ColorSensor``.
+        """
+
+    def detectable_colors(self, colors: Optional[Iterable[Color]] = None) -> Optional[Tuple[Color, ...]]:
+        """detectable_colors(colors)  -- set the colours color() chooses from; with no argument, get them."""
 
     def settings(self) -> Tuple[int, int, int]:
         """settings() -> Tuple[int, int, int]  -- (led_percent, gain_x, atime) in effect."""
@@ -115,12 +154,25 @@ class ColorSensor(_Stream):
 
 
 class IMU(_Stream):
-    """BNO086 on an extension port: roll, pitch, yaw in degrees.
+    """BNO086 IMU on an extension port of a PUMP device: roll, pitch, yaw in degrees.
 
-    The heading offset lives on the hub: :meth:`reset_heading` makes the current
-    yaw read as the given angle.
+    ``IMU(port, ext_port)`` opens it directly; :meth:`FloorPro.imu` returns the
+    same class. The heading offset lives on the hub: :meth:`reset_heading` makes
+    the current yaw read as the given angle.
     """
 
+    ext_port: int
+
+    def __init__(self, port: Union[_Port, PUMPDevice], ext_port: int = 2):
+        """IMU(port, ext_port=ExtPort.EXT2)
+
+        Arguments:
+            port (Port): Hub port of the PUMP device carrying the IMU (or the
+                opened ``PUMPDevice`` itself).
+            ext_port (ExtPort): Extension port the IMU is plugged into. Raises
+                ``OSError`` if there is no IMU there.
+        """
+
     def read(self) -> MaybeAwaitableEuler:
         """read() -> Tuple  -- (roll, pitch, yaw, status), degrees; yaw includes the offset."""
 

{scirodev-0.2.1 → scirodev-0.3.1/scirodev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.2.1
+Version: 0.3.1
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -41,7 +41,7 @@ Then your IDE/type checker knows these, which the upstream `pybricks` stubs don'
 ```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
+from sciro.pump import FloorPro        # PUMP devices (LP-FloorPro, ...)
 from sciro.hubs import PeakHub             # hub class incl. display.device()
 
 hub = PeakHub()
@@ -50,6 +50,10 @@ cog_dark, cog_bright, brightness, darkness, mask, calibrating = fp.line.read()
 hub.display.device(fp, brightness=50)      # mirror the sensor's LED strip on the 5x5
 ```
 
+Full demo programs for the LP FloorPro (both for LEGO hubs and the PeakHub) live in
+[sciurus-robotics/FloorPro-CodeDemos](https://github.com/sciurus-robotics/FloorPro-CodeDemos);
+`examples/` here stays minimal.
+
 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

{scirodev-0.2.1 → scirodev-0.3.1}/scirodev.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ sciro/floorpro.py
 sciro/hubs.py
 sciro/iodevices.py
 sciro/parameters.py
+sciro/pump.py
 sciro/py.typed
 scirodev/__init__.py
 scirodev/cli.py