pybricks.iodevices.LWP3Device: add api and docs

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

Fixes: pybricks/support#534

Author: dlech

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ### Added
 - Added `ColorLightMatrix` class.
+- Added `LWP3Device` class.
 
 ## 1.6.0 - 2021-08-30
 

doc/main/iodevices/index.rst

@@ -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

src/pybricks/iodevices.py

@@ -244,3 +244,59 @@ def waiting(self):
     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: ...