@pybricks/ide-docs v1.3.0

v3: Drop parameters Side and Button.
v3: Drop Remote control.
2026-09-11 17:14:41 +00:00 · 2021-04-12 11:08:51 +02:00 · 2021-04-12 11:05:26 +02:00 · 2021-04-12 11:05:22 +02:00 · 2021-04-12 11:05:17 +02:00 · 2021-04-12 11:05:04 +02:00
73 changed files with 816 additions and 1728 deletions
@@ -1,49 +0,0 @@
-:mod:`geometry <pybricks.geometry>` -- Geometry and algebra
-============================================================
-
-.. module:: pybricks.geometry
-
-.. autoclass:: pybricks.geometry.Matrix
-    :no-members:
-
-    .. autoattribute:: pybricks.geometry::Matrix.T
-
-    .. autoattribute:: pybricks.geometry::Matrix.shape
-
-.. autofunction:: pybricks.geometry.vector
-
-.. autoclass:: pybricks.geometry.Axis
-    :no-members:
-
-.. _robotframe:
-
-Reference frames
-----------------------
-
-The Pybricks module and this documentation use the following conventions:
-
- X: Positive means forward. Negative means backward.
- Y: Positive means to the left. Negative means to the right.
- Z: Positive means upward. Negative means downward.
-
-To make sure that all hub measurements (such as acceleration) have the correct
-value and sign, you can specify how the hub is mounted in your creation. This
-adjust the measurements so that it is easy to see how your *robot* is moving,
-rather than how the *hub* is moving.
-
-For example, the hub may be mounted upside down in your design. If you
-configure the settings as shown in :numref:`fig_imuexamples`, the hub
-measurements will be adjusted accordingly. This way, a positive acceleration
-value in the X direction means that your *robot* accelerates forward, even
-though the *hub* accelerates backward.
-
-.. _fig_imuexamples:
-
-.. figure:: ../api/images/imuexamples_label.png
-   :width: 100 %
-
-   How to configure the ``top_side`` and ``front_side`` settings for three
-   different robot designs. The same technique can be applied to other hubs
-   and other creations, by noting which way the top and
-   front :class:`Side <.parameters.Side>` of the hub are pointing. The example
-   on the left is the default configuration.
@@ -10,46 +10,27 @@
   movehub
   cityhub
   technichub
-   primehub
   ev3brick

-.. class:: MoveHub
-    :noindex:
+.. pybricks-classlink:: MoveHub

 .. figure:: ../../api/images/movehub.png
    :height: 10 em
    :target: movehub.html

-.. class:: CityHub
-    :noindex:
+.. pybricks-classlink:: CityHub

 .. figure:: ../../api/images/cityhub.png
    :height: 10 em
    :target: cityhub.html

-.. class:: TechnicHub
-    :noindex:
+.. pybricks-classlink:: TechnicHub

 .. figure:: ../../api/images/technichub.png
    :height: 10 em
    :target: technichub.html

-.. class:: PrimeHub
-    :noindex:
-
-.. figure:: ../../api/images/primehub.png
-    :height: 10 em
-    :target: primehub.html
-
-.. class:: InventorHub
-    :noindex:
-
-.. figure:: ../../api/images/inventorhub.png
-    :height: 10 em
-    :target: primehub.html
-
-.. class:: EV3Brick
-    :noindex:
+.. pybricks-classlink:: EV3Brick

 .. figure:: ../../api/images/ev3brick.png
    :height: 10 em
@@ -39,3 +39,4 @@ Making the light blink

 .. literalinclude::
    ../../../examples/pup/hub_movehub/light_blink.py
+
@@ -1,210 +0,0 @@
-Prime Hub / Inventor Hub
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. figure:: ../../api/images/primeinventorhub.png
-    :height: 15 em
-
-.. class:: InventorHub
-
-    This class is the same as the ``PrimeHub`` class, shown below. Both classes
-    work on both hubs.
-
-    These hubs are completely identical. They use the same Pybricks firmware.
-
-.. autoclass:: pybricks.hubs.PrimeHub
-    :no-members:
-
-    .. rubric:: Using the hub status light
-
-    .. figure:: ../../api/images/primehub_light_label.png
-        :width: 22 em
-
-    .. automethod:: pybricks.hubs::PrimeHub.light.on
-
-    .. automethod:: pybricks.hubs::PrimeHub.light.off
-
-    .. automethod:: pybricks.hubs::PrimeHub.light.blink
-
-    .. automethod:: pybricks.hubs::PrimeHub.light.animate
-
-    .. rubric:: Using the light matrix display
-
-    .. figure:: ../../api/images/primehub_display_label.png
-        :width: 22 em
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.orientation
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.off
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.pixel
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.image
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.animate
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.number
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.char
-
-    .. automethod:: pybricks.hubs::PrimeHub.display.text
-
-    .. rubric:: Using the buttons
-
-    .. figure:: ../../api/images/primehub_buttons_label.png
-        :width: 22 em
-
-    .. automethod:: pybricks.hubs::PrimeHub.buttons.pressed
-
-    .. rubric:: Using the IMU
-
-    .. automethod:: pybricks.hubs::PrimeHub.imu.up
-
-    .. automethod:: pybricks.hubs::PrimeHub.imu.tilt
-
-    .. automethod:: pybricks.hubs::PrimeHub.imu.acceleration
-
-    .. automethod:: pybricks.hubs::PrimeHub.imu.angular_velocity
-
-    .. automethod:: pybricks.hubs::PrimeHub.imu.heading
-
-    .. automethod:: pybricks.hubs::PrimeHub.imu.reset_heading
-
-    .. rubric:: Using the speaker
-
-    .. automethod:: pybricks.hubs::PrimeHub.speaker.beep
-
-    .. automethod:: pybricks.hubs::PrimeHub.speaker.play_notes
-
-    .. rubric:: Using the battery
-
-    .. automethod:: pybricks.hubs::PrimeHub.battery.voltage
-
-    .. automethod:: pybricks.hubs::PrimeHub.battery.current
-
-.. note:: The examples below use the ``PrimeHub`` class. The examples work fine
-          on both hubs because they are the identical. If you prefer, you can
-          change this to ``InventorHub``.
-
-Status light examples
---------------------
-
-Turning the light on and off
-****************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/light_off.py
-
-Changing brightness and using custom colors
-*******************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/light_hsv.py
-
-Making the light blink
-**********************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/light_blink.py
-
-Creating light animations
-*************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/light_animate.py
-
-Matrix display examples
-----------------------
-
-Displaying images
-*****************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_image.py
-
-Displaying numbers
-******************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_number.py
-
-Displaying text
-***************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_text.py
-
-Displaying individual pixels
-****************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_pixel.py
-
-Changing the display orientation
-********************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_orientation.py
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_orientation_imu.py
-
-Making your own images
-**********************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_matrix.py
-
-Combining images to make expressions
-************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_expression.py
-
-Displaying animations
-*********************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/display_animate.py
-
-Button examples
---------------
-
-Detecting button presses
-************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/button_main.py
-
-IMU examples
---------------
-
-Testing which way is up
-********************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/imu_up.py
-
-
-Reading the tilt value
-********************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/imu_tilt.py
-
-Using a custom hub orientation
-**************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/imu_tilt_blast.py
-
-Reading acceleration and angular velocity vectors
-**************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/imu_read_vector.py
-
-Reading acceleration and angular velocity on one axis
-*****************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_primehub/imu_read_scalar.py
@@ -4,8 +4,7 @@ Technic Hub
 .. figure:: ../../api/images/technichub.png
    :height: 15 em

-.. autoclass:: pybricks.hubs.TechnicHub
-    :no-members:
+.. class:: TechnicHub

    .. rubric:: Using the hub status light

@@ -17,20 +16,6 @@ Technic Hub

    .. automethod:: pybricks.hubs::TechnicHub.light.animate

-    .. rubric:: Using the IMU
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.up
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.tilt
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.acceleration
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.angular_velocity
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.heading
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.reset_heading
-
    .. rubric:: Using the battery

    .. automethod:: pybricks.hubs::TechnicHub.battery.voltage
@@ -63,37 +48,3 @@ Creating light animations

 .. literalinclude::
    ../../../examples/pup/hub_technichub/light_animate.py
-
-IMU examples
---------------
-
-Testing which way is up
-********************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_up.py
-
-
-Reading the tilt value
-********************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_tilt.py
-
-Using a custom hub orientation
-**************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_tilt_blast.py
-
-Reading acceleration and angular velocity vectors
-**************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_read_vector.py
-
-Reading acceleration and angular velocity on one axis
-*****************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_read_scalar.py
@@ -1,4 +1,4 @@
-Welcome to Pybricks!
+Pybricks API Documentation
 ==================================================================

 This documentation has everything you need to install Pybricks and
@@ -18,13 +18,13 @@ the platforms below.
     - **SPIKE / MINDSTORMS Inventor**

   * - .. image:: ../api/images/ev3brick.png
-         :target: start_ev3/index.html
+         :target: https://pybricks.com/install/mindstorms-ev3/installation

     - .. figure:: ../api/images/powereduphubs.png
-         :target: start_pup.html
+         :target: https://pybricks.com/install/technic-boost-city/

     - .. figure:: ../api/images/primeinventorhub.png
-          :target: start_inventor.html
+          :target: https://pybricks.com/install/spike-mindstorms/


 **Step 2: Start coding!**
@@ -53,19 +53,7 @@ findings on our `support page`_ so we can make Pybricks even better.
    :hidden:

    Home Page <https://pybricks.com>
-    Downloads <https://pybricks.com/downloads/>
-    Example Projects <https://github.com/pybricks/pybricks-projects>
-    Support <https://github.com/pybricks/support/issues/>
-    About Pybricks <https://pybricks.com/about/>
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Getting started
-   :hidden:
-
-   start_ev3/index
-   start_pup
-   start_inventor
+    Installation <https://pybricks.com/install/>

 .. toctree::
   :maxdepth: 1
@@ -77,12 +65,11 @@ findings on our `support page`_ so we can make Pybricks even better.
   ev3devices
   nxtdevices
   iodevices/index
-   parameters
+   parameters/index
   tools/index
   robotics
   media
   messaging
-   geometry

 .. toctree::
   :maxdepth: 1
@@ -16,8 +16,7 @@
   dcmotor
   ev3devsensor

-.. class:: PUPDevice
-    :noindex:
+.. pybricks-classlink:: PUPDevice

 .. figure:: ../../api/images/sensor_pup.png
   :width: 70 %
@@ -25,43 +24,37 @@

   This class is only available on Powered Up hubs.

-.. class:: I2CDevice
-    :noindex:
+.. pybricks-classlink:: I2CDevice

 .. figure:: ../../api/images/sensor_rj12_bluegreen.png
   :width: 25 %
   :target: i2cdevice.html

-.. class:: UARTDevice
-    :noindex:
+.. pybricks-classlink:: UARTDevice

 .. figure:: ../../api/images/sensor_rj12_gray.png
   :width: 25 %
   :target: uartdevice.html

-.. class:: AnalogSensor
-    :noindex:
+.. pybricks-classlink:: AnalogSensor

 .. figure:: ../../api/images/sensor_rj12_brown.png
   :width: 25 %
   :target: analogsensor.html

-.. class:: LUMPDevice
-    :noindex:
+.. pybricks-classlink:: LUMPDevice

 .. figure:: ../../api/images/sensor_rj12_green.png
   :width: 25 %
   :target: lumpdevice.html

-.. class:: DCMotor
-    :noindex:
+.. pybricks-classlink:: DCMotor

 .. figure:: ../../api/images/rcxmotor.png
   :width: 40 %
   :target: dcmotor.html

-.. class:: Ev3devSensor
-    :noindex:
+.. pybricks-classlink:: Ev3devSensor

 .. figure:: ../../api/images/sensor_ev3dev.png
   :width: 70 %
@@ -41,7 +41,7 @@ The connection will be made when you run your programs, as described below.
   Pairing one EV3 Brick to another EV3 Brick.

 When you scan for Bluetooth devices, you'll see a list of device names. By
-default, all EV3 Bricks are named *ev3dev*. Click :ref:`here <hostname>` to
+default, all EV3 Bricks are named *ev3dev*. Click `here`_ to
 learn how to change that name. This makes it easy to tell them apart.

 Repeat the steps in :numref:`fig_bluetooth_pair` if you want to pair more than
@@ -134,3 +134,5 @@ is shown in :numref:`fig_messaging_network`.
   :align: center

   An example network with one server and two clients.
+
+.. _here: https://pybricks.com/install/mindstorms-ev3/beyond-micropython
@@ -126,6 +126,8 @@ the settings.

    .. automethod:: pybricks._common.Control.stalled

+    .. automethod:: pybricks._common.Control.load
+
    .. rubric:: Settings

    .. automethod:: pybricks._common.Control.limits
@@ -1,187 +0,0 @@
-:mod:`parameters <pybricks.parameters>` -- Parameters and Constants
-===================================================================
-
-.. automodule:: pybricks.parameters
-    :no-members:
-
-.. autoclass:: pybricks.parameters.Port
-    :no-members:
-
-    Input/Output ports:
-
-        .. data:: A
-        .. data:: B
-        .. data:: C
-        .. data:: D
-        .. data:: E
-        .. data:: F
-
-    EV3 Sensor ports:
-
-        .. data:: S1
-        .. data:: S2
-        .. data:: S3
-        .. data:: S4
-
-.. autoclass:: pybricks.parameters.Direction
-    :no-members:
-
-    In general, clockwise is defined by **looking at the motor shaft, just
-    like looking at a clock**. Some motors have two shafts. If in doubt,
-    refer to the diagram in the ``Motor`` class documentation.
-
-.. autoclass:: pybricks.parameters.Stop
-    :no-members:
-
-    The following table show how each stop type adds an extra level of
-    resistance to motion. In these examples, ``m`` is a
-    :class:`Motor <pybricks.pupdevices.Motor>` and
-    and ``d`` is a :class:`DriveBase <pybricks.robotics.DriveBase>`. The
-    examples also show how running at zero speed compares to these stop types.
-
-    +--------+------------+--------+-------------+---------------+-----------------------------------------+
-    | | Type | | Friction | | Back | | Speed     |  | Angle kept | | Examples                              |
-    |        |            | | EMF  | | kept at 0 |  | at target  |                                         |
-    +========+============+========+=============+===============+=========================================+
-    | Coast  | +          |        |             |               | | ``m.stop()``                          |
-    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.COAST)`` |
-    +--------+------------+--------+-------------+---------------+-----------------------------------------+
-    | Brake  | +          | +      |             |               | | ``m.brake()``                         |
-    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.BRAKE)`` |
-    +--------+------------+--------+-------------+---------------+-----------------------------------------+
-    |        | +          | +      | +           |               | | ``m.run(0)``                          |
-    |        |            |        |             |               | | ``d.drive(0, 0)``                     |
-    +--------+------------+--------+-------------+---------------+-----------------------------------------+
-    | Hold   | +          | +      | +           | +             | | ``m.hold()``                          |
-    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.HOLD)``  |
-    |        |            |        |             |               | | ``d.straight(0)``                     |
-    |        |            |        |             |               | | ``d.straight(100)``                   |
-    +--------+------------+--------+-------------+---------------+-----------------------------------------+
-
-.. autoclass:: pybricks.parameters.Color
-    :no-members:
-
-    .. rubric:: Saturated colors
-
-    .. autoattribute:: RED
-
-        .. pybricks-color:: RED
-
-    .. autoattribute:: ORANGE
-
-        .. pybricks-color:: ORANGE
-
-    .. autoattribute:: YELLOW
-
-        .. pybricks-color:: YELLOW
-
-    .. autoattribute:: GREEN
-
-        .. pybricks-color:: GREEN
-
-    .. autoattribute:: CYAN
-
-        .. pybricks-color:: CYAN
-
-    .. autoattribute:: BLUE
-
-        .. pybricks-color:: BLUE
-
-    .. autoattribute:: VIOLET
-
-        .. pybricks-color:: VIOLET
-
-    .. autoattribute:: MAGENTA
-
-        .. pybricks-color:: MAGENTA
-
-    .. rubric:: Unsaturated colors
-
-    .. autoattribute:: BLACK
-
-        .. pybricks-color:: BLACK
-
-    .. autoattribute:: GRAY
-
-        .. pybricks-color:: GRAY
-
-    .. autoattribute:: WHITE
-
-        .. pybricks-color:: WHITE
-
-.. autoclass:: pybricks.parameters.Button
-    :no-members:
-
-    .. autoattribute:: pybricks.parameters.Button.LEFT_DOWN
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.LEFT_MINUS
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.DOWN
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.RIGHT_DOWN
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.RIGHT_MINUS
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.LEFT
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.CENTER
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.RIGHT
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.LEFT_UP
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.LEFT_PLUS
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.UP
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.BEACON
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.RIGHT_UP
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Button.RIGHT_PLUS
-        :annotation:
-
-.. autoclass:: pybricks.parameters.Side
-    :no-members:
-
-    Screens or light matrices have only four sides. For those,
-    ``TOP`` is treated the same as ``FRONT``, and ``BOTTOM`` is treated the
-    same as ``BACK``. The diagrams below define the sides for relevant devices.
-
-    **Prime Hub**
-
-    .. figure:: ../api/images/orientation_primehub_label.png
-        :height: 15 em
-
-    **Inventor Hub**
-
-    .. figure:: ../api/images/orientation_inventorhub_label.png
-        :height: 15 em
-
-    **Move Hub**
-
-    .. figure:: ../api/images/orientation_movehub_label.png
-        :height: 15 em
-
-    **Technic Hub**
-
-    .. figure:: ../api/images/orientation_technichub_label.png
-        :height: 15 em
-
-    **Tilt Sensor**
-
-    .. figure:: ../api/images/orientation_tiltsensor_label.png
-        :height: 15 em
@@ -0,0 +1,48 @@
+Button
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: Button
+
+    Buttons on a hub or remote.
+
+    .. autoattribute:: pybricks.parameters.Button.LEFT_DOWN
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.LEFT_MINUS
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.DOWN
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.RIGHT_DOWN
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.RIGHT_MINUS
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.LEFT
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.CENTER
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.RIGHT
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.LEFT_UP
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.LEFT_PLUS
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.UP
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.BEACON
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.RIGHT_UP
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Button.RIGHT_PLUS
+        :annotation:
@@ -0,0 +1,84 @@
+Color
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: pybricks.parameters.Color
+    :no-members:
+
+    .. rubric:: Saturated colors
+
+    These colors have maximum saturation and brightness value.
+    They differ only in hue.
+
+    .. autoattribute:: RED
+
+        .. pybricks-color:: RED
+
+    .. autoattribute:: ORANGE
+
+        .. pybricks-color:: ORANGE
+
+    .. autoattribute:: YELLOW
+
+        .. pybricks-color:: YELLOW
+
+    .. autoattribute:: GREEN
+
+        .. pybricks-color:: GREEN
+
+    .. autoattribute:: CYAN
+
+        .. pybricks-color:: CYAN
+
+    .. autoattribute:: BLUE
+
+        .. pybricks-color:: BLUE
+
+    .. autoattribute:: VIOLET
+
+        .. pybricks-color:: VIOLET
+
+    .. autoattribute:: MAGENTA
+
+        .. pybricks-color:: MAGENTA
+
+    .. rubric:: Unsaturated colors
+
+    These colors have zero hue and saturation. They differ only in brightness
+    value.
+
+    When detecting these colors using sensors, their values depend a lot
+    on the distance to the object. If the distance between the sensor and the
+    object is not constant in your robot, it is better to use only one of these
+    colors in your programs.
+
+    .. autoattribute:: WHITE
+
+        .. pybricks-color:: WHITE
+
+    .. autoattribute:: GRAY
+
+        .. pybricks-color:: GRAY
+
+    .. autoattribute:: BLACK
+
+        This represents dark objects that still reflect
+        a very small amount of light.
+
+        .. pybricks-color:: BLACK
+
+    .. autoattribute:: NONE
+
+        This is total darkness, with no reflection or light at all.
+
+        .. pybricks-color:: NONE
+
+.. rubric:: Making your own colors
+
+This example shows the basics of color properties, and how to define new colors.
+
+.. literalinclude::
+    ../../../examples/pup/parameters/color_basics.py
+
+This example shows more advanced use cases of the ``Color`` class.
+
+.. literalinclude::
+    ../../../examples/pup/parameters/color_advanced.py
@@ -0,0 +1,24 @@
+Direction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: Direction
+
+    Rotational direction for positive speed or angle values.
+
+    .. autoattribute:: pybricks.parameters.Direction.CLOCKWISE
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Direction.COUNTERCLOCKWISE
+        :annotation:
+
+    +--------------------------------+-------------------+-----------------+
+    | ``positive_direction =``       | Positive speed:   | Negative speed: |
+    +================================+===================+=================+
+    | ``Direction.CLOCKWISE``        | clockwise         | counterclockwise|
+    +--------------------------------+-------------------+-----------------+
+    | ``Direction.COUNTERCLOCKWISE`` | counterclockwise  | clockwise       |
+    +--------------------------------+-------------------+-----------------+
+
+    In general, clockwise is defined by **looking at the motor shaft, just
+    like looking at a clock**. Some motors have two shafts. If in doubt,
+    refer to the diagram in the ``Motor`` class documentation.
@@ -0,0 +1,26 @@
+:mod:`parameters <pybricks.parameters>` -- Parameters and Constants
+===================================================================
+
+.. automodule:: pybricks.parameters
+    :no-members:
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   button
+   color
+   direction
+   port
+   stop
+
+.. pybricks-classlink:: Button
+
+.. pybricks-classlink:: Color
+
+.. pybricks-classlink:: Direction
+
+.. pybricks-classlink:: Port
+
+.. pybricks-classlink:: Stop
+
@@ -0,0 +1,38 @@
+Port
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: Port
+
+    Input and output ports:
+
+    .. autoattribute:: pybricks.parameters.Port.A
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.B
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.C
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.D
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.E
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.F
+        :annotation:
+
+    EV3 Sensor ports:
+
+    .. autoattribute:: pybricks.parameters.Port.S1
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.S2
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.S3
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.S4
+        :annotation:
@@ -0,0 +1,40 @@
+Stop
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: Stop
+
+    Action after the motor stops.
+
+    .. autoattribute:: pybricks.parameters.Stop.COAST
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Stop.BRAKE
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Stop.HOLD
+        :annotation:
+
+    The following table shows how each stop type adds an extra level of
+    resistance to motion. In these examples, ``m`` is a
+    :class:`Motor <pybricks.pupdevices.Motor>` and
+    and ``d`` is a :class:`DriveBase <pybricks.robotics.DriveBase>`. The
+    examples also show how running at zero speed compares to these stop types.
+
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    | | Type | | Friction | | Back | | Speed     |  | Angle kept | | Examples                              |
+    |        |            | | EMF  | | kept at 0 |  | at target  |                                         |
+    +========+============+========+=============+===============+=========================================+
+    | Coast  | +          |        |             |               | | ``m.stop()``                          |
+    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.COAST)`` |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    | Brake  | +          | +      |             |               | | ``m.brake()``                         |
+    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.BRAKE)`` |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    |        | +          | +      | +           |               | | ``m.run(0)``                          |
+    |        |            |        |             |               | | ``d.drive(0, 0)``                     |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
+    | Hold   | +          | +      | +           | +             | | ``m.hold()``                          |
+    |        |            |        |             |               | | ``m.run_target(500, 90, Stop.HOLD)``  |
+    |        |            |        |             |               | | ``d.straight(0)``                     |
+    |        |            |        |             |               | | ``d.straight(100)``                   |
+    +--------+------------+--------+-------------+---------------+-----------------------------------------+
@@ -67,7 +67,7 @@ Changing the detectable colors
 ******************************

 By default, the sensor is configured to detect red, yellow, green,
-blue, white, or ``None``, which suits many applications.
+blue, white, or no color, which suits many applications.

 For better results in your application, you can measure your desired
 colors in advance, and tell the sensor to look only for those colors.
@@ -58,7 +58,7 @@ Changing the detectable colors
 ******************************

 By default, the sensor is configured to detect red, yellow, green,
-blue, white, or ``None``, which suits many applications.
+blue, white, or no color, which suits many applications.

 For better results in your application, you can measure your desired
 colors in advance, and tell the sensor to look only for those colors.
@@ -18,81 +18,63 @@
   ultrasonicsensor
   forcesensor
   light
-   remote

-.. class:: DCMotor
-    :noindex:
+.. pybricks-classlink:: DCMotor

 .. figure:: ../../api/images/pupdcmotors_label.png
    :width: 70 %
    :target: dcmotor.html

-.. class:: Motor
-    :noindex:
+.. pybricks-classlink:: Motor

 .. figure:: ../../api/images/pupmotors_label.png
    :width: 100 %
    :target: motor.html

-.. class:: TiltSensor
-    :noindex:
+.. pybricks-classlink:: TiltSensor

 .. figure:: ../../api/images/sensor_tilt.png
   :width: 35 %
   :target: tiltsensor.html

-.. class:: InfraredSensor
-    :noindex:
+.. pybricks-classlink:: InfraredSensor

 .. figure:: ../../api/images/sensor_proximity.png
   :width: 35 %
   :target: infraredsensor.html

-.. class:: ColorDistanceSensor
-    :noindex:
+.. pybricks-classlink:: ColorDistanceSensor

 .. figure:: ../../api/images/sensor_colordistance.png
   :width: 32 %
   :target: colordistancesensor.html

-.. class:: PFMotor
-    :noindex:
+.. pybricks-classlink:: PFMotor

 .. figure:: ../../api/images/pfmotor.png
   :width: 95 %
   :target: pfmotor.html

-.. class:: ColorSensor
-    :noindex:
+.. pybricks-classlink:: ColorSensor

 .. figure:: ../../api/images/sensor_color.png
   :width: 32 %
   :target: colorsensor.html

-.. class:: UltrasonicSensor
-    :noindex:
+.. pybricks-classlink:: UltrasonicSensor

 .. figure:: ../../api/images/sensor_ultrasonic.png
   :width: 37 %
   :target: ultrasonicsensor.html

-.. class:: ForceSensor
-    :noindex:
+.. pybricks-classlink:: ForceSensor

 .. figure:: ../../api/images/sensor_force.png
   :width: 35 %
   :target: forcesensor.html

-.. class:: Light
-    :noindex:
+.. pybricks-classlink:: Light

 .. figure:: ../../api/images/light.png
   :width: 90 %
   :target: light.html
-
-.. class:: Remote
-    :noindex:
-
-.. figure:: ../../api/images/pupremote.png
-   :width: 50 %
-   :target: remote.html
@@ -6,7 +6,6 @@ Motors with Rotation Sensors
 .. figure:: ../../api/images/pupmotors_label.png
   :width: 100 %
   :alt: pupmotors
-   :align: left

   Powered Up motors with rotation sensors. The arrows indicate the default
   positive direction. See the :mod:`hubs <pybricks.hubs>` module for default
@@ -1,23 +0,0 @@
-Remote Control
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. warning::
-
-    This remote is not yet supported.
-    Upvote `this issue <https://github.com/pybricks/support/issues/186>`_ if
-    you want to see this happen.
-
-.. figure:: ../../api/images/pupremote.png
-   :width: 60 %
-
-.. autoclass:: pybricks.pupdevices.Remote
-  :no-members:
-
-  .. autoattribute:: pybricks.pupdevices::Remote.address
-       :annotation:
-
-  .. automethod:: pybricks.pupdevices::Remote.light.on
-
-  .. automethod:: pybricks.pupdevices::Remote.light.off
-
-  .. automethod:: pybricks.pupdevices::Remote.buttons.pressed
@@ -172,7 +172,7 @@ the light is off and 100% when the light is fully on. When you choose 50%, this
 means that the light is perceived as approximately half as bright to the human
 eye.

-Force
+Force and torque
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 .. _force:
@@ -194,6 +194,12 @@ following table to convert to and from other units.
 | 1 lbf = | 4448 | 4.448 | 1                           |
 +---------+------+-------+-----------------------------+

+.. _torque:
+
+torque: mNm
+------------
+Torque values are expressed in millinewtonmeter (mNm) unless stated otherwise.
+
 Electricity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -1,23 +0,0 @@
-EV3 Quick Start
-########################
-
-.. note::
-
-   This documentation is for EV3 MicroPython with Pybricks **3.0**.
-
-   Click `here`_ to view the documentation EV3 MicroPython **2.0**. This is
-   is the stable version officially supported by `LEGO Education`_.
-
-.. rubric:: Table of contents
-
-.. toctree::
-   :maxdepth: 1
-
-   start_ev3_install
-   start_ev3_brick
-   start_ev3_run
-   start_ev3_linux
-   start_ev3_upgrade
-
-.. _here: https://pybricks.github.io/ev3-micropython/index.html
-.. _LEGO Education: https://education.lego.com/en-us/support/mindstorms-ev3/python-for-ev3
@@ -1,81 +0,0 @@
-Using the EV3 Brick
-===================
-
-Make sure the EV3 Brick is turned off. Insert the microSD card you prepared
-into the microSD card slot on the EV3 Brick, as shown in :numref:`fig_sd`.
-
-.. _fig_sd:
-
-.. figure:: ../../api/images/sd_label.png
-   :width: 75 %
-   :alt: sd
-   :align: center
-
-   Inserting the flashed microSD card into the EV3 Brick
-
-
-Turning the EV3 Brick on and off
-----------------------------------------------------------
-
-Turn on the EV3 Brick by pressing the dark gray center button.
-
-The boot process may take several minutes. While booting, the EV3 Brick status
-light turns orange and blinks intermittently, and you'll see a lot of text on
-the EV3 screen. The EV3 Brick is ready for use when the status light turns
-green.
-
-To turn the EV3 Brick off, open the shutdown menu with the back button, and
-then select *Power Off* using the center button, as shown
-in :numref:`fig_onoff`.
-
-.. _fig_onoff:
-
-.. figure:: ../../api/images/onoff_label.png
-   :width: 65 %
-   :alt: onoff
-   :align: center
-
-   Turning the EV3 Brick off
-
-Viewing motor and sensor values
-----------------------------------------------------------
-
-When you're not running a program, you can view motor and sensor values using
-the device browser, as shown in :numref:`fig_devicebrowser`.
-
-.. _fig_devicebrowser:
-
-.. figure:: ../../api/images/devicebrowser_label.png
-   :width: 100 %
-   :alt: devicebrowser
-   :align: center
-
-   Viewing motor and sensor values
-
-Running a program without a computer
-----------------------------------------------------------
-
-You can run previously downloaded programs directly from the EV3 Brick.
-
-To do so, find the program using the *file browser* on the EV3 screen and press
-the center button key to start the program as shown in :numref:`fig_manualrun`.
-
-.. _fig_manualrun:
-
-.. figure:: ../../api/images/manualrun_label.png
-   :width: 100 %
-   :alt: manualrun
-   :align: center
-
-   Starting a program using the buttons on the EV3 Brick
-
-Going back to the original firmware
-----------------------------------------------------------
-
-You can go back to the LEGO® firmware and your LEGO programs at any time. To
-do so:
-
-1. Turn the EV3 Brick off as shown above.
-2. Wait for the screen and brick status light to turn off.
-3. Remove the microSD card.
-4. Turn the EV3 on.
@@ -1,118 +0,0 @@
-Installation
-===================
-
-This page guides you through the steps to collect and install everything you
-need to start programming.
-
-What do you need?
-----------------------------------------------------------
-
-To get started, you'll need:
-
- A Windows 10 or Mac OS computer
- Internet access and administrator access
-
-    This is required during the installation only. You will not need special
-    access to write and run programs later on.
-
- A microSD card
-
-    You'll need a card with a minimum capacity of 4GB and a maximum capacity
-    of 32GB. This type of microSD card is also known as microSDHC. We recommend
-    cards with Application Performance Class A1.
-
- A microSD card slot or card reader in your computer
-
-    If your computer does not have a (micro)SD card slot, you can use an
-    external USB (micro)SD card reader.
-
- A mini-USB cable, like the one included with your EV3 set
-
-The typical configuration of this equipment is summarized
-in :numref:`fig_overview`.
-
-.. _fig_overview:
-
-.. figure:: ../../api/images/overview_label.png
-   :width: 90 %
-   :alt: overview
-   :align: center
-
-   Setup overview
-
-Preparing your computer
-----------------------------------------------------------
-
-You'll write your MicroPython programs using Visual Studio Code. Follow the
-steps below to download, install, and configure this application:
-
-1. Download `Visual Studio Code <https://code.visualstudio.com/Download>`_.
-2. Follow the on-screen instructions to install the application.
-3. Launch Visual Studio Code.
-4. Open the extensions tab.
-5. Install the EV3 MicroPython extension as shown in :numref:`fig_store`.
-
-.. _fig_store:
-
-.. figure:: ../../api/images/store_label.png
-    :alt: store
-    :align: center
-
-    Installing the extension from the Visual Studio Code marketplace
-
-.. _prepsdcard:
-
-Preparing the microSD card
-----------------------------------------------------------
-
-To make it possible to run MicroPython programs on your EV3 Brick, you'll now
-learn how to install the required tools on your microSD card.
-
-If the microSD card contains files you want to keep, make sure to create a
-backup of its contents first.
-See :ref:`managing files on the EV3 <managefiles>` to learn how to backup your
-previous MicroPython programs if necessary.
-
-*This process erases everything on your microSD card, including any previous
-MicroPython programs on it.*
-
-
-To install the MicroPython tools on your microSD card:
-
-1. Download the `EV3 MicroPython microSD card image`_ and save it in a
-   convenient location. This file is approximately 360 MB. You do **not** need
-   to unzip the file.
-2. Download and install a microSD card flashing tool
-   such as `Etcher <https://www.balena.io/etcher/>`_.
-3. Insert the microSD card into your computer or card reader.
-4. Launch the flashing tool and follow the steps on your screen to install
-   the file you have just downloaded. If you use Etcher, you can follow the
-   instructions below, as shown in :numref:`fig_etcher`.
-
-    a. Select the EV3 MicroPython microSD card image file you have just
-       downloaded.
-    b. Select your microSD card. Make sure that the device and size correspond
-       to your microSD card.
-    c. Start the flashing process. This may take several minutes. Do not remove
-       the card until the flashing process is complete.
-
-.. _fig_etcher:
-
-.. figure:: ../../api/images/etcher_label.png
-   :width: 85 %
-   :alt: etcher
-   :align: center
-
-   Using Etcher to flash the EV3 MicroPython microSD card image
-
-Updating the microSD card
-----------------------------------------------------------
-
-To update the microSD card, download a new image file using the link above and
-flash it to the microSD card as described above. Be sure
-to :ref:`back up any MicroPython programs you want to save <managefiles>`.
-
-You do not need to erase the contents of the microSD card first. This is done
-automatically when you flash the new image file.
-
-.. _EV3 MicroPython microSD card image: https://education.lego.com/en-us/product-resources/mindstorms-ev3/teacher-resources/python-for-ev3
@@ -1,101 +0,0 @@
-Accessing advanced EV3 features
-===============================
-
-MicroPython runs on top of `ev3dev`_, which is a specific version of Linux.
-Linux is an *operating system*. (Other popular operating
-systems are Microsoft Windows and Apple macOS.) This means that your EV3 is
-almost like a real computer, just much smaller.
-
-The Linux command line
-----------------------------------------
-
-Although your EV3 Brick is quite like a real computer, you do not interact with
-it using a big screen and a mouse. Instead, you can access files and programs
-on it using the *command line*. It is also called the *terminal*.
-
-Follow the steps in :numref:`fig_terminal` to access the command line. Now
-you can enter commands by typing them in and pressing enter.
-
-.. _fig_terminal:
-
-.. figure:: ../../api/images/terminal_label.png
-   :width: 100 %
-   :alt: files
-   :align: center
-
-   Opening the Linux command line and running the ``ls`` command.
-
-**Running basic commands**
-
-For example, if you type the following command and press enter::
-
-   ls
-
-then you will see the contents of the current folder. :numref:`fig_terminal`
-shows the result: it listed the project folder of the ``getting_started``
-project that we just ran.
-
-If you type the following command and press enter::
-
-   exit
-
-then the command line will be closed. Alternatively, click the garbage icon
-shown in :numref:`fig_terminal`.
-
-You can copy text from the command line by selecting it and
-then pressing ``ctrl`` ``shift`` ``c``.
-You can paste text into the command line
-using ``ctrl`` ``shift`` ``v``.
-
-**Running commands as an administrator**
-
-Some commands require a password to run. This is similar to administrative
-tasks on your computer or tablet, such as installing a new app. These commands
-work like any other command, but you add ``sudo`` in front of
-them.
-
-As an exercise, you can run the following command to turn the EV3 Brick off::
-
-   sudo poweroff
-
-You will be prompted for a password. Type ``maker`` and then press ``Enter``.
-
-.. warning::
-
-   Only run commands with ``sudo`` if you know what you are doing.
-
-**Learning more about the command line**
-
-To learn more about the command line and many of the available commands, we
-recommend reading the beginner-friendly free ebook
-called `The Linux Command Line`_.
-
-To learn more about ev3dev-specific tips and tricks, visit the `ev3dev`_
-website.
-
-.. _hostname:
-
-Changing the EV3 Brick name
-----------------------------------------------------------
-
-When you search for your EV3 using Visual Studio Code, you see all EV3 Bricks
-listed by their name. By default, all EV3 Bricks are named *ev3dev*. Follow
-these steps to change that name:
-
-   1. Open Visual Studio Code and connect to your EV3 as usual.
-   2. Read the steps above about running commands as an administrator.
-   3. Think of a good name. In this example, we'll
-      call it ``autonomous-vehicle2``
-   4. Enter the following command and press enter::
-
-         sudo hostnamectl set-hostname autonomous-vehicle2
-
-   5. Reboot the EV3 Brick for the change to take effect.
-   6. You may need to reboot your computer as well.
-
-EV3 Brick names should only contain lowercase letters ``a`` through ``z``,
-the digits ``0`` through ``9``, and the hyphen ``-``. It must start with a
-letter or digit. It cannot include spaces or other symbols.
-
-.. _ev3dev: https://www.ev3dev.org/
-.. _The Linux Command Line: http://linuxcommand.org/tlcl.php
@@ -1,166 +0,0 @@
-Creating and running programs
-=============================
-
-Now that you've set up your computer and EV3 Brick, you're ready to start
-writing programs.
-
-To make it easier to create and manage your programs, let's first have a quick
-look at how MicroPython projects and programs for your EV3 robots are
-organized.
-
-Programs are organized into *project folders*, as shown in
-:numref:`fig_projectstructure`. A project folder is a directory on your
-computer that contains the main program (**main.py**) and other optional
-scripts or files. This project folder and all of its contents will be copied
-to the EV3 Brick, where the main program will be run.
-
-This page shows you how to create such a project and how to transfer it to the
-EV3 Brick.
-
-.. _fig_projectstructure:
-
-.. figure:: ../../api/images/projectstructure_label.png
-   :width: 100 %
-   :alt: projectstructure
-   :align: center
-
-   A project contains a program called **main.py** and optional resources like
-   sounds or MicroPython modules.
-
-
-Creating a new project
-----------------------------------------------------------
-
-To create a new project, open the EV3 MicroPython tab and
-click *create a new project*, as shown in :numref:`fig_newproject`. Enter a
-project name in the text field that appears and press *Enter*. When prompted,
-choose a location for this program and confirm by clicking *choose folder*.
-
-.. _fig_newproject:
-
-.. figure:: ../../api/images/newproject_label.png
-   :width: 100 %
-   :alt: newproject
-   :align: center
-
-   Creating a new project. This example is called *getting_started*, but you
-   can choose any name.
-
-When you create a new project, it already includes a file called *main.py*. To
-see its contents and to modify it, open it from the file browser as shown in
-:numref:`fig_projectoverview`. This is where you'll write your programs.
-
-If you are new to MicroPython programming, we recommend that you keep the
-existing code in place and add your code to it.
-
-.. _fig_projectoverview:
-
-.. figure:: ../../api/images/projectoverview_label.png
-   :width: 100 %
-   :alt: projectoverview
-   :align: center
-
-   Opening the default *main.py* program.
-
-Opening an existing project
-----------------------------------------------------------
-
-To open a project you created previously, click *File* and click
-*Open Folder*, as shown in :numref:`fig_existingproject`. Next, navigate to
-your previously created project folder and click *OK*. You can also open your
-recently used projects using the *Open Recent* menu option.
-
-.. _fig_existingproject:
-
-.. figure:: ../../api/images/existingproject_label.png
-   :width: 75 %
-   :alt: existingproject
-   :align: center
-
-   Opening a previously created project.
-
-
-Connecting to the EV3 Brick with Visual Studio Code
-----------------------------------------------------------
-
-To be able to transfer your code to the EV3 Brick, you'll first need to
-connect the EV3 Brick to your computer with the mini-USB cable and configure
-the connection with Visual Studio Code. To do so:
-
- Turn the EV3 Brick on
- Connect the EV3 Brick to your computer with the mini-USB cable
- Configure the USB connection as shown in :numref:`fig_connecting`.
-
-.. _fig_connecting:
-
-.. figure:: ../../api/images/connecting_label.png
-   :width: 100 %
-   :alt: connecting
-   :align: center
-
-   Configuring the USB connection between the computer and the EV3 Brick
-
-Downloading and running a program
-----------------------------------------------------------
-
-You can press the F5 key to run the program. Alternatively, you can start it
-manually by going to the *debug* tab and clicking the green start arrow, as
-shown in :numref:`fig_running`.
-
-When the program starts, a pop-up toolbar allows you to stop the program if
-necessary. You can also stop the program at any time using the back button on
-the EV3 Brick.
-
-If your program produces any output with the ``print`` command, this is shown
-in the output window.
-
-.. _fig_running:
-
-.. figure:: ../../api/images/running_label.png
-   :width: 100 %
-   :alt: running
-   :align: center
-
-   Running a program
-
-Expanding the example program
-----------------------------------------------------------
-
-Now that you've run the basic code template, you can expand the program to
-make a motor move. First, attach a Large Motor to Port B on the EV3 Brick,
-as shown  in :numref:`fig_firstprogram`.
-
-.. _fig_firstprogram:
-
-.. figure:: ../../api/images/firstprogram_label.png
-   :width: 100 %
-   :alt: firstprogram
-   :align: center
-
-   The EV3 Brick with a Large Motor attached to port B.
-
-Next, edit *main.py* to make it look like this:
-
-.. literalinclude::
-   ../../../examples/ev3/getting_started/main.py
-
-This program makes your robot beep, rotate the motor, and beep again with a
-higher pitched tone. Run the program to make sure that it works as expected.
-
-.. _managefiles:
-
-Managing files on the EV3 Brick
-----------------------------------------------------------
-
-After you've downloaded a project to the EV3 Brick, you can run, delete, or
-back up programs stored on it using the device browser as shown in
-:numref:`fig_files`.
-
-.. _fig_files:
-
-.. figure:: ../../api/images/files_label.png
-   :width: 100 %
-   :alt: files
-   :align: center
-
-   Using the EV3 device browser to manage files on your EV3 Brick
@@ -1,248 +0,0 @@
-Upgrading from v1.0 to v2.0
-===============================
-
-*EV3 MicroPython version 2.0 was released on May 18, 2020.*
-
-This section is for users who have previously used LEGO MINDSTORMS EV3
-MicroPython v1.0. We'll explain what's changed and how you can upgrade to
-benefit from the latest improvements.
-
-If you are a new user and you just got started using version 2.0, you can skip
-this page.
-
-Upgrading the microSD Card
-----------------------------------------
-
-To upgrade, download the latest microSD card file and install it using the
-standard :ref:`instructions <prepsdcard>`.
-
-Note that this will erase all your existing files on the SD Card. Before you
-upgrade, make sure that you still have all your projects on your computer.
-If not, you can upload files back to your computer using
-:ref:`these instructions <managefiles>`.
-
-As with any software update, *be careful about when you update*. For example,
-if you developed your code using version v1.0 and you are halfway into your
-robotics competition season, you may want to stick with v1.0 for now.
-
-
-Upgrading your existing programs
-----------------------------------------
-
-Most changes in v2.0 are *new* features, like support for additional sensors.
-Naturally, this will not affect your existing code.
-However, some changes were made to existing features to improve performance.
-
-All originally documented features in v1.0 will still work after you upgrade.
-This means that most programs originally made for v1.0 will work with the v2.0
-microSD card image without any changes.
-
-To try this, simply download and run your original code as you did before.
-
-However, it is recommended that you upgrade both the microSD card and your
-programs at the same time to ensure everything works as expected.
-
-The new EV3Brick() class replaces the ev3brick module
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Version 2.0 introduces the :class:`EV3Brick() <pybricks.hubs.EV3Brick>` class.
-You can use it instead of the old  ``ev3brick`` module. The old ``ev3brick``
-module can still be used, but it is no longer recommended or documented.
-
-The :class:`EV3Brick() <pybricks.hubs.EV3Brick>` class improves the speed and
-reliability of the EV3 screen and the EV3 speaker. It also adds functionality
-like speech and drawing shapes. The default
-font size is also bigger to make it easier to read text on the screen.
-
-You can use
-the following table as a starting point to upgrade your scripts. See the
-:class:`EV3Brick() <pybricks.hubs.EV3Brick>` class documentation for
-complete details of all methods and arguments.
-
-.. list-table::
-
-  * - **Action**
-    - **v1.0**
-    - **v2.0**
-
-  * - | Initialize
-      | your EV3
-    - ::
-
-          from pybricks import ev3brick as brick
-    - ::
-
-          from pybricks.hubs import EV3Brick
-
-          ev3 = EV3Brick()
-
-  * - | Light on
-    - ::
-
-          brick.light(Color.RED)
-    - ::
-
-          ev3.light.on(Color.RED)
-
-  * - | Light off
-    - ::
-
-          brick.light(None)
-    - ::
-
-          ev3.light.off()
-
-  * - | Read
-      | Buttons
-    - ::
-
-          if Button.LEFT in brick.buttons():
-              print("Left is pressed.")
-    - ::
-
-          if Button.LEFT in ev3.buttons.pressed():
-              print("Left is pressed.")
-
-  * - | Play a
-      | beep
-    - ::
-
-          brick.sound.beep()
-    - ::
-
-          ev3.speaker.beep()
-
-  * - | Play a
-      | sound file
-    - ::
-
-          brick.sound.file(SoundFile.HELLO)
-    - ::
-
-          ev3.speaker.play_file(SoundFile.HELLO)
-
-  * - | Text to
-      | speech
-    -
-    - ::
-
-          ev3.speaker.say("I can say anything!")
-
-  * - | Play
-      | notes
-    -
-    - ::
-
-          ev3.speaker.play_notes(['C4/4', 'G4/4'])
-
-  * - | Write text
-      | at a given
-      | position
-    - ::
-
-          brick.display.text("Hello!", (50, 60))
-    - ::
-
-          ev3.screen.draw_text(50, 60, "Hello!")
-
-  * - | Write text
-      | and scroll
-      | automatically
-    - ::
-
-          brick.display.text("Hello")
-          brick.display.text("world!")
-    - ::
-
-          ev3.screen.print("Hello")
-          ev3.screen.print("world!")
-
-  * - | Change font
-      | size
-    -
-    - ::
-
-          from pybricks.media.ev3dev import Font
-
-          big_font = Font(size=24)
-          ev3.screen.set_font(big_font)
-
-  * - | Display an
-      | image on
-      | the screen
-    - ::
-
-          from pybricks.parameters import ImageFile
-
-          brick.display.image(ImageFile.QUESTION_MARK)
-    - ::
-
-          from pybricks.media.ev3dev import ImageFile
-
-          ev3.screen.load_image(ImageFile.Question_MARK)
-
-  * - | Draw shapes
-      | on the screen
-    -
-    - ::
-
-          ev3.screen.draw_line(30, 30, 30, 100)
-          ev3.screen.draw_box(50, 30, 90, 60)
-          ev3.screen.draw_circle(70, 90, 20, fill=True)
-
-  * - | Read
-      | battery
-      | voltage
-    - ::
-
-          brick.battery.voltage()
-    - ::
-
-          ev3.battery.voltage()
-
-
-Other internal changes to existing features
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- Most methods of the ``Motor`` class now
-  have ``Stop.HOLD`` as the default instead of ``Stop.COAST``. This improves
-  accuracy in most applications. You can still select ``Stop.COAST`` if you
-  like.
- The internal PID controllers for the motors are more accurate than before.
-  If you give a motor command when it is already running, it smoothly adjusts
-  the speed to the newly given command. This works even if you keep
-  adjusting the speed in a fast loop.
- Methods to configure motor settings have changed. You can change settings
-  using the ``control`` attribute now. The old settings setters
-  continue to exist in the implementation, but they are no longer documented.
- So-called Python *keyword arguments* are now supported. Previously, you
-  could only enter the argument *values*. For example:
-
-   ::
-
-       my_motor.run_angle(500, 90, Stop.HOLD, False)
-
-  This is still possible. But you can now choose to omit optional arguments
-  and specify others with *keywords*. This can make your code easier to read.
-  For example:
-
-   ::
-
-      my_motor.run_angle(500, 90, wait=False)
- It is no longer necessary to import ``pybricks.tools.print``. The ``print``
-  function is now built-in. It works just like Python or MicroPython.
- Most parameters in the :mod:`parameters <pybricks.parameters>` now have a
-  specific type and representation. For example, suppose you measure a color
-  and print the result. If you do ``print(Color.RED)``, you will see the
-  parameter instead of a technical number.
- Sound and image files have moved to a dedicated ``media`` module.
-  Importing them from the old location will continue to work in this release,
-  to make sure existing scripts will still work.
-
-**Installing an older version of the Visual Studio Code extension**
-
-The Visual Studio Code extension and this documentation are updated
-automatically. You can still use your existing scripts with the updated
-extension. If you absolutely wish to keep the old version, look for the EV3
-extension on the extension tab, click the gear icon, and
-click *install another version*.
@@ -1,4 +0,0 @@
-SPIKE Prime / Robot Inventor
-########################################################
-
-Coming soon!
@@ -1,151 +0,0 @@
-Powered Up Quick Start
-########################
-
-.. figure:: ../api/images/powereduphubs.png
-    :height: 15 em
-    :align: center
-
-This page shows how you can install Pybricks on your hub and run your first
-program. When you're ready, browse through the Pybricks Modules in the left
-hand menu to modify the example program.
-
-.. note::
-
-    - **This is still in beta! Not everything may work as expected yet.**
-
-    - We welcome your questions, feedback and bug reports on our `support page`_.
-
-    - For now, sensors/motors are detected automatically only once.
-      So if you change the cables, you have to turn the hub off and on again.
-      You can turn it off by holding down the button for about 5 seconds.
-
-Installing Google Chrome
--------------------------------------
-
-Writing Pybricks programs requires a web browser with web Bluetooth
-functionality. Currently, only Google Chrome supports this.
-Download Google Chrome `from here`_.
-
-If you use Linux, enable *Experimental Web Platform features* on
-the ``chrome://flags/`` page.
-
-Installing the Pybricks firmware
--------------------------------
-
-Pybricks uses an improved firmware that can run autonomous programs.
-Installing it is easy:
-
-1. Make sure you use fresh batteries.
-2. Unplug all motors and sensors.
-3. Follow the steps in the video below.
-
-.. raw:: html
-
-    <video controls src="https://pybricks.com/wp-content/uploads/2020/06/install.mp4" width="100%"></video>
-    <br />
-
-If you prefer written instructions, follow these instead:
-
-    - Make sure you use fresh batteries.
-    - Unplug all motors and sensors.
-    - Make sure the hub is off.
-    - Press and hold the green button.
-    - Wait for the light to blink, but keep holding the button.
-    - On the Pybricks Code page, click the firmware update button.
-    - Select the ``LEGO Bootloader`` and click *Pair*.
-    - The light should change to a red/green/blue sequence.
-    - You can now release the button.
-    - Wait for the update to finish, indicated by a blinking blue light.
-    - If you use the recommended browser, this will take about 90 seconds.
-
-Running programs
--------------------------------
-
-Once the firmware is installed, you can start coding! Use the *Bluetooth*
-button to search for and connect to your *Pybricks Hub*. Then press run to
-start your program.
-
-.. figure:: ../api/images/pybrickscode.png
-
-To get started, just copy and paste this snippet::
-
-    from pybricks.pupdevices import Motor
-    from pybricks.parameters import Port, Stop
-    from pybricks.tools import wait
-
-    # We'll use two motors. One is a dial
-    # to set the speed of the other motor.
-    motor = Motor(Port.B)
-    dial = Motor(Port.A)
-
-    # Say hello :)
-    print("Hello, Pybricks!")
-
-    # First, we'll move the dial to zero.
-    dial.run_target(500, 0, Stop.COAST)
-
-    while True:
-        # Set the speed based on dial angle
-        speed = dial.angle()*3
-        if abs(speed) < 100:
-            speed = 0
-
-        # Run motor at desired speed
-        motor.run(speed)
-
-        # Wait briefly, then repeat
-        wait(10)
-
-
-Restoring the LEGO Firmware
---------------------------
-
-Pybricks uses the same update method as the LEGO apps; just with a different
-firmware file. This means you can go back to the original firmware any time.
-As shown in the video below, just put the hub in update mode and
-connect using a LEGO app.
-
-.. raw:: html
-
-    <video controls src="https://pybricks.com/wp-content/uploads/2020/06/restore.mp4" width="100%"></video>
-
-This video shows the Powered Up app in *create* mode. It has firmware for all
-hubs. As usual, you may need to restart the app to detect the hub. If it fails,
-try again with fresh batteries.
-
-Saving a program permanently (BETA)
-----------------------------------
-.. note::
-
-   This functionality is in beta. It is currently only recommended for
-   advanced users. In the long run, we'll make this easy to do with
-   the online editor.
-
-When you run a program the normal way, it is deleted as soon as it's done.
-That's because Powered Up hubs don't have a file system to store programs.
-Fortunately, you can still save a script on the hub by including it
-in the firmware.
-
-Of course, this is a bit slow to do every time. We recommend the
-using the standard procedure most of the time.
-When you're happy with your final program, you can save it permanently as
-described below. To change the program, just repeat these steps:
-
-1. Sign in to GitHub.
-2. Go to our `GitHub builds`_.
-3. Click on the build you want. This is usually the one at the top.
-4. Then scroll down to `Artifacts`.
-5. Download the firmware for your hub. The firmware is a ZIP archive
-   containing the basic firmware and one ``main.py`` script.
-6. Modify the ``main.py`` file as you like.
-7. Drag your modified ZIP file *onto* the firmware update button of the
-   online editor.
-8. The update now proceeds as usual.
-
-*Once installed, you can start that program with the green button.
-No connection required!*
-
-.. _GitHub builds: https://github.com/pybricks/pybricks-micropython/actions?query=is%3Asuccess+branch%3Amaster+workflow%3ABuild
-.. _support page: https://github.com/pybricks/support/issues/
-.. _Pybricks Code: http://code.pybricks.com/
-.. _from here: https://www.google.com/chrome/
@@ -13,7 +13,7 @@ At the moment, this class is only available on EV3.
    use this class on 13 February 2020 on 10:07 and 44.431260
    seconds, the file is called ``log_2020_02_13_10_07_44_431260.csv``.

-    See :ref:`managing files on the EV3 <managefiles>` to learn how to upload
+    See `managing files on the EV3`_ to learn how to upload
    the log file back to your computer.


@@ -71,3 +71,5 @@ name will always be the same. However, this means that the contents of
 ``my_file.txt`` will be overwritten every time you run this script.

 .. literalinclude:: ../../../examples/ev3/datalog_extra/main.py
+
+.. _managing files on the EV3: https://pybricks.com/install/mindstorms-ev3/running-programs#managing-files-on-the-ev3-brick
@@ -4,3 +4,39 @@
 .wy-breadcrumbs li.wy-breadcrumbs-aside {
    display: none;
 }
+
+/* Scrollbar styling to match Pybricks Code. */
+/* https://github.com/pybricks/pybricks-code/blob/master/src/index.scss */
+
+::-webkit-scrollbar {
+    width: 16px;
+}
+
+.bp3-dark ::-webkit-scrollbar-track {
+    background: #293742;
+}
+
+::-webkit-scrollbar-track {
+    background: #e8e8e8;
+}
+
+.bp3-dark ::-webkit-scrollbar-thumb {
+    border-color: #293742;
+    background: #a7b6c2;
+}
+
+::-webkit-scrollbar-thumb {
+    border-width: 3px;
+    border-style: solid;
+    border-radius: 8px;
+    border-color: #e8e8e8;
+    background: #5c7080;
+}
+
+.bp3-dark ::-webkit-scrollbar-thumb:hover {
+    background: #f5f8fa;
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: #182026;
+}
@@ -59,6 +59,7 @@ extensions = [
    'sphinx.ext.todo',
    'sphinx.ext.mathjax',
    'color',
+    'classlink',
 ]

 # Add any paths that contain templates here, relative to this directory.
@@ -130,7 +131,10 @@ nitpick_ignore = [
 # -- Autodoc options ------------------------------------------------------

 autodoc_member_order = 'bysource'
-autodoc_default_flags = ['members', 'undoc-members']
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+}
 autoclass_content = 'both'  # This ensures init arguments are not ignored
 add_module_names = False  # Hide module name

@@ -0,0 +1,31 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+class PybricksClasslinkDirective(Directive):
+
+    required_arguments = 1
+
+    def run(self):
+        # Get link name from sphinx-directive
+        name = self.arguments[0]
+
+        html = (
+            '<a href="{0}.html">'.format(name.lower()) +
+            '<dl class="py class">' +
+            '<dt>' +
+            '<em class="property">class </em>' +
+            '<code class="sig-name descname">' + name + '</code>' +
+            '</dt>' +
+            '<dd></dd>' +
+            '</dl>' +
+            '</a>'
+        )
+
+        # Return the node
+        node = nodes.raw('', html, format="html")
+        return [node]
+
+
+def setup(app):
+    app.add_directive_to_domain('py', 'pybricks-classlink', PybricksClasslinkDirective)
@@ -27,6 +27,11 @@ class PybricksColorDirective(Directive):

        # Render a small block of the given color
        css = "background-color: {0}; color: {0}; width: 50px;".format(rgbhex)
+
+        if name == "WHITE":
+            css += "border-style: solid; border-width: 0.5px;" + \
+                   "border-color: #666666;"
+
        html = '<div id="test" style="{0}">_</div>'.format(css)

        # Return the node
@@ -1,3 +1,24 @@
+# 1.3.0 - 2021-04-12
+
+## Removed:
+- Removed features which not be in the official 3.0 release. These features
+  are still in beta. They'll come back in future releases once tested.
+
+# 1.2.0 - 2021-04-09
+
+## Changed:
+- Moved installation guide to external site.
+
+# 1.1.1 - 2021-02-14
+
+## Added:
+- Added installation guide.
+- Various documentation fixes.
+
+# 1.1.0 - 2021-01-28
+
+## Added:
+- Scrollbar styling.

 # 1.0.0 - 2021-01-25

@@ -1 +0,0 @@
-.. include:: ../api/geometry.rst
@@ -10,39 +10,22 @@
   movehub
   cityhub
   technichub
-   primehub

-.. class:: MoveHub
-    :noindex:
+.. pybricks-classlink:: MoveHub

 .. figure:: ../../api/images/movehub.png
    :height: 10 em
    :target: movehub.html

-.. class:: CityHub
-    :noindex:
+.. pybricks-classlink:: CityHub

 .. figure:: ../../api/images/cityhub.png
    :height: 10 em
    :target: cityhub.html

-.. class:: TechnicHub
-    :noindex:
+.. pybricks-classlink:: TechnicHub

 .. figure:: ../../api/images/technichub.png
    :height: 10 em
    :target: technichub.html

-.. class:: PrimeHub
-    :noindex:
-
-.. figure:: ../../api/images/primehub.png
-    :height: 10 em
-    :target: primehub.html
-
-.. class:: InventorHub
-    :noindex:
-
-.. figure:: ../../api/images/inventorhub.png
-    :height: 10 em
-    :target: primehub.html
@@ -1 +0,0 @@
-.. include:: ../../api/hubs/primehub.rst
@@ -1,12 +1,6 @@
 Pybricks Documentation
 ==================================================================

-.. note::
-
-   The installation guide and other documentation are available at
-   `docs.pybricks.com`_. This window contains only
-   documentation and examples for all available classes and methods.
-
 .. toctree::
   :maxdepth: 1
   :caption: Pybricks Modules
@@ -15,10 +9,9 @@ Pybricks Documentation
   hubs/index
   pupdevices/index
   iodevices/index
-   parameters
+   parameters/index
   tools/index
   robotics
-   geometry

 .. toctree::
   :maxdepth: 1
@@ -28,12 +21,15 @@ Pybricks Documentation
   signaltypes
   motors

+To begin, install the Pybricks firmware on your hub. Check
+`pybricks.com/install`_ to learn how.
+
 Use the ☰ menu to navigate all available classes, methods, and tools. A few
-commonly used devices are listed below for quick reference.
+commonly used devices and classes are listed below for quick reference.

-.. rubric:: Powered Up Hubs
+.. rubric:: Programmable Hubs

-.. figure:: ../api/images/hubsoverview.png
+.. figure:: ../api/images/powereduphubs.png
   :width: 100 %
   :target: hubs/index.html

@@ -43,4 +39,4 @@ commonly used devices are listed below for quick reference.
   :width: 100 %
   :target: pupdevices/index.html

-.. _docs.pybricks.com: https://docs.pybricks.com/
+.. _pybricks.com/install: https://pybricks.com/install/
@@ -10,8 +10,7 @@

   pupdevice

-.. class:: PUPDevice
-    :noindex:
+.. pybricks-classlink:: PUPDevice

 .. figure:: ../../api/images/sensor_pup.png
   :width: 70 %
@@ -1,6 +1,6 @@
 {
  "name": "@pybricks/ide-docs",
-  "version": "1.0.0",
+  "version": "1.3.0",
  "description": "Special build of Pybricks API docs for embedding in an IDE.",
  "repository": {
    "type": "git",
@@ -8,8 +8,8 @@
    "directory": "doc/ide"
  },
  "publishConfig": {
-      "registry": "https://registry.npmjs.org",
-      "access": "public"
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
  },
  "author": "The Pybricks Authors",
  "license": "MIT",
@@ -1 +0,0 @@
-.. include:: ../api/parameters.rst
@@ -0,0 +1 @@
+.. include:: ../../api/parameters/color.rst
@@ -0,0 +1 @@
+.. include:: ../../api/parameters/direction.rst
@@ -0,0 +1,23 @@
+:mod:`parameters <pybricks.parameters>` -- Parameters and Constants
+===================================================================
+
+.. automodule:: pybricks.parameters
+    :no-members:
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   color
+   direction
+   port
+   stop
+
+.. pybricks-classlink:: Color
+
+.. pybricks-classlink:: Direction
+
+.. pybricks-classlink:: Port
+
+.. pybricks-classlink:: Stop
+
@@ -0,0 +1,24 @@
+Port
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: Port
+
+    Input and output ports:
+
+    .. autoattribute:: pybricks.parameters.Port.A
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.B
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.C
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.D
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.E
+        :annotation:
+
+    .. autoattribute:: pybricks.parameters.Port.F
+        :annotation:
@@ -0,0 +1 @@
+.. include:: ../../api/parameters/stop.rst
@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/remote.rst
@@ -0,0 +1,16 @@
+from pybricks.hubs import MoveHub
+from pybricks.tools import wait
+
+# Initialize the hub.
+hub = MoveHub()
+
+# Get the acceleration tuple.
+print(hub.imu.acceleration())
+
+while True:
+    # Get individual acceleration values.
+    x, y, z = hub.imu.acceleration()
+    print(x, y, z)
+
+    # Wait so we can see what we printed.
+    wait(100)
@@ -0,0 +1,29 @@
+from pybricks.hubs import MoveHub
+from pybricks.parameters import Color, Side
+from pybricks.tools import wait
+
+# Initialize the hub.
+hub = MoveHub()
+
+# Define colors for each side in a dictionary.
+SIDE_COLORS = {
+    Side.TOP: Color.RED,
+    Side.BOTTOM: Color.BLUE,
+    Side.LEFT: Color.GREEN,
+    Side.RIGHT: Color.YELLOW,
+    Side.FRONT: Color.MAGENTA,
+    Side.BACK: Color.BLACK,
+}
+
+# Keep updating the color based on detected up side.
+while True:
+
+    # Check which side of the hub is up.
+    up_side = hub.imu.up()
+
+    # Change the color based on the side.
+    hub.light.on(SIDE_COLORS[up_side])
+
+    # Also print the result.
+    print(up_side)
+    wait(50)
@@ -23,7 +23,7 @@ if Button.LEFT in pressed:
    hub.display.image(Icon.ARROW_LEFT_DOWN)
 elif Button.RIGHT in pressed:
    hub.display.image(Icon.ARROW_RIGHT_DOWN)
-elif Button.BT in pressed:
+elif Button.BLUETOOTH in pressed:
    hub.display.image(Icon.ARROW_RIGHT_UP)

 wait(3000)
@@ -1,4 +1,4 @@
-# ExampleHub = TechnicHub PrimeHub
+# ExampleHub = TechnicHub PrimeHub MoveHub
 from pybricks.hubs import ExampleHub
 from pybricks.parameters import Color, Side
 from pybricks.tools import wait
@@ -26,7 +26,7 @@ wait(1500)

 # Run at 500 deg/s for 90 degrees.
 print("Demo of run_angle")
-example_motor.run_angle(500, 180)
+example_motor.run_angle(500, 90)
 wait(1500)

 # Run at 500 deg/s back to the 0 angle
@@ -0,0 +1,31 @@
+from pybricks.parameters import Color
+
+# Two colors are equal if their h, s, and v attributes are equal.
+if Color.BLUE == Color(240, 100, 100):
+    print("Yes, these colors are the same.")
+
+# You can scale colors to change their brightness value.
+red_dark = Color.RED * 0.5
+
+# You can shift colors to change their hue.
+red_shifted = Color.RED >> 30
+
+# Colors are immutable, so you can't change h, s, or v of an existing object.
+try:
+    Color.GREEN.h = 125
+except AttributeError:
+    print("Sorry, can't change the hue of an existing color object!")
+
+# But you can override builtin colors by defining a whole new color.
+Color.GREEN = Color(h=125)
+
+# You can access and store colors as class attributes, or as a dictionary.
+print(Color.BLUE)
+print(Color["BLUE"])
+print(Color["BLUE"] is Color.BLUE)
+print(Color)
+print([c for c in Color])
+
+# This allows you to update existing colors in a loop.
+for name in ("BLUE", "RED", "GREEN"):
+    Color[name] = Color(1, 2, 3)
@@ -0,0 +1,23 @@
+from pybricks.parameters import Color
+
+# You can print colors. Colors may be obtained from the Color class, or
+# from sensors that return color measurements.
+print(Color.RED)
+
+# You can read hue, saturation, and value properties.
+print(Color.RED.h, Color.RED.s, Color.RED.v)
+
+# You can make your own colors. Saturation and value are 100 by default.
+my_green = Color(h=125)
+my_dark_green = Color(h=125, s=80, v=30)
+
+# When you print custom colors, you see exactly how they were defined.
+print(my_dark_green)
+
+# You can also add colors to the builtin colors.
+Color.MY_DARK_BLUE = Color(h=235, s=80, v=30)
+
+# When you add them like this, printing them only shows its name. But you can
+# still read h, s, v by reading its attributes.
+print(Color.MY_DARK_BLUE)
+print(Color.MY_DARK_BLUE.h, Color.MY_DARK_BLUE.s, Color.MY_DARK_BLUE.v)
@@ -5,26 +5,22 @@ from pybricks.tools import wait
 # Initialize the sensor.
 sensor = ColorSensor(Port.A)

-# First, decide which objects you want to detect.
-# Then measure their color with the hsv() method,
-# as shown in the previous example. Write them down
-# as shown below. The name is optional, but it is
-# useful when you print the color value.
-green = Color(h=132, s=94, v=26, name='GREEN_BRICK')
-magenta = Color(h=348, s=96, v=40, name='MAGENTA_BRICK')
-brown = Color(h=17, s=78, v=15, name='BROWN_BRICK')
-red = Color(h=359, s=97, v=39, name='RED_BRICK')
+# First, decide which objects you want to detect, and measure their HSV values.
+# You can do that with the hsv() method as shown in the previous example.
+#
+# Use your measurements to override the default colors, or add new colors:
+Color.GREEN = Color(h=132, s=94, v=26)
+Color.MAGENTA = Color(h=348, s=96, v=40)
+Color.BROWN = Color(h=17, s=78, v=15)
+Color.RED = Color(h=359, s=97, v=39)

 # Put your colors in a list or tuple.
-# Including None is optional. Just omit it if
-# you always want to get one of your colors.
-my_colors = (green, magenta, brown, red, None)
+my_colors = (Color.GREEN, Color.MAGENTA, Color.BROWN, Color.RED, Color.NONE)

 # Save your colors.
 sensor.detectable_colors(my_colors)

-# color() works as usual, but it only
-# returns one of your specified colors.
+# color() works as usual, but now it returns one of your specified colors.
 while True:
    color = sensor.color()

@@ -32,7 +28,7 @@ while True:
    print(color)

    # Check which one it is.
-    if color == magenta:
+    if color == Color.MAGENTA:
        print("It works!")

    # Wait so we can read it.
@@ -11,11 +11,11 @@ while True:
    # Turn on one light at a time, at half the brightness.
    # Do this for all 3 lights and repeat that 5 times.
    for i in range(5):
-        sensor.lights.on(50, 0, 0)
+        sensor.lights.on([50, 0, 0])
        wait(100)
-        sensor.lights.on(0, 50, 0)
+        sensor.lights.on([0, 50, 0])
        wait(100)
-        sensor.lights.on(0, 0, 50)
+        sensor.lights.on([0, 0, 50])
        wait(100)

    # Turn all lights on at maximum brightness.
@@ -5,26 +5,22 @@ from pybricks.tools import wait
 # Initialize the sensor.
 sensor = ColorDistanceSensor(Port.A)

-# First, decide which objects you want to detect.
-# Then measure their color with the hsv() method,
-# as shown in the previous example. Write them down
-# as shown below. The name is optional, but it is
-# useful when you print the color value.
-green = Color(h=132, s=94, v=26, name='GREEN_BRICK')
-magenta = Color(h=348, s=96, v=40, name='MAGENTA_BRICK')
-brown = Color(h=17, s=78, v=15, name='BROWN_BRICK')
-red = Color(h=359, s=97, v=39, name='RED_BRICK')
+# First, decide which objects you want to detect, and measure their HSV values.
+# You can do that with the hsv() method as shown in the previous example.
+#
+# Use your measurements to override the default colors, or add new colors:
+Color.GREEN = Color(h=132, s=94, v=26)
+Color.MAGENTA = Color(h=348, s=96, v=40)
+Color.BROWN = Color(h=17, s=78, v=15)
+Color.RED = Color(h=359, s=97, v=39)

 # Put your colors in a list or tuple.
-# Including None is optional. Just omit it if
-# you always want to get one of your colors.
-my_colors = (green, magenta, brown, red, None)
+my_colors = (Color.GREEN, Color.MAGENTA, Color.BROWN, Color.RED, Color.NONE)

 # Save your colors.
 sensor.detectable_colors(my_colors)

-# color() works as usual, but it only
-# returns one of your specified colors.
+# color() works as usual, but now it returns one of your specified colors.
 while True:
    color = sensor.color()

@@ -32,7 +28,7 @@ while True:
    print(color)

    # Check which one it is.
-    if color == magenta:
+    if color == Color.MAGENTA:
        print("It works!")

    # Wait so we can read it.
@@ -24,9 +24,8 @@ while True:
    # lights do something different.
    brightness = [sin(phase + offset*pi/2) * 50 + 50 for offset in range(4)]

-    # Set the brightness values for all lights. The * symbol unpacks the list
-    # of brightness values into separate arguments.
-    eyes.lights.on(*brightness)
+    # Set the brightness values for all lights.
+    eyes.lights.on(brightness)

    # Wait some time.
    wait(50)
@@ -292,33 +292,38 @@ python-versions = "*"

 [[package]]
 name = "sphinx"
-version = "1.8.5"
+version = "3.4.3"
 description = "Python documentation generator"
 category = "dev"
 optional = false
-python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
+python-versions = ">=3.5"

 [package.dependencies]
 alabaster = ">=0.7,<0.8"
-babel = ">=1.3,<2.0 || >2.0"
+babel = ">=1.3"
 colorama = {version = ">=0.3.5", markers = "sys_platform == \"win32\""}
-docutils = ">=0.11"
+docutils = ">=0.12"
 imagesize = "*"
 Jinja2 = ">=2.3"
 packaging = "*"
 Pygments = ">=2.0"
-requests = ">=2.0.0"
-six = ">=1.5"
+requests = ">=2.5.0"
 snowballstemmer = ">=1.1"
-sphinxcontrib-websupport = "*"
+sphinxcontrib-applehelp = "*"
+sphinxcontrib-devhelp = "*"
+sphinxcontrib-htmlhelp = "*"
+sphinxcontrib-jsmath = "*"
+sphinxcontrib-qthelp = "*"
+sphinxcontrib-serializinghtml = "*"

 [package.extras]
-test = ["mock", "pytest", "pytest-cov", "html5lib", "flake8 (>=3.5.0)", "flake8-import-order", "enum34", "mypy", "typed-ast"]
-websupport = ["sqlalchemy (>=0.9)", "whoosh (>=2.0)"]
+docs = ["sphinxcontrib-websupport"]
+lint = ["flake8 (>=3.5.0)", "isort", "mypy (>=0.790)", "docutils-stubs"]
+test = ["pytest", "pytest-cov", "html5lib", "cython", "typed-ast"]

 [[package]]
 name = "sphinx-rtd-theme"
-version = "0.4.3"
+version = "0.5.1"
 description = "Read the Docs theme for Sphinx"
 category = "dev"
 optional = false
@@ -327,6 +332,68 @@ python-versions = "*"
 [package.dependencies]
 sphinx = "*"

+[package.extras]
+dev = ["transifex-client", "sphinxcontrib-httpdomain", "bump2version"]
+
+[[package]]
+name = "sphinxcontrib-applehelp"
+version = "1.0.2"
+description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books"
+category = "dev"
+optional = false
+python-versions = ">=3.5"
+
+[package.extras]
+lint = ["flake8", "mypy", "docutils-stubs"]
+test = ["pytest"]
+
+[[package]]
+name = "sphinxcontrib-devhelp"
+version = "1.0.2"
+description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document."
+category = "dev"
+optional = false
+python-versions = ">=3.5"
+
+[package.extras]
+lint = ["flake8", "mypy", "docutils-stubs"]
+test = ["pytest"]
+
+[[package]]
+name = "sphinxcontrib-htmlhelp"
+version = "1.0.3"
+description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files"
+category = "dev"
+optional = false
+python-versions = ">=3.5"
+
+[package.extras]
+lint = ["flake8", "mypy", "docutils-stubs"]
+test = ["pytest", "html5lib"]
+
+[[package]]
+name = "sphinxcontrib-jsmath"
+version = "1.0.1"
+description = "A sphinx extension which renders display math in HTML via JavaScript"
+category = "dev"
+optional = false
+python-versions = ">=3.5"
+
+[package.extras]
+test = ["pytest", "flake8", "mypy"]
+
+[[package]]
+name = "sphinxcontrib-qthelp"
+version = "1.0.3"
+description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document."
+category = "dev"
+optional = false
+python-versions = ">=3.5"
+
+[package.extras]
+lint = ["flake8", "mypy", "docutils-stubs"]
+test = ["pytest"]
+
 [[package]]
 name = "sphinxcontrib-serializinghtml"
 version = "1.1.4"
@@ -339,21 +406,6 @@ python-versions = ">=3.5"
 lint = ["flake8", "mypy", "docutils-stubs"]
 test = ["pytest"]

-[[package]]
-name = "sphinxcontrib-websupport"
-version = "1.2.4"
-description = "Sphinx API for Web Apps"
-category = "dev"
-optional = false
-python-versions = ">=3.5"
-
-[package.dependencies]
-sphinxcontrib-serializinghtml = "*"
-
-[package.extras]
-lint = ["flake8"]
-test = ["pytest", "sqlalchemy", "whoosh", "sphinx"]
-
 [[package]]
 name = "stevedore"
 version = "3.3.0"
@@ -405,7 +457,7 @@ socks = ["PySocks (>=1.5.6,<1.5.7 || >1.5.7,<2.0)"]
 [metadata]
 lock-version = "1.1"
 python-versions = "^3.8"
-content-hash = "383f496c8938184431ac13f3086cc28e4601e4f07b121dc98ff1f1752ed0cf11"
+content-hash = "4d6ac2394f202eb7b9e91a510d807c6e2f56ae61ef23c28edeb5d9feaf741fc1"

 [metadata.files]
 alabaster = [
@@ -598,21 +650,37 @@ snowballstemmer = [
    {file = "snowballstemmer-2.1.0.tar.gz", hash = "sha256:e997baa4f2e9139951b6f4c631bad912dfd3c792467e2f03d7239464af90e914"},
 ]
 sphinx = [
-    {file = "Sphinx-1.8.5-py2.py3-none-any.whl", hash = "sha256:9f3e17c64b34afc653d7c5ec95766e03043cc6d80b0de224f59b6b6e19d37c3c"},
-    {file = "Sphinx-1.8.5.tar.gz", hash = "sha256:c7658aab75c920288a8cf6f09f244c6cfdae30d82d803ac1634d9f223a80ca08"},
+    {file = "Sphinx-3.4.3-py3-none-any.whl", hash = "sha256:c314c857e7cd47c856d2c5adff514ac2e6495f8b8e0f886a8a37e9305dfea0d8"},
+    {file = "Sphinx-3.4.3.tar.gz", hash = "sha256:41cad293f954f7d37f803d97eb184158cfd90f51195131e94875bc07cd08b93c"},
 ]
 sphinx-rtd-theme = [
-    {file = "sphinx_rtd_theme-0.4.3-py2.py3-none-any.whl", hash = "sha256:00cf895504a7895ee433807c62094cf1e95f065843bf3acd17037c3e9a2becd4"},
-    {file = "sphinx_rtd_theme-0.4.3.tar.gz", hash = "sha256:728607e34d60456d736cc7991fd236afb828b21b82f956c5ea75f94c8414040a"},
+    {file = "sphinx_rtd_theme-0.5.1-py2.py3-none-any.whl", hash = "sha256:fa6bebd5ab9a73da8e102509a86f3fcc36dec04a0b52ea80e5a033b2aba00113"},
+    {file = "sphinx_rtd_theme-0.5.1.tar.gz", hash = "sha256:eda689eda0c7301a80cf122dad28b1861e5605cbf455558f3775e1e8200e83a5"},
+]
+sphinxcontrib-applehelp = [
+    {file = "sphinxcontrib-applehelp-1.0.2.tar.gz", hash = "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"},
+    {file = "sphinxcontrib_applehelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a"},
+]
+sphinxcontrib-devhelp = [
+    {file = "sphinxcontrib-devhelp-1.0.2.tar.gz", hash = "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"},
+    {file = "sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e"},
+]
+sphinxcontrib-htmlhelp = [
+    {file = "sphinxcontrib-htmlhelp-1.0.3.tar.gz", hash = "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"},
+    {file = "sphinxcontrib_htmlhelp-1.0.3-py2.py3-none-any.whl", hash = "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f"},
+]
+sphinxcontrib-jsmath = [
+    {file = "sphinxcontrib-jsmath-1.0.1.tar.gz", hash = "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"},
+    {file = "sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178"},
+]
+sphinxcontrib-qthelp = [
+    {file = "sphinxcontrib-qthelp-1.0.3.tar.gz", hash = "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72"},
+    {file = "sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl", hash = "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"},
 ]
 sphinxcontrib-serializinghtml = [
    {file = "sphinxcontrib-serializinghtml-1.1.4.tar.gz", hash = "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc"},
    {file = "sphinxcontrib_serializinghtml-1.1.4-py2.py3-none-any.whl", hash = "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"},
 ]
-sphinxcontrib-websupport = [
-    {file = "sphinxcontrib-websupport-1.2.4.tar.gz", hash = "sha256:4edf0223a0685a7c485ae5a156b6f529ba1ee481a1417817935b20bde1956232"},
-    {file = "sphinxcontrib_websupport-1.2.4-py2.py3-none-any.whl", hash = "sha256:6fc9287dfc823fe9aa432463edd6cea47fa9ebbf488d7f289b322ffcfca075c7"},
-]
 stevedore = [
    {file = "stevedore-3.3.0-py3-none-any.whl", hash = "sha256:50d7b78fbaf0d04cd62411188fa7eedcb03eb7f4c4b37005615ceebe582aa82a"},
    {file = "stevedore-3.3.0.tar.gz", hash = "sha256:3a5bbd0652bf552748871eaa73a4a8dc2899786bc497a2aa1fcb4dcdb0debeee"},
@@ -54,8 +54,8 @@ class Control:
            motor this is the number of encoder pulses per degree of rotation.
    """

-    def limits(self, speed, acceleration, actuation):
-        """Configures the maximum speed, acceleration, and actuation.
+    def limits(self, speed, acceleration, duty, torque):
+        """Configures the maximum speed, acceleration, duty, and torque.

        If no arguments are given, this will return the current values.

@@ -64,8 +64,10 @@ class Control:
                Maximum speed. All speed commands will be capped to this value.
            acceleration (:ref:`acceleration` or :ref:`linacceleration`):
                Maximum acceleration.
-            actuation (:ref:`percentage`):
-                Maximum actuation as percentage of absolute maximum.
+            duty (:ref:`percentage`):
+                Maximum duty cycle during control.
+            torque (:ref:`torque`):
+                Maximum feedback torque during control.
        """
        pass

@@ -75,11 +77,14 @@ class Control:
        If no arguments are given, this will return the current values.

        Arguments:
-            kp (int): Proportional position (or integral speed) control
-                constant.
-            ki (int): Integral position control constant.
+            kp (int): Proportional position control
+                constant. It is the feedback torque per degree of
+                error: µNm/deg.
+            ki (int): Integral position control constant. It is the feedback
+                torque per accumulated degree of error: µNm/(deg s).
            kd (int): Derivative position (or proportional speed) control
-                constant.
+                constant. It is the feedback torque per
+                unit of speed: µNm/(deg/s).
            integral_range (:ref:`angle` or :ref:`distance`): Region around
                the target angle or distance, in which integral control errors
                are accumulated.
@@ -139,6 +144,21 @@ class Control:
        """
        pass

+    def load(self):
+        """Gets the load acting on the ``Motor`` or ``DriveBase``.
+
+        This value is determined from the feedback torque that is
+        needed to track the speed or position command given by the user.
+
+        When coasting, braking, or controlling the duty cycle manually, the
+        load cannot be estimated in this way. Then this method returns zero.
+
+        Returns:
+            :ref:`torque`: The load torque. It returns 0 if control
+            is not active.
+        """
+        pass
+

 class Motor(DCMotor):
    """Generic class to control motors with built-in rotation sensors."""
@@ -247,7 +267,7 @@ class Motor(DCMotor):
        given target angle.

        The direction of rotation is automatically selected based on the target
-        angle. It does matter if ``speed`` is positive or negative.
+        angle. It does not matter if ``speed`` is positive or negative.

        Arguments:
            speed (:ref:`speed`): Speed of the motor.
@@ -266,7 +286,7 @@ class Motor(DCMotor):
        Arguments:
            speed (:ref:`speed`): Speed of the motor.
            then (Stop): What to do after coming to a standstill.
-            duty_limit (:ref:`percentage`): Torque limit during this
+            duty_limit (:ref:`percentage`): Duty cycle limit during this
                command. This is useful to avoid applying the full motor
                torque to a geared or lever mechanism.

@@ -668,7 +688,7 @@ class Keypad:
        """Checks which buttons are currently pressed.

        :returns: Tuple of pressed buttons.
-        :rtype: Tuple of :class:`Button <.parameters.Button>`
+        :rtype: Tuple of :class:`Button`

        """
        pass
@@ -695,7 +715,31 @@ class Battery:
        pass


-class Accelerometer:
+class SimpleAccelerometer:
+    """Get measurements from an accelerometer."""
+
+    def acceleration(self):
+        """Gets the acceleration of the device.
+
+        Returns:
+            tuple of :ref:`linacceleration_m`: Acceleration along all three
+            axes.
+        """
+        pass
+
+    def up(self):
+        """Checks which side of the hub currently faces upward.
+
+        :returns:
+            ``Side.TOP``, ``Side.BOTTOM``, ``Side.LEFT``, ``Side.RIGHT``,
+            ``Side.FRONT`` or ``Side.BACK``.
+        :rtype: :class:`Side`
+
+        """
+        pass
+
+
+class Accelerometer(SimpleAccelerometer):
    """Get measurements from an accelerometer."""

    def neutral(self, top, front):
@@ -766,17 +810,6 @@ class Accelerometer:
        """
        pass

-    def up(self):
-        """Checks 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):

@@ -130,7 +130,7 @@ class InfraredSensor:
            channel (int): Channel number of the remote.

        :returns: List of pressed buttons on the remote on selected channel.
-        :rtype: List of :class:`Button <.parameters.Button>`
+        :rtype: List of :class:`Button <Button>`

        """
        pass
@@ -144,7 +144,7 @@ class InfraredSensor:
        This method only works with the remote in channel 1.

        :returns: List of pressed buttons on the remote on selected channel.
-        :rtype: List of :class:`Button <.parameters.Button>`
+        :rtype: List of :class:`Button <Button>`

        """
        pass
@@ -4,7 +4,8 @@
 """LEGO® Programmable Hubs."""
 from ._common import (Speaker as _Speaker, Battery as _Battery,
                      ColorLight as _ColorLight, Keypad as _Keypad,
-                      LightMatrix as _LightMatrix, IMU as _IMU)
+                      LightMatrix as _LightMatrix, IMU as _IMU,
+                      SimpleAccelerometer as _SimpleAccelerometer)
 from .media.ev3dev import Image as _Image
 from .parameters import Button as _Button
 from .geometry import Axis as _Axis
@@ -35,6 +36,7 @@ class MoveHub:
    # In reality, they are instance attributes created by __init__.
    battery = _Battery()
    light = _ColorLight()
+    imu = _SimpleAccelerometer()


 class CityHub:
@@ -197,7 +197,7 @@ class UARTDevice:
            port (Port): Port to which the device is connected.
            baudrate (int): Baudrate of the UART device.
            timeout (:ref:`time`): How long to wait
-                during :meth:`.read` before giving up. If you choose ``None``,
+                during ``read`` before giving up. If you choose ``None``,
                it will wait forever.
        """
        pass
@@ -180,5 +180,5 @@ class BluetoothMailboxClient:
                There was a problem establishing the connection.
        """

-    def close(self):
+    def server_close(self):
        """Closes all connections."""
@@ -40,7 +40,7 @@ class BluetoothMailboxServer(Connection):
    def __enter__(self) -> BluetoothMailboxServer: ...
    def __exit__(self, type, value, traceback) -> None: ...
    def wait_for_connection(self, count: int = 1) -> None: ...
-    def close(self) -> None: ...
+    def server_close(self) -> None: ...

 class BluetoothMailboxClient(Connection):
    def __enter__(self) -> BluetoothMailboxClient: ...
@@ -81,9 +81,8 @@ class ColorSensor:

        :returns:
            ``Color.BLACK``, ``Color.BLUE``, ``Color.GREEN``, ``Color.YELLOW``,
-            ``Color.RED``, ``Color.WHITE`` or ``None``.
-        :rtype: :class:`Color <.parameters.Color>`, or ``None`` if no color is
-                detected.
+            ``Color.RED``, ``Color.WHITE`` or ``Color.NONE``.
+        :rtype: :class:`Color <.parameters.Color>`

        """
        pass
@@ -250,7 +249,7 @@ class VernierAdapter(_AnalogSensor):

        Arguments:
            port (Port): Port to which the sensor is connected.
-            conversion (callable): Function of the format :meth:`.conversion`.
+            conversion (callable): Function of the format ``conversion``.
                This function is used to convert the raw analog voltage to the
                sensor-specific output value. Each Vernier Sensor has its
                own conversion function. The example given below demonstrates
@@ -30,16 +30,13 @@ class _PybricksEnum(_Enum, metaclass=_PybricksEnumMeta):
 class Color:
    """Light or surface color."""

-    def __init__(self, h, s=100, v=100, name=None):
+    def __init__(self, h, s=100, v=100):
        self.h = h % 360
        self.s = max(0, min(s, 100))
        self.v = max(0, min(v, 100))
-        self.name = name

    def __repr__(self):
-        name_str = '' if self.name is None else ", '{}'".format(self.name)
-
-        return "Color({}, {}, {}{})".format(self.h, self.s, self.v, name_str)
+        return "Color(h={}, s={}, v={})".format(self.h, self.s, self.v)

    def __eq__(self, other):
        return (isinstance(other, Color) and
@@ -59,17 +56,19 @@ class Color:
        return self.__mul__(1/scale)


-Color.BLACK = Color(0, 0, 0, 'BLACK')
-Color.GRAY = Color(0, 0, 50, 'GRAY')
-Color.WHITE = Color(0, 0, 100, 'WHITE')
-Color.RED = Color(0, 100, 100, 'RED')
-Color.ORANGE = Color(30, 100, 100, 'ORANGE')
-Color.YELLOW = Color(60, 100, 100, 'YELLOW')
-Color.GREEN = Color(120, 100, 100, 'GREEN')
-Color.CYAN = Color(180, 100, 100, 'CYAN')
-Color.BLUE = Color(240, 100, 100, 'BLUE')
-Color.VIOLET = Color(270, 100, 100, 'VIOLET')
-Color.MAGENTA = Color(300, 100, 100, 'MAGENTA')
+Color.NONE = Color(0, 0, 0)
+Color.BLACK = Color(0, 0, 10)
+Color.GRAY = Color(0, 0, 50)
+Color.WHITE = Color(0, 0, 100)
+Color.RED = Color(0, 100, 100)
+Color.ORANGE = Color(30, 100, 100)
+Color.BROWN = Color(30, 100, 50)
+Color.YELLOW = Color(60, 100, 100)
+Color.GREEN = Color(120, 100, 100)
+Color.CYAN = Color(180, 100, 100)
+Color.BLUE = Color(240, 100, 100)
+Color.VIOLET = Color(270, 100, 100)
+Color.MAGENTA = Color(300, 100, 100)


 class Port(_PybricksEnum):
@@ -91,53 +90,31 @@ class Port(_PybricksEnum):


 class Stop(_PybricksEnum):
-    """Action after the motor stops: coast, brake, or hold.
-
-    .. data:: COAST
-
-        Let the motor move freely.
-
-    .. data:: BRAKE
-
-        Passively resist small external forces.
-
-    .. data:: HOLD
-
-        Keep controlling the motor to hold it at the commanded angle. This is
-        only available on motors with encoders.
-    """
+    """Action after the motor stops."""

    COAST = 0
+    """Let the motor move freely."""
+
    BRAKE = 1
+    """Passively resist small external forces."""
+
    HOLD = 2
+    """Keep controlling the motor to hold it at the commanded angle. This is
+    only available on motors with encoders."""


 class Direction(_PybricksEnum):
-    """Rotational direction for positive speed or angle values.
-
-    .. data:: CLOCKWISE
-
-        A positive speed value should make the motor move clockwise.
-
-    .. data:: COUNTERCLOCKWISE
-
-        A positive speed value should make the motor move counterclockwise.
-
-    +--------------------------------+-------------------+-----------------+
-    | ``positive_direction =``       | Positive speed:   | Negative speed: |
-    +================================+===================+=================+
-    | ``Direction.CLOCKWISE``        | clockwise         | counterclockwise|
-    +--------------------------------+-------------------+-----------------+
-    | ``Direction.COUNTERCLOCKWISE`` | counterclockwise  | clockwise       |
-    +--------------------------------+-------------------+-----------------+
-    """
+    """Rotational direction for positive speed or angle values."""

    CLOCKWISE = 0
+    """A positive speed value should make the motor move clockwise."""
+
    COUNTERCLOCKWISE = 1
+    """A positive speed value should make the motor move counterclockwise."""


 class Button(_PybricksEnum):
-    """Buttons on a brick or remote"""
+    """Buttons on a hub or remote."""

    LEFT_DOWN = 1
    LEFT_MINUS = 1
@@ -157,16 +134,7 @@ class Button(_PybricksEnum):


 class Side(_PybricksEnum):
-    """Side of a hub or a sensor. These devices are
-    mostly rectangular boxes with six sides:
-
-    .. data:: TOP
-    .. data:: BOTTOM
-    .. data:: FRONT
-    .. data:: BACK
-    .. data:: LEFT
-    .. data:: RIGHT
-    """
+    """Side of a hub or a sensor."""

    RIGHT = 6
    FRONT = 0
@@ -4,13 +4,17 @@
 class Color:
    BLACK: Color
    BLUE: Color
-    GREEN: Color
-    YELLOW: Color
-    RED: Color
-    WHITE: Color
    BROWN: Color
+    CYAN: Color
+    GRAY: Color
+    GREEN: Color
+    MAGENTA: Color
+    NONE: Color
    ORANGE: Color
-    PURPLE: Color
+    RED: Color
+    VIOLET: Color
+    WHITE: Color
+    YELLOW: Color
    def __mul__(self, scale: float) -> Color: ...
    def __rmul__(self, scale: float) -> Color: ...
    def __truediv__(self, scale: float) -> Color: ...
@@ -91,7 +91,7 @@ class ColorDistanceSensor:
        You choose which colors are detected using the
        :meth:`.detectable_colors` method. By default, it detects
        ``Color.RED``, ``Color.YELLOW``, ``Color.GREEN``, ``Color.BLUE``,
-        ``Color.WHITE``, or ``None``.
+        ``Color.WHITE``, or ``Color.NONE``.

        :returns:
            Detected color.
@@ -128,11 +128,10 @@ class ColorDistanceSensor:
        as a tuple.

        Arguments:
-            colors (list): List of :class:`Color <.parameters.Color>` objects:
+            colors (list): Tuple of :class:`Color <.parameters.Color>` objects:
                the colors that you want to detect. You can pick
                standard colors such as ``Color.MAGENTA``, or provide your own
-                colors like
-                ``Color(h=348, s=96, v=40, name='MY_MAGENTA_BRICK')`` for even
+                colors like ``Color(h=348, s=96, v=40)`` for even
                better results. You measure your own colors with the
                :meth:`.hsv` method.
        """
@@ -210,7 +209,7 @@ class ColorSensor:
        You choose which colors are detected using the
        :meth:`.detectable_colors` method. By default, it detects
        ``Color.RED``, ``Color.YELLOW``, ``Color.GREEN``, ``Color.BLUE``,
-        ``Color.WHITE``, or ``None``.
+        ``Color.WHITE``, or ``Color.NONE``.

        Arguments:
            surface (bool): Choose ``true`` to scan the color of objects
@@ -233,11 +232,10 @@ class ColorSensor:
        as a tuple.

        Arguments:
-            colors (list): List of :class:`Color <.parameters.Color>` objects:
+            colors (list): Tuple of :class:`Color <.parameters.Color>` objects:
                the colors that you want to detect. You can pick
                standard colors such as ``Color.MAGENTA``, or provide your own
-                colors like
-                ``Color(h=348, s=96, v=40, name='MY_MAGENTA_BRICK')`` for even
+                colors like ``Color(h=348, s=96, v=40)`` for even
                better results. You measure your own colors with the
                :meth:`.hsv` method.
        """
@@ -20,10 +20,10 @@ python = "^3.8"

 [tool.poetry.dev-dependencies]
 black = {version = "^20.8b1", allow-prereleases = true}
-doc8 = "*"
-flake8 = "*"
-sphinx = "==1.8.5"
-sphinx-rtd-theme = "==0.4.3"
+doc8 = "^0.8.1"
+flake8 = "^3.8.4"
+Sphinx = "^3.4.3"
+sphinx-rtd-theme = "^0.5.1"
 toml = "^0.10.0"

 [build-system]
@@ -1,5 +1,5 @@
 # This file is strictly for building docs on readthedocs.org
 # See pyproject.toml for local development
-Sphinx==1.8.5
-sphinx-rtd-theme==0.4.3
+Sphinx==3.4.3
+sphinx-rtd-theme==0.5.1
 toml
Author	SHA1	Message	Date
Laurens Valk	9594adae48	@pybricks/ide-docs v1.3.0	2021-04-12 11:08:51 +02:00
Laurens Valk	8dd171fc4c	v3: Drop parameters Side and Button.	2021-04-12 11:05:26 +02:00
Laurens Valk	5effd921b4	v3: Drop Remote control.	2021-04-12 11:05:22 +02:00
Laurens Valk	d503966862	v3: Drop geometry module.	2021-04-12 11:05:17 +02:00
Laurens Valk	7563b1c6cf	v3: Drop Prime Hub and Inventor Hub.	2021-04-12 11:05:04 +02:00
Laurens Valk	c9132b45db	v3: Drop IMU documentation. This is not officially supported yet, so drop from release docs.	2021-04-12 11:03:28 +02:00
Laurens Valk	de13c01673	api/nxtdevices: Update color method. This shares the implementation with the PUP color sensors, so update accordingly.	2021-04-10 15:31:29 +02:00
Laurens Valk	ca96ee2fce	examples: Update detectable colors API.	2021-04-10 15:31:28 +02:00
Laurens Valk	68f626f1ef	doc/pupdevices: Update usage of color.	2021-04-10 15:31:28 +02:00
Laurens Valk	570fac30c5	api/parameters/Color: Fix color definitions. Match the implementation.	2021-04-10 15:31:28 +02:00
Laurens Valk	1f0be98649	api/parameters/Color: Add missing color typing.	2021-04-10 15:31:27 +02:00
Laurens Valk	e91590feec	examples/pup/sensor: Fix use of lights.on. The documentation says to use a list or tuple of brightness values. https://github.com/pybricks/support/issues/273 Implementation fixed via https://github.com/pybricks/pybricks-micropython/commit/28b5413c2b41283a5c1ea3e8cccf4a2900dd7fc3	2021-04-09 15:44:08 +02:00
Laurens Valk	597b6d682f	@pybricks/ide-docs v1.2.0	2021-04-09 12:31:37 +02:00
Laurens Valk	9c8d41efb8	doc/index: Update install note in IDE docs.	2021-04-09 12:21:47 +02:00
Laurens Valk	a06e01c6de	doc/start_pup/ev3: Drop installation guide. These are now at https://pybricks.com/install/	2021-04-07 19:56:56 +02:00
David Lechner	186c46f52c	api/pybricks/messaging: fix BluetoothMailboxServer close As per standard Python socketserver, there is `server_close()` rather than `close()`. Fixes #51	2021-04-07 19:42:33 +02:00
Laurens Valk	7679b8b47d	examples/hubs/MoveHub: imu examples	2021-02-17 23:31:19 +01:00
Laurens Valk	c14f1cf473	api/hubs/MoveHub: add basic imu This is similar to the other hubs, but with reduced functionality.	2021-02-17 23:23:40 +01:00
Jerry Nicholls	6ce8336c26	doc/common/Motor: fix docstring for run_target Changed "does" to "doesn't" for the target angle. The sign of the speed is irrelevant.	2021-02-15 19:12:41 +01:00
Laurens Valk	c46b249c8c	@pybricks/ide-docs v1.1.1	2021-02-14 19:32:52 +01:00
Laurens Valk	67008b67d8	doc/ide: include installation guide	2021-02-14 19:26:10 +01:00
Laurens Valk	9c1beef6b6	doc/parameters/Port: move doc to rst	2021-02-14 19:00:52 +01:00
Laurens Valk	5eb7a143fa	doc/parameters/Stop: move doc to rst	2021-02-14 19:00:52 +01:00
Laurens Valk	fc04059d86	doc/parameters/Button: move doc to rst	2021-02-14 19:00:45 +01:00
Laurens Valk	0082f0502a	doc/parameters/Direction: move doc to rst	2021-02-14 18:44:25 +01:00
Laurens Valk	e7dc4bb609	doc/parameters/Side: move doc to rst	2021-02-14 18:41:17 +01:00
Laurens Valk	fb86e4bcef	doc/parameters/Stop: fix typo	2021-02-14 16:21:37 +01:00
Laurens Valk	632908f59a	doc/parameters: split out page per class	2021-02-14 16:06:23 +01:00
Laurens Valk	4a7fa12eaa	config: add classlink directive We have index pages for most modules now, which link to individual classes. It is helpful if these empty class headers are hyperlinks. This commit does just that. For most sensors/devices so far this is not really necessary as the images are already hyperlinks. But this will become more useful as we start adding index pages like these for classes without images, such as parameters.	2021-02-14 15:39:39 +01:00
Jorge Pereira	109fcf19c1	examples/pup/motor: update motor_action_basic Demo of run_angle had a typo	2021-02-14 13:54:58 +01:00
Laurens Valk	3229da030b	doc/start_pup: update getting started instructions	2021-02-14 12:41:05 +01:00
Laurens Valk	4b052fa66d	doc/pupdevices/motor: drop image alignment Fixes https://github.com/pybricks/pybricks-api/issues/40	2021-02-12 11:10:51 +01:00
Laurens Valk	3c6ebd09bd	doc/parameters/Color: add examples	2021-02-12 10:53:40 +01:00
Laurens Valk	af1b84afe2	api/parameters/Color: drop name attribute	2021-02-12 10:16:43 +01:00
Laurens Valk	45dbd7db5a	config: display border around white div Makes it easier to see white box on white background.	2021-02-12 10:15:58 +01:00
Laurens Valk	a7699d6546	api/common/Control: add load method	2021-02-10 18:49:51 +01:00
Laurens Valk	55c83cb026	api/common: add torque limit setter Also document units of torque	2021-02-10 15:48:56 +01:00
David Lechner	deb211bdb7	@pybricks/ide-docs v1.1.0	2021-01-28 12:31:19 -06:00
David Lechner	8a5e5c3fb4	doc/ide: styling to match Pybricks Code We were injecting this from Pybricks code, but it caused the scroll bars to flash when loading a page.	2021-01-28 12:31:19 -06:00
ZPhilo	2a1640f7dc	examples/pup/hubs/hub_primehub: fix button Corrected Bluetooth button name (from BT to BLUETOOTH)	2021-01-28 09:31:41 +01:00
Laurens Valk	535aac8144	config: fix missing automembers in sphinx upgrade This setting was renamed and should now be a dictionary. Fixes https://github.com/pybricks/pybricks-api/issues/45	2021-01-28 09:30:23 +01:00
David Lechner	00cc5ee44e	poetry: move dev dependencies to dev section Users who install this package from PyPi don't need all of the dev dependencies.	2021-01-26 11:46:32 -06:00
Laurens Valk	f0b882b576	config: update to Sphinx 3.4	2021-01-26 09:18:13 +01:00
Laurens Valk	8ed45aecfb	doc/nxtdevices: drop method link For some reason, these are not working after upgrading to Sphinx 3.X, even though the same reference to conversion works just fine elsewhere.	2021-01-26 09:07:19 +01:00
David Lechner	77605e8701	github: add workflow for publishing ide-docs package	2021-01-26 08:30:48 +01:00
David Lechner	b4c8242133	doc/ide: add node package This will be used to publish the docs in a way that is easy for pybricks-code to use.	2021-01-26 08:30:48 +01:00
David Lechner	06e01e5ac8	doc/ide: use sphinx.ext.imgmath MathJax uses a CDN to to distribute the package. So in order to use the docs offline, we would have to include our own copy. But it is a bit large (50-ish MB), so it is easier to use sphinx.ext.imgmath instead to generate svg images. The situation might be different with MathJax v3, but that requires Sphinx v4.	2021-01-26 08:30:48 +01:00
David Lechner	ff22c32c24	doc/api/signaltypes: use ^{\circ} instead of ° in :math: This works for both sphinx.ext.mathjax and sphinx.ext.imgmath.	2021-01-26 08:30:48 +01:00
David Lechner	95eb999493	doc/api/signaltypes: fix degree symbol overlapping The degree symbol was a bit too close to the letters.	2021-01-26 08:30:48 +01:00
David Lechner	7d729a8e9e	doc/ide: hide the "view source" link Since these are meant to be offline docs and use a smaller screen area we can omit this to keep things cleaner.	2021-01-26 08:30:48 +01:00
David Lechner	c750a3cd88	doc/ide: hide prev/next buttons In the IDE this is more of a reference and less of a book so going to the next page doesn't make as much sense.	2021-01-26 08:30:48 +01:00
David Lechner	adf6e03bc9	doc: open external links in a new window This adds a hack to open external links in a new window. Requires Sphinx v1.8.	2021-01-26 08:30:48 +01:00
David Lechner	0466ce947f	doc: override external link style on figure target This works around https://github.com/readthedocs/sphinx_rtd_theme/pull/494#issuecomment-354063112	2021-01-26 08:30:48 +01:00
David Lechner	7abb670f66	doc/ide: hide footers This information is duplicated in the IDE about dialog so we don't need it in the docs.	2021-01-26 08:30:48 +01:00
				`@@ -0,0 +1 @@`
				`.. include:: ../../api/parameters/color.rst`
				`@@ -0,0 +1 @@`
				`.. include:: ../../api/parameters/direction.rst`
				`@@ -1 +0,0 @@`
				`.. include:: ../../api/pupdevices/remote.rst`