scirodev 0.4.1__tar.gz → 0.5.2__tar.gz

{scirodev-0.4.1 → scirodev-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.4.1
+Version: 0.5.2
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -16,6 +16,9 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pybricksdev>=2.3
 Requires-Dist: pybricks>=3.6
+Provides-Extra: docs
+Requires-Dist: sphinx>=8; extra == "docs"
+Requires-Dist: furo; extra == "docs"
 Dynamic: license-file
 
 # scirodev
@@ -43,6 +46,8 @@ 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.tools import RingBuffer         # experimental: RAM recorder -> CSV file via the console
+from sciro.robotics import PIDController   # experimental: PID with optional logging
 
 hub = PeakHub()
 fp = FloorPro(Port.G)
@@ -50,6 +55,32 @@ 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
 ```
 
+Experimental (API may change): a RAM recorder that publishes CSV through the
+console, and a PID controller that can log into it:
+
+```python
+from sciro.robotics import PIDController
+from sciro.tools import RingBuffer
+
+pid = PIDController(kp=15, kd=0.2, output_limit=300)
+log = pid.make_log(seconds=10, rate=100)     # RingBuffer of pid.LOG_FIELDS
+turn_rate = pid.update(error, derivative=-hub.imu.angular_velocity(Axis.Z))
+log.publish("doc/pid_run.csv")               # scirodev run writes the file next to the script
+```
+
+The drivebase's own controllers log too (built into Pybricks, undocumented
+upstream): `db.heading_control.log.start(5000, down_sample=2)` records the
+reference trajectory, the estimated state and the P/I/D terms at 100 Hz from the
+firmware's control loop; `db.heading_control.log.publish("heading.csv")` writes
+it with a header line. `sciro.robotics.DriveBase` is the Pybricks class with
+these attributes typed. `log.record(db.state)` is the coroutine form for
+anything else.
+
+`publish(path)` wraps the CSV in pybricksdev's `_file_begin_ <path>` /
+`_file_end_` lines; `scirodev run` (and `pybricksdev run`) then write the block
+to that file, relative to the script's folder, instead of echoing it. Without a
+path the CSV goes to the terminal.
+
 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.
@@ -61,6 +92,18 @@ 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.
 
+## API reference (HTML)
+
+The stubs double as the source of the API reference, built with Sphinx the way
+docs.pybricks.com is (cross-links into it for the upstream types):
+
+```
+pip install -e ".[docs]"
+scripts/build-docs            # -> docs/_build/html/index.html
+```
+
+The build output is static HTML; a website can copy that folder as is.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml`, commit, tag `vX.Y.Z` and push the tag. The

{scirodev-0.4.1 → scirodev-0.5.2}/README.md

@@ -23,6 +23,8 @@ 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.tools import RingBuffer         # experimental: RAM recorder -> CSV file via the console
+from sciro.robotics import PIDController   # experimental: PID with optional logging
 
 hub = PeakHub()
 fp = FloorPro(Port.G)
@@ -30,6 +32,32 @@ 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
 ```
 
+Experimental (API may change): a RAM recorder that publishes CSV through the
+console, and a PID controller that can log into it:
+
+```python
+from sciro.robotics import PIDController
+from sciro.tools import RingBuffer
+
+pid = PIDController(kp=15, kd=0.2, output_limit=300)
+log = pid.make_log(seconds=10, rate=100)     # RingBuffer of pid.LOG_FIELDS
+turn_rate = pid.update(error, derivative=-hub.imu.angular_velocity(Axis.Z))
+log.publish("doc/pid_run.csv")               # scirodev run writes the file next to the script
+```
+
+The drivebase's own controllers log too (built into Pybricks, undocumented
+upstream): `db.heading_control.log.start(5000, down_sample=2)` records the
+reference trajectory, the estimated state and the P/I/D terms at 100 Hz from the
+firmware's control loop; `db.heading_control.log.publish("heading.csv")` writes
+it with a header line. `sciro.robotics.DriveBase` is the Pybricks class with
+these attributes typed. `log.record(db.state)` is the coroutine form for
+anything else.
+
+`publish(path)` wraps the CSV in pybricksdev's `_file_begin_ <path>` /
+`_file_end_` lines; `scirodev run` (and `pybricksdev run`) then write the block
+to that file, relative to the script's folder, instead of echoing it. Without a
+path the CSV goes to the terminal.
+
 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.
@@ -41,6 +69,18 @@ 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.
 
+## API reference (HTML)
+
+The stubs double as the source of the API reference, built with Sphinx the way
+docs.pybricks.com is (cross-links into it for the upstream types):
+
+```
+pip install -e ".[docs]"
+scripts/build-docs            # -> docs/_build/html/index.html
+```
+
+The build output is static HTML; a website can copy that folder as is.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml`, commit, tag `vX.Y.Z` and push the tag. The

{scirodev-0.4.1 → scirodev-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scirodev"
-version = "0.4.1"
+version = "0.5.2"
 description = "PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,9 @@ dependencies = [
     "pybricks>=3.6",
 ]
 
+[project.optional-dependencies]
+docs = ["sphinx>=8", "furo"]
+
 [project.urls]
 Homepage = "https://github.com/sciurus-robotics/scirodev"
 Repository = "https://github.com/sciurus-robotics/scirodev"

{scirodev-0.4.1 → scirodev-0.5.2}/sciro/_common.py

@@ -20,6 +20,7 @@ if TYPE_CHECKING:
     _RGB = Tuple[int, int, int]
     _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, ...]
 
     class MaybeAwaitableLine(_Line, Awaitable[_Line]): ...
 
@@ -40,3 +41,5 @@ if TYPE_CHECKING:
     class MaybeAwaitableCalibration(_Calibration, Awaitable[_Calibration]): ...
 
     class MaybeAwaitableStr(str, Awaitable[str]): ...
+
+    class MaybeAwaitableBools(_Bools, Awaitable[_Bools]): ...

{scirodev-0.4.1 → scirodev-0.5.2}/sciro/iodevices.py

@@ -11,7 +11,7 @@ if TYPE_CHECKING:
 
     from ._common import MaybeAwaitableStateData
 
-from .parameters import Port as _Port
+from pybricks.parameters import Port as _Port  # base type: sciro.parameters.Port is a subclass
 
 # (stream id, url, ext_port, state length)
 StreamInfo = Tuple[int, str, int, int]

scirodev-0.5.2/sciro/parameters.py

@@ -0,0 +1,62 @@
+"""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 typing import TYPE_CHECKING
+
+from pybricks.parameters import _PybricksEnum
+
+if TYPE_CHECKING:
+    from pybricks.parameters import Port as _Port
+
+    class Port(_Port):
+        """Port on the PeakHub. Eight LPF2/PUP ports, A .. H.
+
+        For the type checker this is a subclass of ``pybricks.parameters.Port``
+        (on the hub it is the same object), so a ``sciro`` port is accepted
+        wherever the upstream stubs expect a ``pybricks.parameters.Port``
+        (``Motor``, ``DriveBase``, ...). A .. F are inherited; G and H are
+        the two extra PeakHub ports.
+        """
+
+        G: Port
+        H: Port
+
+else:
+    # At runtime the upstream Port is a real Enum, which cannot be subclassed
+    # once it has members; tooling that imports the stubs (docs, tests) gets
+    # an equivalent enum with all eight ports instead.
+    class Port(_PybricksEnum):
+        """Port on the PeakHub. Eight LPF2/PUP ports, A .. H."""
+
+        A = ord("A")
+        B = ord("B")
+        C = ord("C")
+        D = ord("D")
+        E = ord("E")
+        F = ord("F")
+        G = ord("G")
+        H = 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.4.1 → scirodev-0.5.2}/sciro/pump.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Iterable, Optional, Tuple, Union
 
 if TYPE_CHECKING:
-    from pybricks._common import MaybeAwaitable, MaybeAwaitableColor, MaybeAwaitableFloat
+    from pybricks._common import MaybeAwaitable, MaybeAwaitableBool, MaybeAwaitableColor, MaybeAwaitableFloat
 
     from ._common import (
         MaybeAwaitableEuler,
@@ -22,6 +22,7 @@ if TYPE_CHECKING:
         MaybeAwaitableRGB8,
         MaybeAwaitableCalibration,
         MaybeAwaitableStr,
+        MaybeAwaitableBools,
         MaybeAwaitableRGBC,
     )
 
@@ -29,7 +30,7 @@ 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
+from pybricks.parameters import Port as _Port  # base type: sciro.parameters.Port is a subclass
 
 
 class _Stream:
@@ -50,12 +51,32 @@ class Line(_Stream):
         """read() -> Tuple
 
         Returns ``(cog_dark, cog_bright, brightness, darkness, mask, calibrating)``:
-        centre of gravity of the dark / bright pixels in sensor pitches from the
+        center 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 dark_centroid(self) -> MaybeAwaitableFloat:
+        """dark_centroid() -> float  -- center of gravity of the dark pixels, in
+        sensor pitches from the middle sensor (-7 .. +7)."""
+
+    def bright_centroid(self) -> MaybeAwaitableFloat:
+        """bright_centroid() -> float  -- center of gravity of the bright pixels (-7 .. +7)."""
+
+    def brightness(self) -> MaybeAwaitableFloat:
+        """brightness() -> float  -- overall brightness 0 .. 1."""
+
+    def darkness(self) -> MaybeAwaitableFloat:
+        """darkness() -> float  -- overall darkness 0 .. 1."""
+
+    def line_sensors_binary(self) -> MaybeAwaitableBools:
+        """line_sensors_binary() -> Tuple[bool, ...]  -- 15 flags, sensor 0 first,
+        True where the sensor sees bright."""
+
+    def calibrating(self) -> MaybeAwaitableBool:
+        """calibrating() -> bool  -- True while the min-max calibration runs."""
+
     def calibrate(self, enable: bool = True) -> MaybeAwaitable:
         """calibrate(enable=True)  -- start/stop min-max calibration of the array."""
 
@@ -99,7 +120,7 @@ class Pixels(_Stream):
 
 
 class ColorSensor(_Stream):
-    """TCS3400 colour sensor on an extension port of a PUMP device.
+    """TCS3400 color 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
@@ -119,7 +140,7 @@ class ColorSensor(_Stream):
             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.
+                Raises ``OSError`` if there is no color sensor there.
         """
 
     def read(self) -> MaybeAwaitableRGBC:
@@ -137,7 +158,7 @@ class ColorSensor(_Stream):
         """hsv() -> Color
 
         Hue (0 .. 359), saturation (0 .. 100) and value (0 .. 100) of the
-        surface, as a ``Color``: standard HSV of the calibrated colour when a
+        surface, as a ``Color``: standard HSV of the calibrated color when a
         valid calibration applies, of the raw reading otherwise.
         """
 
@@ -159,7 +180,7 @@ class ColorSensor(_Stream):
         """
 
     def clear_calibration(self) -> MaybeAwaitable:
-        """clear_calibration()  -- drop the stored calibration (back to full-scale colour)."""
+        """clear_calibration()  -- drop the stored calibration (back to full-scale color)."""
 
     def calibration(self) -> MaybeAwaitableCalibration:
         """calibration() -> Tuple
@@ -172,12 +193,12 @@ class ColorSensor(_Stream):
     def color(self) -> MaybeAwaitableColor:
         """color() -> Color
 
-        The nearest of the detectable colours (default: red, yellow, green,
+        The nearest of the detectable colors (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."""
+        """detectable_colors(colors)  -- set the colors 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."""
@@ -259,6 +280,30 @@ class FloorPro:
     def imu(self, ext_port: int = 2) -> Gyro:
         """imu(ext_port=2) -> Gyro  -- alias of :meth:`gyro`."""
 
+    # Line conveniences at device level (the names of the LUMP driver class):
+
+    def all_sensor_data(self) -> MaybeAwaitableLine:
+        """all_sensor_data() -> Tuple  -- the same as ``line.read()``."""
+
+    def dark_centroid(self) -> MaybeAwaitableFloat:
+        """dark_centroid() -> float  -- see :meth:`Line.dark_centroid`."""
+
+    def bright_centroid(self) -> MaybeAwaitableFloat:
+        """bright_centroid() -> float  -- see :meth:`Line.bright_centroid`."""
+
+    def brightness(self) -> MaybeAwaitableFloat:
+        """brightness() -> float  -- overall brightness 0 .. 1."""
+
+    def darkness(self) -> MaybeAwaitableFloat:
+        """darkness() -> float  -- overall darkness 0 .. 1."""
+
+    def line_sensors_binary(self) -> MaybeAwaitableBools:
+        """line_sensors_binary() -> Tuple[bool, ...]  -- 15 flags, True = bright."""
+
+    def line_sensors_analog(self) -> MaybeAwaitableInts:
+        """line_sensors_analog() -> Tuple[int, ...]  -- 15 raw ADC counts
+        (0 .. 4095), sensor 0 first; one ``ir_raw`` frame on demand."""
+
     def streams(self) -> Tuple[StreamInfo, ...]:
         """streams() -> Tuple  -- the enumerated streams ``(id, url, ext_port, state_len)``."""
 

scirodev-0.5.2/sciro/robotics.py

@@ -0,0 +1,156 @@
+"""Stubs for ``sciro.robotics`` (PeakHub firmware) -- control helpers.
+EXPERIMENTAL: the API may still change between releases.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Tuple, Union
+
+from pybricks.parameters import Stop
+
+if TYPE_CHECKING:
+    from pybricks._common import MaybeAwaitable
+    from pybricks.parameters import Number
+else:
+    # Upstream defines these only for type checkers; runtime importers of the
+    # stubs (the docs build) need values. Annotations are strings here
+    # (from __future__ import annotations), so placeholders suffice.
+    Number = Union[int, float]
+    MaybeAwaitable = None
+
+from pybricks import _common
+from pybricks.robotics import DriveBase as _DriveBase
+from pybricks.tools import StopWatch
+
+from sciro.tools import Logger, RingBuffer
+
+
+class Control(_common.Control):
+    """A drivebase / motor controller, with its built-in logger exposed."""
+
+    log: Logger
+
+
+class DriveBase(_DriveBase):
+    """``pybricks.robotics.DriveBase`` (the same class on the hub). The stub
+    adds the ``log`` on ``heading_control`` / ``distance_control`` and the
+    PeakHub extensions of :meth:`straight`."""
+
+    heading_control: Control  # type: ignore[assignment]
+    distance_control: Control  # type: ignore[assignment]
+
+    def straight(  # type: ignore[override]
+        self,
+        distance: Number,
+        then: Stop = Stop.HOLD,
+        wait: bool = True,
+        speed: Optional[Number] = None,
+        heading: Optional[Number] = None,
+        exit_speed: Number = 0,
+    ) -> MaybeAwaitable:
+        """straight(distance, then=Stop.HOLD, wait=True, speed=None, heading=None, exit_speed=0)
+
+        Drives straight for ``distance`` mm, as in Pybricks, with three
+        PeakHub extensions (keyword use recommended):
+
+        ``speed``: drive speed in mm/s for this move only; ``None`` uses the
+        ``straight_speed`` setting.
+
+        ``heading``: absolute heading in degrees to hold during the move
+        instead of the heading at its start (the gyro heading with
+        ``use_gyro(True)``, else the wheel-based one since the last
+        ``reset()``). Any value is accepted: the nearest whole-turn
+        equivalent of the current heading is targeted, so ``heading=90``
+        while the internal heading reads 450 corrects by 0 degrees, never by
+        a full turn. ``None`` keeps the Pybricks behavior.
+
+        ``exit_speed``: speed in mm/s the robot has when it reaches the
+        target; it keeps driving at that speed until the next command, so the
+        next ``straight()`` (or ``drive()``) blends in without a stop. Implies
+        ``then=Stop.NONE``; any other explicit ``then`` raises ``ValueError``.
+        Clamped to the move's drive speed. ``0`` (default) stops or holds as
+        ``then`` says. ``then=Stop.NONE`` without ``exit_speed`` keeps the
+        upstream meaning: continue at the drive speed.
+        """
+
+    def heading_target(self, angle: Optional[Number] = None) -> Optional[float]:
+        """heading_target(angle) / heading_target() -> float
+
+        Steers a running :meth:`straight` (PeakHub): replaces the heading
+        setpoint without touching the distance trajectory (position, speed,
+        exit speed and end condition stay). Absolute heading in degrees,
+        float, same frame and nearest-whole-turn rule as ``straight(heading=)``.
+        The heading controller branches off its current reference on a new
+        trajectory, so small steps (the usual < 1 degree per 10 ms) are smooth
+        and large ones are limited by the ``turn_rate`` / ``turn_acceleration``
+        settings. Without an argument returns the current heading target.
+
+        Typical use, a line follower as a setpoint generator::
+
+            db.straight(dist, speed=v, exit_speed=e, heading=course, wait=False)
+            while not db.done():
+                data = await floor.all_sensor_data()
+                db.heading_target(course + K * data[0])
+                await wait(10)
+
+        Raises ``OSError`` when no ``straight()`` is running (``drive()``,
+        ``turn()``, ``curve()``, ``arc()`` and an idle drivebase are not
+        steerable).
+        """
+
+
+class PIDController:
+    """Discrete PID controller: ``output = kp*e + ki*integral(e) + kd*de/dt``.
+
+    ``ki = kd = 0`` gives a plain P or PD controller. ``integral_limit`` clamps
+    the I term (anti-windup), ``output_limit`` the total output; ``None`` means
+    unlimited. A gap between updates longer than ``reset_after`` milliseconds
+    restarts the controller (a new movement); ``None`` never. ``stopwatch``
+    is the time source (default: an own ``StopWatch``); ``log`` a
+    :class:`RingBuffer` with :attr:`LOG_FIELDS` (see :meth:`make_log`).
+    """
+
+    LOG_FIELDS: Tuple[Tuple[str, str], ...]
+    """``t_ms, dt, error, p, i, d, output`` -- the row layout of the log."""
+
+    kp: float
+    ki: float
+    kd: float
+    integral_limit: Optional[float]
+    output_limit: Optional[float]
+    reset_after: Optional[int]
+    stopwatch: StopWatch
+    log: Optional[RingBuffer]
+    name: str
+    output: float
+    """The last output."""
+    integral: float
+
+    def __init__(
+        self,
+        kp: float,
+        ki: float = 0.0,
+        kd: float = 0.0,
+        integral_limit: Optional[float] = None,
+        output_limit: Optional[float] = None,
+        reset_after: Optional[int] = 100,
+        stopwatch: Optional[StopWatch] = None,
+        log: Optional[RingBuffer] = None,
+        name: str = "PID",
+    ) -> None: ...
+
+    def make_log(self, seconds: float, rate: int = 100) -> RingBuffer:
+        """Attach and return a RingBuffer for ``seconds`` of updates at ``rate`` Hz."""
+
+    def reset(self) -> None:
+        """Forget the integral, the last error and the last update time."""
+
+    def update(self, error: float, derivative: Optional[float] = None, p_limit: Optional[float] = None) -> float:
+        """One controller step; returns the output.
+
+        ``error`` is setpoint minus measurement. ``derivative`` is d(error)/dt
+        when measured (e.g. minus the gyro rate for a heading error); ``None``
+        differentiates the error numerically. ``p_limit`` clamps the P term for
+        this step only, e.g. a braking profile that leaves the D term free to
+        damp.
+        """

scirodev-0.5.2/sciro/tools.py

@@ -0,0 +1,92 @@
+"""Stubs for ``sciro.tools`` (PeakHub firmware) -- recording and publishing
+helpers. EXPERIMENTAL: the API may still change between releases.
+"""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable, Iterable, Iterator, Optional, Sequence, Tuple
+
+
+class RingBuffer:
+    """Fixed-size recorder of rows with a fixed binary layout, kept in RAM.
+
+    ``fields`` are ``(name, format)`` pairs with ``struct`` formats (``"I"``
+    unsigned 32 bit, ``"i"`` signed, ``"f"`` float, ``"h"`` 16 bit, ``"B"``
+    byte, ...); ``capacity`` rows are kept, older rows are overwritten.
+    RAM used = capacity * row size (100 Hz * 30 s * 7 floats = 84 KB).
+    """
+
+    fields: Tuple[Tuple[str, str], ...]
+    names: Tuple[str, ...]
+    format: str
+    row_size: int
+    capacity: int
+    name: Optional[str]
+    count: int
+    """Rows appended since the last clear (not capped at capacity)."""
+
+    def __init__(self, fields: Iterable[Sequence[str]], capacity: int, name: Optional[str] = None) -> None: ...
+
+    def __len__(self) -> int:
+        """Rows currently kept (at most ``capacity``)."""
+
+    def __getitem__(self, idx: int) -> Tuple[float | int, ...]:
+        """Row ``idx`` as a tuple; 0 is the oldest kept row, -1 the newest."""
+
+    def __iter__(self) -> Iterator[Tuple[float | int, ...]]:
+        """Rows, oldest first."""
+
+    def clear(self) -> None: ...
+
+    def append(self, *values: float | int) -> None:
+        """Append one row; values in field order."""
+
+    def record(self, source: Callable[[], Sequence[float | int]], period: int = 10) -> Awaitable[None]:
+        """Coroutine: append ``source()`` every ``period`` ms until cancelled.
+
+        Run it next to the movement, e.g.
+        ``await multitask(drive(), log.record(db.state), race=True)``.
+        """
+
+    def publish(self, path: Optional[str] = None, decimals: int = 3) -> None:
+        """Print the rows as CSV (``#`` header comments, then the names).
+
+        With ``path`` the block is wrapped in the pybricksdev file markers
+        (``_file_begin_ <path>`` ... ``_file_end_``): ``scirodev run`` writes it
+        to that file, relative to the folder of the running script, instead of
+        the terminal. Expect on the order of 1000 rows per few seconds over BLE.
+        """
+
+
+class Logger:
+    """The built-in pbio logger of a controller (``DriveBase.heading_control.log``,
+    ``DriveBase.distance_control.log``, ``Motor.log``): rows are written by
+    the firmware's 5 ms control loop while the controller is active, into a
+    fixed buffer (not a ring) allocated by :meth:`start`.
+
+    Controller columns: ``t_ms, traj_ms, position, speed, status, torque,
+    ref_position, ref_speed, est_position, est_speed, p, i, d, position_c``
+    (``position_c`` = position in 0.01 units, PeakHub; position in
+    the controller's units: mm or deg; torque in uNm; status bits: actuation
+    0..1, stalled 2, on target 3, integration paused 4).
+    Servo (Motor) columns: ``t_ms, time_ms, angle, speed, status, voltage_mv,
+    est_angle, est_speed, torque_fb, torque_ff, observer_mv``.
+    """
+
+    def start(self, duration: int, down_sample: int = 1) -> None:
+        """Allocate and start: ``duration`` ms, one row every
+        ``5 * down_sample`` ms. RAM = rows * 52 bytes (controller), so 30 s at
+        ``down_sample=2`` (100 Hz) is 156 KB; prefer 10 (20 Hz) for long runs.
+        """
+
+    def stop(self) -> None: ...
+
+    def save(self, path: Optional[str] = None) -> None:
+        """Upstream: print the rows framed with ``PB_OF:<path>`` / ``PB_EOF``,
+        no header. Kept unchanged."""
+
+    def publish(self, path: Optional[str] = None, names: Optional[str] = None) -> None:
+        """PeakHub: print the rows as CSV with a header line, framed with the
+        ``_file_begin_ <path>`` / ``_file_end_`` markers like
+        :meth:`RingBuffer.publish`. ``names`` overrides the header
+        (comma separated). Stops logging first."""

{scirodev-0.4.1 → scirodev-0.5.2}/scirodev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.4.1
+Version: 0.5.2
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -16,6 +16,9 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pybricksdev>=2.3
 Requires-Dist: pybricks>=3.6
+Provides-Extra: docs
+Requires-Dist: sphinx>=8; extra == "docs"
+Requires-Dist: furo; extra == "docs"
 Dynamic: license-file
 
 # scirodev
@@ -43,6 +46,8 @@ 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.tools import RingBuffer         # experimental: RAM recorder -> CSV file via the console
+from sciro.robotics import PIDController   # experimental: PID with optional logging
 
 hub = PeakHub()
 fp = FloorPro(Port.G)
@@ -50,6 +55,32 @@ 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
 ```
 
+Experimental (API may change): a RAM recorder that publishes CSV through the
+console, and a PID controller that can log into it:
+
+```python
+from sciro.robotics import PIDController
+from sciro.tools import RingBuffer
+
+pid = PIDController(kp=15, kd=0.2, output_limit=300)
+log = pid.make_log(seconds=10, rate=100)     # RingBuffer of pid.LOG_FIELDS
+turn_rate = pid.update(error, derivative=-hub.imu.angular_velocity(Axis.Z))
+log.publish("doc/pid_run.csv")               # scirodev run writes the file next to the script
+```
+
+The drivebase's own controllers log too (built into Pybricks, undocumented
+upstream): `db.heading_control.log.start(5000, down_sample=2)` records the
+reference trajectory, the estimated state and the P/I/D terms at 100 Hz from the
+firmware's control loop; `db.heading_control.log.publish("heading.csv")` writes
+it with a header line. `sciro.robotics.DriveBase` is the Pybricks class with
+these attributes typed. `log.record(db.state)` is the coroutine form for
+anything else.
+
+`publish(path)` wraps the CSV in pybricksdev's `_file_begin_ <path>` /
+`_file_end_` lines; `scirodev run` (and `pybricksdev run`) then write the block
+to that file, relative to the script's folder, instead of echoing it. Without a
+path the CSV goes to the terminal.
+
 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.
@@ -61,6 +92,18 @@ 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.
 
+## API reference (HTML)
+
+The stubs double as the source of the API reference, built with Sphinx the way
+docs.pybricks.com is (cross-links into it for the upstream types):
+
+```
+pip install -e ".[docs]"
+scripts/build-docs            # -> docs/_build/html/index.html
+```
+
+The build output is static HTML; a website can copy that folder as is.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml`, commit, tag `vX.Y.Z` and push the tag. The

{scirodev-0.4.1 → scirodev-0.5.2}/scirodev.egg-info/SOURCES.txt

@@ -9,6 +9,8 @@ sciro/iodevices.py
 sciro/parameters.py
 sciro/pump.py
 sciro/py.typed
+sciro/robotics.py
+sciro/tools.py
 scirodev/__init__.py
 scirodev/cli.py
 scirodev.egg-info/PKG-INFO

{scirodev-0.4.1 → scirodev-0.5.2}/scirodev.egg-info/requires.txt

@@ -1,2 +1,6 @@
 pybricksdev>=2.3
 pybricks>=3.6
+
+[docs]
+sphinx>=8
+furo

scirodev-0.4.1/sciro/parameters.py

@@ -1,41 +0,0 @@
-"""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")
-
-
-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