api: accelerometer drafts

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

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
 ---------------
 

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:

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 <self.light> of the
 # the ColorDistanceSensor. Autodoc does not pick those up, so instantiate them
 # here. Modules can just import them as needed.

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)

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.
 

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.