From e453cecb2e41fb5d4f10f03b473d19a0a2a13c9f Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Tue, 2 Jul 2019 11:57:00 +0200 Subject: [PATCH] api: accelerometer drafts --- doc/common/signaltypes.rst | 29 ++++++++++++++++++++++++++++- doc/lpf2/lpf2devices.rst | 9 +++++++++ doc/lpf2/parameters.rst | 6 ++++++ pybricks/_common.py | 21 ++++++++++++++++++++- pybricks/lpf2devices.py | 27 ++++++++++++++++++++++++--- pybricks/parameters.py | 32 ++++++++++++++++++++++++++++++++ pybricks/robotics.py | 4 ++-- 7 files changed, 121 insertions(+), 7 deletions(-) diff --git a/doc/common/signaltypes.rst b/doc/common/signaltypes.rst index a7636b6..55480c6 100644 --- a/doc/common/signaltypes.rst +++ b/doc/common/signaltypes.rst @@ -1,6 +1,9 @@ Signals and Units ================= +Units +~~~~~~ + Many commands allow you to specify arguments in terms of well-known physical quantities. This page gives an overview of each quantity and its unit. @@ -97,7 +100,7 @@ For example, the distance value of the :meth:`InfraredSensor -.. _travelspeed: +.. _linspeed: speed: mm/s ------------ @@ -105,6 +108,13 @@ Linear speeds are expressed as millimeters per second (mm/s). For example, the speed of a robotic vehicle is expressed in mm/s. +.. _linacceleration: + +linear acceleration: mm/s/s +-------------------------------- + +TODO + .. _acceleration: rotational acceleration: deg/s/s @@ -187,3 +197,20 @@ Electrical currents are expressed in milliampere (mA). For example, you can check the current supplied by the :meth:`battery <.ev3brick.battery.current>`. + +Scalars and Vectors +~~~~~~~~~~~~~~~~~~~~~~~ + +.. _scalar: + +scalar +-------------- + +TODO + +.. _vector: + +vector +-------------- + +TODO diff --git a/doc/lpf2/lpf2devices.rst b/doc/lpf2/lpf2devices.rst index 7eff05c..2c87adb 100644 --- a/doc/lpf2/lpf2devices.rst +++ b/doc/lpf2/lpf2devices.rst @@ -123,6 +123,15 @@ Color and Distance Sensor .. automethod:: pybricks._common.light.off + +Tilt Sensor +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. autoclass:: pybricks.lpf2devices.TiltSensor + :no-members: + + .. automethod:: acceleration + Other Devices --------------- diff --git a/doc/lpf2/parameters.rst b/doc/lpf2/parameters.rst index be2a2d6..4a9cc37 100644 --- a/doc/lpf2/parameters.rst +++ b/doc/lpf2/parameters.rst @@ -25,3 +25,9 @@ .. autoclass:: pybricks.parameters.Button :no-members: + +.. autoclass:: pybricks.parameters.Side + :no-members: + +.. autoclass:: pybricks.parameters.Axis + :no-members: diff --git a/pybricks/_common.py b/pybricks/_common.py index 2056137..da3482e 100644 --- a/pybricks/_common.py +++ b/pybricks/_common.py @@ -2,7 +2,7 @@ speakers, and batteries.""" from types import ModuleType -from .parameters import Align, Direction, Stop +from .parameters import Align, Direction, Stop, Side, Axis class Motor(): @@ -608,6 +608,25 @@ class Battery(): pass +class Accelerometer(): + """Get measurements from an accelerometer.""" + + def acceleration(self, axis=None): + """Measure the acceleration of the device along a given axis. + + Arguments: + axis (Axis): Body frame axis along which the acceleration is + measured. (*Default*: ``None``) + Returns: + :ref:`linacceleration`. Returns a :ref:`scalar` of the acceleration + along the specified axis. + If ``axis`` is ``None``, you get a :ref:`vector` with the + accelerations along all three body axes (x, y, z). + + """ + pass + + # Workaround for documenting instance attributes such as of the # the ColorDistanceSensor. Autodoc does not pick those up, so instantiate them # here. Modules can just import them as needed. diff --git a/pybricks/lpf2devices.py b/pybricks/lpf2devices.py index 72a8fe1..cb17743 100644 --- a/pybricks/lpf2devices.py +++ b/pybricks/lpf2devices.py @@ -2,7 +2,8 @@ from ._common import Motor as CommonMotor, ColorLight -from ._common import KeyPad +from ._common import KeyPad, Accelerometer +from .parameters import Side # The above abviously needs fixing (but not until after fixing merge conflict) @@ -38,9 +39,29 @@ class RemoteControl(): self.light = ColorLight() +class TiltSensor(Accelerometer): + """LEGO® Power Functions 2.0 Tilt Sensor (45305/?)""" + + def __init__(self, port, upward=Side.TOP, forward=Side.FRONT): + """TiltSensor(port, upward=Side.TOP, forward=Side.FRONT) + + Arguments: + port (Port): Port to which the sensor is connected. + upward (Side): Which side of the device points upward in + your design. For example, you can choose + ``upward=Side.BOTTOM`` if you + mounted it upside down. (*Default*: + :class:`Side.TOP <.parameters.Side>`). + + forward (Side): Which side of the device points forward in + your design. (*Default*: + :class:`Side.FRONT <.parameters.Side>`). + """ + pass + + class ColorDistanceSensor(): - """LEGO® Power Functions 2.0 Color and Distance Sensor (?/6182145) - """ + """LEGO® Power Functions 2.0 Color and Distance Sensor (?/6182145)""" def __init__(self, port): """ColorDistanceSensor(port) diff --git a/pybricks/parameters.py b/pybricks/parameters.py index 6463a29..e583d40 100644 --- a/pybricks/parameters.py +++ b/pybricks/parameters.py @@ -186,6 +186,38 @@ class Button(Enum): RIGHT_UP = 9 +class Axis(): + """Unit axes of a coordinate system. + + .. data:: X + .. data:: Y + .. data:: Z + """ + X = (1, 0, 0) + Y = (0, 1, 0) + Z = (0, 0, 1) + + +class Side(): + """Sides or face of a device such as a hub or a sensor. Such devices are + usually shaped like a rectangular box with six of the following sides: + + .. data:: TOP + .. data:: BOTTOM + .. data:: FRONT + .. data:: BACK + .. data:: LEFT + .. data:: RIGHT + """ + + RIGHT = Axis.X + FRONT = Axis.Y + TOP = Axis.Z + LEFT = tuple([-u for u in Axis.X]) + BACK = tuple([-u for u in Axis.Y]) + BOTTOM = tuple([-u for u in Axis.Z]) + + class Align(): """Alignment of an image on the display. diff --git a/pybricks/robotics.py b/pybricks/robotics.py index 8ec40d9..9dcb081 100644 --- a/pybricks/robotics.py +++ b/pybricks/robotics.py @@ -24,7 +24,7 @@ class DriveBase(): the center point between the wheels of the robot. Arguments: - speed (:ref:`travelspeed`): Forward speed of the robot. + speed (:ref:`linspeed`): Forward speed of the robot. steering (:ref:`speed`): Turn rate of the robot. """ pass @@ -34,7 +34,7 @@ class DriveBase(): time, and then stop. Arguments: - speed (:ref:`travelspeed`): Forward speed of the robot. + speed (:ref:`linspeed`): Forward speed of the robot. steering (:ref:`speed`): Turn rate of the robot. time (:ref:`time`): Duration of the maneuver.