Michel2/pybricks-api
1
0
Fork 0
mirror of https://github.com/pybricks/pybricks-api.git synced 2026-09-11 09:05:07 +00:00
Code Issues Releases Activity

pybricks.ev3devices: Re-enable.

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

Also make various EV3 and NXT sensor methods awaitable.
This commit is contained in:
Laurens Valk
2026-08-25 09:26:17 +02:00
parent bc70549edd
commit 8dba975894
21 changed files with 333 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/common/conf.py
-2
View File
@@ -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
-134
View File
@@ -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
+9
View File
@@ -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
+16
View File
@@ -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
+53
View File
@@ -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
+13
View File
@@ -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
+9
View File
@@ -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
+9
View File
@@ -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
+14
View File
@@ -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
-101
View File
@@ -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
+33
View File
@@ -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
+9
View File
@@ -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
+70
View File
@@ -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
+9
View File
@@ -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
+9
View File
@@ -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
+9
View File
@@ -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
+12
View File
@@ -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
+9
View File
@@ -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
+15
View File
@@ -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
+2
View File
@@ -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
+33 -17
View File
@@ -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]:
"""keypad() -> List[Button]
def keypad(self) -> MaybeAwaitableSet[_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