pybricks.ev3devices: Re-enable.

Also split out to separate class files like we did for pupdevices.

Also make various EV3 and NXT sensor methods awaitable.

doc/common/conf.py

@@ -192,11 +192,9 @@ htmlhelp_basename = "Pybricksdoc"
 
 
 exclude_patterns = [
-    "ev3devices.rst",
     "hubs/ev3brick.rst",
     "media.rst",
     "messaging.rst",
-    "nxtdevices.rst",
     "tools/datalog.rst",
     "*.rst.txt",
 ]

doc/main/ev3devices.rst

@@ -1,134 +0,0 @@
-:mod:`ev3devices <pybricks.ev3devices>` -- EV3 devices
-======================================================
-
-.. automodule:: pybricks.ev3devices
-    :no-members:
-
-Motors
-^^^^^^^^^^^^
-
-.. _fig_ev3motors:
-
-.. figure:: ../main/diagrams/ev3motors.png
-   :width: 100 %
-
-   EV3-compatible motors. The arrows indicate the default positive direction.
-
-.. autoclass:: pybricks.ev3devices.Motor
-    :noindex:
-    :no-members:
-
-    .. rubric:: Measuring
-
-    .. automethod:: pybricks.ev3devices.Motor.angle
-
-    .. automethod:: pybricks.ev3devices.Motor.reset_angle
-
-    .. automethod:: pybricks.ev3devices.Motor.speed
-
-    .. automethod:: pybricks.ev3devices.Motor.load
-
-    .. automethod:: pybricks.ev3devices.Motor.stalled
-
-    .. rubric:: Stopping
-
-    .. automethod:: pybricks.ev3devices.Motor.stop
-
-    .. automethod:: pybricks.ev3devices.Motor.brake
-
-    .. automethod:: pybricks.ev3devices.Motor.hold
-
-    .. rubric:: Running forever
-
-    .. automethod:: pybricks.ev3devices.Motor.run
-
-    .. automethod:: pybricks.ev3devices.Motor.dc
-
-    .. rubric:: Running by a fixed amount
-
-    .. automethod:: pybricks.ev3devices.Motor.run_time
-
-    .. automethod:: pybricks.ev3devices.Motor.run_angle
-
-    .. automethod:: pybricks.ev3devices.Motor.run_target
-
-    .. automethod:: pybricks.ev3devices.Motor.track_target
-
-    .. automethod:: pybricks.ev3devices.Motor.run_until_stalled
-
-    .. automethod:: pybricks.ev3devices.Motor.done
-
-    .. rubric:: Motor settings
-
-    .. automethod:: pybricks.ev3devices.Motor.settings
-
-    .. rubric:: Control settings
-
-    .. automethod:: pybricks.ev3devices::Motor.control.limits
-
-    .. automethod:: pybricks.ev3devices::Motor.control.pid
-
-    .. automethod:: pybricks.ev3devices::Motor.control.target_tolerances
-
-    .. automethod:: pybricks.ev3devices::Motor.control.stall_tolerances
-
-    .. attribute:: control.scale
-
-        Number of degrees that the motor turns to complete one degree at the
-        output of the gear train. This is the gear ratio determined from the
-        ``gears`` argument when initializing the motor.
-
-Touch Sensor
-^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/ev3device-touch.png
-   :width: 18 %
-
-.. autoclass:: pybricks.ev3devices.TouchSensor
-
-Color Sensor
-^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/ev3device-color.png
-   :width: 18 %
-
-.. autoclass:: pybricks.ev3devices.ColorSensor
-
-Infrared Sensor and Beacon
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Each method of this class puts the sensor in a different *mode*. Switching
-modes takes about one second on this sensor. To make sure that your program
-runs quickly, use only of these methods in your program.
-
-.. figure:: ../main/cad/output/ev3device-infrared.png
-   :width: 60 %
-
-.. autoclass:: pybricks.ev3devices.InfraredSensor
-
-Ultrasonic Sensor
-^^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/ev3device-ultrasonic.png
-   :width: 22 %
-
-.. autoclass:: pybricks.ev3devices.UltrasonicSensor
-
-Gyroscopic Sensor
-^^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/ev3device-gyro.png
-   :width: 18 %
-
-.. autoclass:: pybricks.ev3devices.GyroSensor
-    :no-members:
-
-    .. automethod:: pybricks.ev3devices.GyroSensor.speed
-
-    .. automethod:: pybricks.ev3devices.GyroSensor.angle
-
-         If you use the :meth:`.angle` method, you cannot use the
-         :meth:`.speed` method in the same program. Doing so would reset the
-         sensor angle to zero every time you read the speed.
-
-    .. automethod:: pybricks.ev3devices.GyroSensor.reset_angle

doc/main/ev3devices/colorsensor.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+Color Sensor
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/ev3device-color.png
+   :width: 18 %
+
+.. autoclass:: pybricks.ev3devices.ColorSensor

doc/main/ev3devices/gyrosensor.rst

@@ -0,0 +1,16 @@
+.. pybricks-requirements:: ev3
+
+Gyroscopic Sensor
+^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/ev3device-gyro.png
+   :width: 18 %
+
+.. autoclass:: pybricks.ev3devices.GyroSensor
+    :no-members:
+
+    .. automethod:: pybricks.ev3devices.GyroSensor.speed
+
+    .. automethod:: pybricks.ev3devices.GyroSensor.angle
+
+    .. automethod:: pybricks.ev3devices.GyroSensor.reset_angle

doc/main/ev3devices/index.rst

@@ -0,0 +1,53 @@
+.. pybricks-requirements:: ev3
+
+:mod:`ev3devices <pybricks.ev3devices>` -- EV3 motors and sensors
+=================================================================
+
+.. automodule:: pybricks.ev3devices
+    :no-members:
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   touchsensor
+   colorsensor
+   infraredsensor
+   ultrasonicsensor
+   gyrosensor
+
+.. pybricks-classlink:: Motor ../pupdevices/motor
+
+.. figure:: ../../main/cad/output/ev3device-motors.png
+    :width: 100 %
+    :target: ../pupdevices/motor.html
+
+.. pybricks-classlink:: TouchSensor
+
+.. figure:: ../../main/cad/output/ev3device-touch.png
+   :width: 18 %
+   :target: touchsensor.html
+
+.. pybricks-classlink:: ColorSensor
+
+.. figure:: ../../main/cad/output/ev3device-color.png
+   :width: 18 %
+   :target: colorsensor.html
+
+.. pybricks-classlink:: InfraredSensor
+
+.. figure:: ../../main/cad/output/ev3device-infrared.png
+   :width: 60 %
+   :target: infraredsensor.html
+
+.. pybricks-classlink:: UltrasonicSensor
+
+.. figure:: ../../main/cad/output/ev3device-ultrasonic.png
+   :width: 22 %
+   :target: ultrasonicsensor.html
+
+.. pybricks-classlink:: GyroSensor
+
+.. figure:: ../../main/cad/output/ev3device-gyro.png
+   :width: 18 %
+   :target: gyrosensor.html

doc/main/ev3devices/infraredsensor.rst

@@ -0,0 +1,13 @@
+.. pybricks-requirements:: ev3
+
+Infrared Sensor and Beacon
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each method of this class puts the sensor in a different *mode*. Switching
+modes takes about one second on this sensor. To make sure that your program
+runs quickly, use only one of these methods in your program.
+
+.. figure:: ../../main/cad/output/ev3device-infrared.png
+   :width: 60 %
+
+.. autoclass:: pybricks.ev3devices.InfraredSensor

doc/main/ev3devices/touchsensor.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+Touch Sensor
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/ev3device-touch.png
+   :width: 18 %
+
+.. autoclass:: pybricks.ev3devices.TouchSensor

doc/main/ev3devices/ultrasonicsensor.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+Ultrasonic Sensor
+^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/ev3device-ultrasonic.png
+   :width: 22 %
+
+.. autoclass:: pybricks.ev3devices.UltrasonicSensor

doc/main/index.rst

@@ -54,6 +54,18 @@ above to reveal this menu.
    :width: 70 %
    :target: pupdevices/dcmotor.html
 
+.. rubric:: EV3 motors and sensors
+
+.. figure:: ../main/cad/output/ev3device-all.png
+   :width: 100 %
+   :target: ev3devices/index.html
+
+.. rubric:: NXT motors and sensors
+
+.. figure:: ../main/cad/output/nxtdevice-all.png
+   :width: 100 %
+   :target: nxtdevices/index.html
+
 .. toctree::
     :maxdepth: 1
     :caption: Table of contents
@@ -66,6 +78,8 @@ above to reveal this menu.
 
    hubs/index
    pupdevices/index
+   ev3devices/index
+   nxtdevices/index
    iodevices/index
    parameters/index
    tools/index

doc/main/nxtdevices.rst

@@ -1,101 +0,0 @@
-:mod:`nxtdevices <pybricks.nxtdevices>` -- NXT devices
-======================================================
-
-.. automodule:: pybricks.nxtdevices
-    :no-members:
-
-NXT Motor
-^^^^^^^^^^^^^^^^
-This motor works just like a LEGO MINDSTORMS EV3 Large Motor. You can use it in
-your programs using the :mod:`Motor <.ev3devices>` class.
-
-NXT Touch Sensor
-^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/nxtdevice-touch.png
-   :width: 18 %
-
-.. autoclass:: pybricks.nxtdevices.TouchSensor
-    :no-members:
-
-    .. automethod:: pybricks.nxtdevices.TouchSensor.pressed
-
-NXT Light Sensor
-^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/nxtdevice-light.png
-   :width: 18 %
-
-.. autoclass:: pybricks.nxtdevices.LightSensor
-
-NXT Color Sensor
-^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/nxtdevice-color.png
-   :width: 18 %
-
-.. autoclass:: pybricks.nxtdevices.ColorSensor
-    :no-members:
-
-    .. automethod:: pybricks.nxtdevices.ColorSensor.color
-
-    .. automethod:: pybricks.nxtdevices.ColorSensor.ambient
-
-    .. automethod:: pybricks.nxtdevices.ColorSensor.reflection
-
-    .. automethod:: pybricks.nxtdevices.ColorSensor.rgb
-
-    .. rubric:: Advanced color sensing
-
-    .. automethod:: pybricks.nxtdevices.ColorSensor.hsv
-
-    .. automethod:: pybricks.nxtdevices.ColorSensor.detectable_colors
-
-    .. rubric:: Built-in light
-
-    This sensor has a built-in light. You can make it red, green, blue, or turn
-    it off.
-
-    .. automethod:: pybricks.nxtdevices::ColorSensor.light.on
-
-    .. automethod:: pybricks.nxtdevices::ColorSensor.light.off
-
-NXT Ultrasonic Sensor
-^^^^^^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/nxtdevice-ultrasonic.png
-   :width: 24 %
-
-.. autoclass:: pybricks.nxtdevices.UltrasonicSensor
-
-NXT Sound Sensor
-^^^^^^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/nxtdevice-sound.png
-   :width: 18 %
-
-.. autoclass:: pybricks.nxtdevices.SoundSensor
-
-NXT Temperature Sensor
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/nxtdevice-temperature.png
-   :width: 32 %
-
-.. autoclass:: pybricks.nxtdevices.TemperatureSensor
-
-NXT Energy Meter
-^^^^^^^^^^^^^^^^^
-
-.. figure:: ../main/cad/output/nxtdevice-energy.png
-   :width: 30 %
-
-.. autoclass:: pybricks.nxtdevices.EnergyMeter
-
-Vernier Adapter
-^^^^^^^^^^^^^^^^^
-.. autoclass:: pybricks.nxtdevices.VernierAdapter
-
-**Example: Using the Surface Temperature Sensor.**
-
-.. literalinclude:: ../../examples/ev3/vernier_surface_temperature/main.py

doc/main/nxtdevices/colorsensor.rst

@@ -0,0 +1,33 @@
+.. pybricks-requirements:: ev3
+
+NXT Color Sensor
+^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/nxtdevice-color.png
+   :width: 18 %
+
+.. autoclass:: pybricks.nxtdevices.ColorSensor
+    :no-members:
+
+    .. automethod:: pybricks.nxtdevices.ColorSensor.color
+
+    .. automethod:: pybricks.nxtdevices.ColorSensor.ambient
+
+    .. automethod:: pybricks.nxtdevices.ColorSensor.reflection
+
+    .. automethod:: pybricks.nxtdevices.ColorSensor.rgb
+
+    .. rubric:: Advanced color sensing
+
+    .. automethod:: pybricks.nxtdevices.ColorSensor.hsv
+
+    .. automethod:: pybricks.nxtdevices.ColorSensor.detectable_colors
+
+    .. rubric:: Built-in light
+
+    This sensor has a built-in light. You can make it red, green, blue, or turn
+    it off.
+
+    .. automethod:: pybricks.nxtdevices::ColorSensor.light.on
+
+    .. automethod:: pybricks.nxtdevices::ColorSensor.light.off

doc/main/nxtdevices/energymeter.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+NXT Energy Meter
+^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/nxtdevice-energy.png
+   :width: 30 %
+
+.. autoclass:: pybricks.nxtdevices.EnergyMeter

doc/main/nxtdevices/index.rst

@@ -0,0 +1,70 @@
+.. pybricks-requirements:: ev3
+
+:mod:`nxtdevices <pybricks.nxtdevices>` -- NXT motors and sensors
+=================================================================
+
+.. automodule:: pybricks.nxtdevices
+    :no-members:
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   touchsensor
+   lightsensor
+   colorsensor
+   ultrasonicsensor
+   soundsensor
+   temperaturesensor
+   energymeter
+   vernieradapter
+
+.. pybricks-classlink:: Motor ../pupdevices/motor
+
+.. figure:: ../../main/cad/output/ev3device-motors.png
+    :width: 100 %
+    :target: ../pupdevices/motor.html
+
+.. pybricks-classlink:: TouchSensor
+
+.. figure:: ../../main/cad/output/nxtdevice-touch.png
+   :width: 18 %
+   :target: touchsensor.html
+
+.. pybricks-classlink:: LightSensor
+
+.. figure:: ../../main/cad/output/nxtdevice-light.png
+   :width: 18 %
+   :target: lightsensor.html
+
+.. pybricks-classlink:: ColorSensor
+
+.. figure:: ../../main/cad/output/nxtdevice-color.png
+   :width: 18 %
+   :target: colorsensor.html
+
+.. pybricks-classlink:: UltrasonicSensor
+
+.. figure:: ../../main/cad/output/nxtdevice-ultrasonic.png
+   :width: 24 %
+   :target: ultrasonicsensor.html
+
+.. pybricks-classlink:: SoundSensor
+
+.. figure:: ../../main/cad/output/nxtdevice-sound.png
+   :width: 18 %
+   :target: soundsensor.html
+
+.. pybricks-classlink:: TemperatureSensor
+
+.. figure:: ../../main/cad/output/nxtdevice-temperature.png
+   :width: 32 %
+   :target: temperaturesensor.html
+
+.. pybricks-classlink:: EnergyMeter
+
+.. figure:: ../../main/cad/output/nxtdevice-energy.png
+   :width: 30 %
+   :target: energymeter.html
+
+.. pybricks-classlink:: VernierAdapter

doc/main/nxtdevices/lightsensor.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+NXT Light Sensor
+^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/nxtdevice-light.png
+   :width: 18 %
+
+.. autoclass:: pybricks.nxtdevices.LightSensor

doc/main/nxtdevices/soundsensor.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+NXT Sound Sensor
+^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/nxtdevice-sound.png
+   :width: 18 %
+
+.. autoclass:: pybricks.nxtdevices.SoundSensor

doc/main/nxtdevices/temperaturesensor.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+NXT Temperature Sensor
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/nxtdevice-temperature.png
+   :width: 32 %
+
+.. autoclass:: pybricks.nxtdevices.TemperatureSensor

doc/main/nxtdevices/touchsensor.rst

@@ -0,0 +1,12 @@
+.. pybricks-requirements:: ev3
+
+NXT Touch Sensor
+^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/nxtdevice-touch.png
+   :width: 18 %
+
+.. autoclass:: pybricks.nxtdevices.TouchSensor
+    :no-members:
+
+    .. automethod:: pybricks.nxtdevices.TouchSensor.pressed

doc/main/nxtdevices/ultrasonicsensor.rst

@@ -0,0 +1,9 @@
+.. pybricks-requirements:: ev3
+
+NXT Ultrasonic Sensor
+^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/cad/output/nxtdevice-ultrasonic.png
+   :width: 24 %
+
+.. autoclass:: pybricks.nxtdevices.UltrasonicSensor

doc/main/nxtdevices/vernieradapter.rst

@@ -0,0 +1,15 @@
+.. pybricks-requirements:: ev3
+
+Vernier Adapter
+^^^^^^^^^^^^^^^
+
+.. autoclass:: pybricks.nxtdevices.VernierAdapter
+
+Examples
+-------------------
+
+Using the Surface Temperature Sensor
+************************************
+
+.. literalinclude::
+    ../../../examples/ev3/vernier_surface_temperature/main.py

src/pybricks/_common.py

@@ -38,6 +38,8 @@ if TYPE_CHECKING:
 
     class MaybeAwaitableTuple(Tuple[_T_co], Awaitable[Tuple[_T_co]]): ...
 
+    class MaybeAwaitableSet(Set[_T_co], Awaitable[Set[_T_co]]): ...
+
     class MaybeAwaitableColor(Color, Awaitable[Color]): ...
 
     class MaybeAwaitableBytes(bytes, Awaitable[bytes]): ...

src/pybricks/ev3devices.py

@@ -3,7 +3,9 @@
 
 """LEGO® MINDSTORMS® EV3 motors and sensors."""
 
-from typing import Optional, Tuple, List, Set
+from __future__ import annotations
+
+from typing import Optional, Tuple, List
 
 from . import _common
 from .parameters import (
@@ -13,6 +15,20 @@ from .parameters import (
     Port as _Port,
 )
 
+from typing import (
+    TYPE_CHECKING,
+)
+
+if TYPE_CHECKING:
+    from ._common import (
+        MaybeAwaitableColor,
+        MaybeAwaitableBool,
+        MaybeAwaitableInt,
+        MaybeAwaitableSet,
+        MaybeAwaitableTuple,
+    )
+    from .parameters import Number, Port
+
 
 class Motor(_common.Motor):
     """LEGO® MINDSTORMS® EV3 Motor."""
@@ -49,7 +65,7 @@ class ColorSensor:
             port (Port): Port to which the sensor is connected.
         """
 
-    def color(self) -> Optional[_Color]:
+    def color(self) -> MaybeAwaitableColor:
         """color() -> Color
 
         Measures the color of a surface.
@@ -61,7 +77,7 @@ class ColorSensor:
 
         """
 
-    def ambient(self) -> int:
+    def ambient(self) -> MaybeAwaitableInt:
         """ambient() -> int: %
 
         Measures the ambient light intensity.
@@ -71,18 +87,18 @@ class ColorSensor:
             to 100% (bright).
         """
 
-    def reflection(self) -> int:
+    def reflection(self) -> MaybeAwaitableInt:
         """reflection() -> int: %
 
-        Measures the reflection of a surface using a red light.
+        Measures how much a surface reflects the light emitted by the
+        sensor.
 
         Returns:
-            Reflection, ranging from 0% (no reflection) to
+            Measured reflection, ranging from 0% (no reflection) to
             100% (high reflection).
-
         """
 
-    def rgb(self) -> Tuple[int, int, int]:
+    def rgb(self) -> MaybeAwaitableTuple[int, int, int]:
         """rgb() -> Tuple[int, int, int]
 
         Measures the reflection of a surface using a red, green, and then a
@@ -105,7 +121,7 @@ class InfraredSensor:
 
         """
 
-    def distance(self) -> int:
+    def distance(self) -> MaybeAwaitableInt:
         """distance() -> int: %
 
         Measures the relative distance between the sensor and an object using
@@ -117,7 +133,7 @@ class InfraredSensor:
 
         """
 
-    def beacon(self, channel: int) -> Tuple[Optional[int], Optional[int]]:
+    def beacon(self, channel: int) -> MaybeAwaitableTuple[Optional[int], Optional[int]]:
         """
         beacon(channel) -> Tuple[int, int]
         beacon(channel) -> Tuple[None, None]
@@ -134,7 +150,7 @@ class InfraredSensor:
             a tuple of (``None``, ``None``) if no remote is detected.
         """
 
-    def buttons(self, channel: int) -> Set[_Button]:
+    def buttons(self, channel: int) -> MaybeAwaitableSet[_Button]:
         """buttons(channel) -> Set[Button]
 
         Checks which buttons on the infrared remote are pressed.
@@ -146,12 +162,12 @@ class InfraredSensor:
             channel (int): Channel number of the remote.
 
         Returns:
-            List of pressed buttons on the remote on the selected channel.
+            Set of pressed buttons on the remote on the selected channel.
 
         """
 
-    def keypad(self) -> List[_Button]:
+    def keypad(self) -> MaybeAwaitableSet[_Button]:
-        """keypad() -> List[Button]
+        """keypad() -> Set[Button]
 
         Checks which buttons on the infrared remote are pressed.
 
@@ -161,7 +177,7 @@ class InfraredSensor:
         This method only works with the remote in channel 1.
 
         Returns:
-            List of pressed buttons.
+            Set of pressed buttons.
         """
 
 
@@ -220,7 +236,7 @@ class UltrasonicSensor:
 
         """
 
-    def distance(self, silent: bool = False) -> int:
+    def distance(self, silent: bool = False) -> MaybeAwaitableInt:
         """distance(silent=False) -> int: mm
 
         Measures the distance between the sensor and an object using
@@ -238,7 +254,7 @@ class UltrasonicSensor:
 
         """
 
-    def presence(self) -> bool:
+    def presence(self) -> MaybeAwaitableBool:
         """presence() -> bool
 
         Checks for the presence of other ultrasonic sensors by detecting