v3.1.0rc1

This adds docs and API stubs for pybricks.iodevices.LWP3Device.

Fixes: https://github.com/pybricks/support/issues/534

CHANGELOG.md

@@ -1,66 +1,79 @@
-# 1.6.0 - 2021-08-30
+# Changelog
 
-## Added:
+<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
+
+## 3.1.0rc1 - 2021-11-19
+
+### Added
+- Added `ColorLightMatrix` class.
+- Added `LWP3Device` class.
+
+**NOTE: version number after this point were from JavaScript package and do
+not correspond to Pybricks firmware version numbers.**
+
+## 1.6.0 - 2021-08-30
+
+### Added
 - MicroPython module documentation.
 - Examples for hub system functions including stop button and shutdown.
 
-## Changed:
+### Changed
 - Build IDE docs as main docs with minor changes, instead of a completely
   separate build.
 - Moved motor control documentation to the motor page.
 
-# 1.5.0 - 2021-07-01
+## 1.5.0 - 2021-07-01
 
-## Added:
+### Added
 - Documentation for Powered Up Remote Control.
 
-# 1.4.0 - 2021-06-23
+## 1.4.0 - 2021-06-23
 
-## Added:
+### Added
 - Enabled beta content that was hidden for the 3.0 release.
 - Added notice about using the latest beta version.
 
-# 1.3.3 - 2021-05-21
+## 1.3.3 - 2021-05-21
 
-## Changed:
+### Changed
 - Match example snippet styling to IDE.
 - Add more examples.
 
-# 1.3.2 - 2021-04-26
+## 1.3.2 - 2021-04-26
 
-## Changed:
+## Changed
 - Theme style fixes.
 - Example code fixes
 - Match doc version to firmware version.
 
-# 1.3.1 - 2021-04-12
+## 1.3.1 - 2021-04-12
 
-## Changed:
+### Changed
 - Upgrade sphinx and rtd-theme to fix style issues.
 
-# 1.3.0 - 2021-04-12
+## 1.3.0 - 2021-04-12
 
-## Removed:
+### 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
+## 1.2.0 - 2021-04-09
 
-## Changed:
+### Changed
 - Moved installation guide to external site.
 
-# 1.1.1 - 2021-02-14
+## 1.1.1 - 2021-02-14
 
-## Added:
+### Added
 - Added installation guide.
 - Various documentation fixes.
 
-# 1.1.0 - 2021-01-28
+## 1.1.0 - 2021-01-28
 
-## Added:
+### Added
 - Scrollbar styling.
 
-# 1.0.0 - 2021-01-25
+## 1.0.0 - 2021-01-25
 
-## Added:
+### Added
 - Sphinx build output.

doc/main/ev3devices.rst

@@ -1,4 +1,4 @@
-:mod:`ev3devices <pybricks.ev3devices>` -- EV3 Devices
+:mod:`ev3devices <pybricks.ev3devices>` -- EV3 devices
 ======================================================
 
 .. automodule:: pybricks.ev3devices

doc/main/hubs/index.rst

@@ -1,6 +1,6 @@
 .. pybricks-requirements::
 
-:mod:`hubs <pybricks.hubs>` -- Programmable Hubs
+:mod:`hubs <pybricks.hubs>` -- Programmable hubs
 ================================================
 
 .. module:: pybricks.hubs

doc/main/index.rst

@@ -65,13 +65,13 @@ Pybricks Documentation
    Use the ☰ menu to navigate all available classes, methods, and tools. A few
    commonly used devices and classes are listed below for quick reference.
 
-   .. rubric:: Programmable Hubs
+   .. rubric:: Programmable hubs
 
    .. figure:: ../main/images/hubsoverview.png
       :width: 100 %
       :target: hubs/index.html
 
-   .. rubric:: Powered Up Motors and Sensors
+   .. rubric:: Powered Up motors and sensors
 
    .. figure:: ../main/images/pupdevicesoverview.png
       :width: 100 %
@@ -88,7 +88,7 @@ Pybricks Documentation
 
 .. toctree::
     :maxdepth: 1
-    :caption: Table of Contents
+    :caption: Table of contents
     :hidden:
 
 .. toctree::
@@ -96,12 +96,12 @@ Pybricks Documentation
     :caption: Pybricks
     :hidden:
 
-    Home Page <https://pybricks.com>
+    Home page <https://pybricks.com>
     Installation <https://pybricks.com/install/>
 
 .. toctree::
    :maxdepth: 1
-   :caption: Pybricks Package
+   :caption: Pybricks modules
    :hidden:
 
    hubs/index
@@ -115,7 +115,7 @@ Pybricks Documentation
 
 .. toctree::
    :maxdepth: 1
-   :caption: MicroPython Modules
+   :caption: MicroPython modules
    :hidden:
 
    micropython/builtins

doc/main/iodevices/index.rst

@@ -1,6 +1,6 @@
 .. pybricks-requirements:: pybricks-iodevices
 
-:mod:`iodevices <pybricks.iodevices>` -- Generic I/O Devices
+:mod:`iodevices <pybricks.iodevices>` -- Generic I/O devices
 ============================================================
 
 .. module:: pybricks.iodevices
@@ -10,6 +10,7 @@
    :hidden:
 
    pupdevice
+   lwp3device
 
 This module has classes for generic input/output devices.
 
@@ -18,3 +19,9 @@ This module has classes for generic input/output devices.
 .. figure:: ../../main/images/sensor_pup.png
    :width: 70 %
    :target: pupdevice.html
+
+.. pybricks-classlink:: LWP3Device
+
+.. figure:: ../../main/images/powereduphubs.png
+   :width: 70 %
+   :target: lwp3device.html

doc/main/iodevices/lwp3device.rst

@@ -0,0 +1,12 @@
+LEGO Wireless Protocol v3 device
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. warning::
+
+   This is an experimental class. It has not been well tested and may be
+   changed in future.
+
+.. figure:: ../../main/images/powereduphubs.png
+   :width: 25 %
+
+.. autoclass:: pybricks.iodevices.LWP3Device

doc/main/media.rst

@@ -1,4 +1,4 @@
-:mod:`media <pybricks.media>` -- Sounds and Images
+:mod:`media <pybricks.media>` -- Sounds and images
 ==================================================
 
 .. module:: pybricks.media
@@ -18,7 +18,7 @@ and sound files. You can access them using the classes below.
 You can also use your own sound and image files by placing them in your project
 folder.
 
-Image Files
+Image files
 ^^^^^^^^^^^
 
 .. autoclass:: pybricks.media.ev3dev.ImageFile
@@ -223,7 +223,7 @@ Image Files
         .. image:: ../../media/ev3dev-media/images/mono/eyes/winking.png
             :width: 15 %
 
-Sound Files
+Sound files
 ^^^^^^^^^^^
 
 .. autoclass:: pybricks.media.ev3dev.SoundFile
@@ -1452,7 +1452,7 @@ Fonts
 .. _FontConfig: https://www.freedesktop.org/wiki/Software/fontconfig/
 
 
-Image Manipulation
+Image manipulation
 ^^^^^^^^^^^^^^^^^^
 
 Instead of drawing directly on the EV3 screen, you can make and interact

doc/main/messaging.rst

@@ -107,13 +107,13 @@ numbers, or text), you can choose one of the Mailboxes below.
 Examples
 -----------------
 
-**EV3 Bluetooth Server**
+**EV3 Bluetooth server**
 
 This is the full version of the excerpt shown in :numref:`fig_messaging`.
 
 .. literalinclude:: ../../examples/ev3/bluetooth_server/server.py
 
-**EV3 Bluetooth Client**
+**EV3 Bluetooth client**
 
 This is the full version of the excerpt shown in :numref:`fig_messaging`.
 

doc/main/nxtdevices.rst

@@ -1,4 +1,4 @@
-:mod:`nxtdevices <pybricks.nxtdevices>` -- NXT Devices
+:mod:`nxtdevices <pybricks.nxtdevices>` -- NXT devices
 ======================================================
 
 .. automodule:: pybricks.nxtdevices

doc/main/parameters/index.rst

@@ -1,6 +1,6 @@
 .. pybricks-requirements::
 
-:mod:`parameters <pybricks.parameters>` -- Parameters and Constants
+:mod:`parameters <pybricks.parameters>` -- Parameters and constants
 ===================================================================
 
 .. automodule:: pybricks.parameters

doc/main/pupdevices/colorlightmatrix.rst

@@ -0,0 +1,15 @@
+.. pybricks-requirements::
+
+Color Light Matrix
+^^^^^^^^^^^^^^^^^^
+
+.. figure:: ../../main/images/color_light_matrix.png
+   :width: 35 %
+
+.. autoclass:: pybricks.pupdevices.ColorLightMatrix
+    :no-members:
+
+    .. automethod:: pybricks.pupdevices.ColorLightMatrix.on
+
+    .. automethod:: pybricks.pupdevices.ColorLightMatrix.off
+

doc/main/pupdevices/dcmotor.rst

@@ -1,6 +1,6 @@
 .. pybricks-requirements::
 
-Motors without Rotation Sensors
+Motors without rotation sensors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. _fig_pupdcmotors:

doc/main/pupdevices/index.rst

@@ -1,6 +1,6 @@
 .. pybricks-requirements::
 
-:mod:`pupdevices <pybricks.pupdevices>` -- Powered Up Devices
+:mod:`pupdevices <pybricks.pupdevices>` -- Powered Up devices
 =============================================================
 
 .. automodule:: pybricks.pupdevices
@@ -19,6 +19,7 @@
    colorsensor
    ultrasonicsensor
    forcesensor
+   colorlightmatrix
    light
    remote
 
@@ -76,6 +77,12 @@
    :width: 35 %
    :target: forcesensor.html
 
+.. pybricks-classlink:: ColorLightMatrix
+
+.. figure:: ../../main/images/color_light_matrix.png
+   :width: 35 %
+   :target: color-light-matrix.html
+
 .. pybricks-classlink:: Light
 
 .. figure:: ../../main/images/light.png

doc/main/pupdevices/motor.rst

@@ -1,6 +1,6 @@
 .. pybricks-requirements::
 
-Motors with Rotation Sensors
+Motors with rotation sensors
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. _fig_pupmotors:
@@ -78,7 +78,7 @@ Motors with Rotation Sensors
 
     .. automethod:: pybricks.pupdevices.Motor.control.stall_tolerances
 
-Initialization Examples
+Initialization examples
 -----------------------
 
 Making the motor move back and forth
@@ -105,7 +105,7 @@ Using gears
 .. literalinclude::
     ../../../examples/pup/motor/motor_init_gears.py
 
-Measurement Examples
+Measurement examples
 -----------------------
 
 Measuring the angle and speed
@@ -121,7 +121,7 @@ Resetting the measured angle
     ../../../examples/pup/motor/motor_reset_angle.py
 
 
-Movement Examples
+Movement examples
 -----------------------
 
 Basic usage of all run methods
@@ -142,7 +142,7 @@ Using the ``then`` argument to change how a run command stops
 .. literalinclude::
     ../../../examples/pup/motor/motor_action_then.py
 
-Stall Examples
+Stall examples
 -----------------------
 
 Running a motor until a mechanical endpoint
@@ -158,7 +158,7 @@ Centering a steering mechanism
     ../../../examples/pup/motor/motor_until_stalled.py
 
 
-Parallel Movement Examples
+Parallel movement examples
 --------------------------
 
 Using the ``wait`` argument to run motors in parallel

doc/main/robotics.rst

@@ -88,7 +88,7 @@
     To deactivate the :class:`.DriveBase`, call :meth:`.stop`.
 
 
-    .. rubric:: Advanced Settings
+    .. rubric:: Advanced settings
 
     The :meth:`.settings` method is used to adjust commonly used settings like
     the default speed and acceleration for straight maneuvers and turns.

npm/ide-docs/.gitignore

@@ -0,0 +1,5 @@
+# build directory
+html/
+
+# yarn pack output
+*.tgz

npm/ide-docs/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
+
+## Unreleased
+
+### Changed
+- Changed package directory structure.

npm/ide-docs/package.json

@@ -5,7 +5,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/pybricks/pybricks-api",
-    "directory": "doc/ide"
+    "directory": "npm/ide-docs"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -14,11 +14,10 @@
   "author": "The Pybricks Authors",
   "license": "MIT",
   "files": [
-    "build/html/**"
+    "html"
   ],
-  "types": "index.d.ts",
   "scripts": {
-    "clean": "poetry run make -C .. clean",
-    "build": "poetry run make -C .. TAG=ide html"
+    "clean": "poetry run make -C ../../doc clean",
+    "build": "poetry run make -C ../../doc TAG=ide html && rm -rf html && cp -R ../../doc/main/build/html html"
   }
 }

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pybricks"
-version = "3.1.0a1"
+version = "3.1.0rc1"
 description = "Documentation and user-API stubs for Pybricks MicroPython"
 authors = ["The Pybricks Authors <dev@pybricks.com>"]
 maintainers = ["Laurens Valk <laurens@pybricks.com>", "David Lechner <david@pybricks.com>" ]

setup.cfg

@@ -4,5 +4,5 @@ exclude = .venv/,*.pyi
 max-line-length = 88
 
 [doc8]
-ignore-path = .venv/,doc/main/build/,pybricks.egg-info/
+ignore-path = .venv/,doc/main/build/,doc/api/build/,pybricks.egg-info/,npm/
 max-line-length = 88

src/pybricks/iodevices.py

@@ -244,3 +244,59 @@ class UARTDevice:
     def clear(self):
         """Empties the buffer."""
         pass
+
+
+class LWP3Device:
+    """
+    Connects to a remote hub running official LEGO firmware using the the
+    `LEGO Wireless Protocol v3`_
+
+    .. _`LEGO Wireless Protocol v3`:
+        https://lego.github.io/lego-ble-wireless-protocol-docs/
+    """
+
+    def __init__(self, hub_kind, name=None, timeout=10000):
+        """
+
+        Arguments:
+            hub_kind (int):
+                The `hub type identifier`_ of the hub to connect to.
+            name (str):
+                The name of the hub to connect to or ``None`` to connect to any
+                hub.
+            timeout (int):
+                The time, in milliseconds, to wait for a connection before
+                raising an exception.
+
+
+        .. _`hub type identifier`:
+            https://github.com/pybricks/technical-info/blob/master/assigned-numbers.md#hub-type-ids
+        """
+
+    def name(self, name=None):
+        """Gets or sets the Bluetooth name of the remote.
+
+        If no name is given, this method returns the current name.
+
+        Arguments:
+            name (str): New Bluetooth name of the remote.
+        """
+
+    def write(self, buf):
+        """
+        Sends a message to the remote hub.
+
+        Arguments:
+            buf (bytes): The raw binary message to send.
+        """
+
+    def read(self):
+        """
+        Retrieves the most recent message received from the remote hub.
+
+        If a message has not been received since the last read, the method will
+        block until a message is received.
+
+        Returns:
+            bytes: The raw binary message.
+        """

src/pybricks/iodevices.pyi

@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: MIT
 # Copyright (c) 2020 The Pybricks Authors
 
-from typing import Dict, Optional, Tuple
+from typing import Dict, Optional, Tuple, overload
 
 from .parameters import Port
 
@@ -40,3 +40,13 @@ class UARTDevice:
     def write(self, data: bytes) -> None: ...
     def waiting(self) -> int: ...
     def clear(self) -> None: ...
+
+class LWP3Device:
+    def __init__(self, hub_kind: int, name: str = None, timeout: int = 10000): ...
+    @overload
+    def name(self) -> str: ...
+    @overload
+    def name(self, name: str) -> None: ...
+    def name(self, *args): ...
+    def read(self) -> bytes: ...
+    def write(self, buf: bytes) -> None: ...

src/pybricks/pupdevices.py

@@ -377,6 +377,39 @@ class ForceSensor:
         pass
 
 
+class ColorLightMatrix:
+    """
+    LEGO® SPIKE 3x3 Color Light Matrix.
+    """
+
+    def __init__(self, port):
+        """
+
+        Arguments:
+            port (Port): Port to which the device is connected.
+
+        """
+        ...
+
+    def on(self, colors):
+        """
+        Turns the lights on.
+
+        Arguments:
+            colors (Color or list):
+                If a single :class:`.Color` is given, then all 9 lights are set
+                to that color. If a list of colors is given, then each light is
+                set to that color.
+        """
+        ...
+
+    def off(self):
+        """
+        Turns all of the lights off.
+        """
+        ...
+
+
 class InfraredSensor:
     """LEGO® Powered Up Infrared Sensor."""
 

src/pybricks/pupdevices.pyi

@@ -60,6 +60,11 @@ class ForceSensor:
     def pressed(self, force: int = 3) -> bool: ...
     def touched(self) -> bool: ...
 
+class ColorLightMatrix:
+    def __init__(self, port: Port) -> None: ...
+    def on(self, color: Union[Color, List[Color]]) -> None: ...
+    def off(self)-> None: ...
+
 class InfraredSensor:
     def __init__(self, port: Port): ...
     def reflection(self) -> int: ...