pybricks 3.2.0rc2__tar.gz → 3.3.0a5__tar.gz

{pybricks-3.2.0rc2 → pybricks-3.3.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pybricks
-Version: 3.2.0rc2
+Version: 3.3.0a5
 Summary: Documentation and user-API stubs for Pybricks MicroPython
 Home-page: https://pybricks.com
 License: MIT
@@ -35,6 +35,11 @@ used to generate the `official documentation`_.
 See the `contributor's guide <CONTRIBUTING.md>`_ for acceptable changes and
 instructions to build the documentation locally.
 
+You can use the API stubs in this repository for syntax highlighting and code
+completion when programming the EV3 with VS Code. To enable, remove the
+``"python.languageServer"="None"`` line in the ``.vscode/settings.json`` file
+generated by the *LEGO® MINDSTORMS® EV3 MicroPython* extension.
+
 For general discussion, please visit the `support`_ issue tracker.
 
 .. _Pybricks package: pybricks

{pybricks-3.2.0rc2 → pybricks-3.3.0a5}/README.rst

@@ -12,6 +12,11 @@ used to generate the `official documentation`_.
 See the `contributor's guide <CONTRIBUTING.md>`_ for acceptable changes and
 instructions to build the documentation locally.
 
+You can use the API stubs in this repository for syntax highlighting and code
+completion when programming the EV3 with VS Code. To enable, remove the
+``"python.languageServer"="None"`` line in the ``.vscode/settings.json`` file
+generated by the *LEGO® MINDSTORMS® EV3 MicroPython* extension.
+
 For general discussion, please visit the `support`_ issue tracker.
 
 .. _Pybricks package: pybricks

{pybricks-3.2.0rc2 → pybricks-3.3.0a5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.2.0c2"
+version = "3.3.0a5"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <dev@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]
@@ -29,10 +29,12 @@ packages = [
 [tool.poetry.dependencies]
 python = "^3.8"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.lint.dependencies]
 black = "^22.3.0"
 doc8 = "^0.8.1"
 flake8 = "^4.0"
+
+[tool.poetry.group.doc.dependencies]
 Sphinx = { git = "https://github.com/pybricks/sphinx.git", rev = "b00124cb" }
 sphinx-rtd-theme = "^1.0.0"
 toml = "^0.10.0"

{pybricks-3.2.0rc2 → pybricks-3.3.0a5}/src/pybricks/_common.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2018-2021 The Pybricks Authors
+# Copyright (c) 2018-2023 The Pybricks Authors
 
 """Generic cross-platform module for typical devices like lights, displays,
 speakers, and batteries."""
@@ -8,8 +8,8 @@ from __future__ import annotations
 
 from typing import Union, Iterable, overload, Optional, Tuple, Collection, TYPE_CHECKING
 
-from .geometry import Matrix, Axis
-from .parameters import Direction, Stop, Button, Port, Color, Side
+from .tools import Matrix
+from .parameters import Axis, Direction, Stop, Button, Port, Color, Side
 
 if TYPE_CHECKING:
     from .parameters import Number
@@ -219,18 +219,18 @@ class Control:
         kp: Optional[Number] = None,
         ki: Optional[Number] = None,
         kd: Optional[Number] = None,
-        reserved: Optional[Number] = None,
+        integral_deadzone: Optional[Number] = None,
         integral_rate: Optional[Number] = None,
     ) -> None:
         ...
 
     @overload
-    def pid(self) -> Tuple[int, int, int, None, int]:
+    def pid(self) -> Tuple[int, int, int, int, int]:
         ...
 
     def pid(self, *args):
-        """pid(kp, ki, kd, reserved, integral_rate)
-        pid() -> Tuple[int, int, int, None, int]
+        """pid(kp, ki, kd, integral_deadzone, integral_rate)
+        pid() -> Tuple[int, int, int, int, int]
 
         Gets or sets the PID values for position and speed control.
 
@@ -245,7 +245,8 @@ class Control:
             kd (int): Derivative position (or proportional speed) control
                 constant. It is the feedback torque per
                 unit of speed: µNm/(deg/s).
-            reserved: This setting is not used.
+            integral_deadzone (Number, deg or Number, mm): Zone around the
+                target where the error integral does not accumulate errors.
             integral_rate (Number, deg/s or Number, mm/s): Maximum rate at
                 which the error integral is allowed to grow.
         """
@@ -303,6 +304,52 @@ class Control:
         """
 
 
+class Model:
+    """Class to interact with motor state observer and settings."""
+
+    def state(self) -> Tuple[float, float, float, bool]:
+        """state() -> Tuple[float, float, float, bool]
+
+        Gets the estimated angle, speed, current, and stall state of the motor,
+        using a simulation model that mimics the real motor.
+        These estimates are updated faster than the real measurements,
+        which can be useful when building your own PID controllers.
+
+        For most applications it is better to used the *measured*
+        :meth:`angle <pybricks.pupdevices.Motor.angle>`,
+        :meth:`speed <pybricks.pupdevices.Motor.speed>`,
+        :meth:`load <pybricks.pupdevices.Motor.load>`, and
+        :meth:`stall <pybricks.pupdevices.Motor.stalled>` state instead.
+
+        Returns:
+            Tuple with the estimated angle (deg), speed (deg/s), current (mA),
+            and stall state (``True`` or ``False``).
+        """
+
+    @overload
+    def settings(self, values: tuple) -> None:
+        ...
+
+    @overload
+    def settings(self) -> tuple:
+        ...
+
+    def settings(self, speed, time):
+        """settings(values)
+        settings() -> Tuple
+
+        Gets or sets model settings as a tuple of integers. If no arguments are
+        given, this will return the current values. This method is mainly used
+        to debug the motor model class. Changing these settings should not be
+        needed in user programs.
+
+        .. _model settings: https://docs.pybricks.com/projects/pbio/en/latest/struct__pbio__observer__settings__t.html
+
+        Arguments:
+            values (Tuple): Tuple with `model settings`_.
+        """
+
+
 class Motor(DCMotor):
     """Generic class to control motors with built-in rotation sensors."""
 
@@ -312,14 +359,18 @@ class Motor(DCMotor):
     ``control`` attribute of the motor. See :ref:`control` for an overview
     of available methods."""
 
+    model = Model()
+    """Model representing the observer that estimates the motor state."""
+
     def __init__(
         self,
         port: Port,
         positive_direction: Direction = Direction.CLOCKWISE,
         gears: Optional[Union[Collection[int], Collection[Collection[int]]]] = None,
         reset_angle: bool = True,
+        profile: Number = None,
     ):
-        """__init__(port, positive_direction=Direction.CLOCKWISE, gears=None, reset_angle=True)
+        """__init__(port, positive_direction=Direction.CLOCKWISE, gears=None, reset_angle=True, profile=None)
 
         Arguments:
             port (Port): Port to which the motor is connected.
@@ -336,12 +387,16 @@ class Motor(DCMotor):
                 When you specify a gear train, all motor commands and settings
                 are automatically adjusted to account for the resulting gear
                 ratio.  The motor direction remains unchanged by this.
-            reset_angle(bool):
+            reset_angle (bool):
                 Choose ``True`` to reset the rotation sensor value to the
                 absolute marker angle (between -180 and 179).
                 Choose ``False`` to keep the
                 current value, so your program knows where it left off last
                 time.
+            profile (Number, deg): Precision profile. A lower value
+                means more precise movement; a larger value means
+                smoother movement. If no value is given, a suitable profile for
+                this motor type will be selected automatically.
         """
 
     def angle(self) -> int:
@@ -353,11 +408,19 @@ class Motor(DCMotor):
             Motor angle.
         """
 
-    def speed(self) -> int:
-        """speed() -> int: deg/s
+    def speed(self, window: Number = 100) -> int:
+        """speed(window=100) -> int: deg/s
 
         Gets the speed of the motor.
 
+        The speed is measured as the change in the motor angle during the
+        given time window. A short window makes the speed value more
+        responsive to motor movement, but less steady. A long window makes the
+        speed value less responsive, but more steady.
+
+        Arguments:
+            window (Number, ms): The time window used to determine the speed.
+
         Returns:
             Motor speed.
 
@@ -731,7 +794,7 @@ class LightMatrix:
 
         Arguments:
             matrices (iter): Sequence of
-                :class:`Matrix <pybricks.geometry.Matrix>` of intensities.
+                :class:`Matrix <pybricks.tools.Matrix>` of intensities.
             interval (Number, ms): Time to display each image in the list.
         """
 
@@ -928,22 +991,94 @@ class Accelerometer(SimpleAccelerometer):
         along the x-axis.
 
         Returns:
-            Tuple of pitch and roll angles.
+            Tuple of pitch and roll angles in degrees.
         """
 
 
 class IMU(Accelerometer):
+    def ready(self) -> bool:
+        """ready() -> bool
+
+        Checks if the device is calibrated and ready for use.
+
+        This becomes ``True`` when the robot has been sitting stationary for a
+        few seconds, which allows the device to re-calibrate. It is ``False``
+        if the hub has just been started, or if it hasn't had a chance to
+        calibrate for more than 10 minutes.
+
+        Returns:
+            ``True`` if it is ready for use, ``False`` if not.
+        """
+
+    def stationary(self) -> bool:
+        """stationary() -> bool
+
+        Checks if the device is currently stationary (not moving).
+
+        Returns:
+            ``True`` if stationary for at least a second, ``False`` if it is
+            moving.
+        """
+
+    @overload
+    def settings(
+        self,
+        angular_velocity_threshold: float = None,
+        acceleration_threshold: float = None,
+    ) -> None:
+        ...
+
+    @overload
+    def settings(self) -> Tuple[float, float]:
+        ...
+
+    def settings(self, *args):
+        """
+        settings(angular_velocity_threshold, acceleration_threshold)
+        settings() -> Tuple[float, float]
+
+        Configures the IMU settings. If no arguments are given,
+        this returns the current values.
+
+        The ``angular_velocity_threshold`` and ``acceleration_threshold``
+        define when the hub is considered stationary. If all
+        measurements stay below these thresholds for one second, the IMU
+        will recalibrate itself.
+
+        In a noisy room with high ambient vibrations (such as a
+        competition hall), it is recommended to increase the thresholds
+        slightly to give your robot the chance to calibrate.
+        To verify that your settings are working as expected, test that
+        the ``stationary()`` method gives ``False`` if your robot is moving,
+        and ``True`` if it is sitting still for at least a second.
+
+        Arguments:
+            angular_velocity_threshold (Number, deg/s): The threshold for
+                angular velocity. The default value is 1.5 deg/s.
+            acceleration_threshold (Number, mm/s²): The threshold for angular
+                velocity. The default value is 250 mm/s².
+        """
+
     def heading(self) -> float:
         """heading() -> float: deg
 
-        Gets the heading angle relative to the starting orientation. It is a
-        positive rotation around the :ref:`z-axis in the robot
-        frame <robotframe>`, prior to applying any tilt rotation.
+        Gets the heading angle of your robot. A positive value means a
+        clockwise turn.
 
-        For a vehicle viewed from the top, this means that
-        a positive heading value corresponds to a counterclockwise rotation.
+        The heading is 0 when your program starts. The value continues to grow
+        even as the robot turns more than 180 degrees. It does not wrap around
+        to -180 like it does in some apps.
 
-        .. note:: This method is not yet implemented.
+
+        .. note:: *For now, this method only keeps track of the heading while
+                  the robot is on a flat surface.*
+
+                  This means that the value is
+                  no longer correct if you lift it from the table. To solve
+                  this, you can call ``reset_heading`` to reset the heading to
+                  a known value *after* you put it back down. For example, you
+                  could align your robot with the side of the competition table
+                  and reset the heading 90 degrees as the new starting point.
 
         Returns:
             Heading angle relative to starting orientation.
@@ -955,8 +1090,6 @@ class IMU(Accelerometer):
 
         Resets the accumulated heading angle of the robot.
 
-        .. note:: This method is not yet implemented.
-
         Arguments:
             angle (Number, deg): Value to which the heading should be reset.
         """
@@ -985,6 +1118,41 @@ class IMU(Accelerometer):
             this returns a vector of accelerations along all axes.
         """
 
+    def rotation(self, axis: Axis) -> float:
+        """
+        rotation(axis) -> float: deg
+
+        Gets the rotation of the device along a given axis in
+        the :ref:`robot reference frame <robotframe>`.
+
+        This value is useful if your robot *only* rotates along the requested
+        axis. For general three-dimensional motion, use the
+        ``orientation()`` method instead.
+
+        The value starts counting from ``0`` when you initialize this class.
+
+        Arguments:
+            axis (Axis): Axis along which the rotation should be measured.
+        Returns:
+            The rotation angle.
+        """
+
+    def orientation(self) -> Matrix:
+        """
+        orientation() -> Matrix
+
+        Gets the three-dimensional orientation of the robot in
+        the :ref:`robot reference frame <robotframe>`.
+
+        It returns a rotation matrix whose columns represent the ``X``, ``Y``,
+        and ``Z`` axis of the robot.
+
+        .. note:: This method is not yet implemented.
+
+        Returns:
+            The rotation matrix.
+        """
+
 
 class CommonColorSensor:
     """Generic color sensor that supports Pybricks color calibration."""
@@ -1117,3 +1285,79 @@ class AmbientColorSensor(CommonColorSensor):
             Measured color. The color is described by a hue (0--359), a
             saturation (0--100), and a brightness value (0--100).
         """
+
+
+class BLE:
+    """
+    Bluetooth Low Energy.
+
+    .. versionadded:: 3.3
+    """
+
+    def broadcast(self, *args: Union[None, bool, int, float, str, bytes]) -> None:
+        """broadcast(data0, data1, ...)
+
+        Starts broadcasting the given data values.
+
+        Each value can be any of ``int``, ``float``, ``str`, ``bytes``,
+        ``None``, ``True``, or ``False``. The data is broadcasted on the
+        *broadcast_channel* you selected when initializing the hub.
+
+        The total data size is quite limited (26 bytes). ``None``, ``True`` and
+        ``False`` take 1 byte each. ``float`` takes 5 bytes. ``int`` takes 2 to
+        5 bytes depending on how big the number is. ``str`` and ``bytes`` take
+        the number of bytes in the object plus one extra byte.
+
+        Params:
+            args: Zero or more values to be broadcast.
+
+
+
+        .. versionadded:: 3.3
+        """
+
+    def observe(
+        self, channel: int
+    ) -> Optional[Tuple[Union[None, bool, int, float, str, bytes], ...]]:
+        """observe(channel) -> tuple | None
+
+        Retrieves the last observed data for a given channel.
+
+        Args:
+            channel (int): The channel to observe (0 to 255).
+
+        Returns:
+            A tuple of the received data or ``None`` if no recent data is
+            available.
+
+        .. tip:: Receiving data is more reliable when the hub is not connected
+            to a computer or other devices at the same time.
+
+        .. versionadded:: 3.3
+        """
+
+    def signal_strength(self, channel: int) -> int:
+        """signal_strength(channel) -> int: dBm
+
+        Gets the average signal strength in dBm for the given channel.
+
+        This is useful for detecting how near the broadcasting device is. A close
+        device may have a signal strength around -40 dBm while a far away device
+        might have a signal strength around -70 dBm.
+
+        Args:
+            channel (int): The channel number (0 to 255).
+
+        Returns:
+            The signal strength or ``-128`` if there is no recent observed data.
+
+        .. versionadded:: 3.3
+        """
+
+    def version(self) -> str:
+        """version() -> str
+
+        Gets the firmware version from the Bluetooth chip.
+
+        .. versionadded:: 3.3
+        """

{pybricks-3.2.0rc2 → pybricks-3.3.0a5}/src/pybricks/ev3devices.py

@@ -168,14 +168,12 @@ class InfraredSensor:
 class GyroSensor:
     """LEGO® MINDSTORMS® EV3 Gyro Sensor."""
 
-    def __init__(
-        self, port: _Port, positive_direction: _Direction = _Direction.CLOCKWISE
-    ):
+    def __init__(self, port: _Port, direction: _Direction = _Direction.CLOCKWISE):
         """GyroSensor(port)
 
         Arguments:
             port (Port): Port to which the sensor is connected.
-            positive_direction (Direction):
+            direction (Direction):
                 Positive rotation direction when looking at the red dot on top
                 of the sensor.
 

{pybricks-3.2.0rc2 → pybricks-3.3.0a5}/src/pybricks/hubs.py

@@ -1,12 +1,14 @@
 # SPDX-License-Identifier: MIT
-# Copyright (c) 2018-2022 The Pybricks Authors
+# Copyright (c) 2018-2023 The Pybricks Authors
 
 """LEGO® Programmable Hubs."""
+
+from typing import Sequence
+
 from . import _common
 from .ev3dev import _speaker
-from .geometry import Axis
 from .media.ev3dev import Image as _Image
-from .parameters import Button as _Button
+from .parameters import Button as _Button, Axis
 
 
 class EV3Brick:
@@ -39,6 +41,25 @@ class MoveHub:
     imu = _common.SimpleAccelerometer()
     system = _common.System()
     button = _common.Keypad([_Button.CENTER])
+    ble = _common.BLE()
+
+    def __init__(
+        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+    ):
+        """MoveHub(broadcast_channel=0, observe_channels=[])
+
+        Arguments:
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
+        """
 
 
 class CityHub:
@@ -50,6 +71,25 @@ class CityHub:
     light = _common.ColorLight()
     system = _common.System()
     button = _common.Keypad([_Button.CENTER])
+    ble = _common.BLE()
+
+    def __init__(
+        self, broadcast_channel: int = 0, observe_channels: Sequence[int] = []
+    ):
+        """CityHub(broadcast_channel=0, observe_channels=[])
+
+        Arguments:
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
+        """
 
 
 class TechnicHub:
@@ -62,9 +102,16 @@ class TechnicHub:
     imu = _common.IMU()
     system = _common.System()
     button = _common.Keypad([_Button.CENTER])
+    ble = _common.BLE()
 
-    def __init__(self, top_side: Axis = Axis.Z, front_side: Axis = Axis.X):
-        """TechnicHub(top_side=Axis.Z, front_side=Axis.X)
+    def __init__(
+        self,
+        top_side: Axis = Axis.Z,
+        front_side: Axis = Axis.X,
+        broadcast_channel: int = 0,
+        observe_channels: Sequence[int] = [],
+    ):
+        """TechnicHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -76,6 +123,16 @@ class TechnicHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
         """
 
 
@@ -90,9 +147,16 @@ class EssentialHub:
     light = _common.ColorLight()
     imu = _common.IMU()
     system = _common.System()
+    ble = _common.BLE()
 
-    def __init__(self, top_side=Axis.Z, front_side=Axis.X):
-        """__init__(top_side=Axis.Z, front_side=Axis.X)
+    def __init__(
+        self,
+        top_side: Axis = Axis.Z,
+        front_side: Axis = Axis.X,
+        broadcast_channel: int = 0,
+        observe_channels: Sequence[int] = [],
+    ):
+        """EssentialHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -104,6 +168,16 @@ class EssentialHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
         """
         pass
 
@@ -128,9 +202,16 @@ class PrimeHub:
     speaker = _common.Speaker()
     imu = _common.IMU()
     system = _common.System()
+    ble = _common.BLE()
 
-    def __init__(self, top_side: Axis = Axis.Z, front_side: Axis = Axis.X):
-        """PrimeHub(top_side=Axis.Z, front_side=Axis.X)
+    def __init__(
+        self,
+        top_side: Axis = Axis.Z,
+        front_side: Axis = Axis.X,
+        broadcast_channel: int = 0,
+        observe_channels: Sequence[int] = [],
+    ):
+        """PrimeHub(top_side=Axis.Z, front_side=Axis.X, broadcast_channel=0, observe_channels=[])
 
         Initializes the hub. Optionally, specify how the hub is
         :ref:`placed in your design <robotframe>` by saying in which
@@ -142,6 +223,16 @@ class PrimeHub:
                 the hub.
             front_side (Axis): The axis that passes through the *front side* of
                 the hub.
+            broadcast_channel:
+                A value from 0 to 255 indicating which channel ``hub.ble.broadcast()``
+                will use. Default is channel 0.
+            observe_channels:
+                A list of channels to listen to when ``hub.ble.observe()`` is
+                called. Listening to more channels requires more memory.
+                Default is an empty list (no channels).
+
+        .. versionchanged:: 3.3
+            Added *broadcast_channel* and *observe_channels* arguments.
         """
 
 

{pybricks-3.2.0rc2 → pybricks-3.3.0a5}/src/pybricks/parameters.py

@@ -9,7 +9,7 @@ from enum import Enum
 from typing import Union, TYPE_CHECKING
 import os
 
-from .geometry import Matrix as _Matrix
+from .tools import Matrix as _Matrix, vector as _vector
 
 if TYPE_CHECKING or os.environ.get("SPHINX_BUILD") == "True":
     Number = Union[int, float]
@@ -57,6 +57,20 @@ class _PybricksEnum(Enum, metaclass=_PybricksEnumMeta):
         return str(self)
 
 
+class Axis:
+    """Unit axes of a coordinate system.
+
+    .. data:: X = vector(1, 0, 0)
+    .. data:: Y = vector(0, 1, 0)
+    .. data:: Z = vector(0, 0, 1)
+
+    """
+
+    X: _Matrix = _vector(1, 0, 0)
+    Y: _Matrix = _vector(0, 1, 0)
+    Z: _Matrix = _vector(0, 0, 1)
+
+
 class Color:
     """Light or surface color."""