scirodev 0.5.0__tar.gz → 0.5.3__tar.gz

{scirodev-0.5.0/scirodev.egg-info → scirodev-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.5.0
+Version: 0.5.3
 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
@@ -89,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.5.0 → scirodev-0.5.3}/README.md

@@ -69,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.5.0 → scirodev-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scirodev"
-version = "0.5.0"
+version = "0.5.3"
 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.5.0 → scirodev-0.5.3}/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.5.0 → scirodev-0.5.3}/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.3/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.5.0 → scirodev-0.5.3}/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.3/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.0 → scirodev-0.5.3}/sciro/tools.py

@@ -4,7 +4,56 @@ helpers. EXPERIMENTAL: the API may still change between releases.
 
 from __future__ import annotations
 
-from typing import Awaitable, Callable, Iterable, Iterator, Optional, Sequence, Tuple
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Awaitable,
+    Callable,
+    Iterable,
+    Iterator,
+    Optional,
+    Sequence,
+    Tuple,
+)
+
+if TYPE_CHECKING:
+    from pybricks._common import MaybeAwaitableTuple
+else:
+    # Upstream defines this only for type checkers; runtime importers of the
+    # stubs (the docs build) need a value. Annotations are strings here
+    # (from __future__ import annotations), so a placeholder suffices.
+    MaybeAwaitableTuple = None
+
+
+def multitask(*coroutines: Awaitable[Any], race: bool = False) -> MaybeAwaitableTuple:
+    """multitask(coroutine1, coroutine2, ..., race=False) -> Tuple
+
+    ``pybricks.tools.multitask`` (the same function on the hub), typed to
+    accept any awaitable.
+
+    The upstream stub asks for ``Coroutine``, which every *maybe-awaitable*
+    hub method fails to satisfy for a type checker: ``motor.run_angle(...)``,
+    ``db.straight(...)`` or ``sensor.read()`` are declared as awaitables, not
+    as coroutines, because they return a plain value when called outside
+    ``run_task``. Importing ``multitask`` (and :func:`run_task`) from
+    ``sciro.tools`` instead of ``pybricks.tools`` removes those warnings::
+
+        from sciro.tools import multitask, run_task
+
+        async def main():
+            await multitask(db.straight(500), log.record(db.state), race=True)
+
+        run_task(main())
+    """
+
+
+def run_task(coroutine: Optional[Awaitable[Any]] = None) -> Optional[bool]:
+    """run_task(coroutine) -> bool | None
+
+    ``pybricks.tools.run_task`` (the same function on the hub), typed to
+    accept any awaitable; see :func:`multitask`. Without an argument it
+    returns whether the run loop is active.
+    """
 
 
 class RingBuffer:
@@ -65,7 +114,8 @@ class Logger:
     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
+    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,

{scirodev-0.5.0 → scirodev-0.5.3/scirodev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scirodev
-Version: 0.5.0
+Version: 0.5.3
 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
@@ -89,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.5.0 → scirodev-0.5.3}/scirodev.egg-info/requires.txt

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

scirodev-0.5.0/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

scirodev-0.5.0/sciro/robotics.py

@@ -1,84 +0,0 @@
-"""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.
-        """