From 0f6656ada16c9bc4d45ec4bf5dc05988541471f8 Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Thu, 7 Feb 2019 12:29:42 +0100 Subject: [PATCH] doc: signal types fixes #111 --- source/conf.py | 1 - source/index.rst | 11 +++--- source/signaltypes.rst | 79 ++++++++++++++++++++++++++++++------------ 3 files changed, 63 insertions(+), 28 deletions(-) diff --git a/source/conf.py b/source/conf.py index 1da0ff1..8dacff4 100644 --- a/source/conf.py +++ b/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', ] diff --git a/source/index.rst b/source/index.rst index 26537fd..2df9b25 100644 --- a/source/index.rst +++ b/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 diff --git a/source/signaltypes.rst b/source/signaltypes.rst index 000fe93..d727a2e 100644 --- a/source/signaltypes.rst +++ b/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 `. + +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.