scirodev 0.4.0__tar.gz → 0.5.0__tar.gz

{scirodev-0.4.0 → scirodev-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.4.0
+Version: 0.5.0
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -43,6 +43,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 +52,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.

{scirodev-0.4.0 → scirodev-0.5.0}/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.

{scirodev-0.4.0 → scirodev-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scirodev"
-version = "0.4.0"
+version = "0.5.0"
 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.4.0 → scirodev-0.5.0}/sciro/_common.py

@@ -18,6 +18,7 @@ if TYPE_CHECKING:
     _Euler = Tuple[float, float, float, int]
     _StateData = Tuple[bytes, bytes]
     _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, ...]
 
     class MaybeAwaitableLine(_Line, Awaitable[_Line]): ...
@@ -33,3 +34,9 @@ if TYPE_CHECKING:
     class MaybeAwaitableStateData(_StateData, Awaitable[_StateData]): ...
 
     class MaybeAwaitablePixels(_Pixels, Awaitable[_Pixels]): ...
+
+    class MaybeAwaitableRGB8(_RGB, Awaitable[_RGB]): ...
+
+    class MaybeAwaitableCalibration(_Calibration, Awaitable[_Calibration]): ...
+
+    class MaybeAwaitableStr(str, Awaitable[str]): ...

{scirodev-0.4.0 → scirodev-0.5.0}/sciro/hubs.py

@@ -45,6 +45,34 @@ class LightMatrix(_common.LightMatrix):
         """
 
 
+class System(_common.System):
+    """The PeakHub's system object: everything ``pybricks`` offers, plus the
+    board identity.
+    """
+
+    def device_id(self) -> str:
+        """device_id() -> str
+
+        The full factory unique ID of the hub's MCU as a 24-character uppercase
+        hex string. Stable per physical hub.
+        """
+
+    def short_id(self) -> str:
+        """short_id() -> str
+
+        The hub's 8-character short ID (Crockford base32, derived from the
+        device ID): the same value the boot console prints and the device
+        inventory uses.
+        """
+
+    def info(self) -> dict:
+        """info() -> dict
+
+        ``{"name", "device_id", "short_id", "reset_reason", "program_id",
+        "program_start_type"}`` in one call.
+        """
+
+
 class PeakHub:
     """LEGO-compatible hub by Sciurus Robotics: 8 ports, 5x5 RGB matrix, IMU."""
 
@@ -56,7 +84,7 @@ class PeakHub:
     display = LightMatrix(5, 5)
     imu = _common.IMU()
     speaker = _common.Speaker()
-    system = _common.System()
+    system = System()
     ble = _common.BLE()
 
     def __init__(

{scirodev-0.4.0 → scirodev-0.5.0}/sciro/pump.py

@@ -19,6 +19,9 @@ if TYPE_CHECKING:
         MaybeAwaitableIRCalib,
         MaybeAwaitableLine,
         MaybeAwaitablePixels,
+        MaybeAwaitableRGB8,
+        MaybeAwaitableCalibration,
+        MaybeAwaitableStr,
         MaybeAwaitableRGBC,
     )
 
@@ -122,12 +125,48 @@ class ColorSensor(_Stream):
     def read(self) -> MaybeAwaitableRGBC:
         """read() -> Tuple[int, int, int, int, int]  -- raw (red, green, blue, clear, status) at device resolution."""
 
+    def calibrated(self) -> MaybeAwaitableRGB8:
+        """calibrated() -> Tuple[int, int, int]
+
+        Red, green, blue 0 .. 255 as the device itself shows them: stretched
+        over the calibrated range when a valid calibration applies, scaled to
+        full scale otherwise.
+        """
+
     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.
+        surface, as a ``Color``: standard HSV of the calibrated colour when a
+        valid calibration applies, of the raw reading otherwise.
+        """
+
+    def calibration_status(self) -> MaybeAwaitableStr:
+        """calibration_status() -> str
+
+        ``"none"`` (nothing stored), ``"weak"`` (stored but not applicable:
+        incomplete, or LED / gain / integration differ from the calibration
+        profile), ``"ok"`` (applied), or ``"calibrating"``.
+        """
+
+    def calibrate(self, enable: bool = True) -> MaybeAwaitable:
+        """calibrate(enable=True)
+
+        Start or stop the range calibration on the device. While it runs, move
+        the sensor over the darkest and brightest surfaces (or elements) it
+        will see; stopping stores the table on the sensor, bound to the LED,
+        gain and integration time in force. Changing those meanwhile aborts it.
+        """
+
+    def clear_calibration(self) -> MaybeAwaitable:
+        """clear_calibration()  -- drop the stored calibration (back to full-scale colour)."""
+
+    def calibration(self) -> MaybeAwaitableCalibration:
+        """calibration() -> Tuple
+
+        The stored table: ``(min, max, (led, gain, atime), valid, applicable,
+        visited_mask)`` with ``min``/``max`` tuples of four counts (red, green,
+        blue, clear). Fetched from the device on demand.
         """
 
     def color(self) -> MaybeAwaitableColor:

scirodev-0.5.0/sciro/robotics.py

@@ -0,0 +1,84 @@
+"""Stubs for ``sciro.robotics`` (PeakHub firmware) -- control helpers.
+EXPERIMENTAL: the API may still change between releases.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+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``."""
+
+    heading_control: Control  # type: ignore[assignment]
+    distance_control: Control  # type: ignore[assignment]
+
+
+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.0/sciro/tools.py

@@ -0,0 +1,91 @@
+"""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 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.0 → scirodev-0.5.0}/scirodev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.4.0
+Version: 0.5.0
 Summary: PeakHub / sciro extensions to Pybricks: typed API stubs (sciro.*) and hub tooling on top of pybricksdev
 Author: Thomas Schank
 License: MIT
@@ -43,6 +43,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 +52,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.

{scirodev-0.4.0 → scirodev-0.5.0}/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