doc: signal types

fixes #111

source/conf.py

@@ -89,7 +89,6 @@ language = None
 # This patterns also effect to html_static_path and html_extra_path
 exclude_patterns = [
     'motorcontrol.rst',
-    'signaltypes.rst',
     'startinstall.rst',
     'startrun.rst',
 ]

source/index.rst

@@ -23,12 +23,13 @@ Using Python with LEGO\ :sup:`®` MINDSTORMS\ :sup:`®` EV3
    parameters
    tools
 
-.. .. toctree::
-..    :maxdepth: 1
-..    :caption: Engineering essentials:
+.. toctree::
+   :maxdepth: 1
+   :caption: Engineering essentials:
 
-..    signaltypes
-..    motorcontrol
+   signaltypes
+
+.. motorcontrol
 
 
 

source/signaltypes.rst

@@ -1,70 +1,105 @@
 Signals and Units
 =================
 
-Intro
+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.
 
 .. _time:
 
 time: ms
 ---------
-TODO definition of physical quantity and units and :py:obj:`float` type
+All time and duration values are measured in milliseconds (ms).
+
+For example, the duration of motion with :meth:`run_time <.ev3devices.Motor.run_time>`, the duration of :func:`wait <.tools.wait>`, or the time values returned by the :class:`StopWatch <.tools.StopWatch>` are specified in milliseconds.
 
 .. _angle:
 
 angle: deg
 -----------
-TODO definition of physical quantity and units and :py:obj:`float` type
+All angles are measured in degrees (deg). One full rotation corresponds to 360 degrees.
 
+For example, the angle values of a :meth:`Motor <.ev3devices.Motor.angle>` or the :meth:`GyroSensor <.ev3devices.GyroSensor.angle>` are expressed in degrees.
+
+.. _speed:
+
+rotational speed: deg/s
+-----------------------
+
+Rotational speed, or *angular velocity* describes how fast something rotates, expressed as the number of degrees per second (deg/s).
+
+For example, the rotational speed values of a :meth:`Motor <.ev3devices.Motor.speed>` or the :meth:`GyroSensor <.ev3devices.GyroSensor.speed>` are expressed in degrees per second.
+
+While we recommend to work with degrees per second in your programs, you can use the following table to convert between commonly used units.
+
++-----------+-------+-----------+
+|           | deg/s | rpm       |
++-----------+-------+-----------+
+| 1 deg/s = | 1     | 1/6=0.167 |
++-----------+-------+-----------+
+| 1 rpm =   | 6     | 1         |
++-----------+-------+-----------+
 
 .. _distance:
 
 distance: mm
 -------------
-TODO definition of physical quantity and units and :py:obj:`float` type
+Distances are expressed in millimeters (mm) whenever possible.
+
+For example, the distance value of the :meth:`UltrasonicSensor <.ev3devices.UltrasonicSensor.distance>` is measured in millimeters.
+
+While we recommend to work with millimeters in your programs, you can use the following table to convert between commonly used units.
+
++---------+------+-----+--------+
+|         | mm   | cm  | inch   |
++---------+------+-----+--------+
+| 1 mm =  | 1    | 0.1 | 0.0394 |
++---------+------+-----+--------+
+| 1 cm =  | 10   | 1   | 0.394  |
++---------+------+-----+--------+
+| 1 inch =| 25.4 | 2.54| 1      |
++---------+------+-----+--------+
 
 
 .. _relativedistance:
 
 relative distance: %
 ---------------------
-TODO definition of physical quantity and units and :py:obj:`float` type
 
-.. _speed:
+Some distance measurements do not provide an accurate value with a specific unit, but they range from very close (0%) to very far (100%). These are referred to as relative distances.
+
+For example, the distance value of the :meth:`InfraredSensor <.ev3devices.InfraredSensor.distance>` is a relative distance.
+
 
-speed: deg/s
--------------
-(angular velocity for motor, sensor) TODO definition of physical quantity and units and :py:obj:`float` type
 
 
 .. _travelspeed:
 
 speed: mm/s
 ------------
-(drive speed) TODO definition of physical quantity and units and :py:obj:`float` type
-
+Linear speeds are expressed as millimeters per second (mm/s).
 
+For example, the speed of a robotic vehicle is expressed in mm/s.
 
 .. _acceleration:
 
-acceleration: deg/s/s
-----------------------
-TODO definition of physical quantity and units and :py:obj:`float` type
+rotational acceleration: deg/s/s
+--------------------------------
+Rotational acceleration, or *angular acceleration* describes how fast the rotational speed changes. This is expressed as the change of the number of degrees per second, during one second (deg/s/s). This is also commonly written as  :math:`deg/s^2`.
+
+For example, you can adjust the rotational acceleration setting of a :meth:`Motor <.ev3devices.Motor.set_run_settings>` to change how smoothly or how quickly a motor reaches the constant speed set point.
+
 
 .. _percentage:
 
 percentage: %
 --------------
-TODO definition of physical quantity and units and :py:obj:`float` type
+Some signals do not have specific units but range from a minimum (0%) to a maximum (100%). A specific type of percentages are :ref:`relative distances <relativedistance>`.
+
+For example, the sound :meth:`volume <.ev3brick.sound.beep>` range from 0% to 100%.
 
 .. _frequency:
 
 frequency: Hz
 --------------
-TODO definition of physical quantity and units and :py:obj:`float` type
+Sound frequencies are expressed in Herz (Hz).
 
-
-.. _colortuple:
-
-custom color
---------------
-TODO definition of physical quantity and units and :py:obj:`float` type
+For example, you can choose the frequency of a :meth:`beep <.ev3brick.sound.beep>` to change the pitch.