scirodev 0.4.1__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.4.1
+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.1 → 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.1 → scirodev-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scirodev"
-version = "0.4.1"
+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.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.1 → scirodev-0.5.0}/scirodev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.4.1
+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.1 → 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