From b5c9e3feb7e4fac38176e1c66f9996e6bd8c5fa4 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Thu, 4 Jul 2019 11:55:01 +0200
Subject: [PATCH] api: add simpler method for tilt

Provides a way of basic orientation checking independently of reference frame settings.
---
 doc/lpf2/lpf2devices.rst |  2 ++
 doc/lpf2/parameters.rst  |  3 +++
 pybricks/_common.py      | 38 ++++++++++++++++++++++++++++++++++----
 pybricks/parameters.py   | 20 ++++++++++++++++++++
 4 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/doc/lpf2/lpf2devices.rst b/doc/lpf2/lpf2devices.rst
index 225f79d..242234f 100644
--- a/doc/lpf2/lpf2devices.rst
+++ b/doc/lpf2/lpf2devices.rst
@@ -136,6 +136,8 @@ Tilt Sensor
 
     .. automethod:: tilt
 
+    .. automethod:: up
+
 Other Devices
 ---------------
 
diff --git a/doc/lpf2/parameters.rst b/doc/lpf2/parameters.rst
index 3480e28..46a532a 100644
--- a/doc/lpf2/parameters.rst
+++ b/doc/lpf2/parameters.rst
@@ -28,3 +28,6 @@
 
 .. autoclass:: pybricks.parameters.Axis
     :no-members:
+
+.. autoclass:: pybricks.parameters.Side
+    :no-members:
diff --git a/pybricks/_common.py b/pybricks/_common.py
index 82f212f..1e0e82e 100644
--- a/pybricks/_common.py
+++ b/pybricks/_common.py
@@ -614,9 +614,10 @@ class Accelerometer():
     def neutral(self, top, front):
         """Configure the neutral orientation of the device or hub. You do this
         by specifying how it is mounted on your design, in terms of the
-        :ref:`robot reference frame <robotframe>`. In this given neutral
-        orientation, the tilt will be zero. Now, all imu accelerations and
-        angles will be given in the :ref:`robot reference frame <robotframe>`.
+        :ref:`robot reference frame <robotframe>`.
+
+        In this given neutral orientation, the tilt and heading will then be
+        zero.
 
         Arguments:
             top (Axis): Which direction the top of the device faces in the
@@ -647,7 +648,7 @@ class Accelerometer():
         pass
 
     def tilt(self):
-        """Get the pitch and roll angles relative to the horizontal
+        """Get the pitch and roll angles relative to the neutral, horizontal
         orientation.
 
         The order of rotation is pitch-then-roll. This is equivalent to a
@@ -684,6 +685,17 @@ class Accelerometer():
         # def shaken(self, axis=Axis.ALL, bidirectional=True, tolerance=45):
         pass
 
+    def up(self):
+        """Check which side of the device or hub currently faces upward.
+
+        :returns:
+            ``Side.TOP``, ``Side.BOTTOM``, ``Side.LEFT``, ``Side.RIGHT``,
+            ``Side.FRONT`` or ``Side.BACK``.
+        :rtype: :class:`Side <.parameters.Side>`
+
+        """
+        pass
+
 
 class IMU(Accelerometer):
 
@@ -709,6 +721,24 @@ class IMU(Accelerometer):
         """
         pass
 
+    def gyro(self, axis=Axis.ALL):
+        """gyro(axis=Axis.ALL)
+
+        Measure the angular velocity of the device along a given axis in the
+        :ref:`robot reference frame <robotframe>`.
+
+        Arguments:
+            axis (Axis): Axis along which the angular velocity is
+                         measured. (*Default*: ``axis=Axis.ALL``)
+        Returns:
+            :ref:`speed`. Returns a :ref:`scalar` of the angular velocity
+            along the specified axis.
+            If you choose ``axis=Axis.ALL``, you get a :ref:`vector` with the
+            angular velocities along all three 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
diff --git a/pybricks/parameters.py b/pybricks/parameters.py
index ec58ea7..d346203 100644
--- a/pybricks/parameters.py
+++ b/pybricks/parameters.py
@@ -203,6 +203,26 @@ class Axis():
     ALL = None
 
 
+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 = 6
+    FRONT = 0
+    TOP = 8
+    LEFT = 4
+    BACK = 5
+    BOTTOM = 2
+
+
 class Align():
     """Alignment of an image on the display.