From 1b69e42b6bc81ae732a1151f3a84ab98a003c5ff Mon Sep 17 00:00:00 2001 From: Laurens Valk Date: Fri, 29 May 2026 14:57:53 +0200 Subject: [PATCH] pybricks.iodevices: Update UARTDevice docstrings. --- doc/main/iodevices/index.rst | 86 +++++++++++++++++++------------ doc/main/iodevices/uartdevice.rst | 9 +++- src/pybricks/iodevices.py | 77 ++++++++++++++++++++++----- 3 files changed, 125 insertions(+), 47 deletions(-) diff --git a/doc/main/iodevices/index.rst b/doc/main/iodevices/index.rst index 73f8aab..a60c7ac 100644 --- a/doc/main/iodevices/index.rst +++ b/doc/main/iodevices/index.rst @@ -3,32 +3,17 @@ .. module:: pybricks.iodevices +This module has classes for generic and custom input/output devices. + +Wireless devices +---------------- + .. toctree:: :maxdepth: 1 :hidden: - lwp3device - - analogsensor - dcmotor - lumpdevice - pupdevice - - i2cdevice - uartdevice - xboxcontroller -This module has classes for generic and custom input/output devices. - -.. pybricks-requirements:: pybricks-iodevices - -.. pybricks-classlink:: LWP3Device - -.. figure:: ../../main/cad/output/hub-lwp3.png - :width: 80 % - :target: lwp3device.html - .. pybricks-requirements:: pybricks-iodevices .. pybricks-classlink:: XboxController @@ -37,13 +22,24 @@ This module has classes for generic and custom input/output devices. :width: 40 % :target: xboxcontroller.html +LEGO protocol devices +--------------------- + +.. toctree:: + :maxdepth: 1 + :hidden: + + lwp3device + lumpdevice + pupdevice + .. pybricks-requirements:: pybricks-iodevices -.. pybricks-classlink:: PUPDevice +.. pybricks-classlink:: LWP3Device -.. figure:: ../../main/cad/output/iodevice-pupdevice.png - :width: 50 % - :target: pupdevice.html +.. figure:: ../../main/cad/output/hub-lwp3.png + :width: 80 % + :target: lwp3device.html .. pybricks-requirements:: ev3 pybricks-iodevices @@ -53,6 +49,40 @@ This module has classes for generic and custom input/output devices. :width: 20 % :target: lumpdevice.html +.. pybricks-requirements:: pybricks-iodevices + +.. pybricks-classlink:: PUPDevice + +.. figure:: ../../main/cad/output/iodevice-pupdevice.png + :width: 50 % + :target: pupdevice.html + +Generic protocols +----------------- + +.. toctree:: + :maxdepth: 1 + :hidden: + + uartdevice + i2cdevice + analogsensor + dcmotor + +.. pybricks-requirements:: pybricks-iodevices + +.. pybricks-classlink:: UARTDevice + +.. |uart-wired| image:: ../../main/cad/output/iodevice-rj12grey.png + :width: 20 % + :target: uartdevice.html + +.. |uart-wireless| image:: ../../main/cad/output/iodevice-pupdevice.png + :width: 50 % + :target: uartdevice.html + +|uart-wired| |uart-wireless| + .. pybricks-requirements:: ev3 pybricks-iodevices .. pybricks-classlink:: I2CDevice @@ -76,11 +106,3 @@ This module has classes for generic and custom input/output devices. .. figure:: ../../main/cad/output/iodevice-dcmotor.png :width: 40 % :target: dcmotor.html - -.. pybricks-requirements:: pybricks-iodevices - -.. pybricks-classlink:: UARTDevice - -.. figure:: ../../main/cad/output/iodevice-rj12grey.png - :width: 20 % - :target: uartdevice.html diff --git a/doc/main/iodevices/uartdevice.rst b/doc/main/iodevices/uartdevice.rst index 2dd08b3..d6bf12d 100644 --- a/doc/main/iodevices/uartdevice.rst +++ b/doc/main/iodevices/uartdevice.rst @@ -3,8 +3,13 @@ Generic UART Device ^^^^^^^^^^^^^^^^^^^ -.. figure:: ../../main/cad/output/iodevice-rj12grey.png - :width: 25 % +.. |uart-wired| image:: ../../main/cad/output/iodevice-rj12grey.png + :width: 20 % + +.. |uart-wireless| image:: ../../main/cad/output/iodevice-pupdevice.png + :width: 50 % + +|uart-wired| |uart-wireless| .. autoclass:: pybricks.iodevices.UARTDevice diff --git a/src/pybricks/iodevices.py b/src/pybricks/iodevices.py index 4e0adc4..b0a1994 100644 --- a/src/pybricks/iodevices.py +++ b/src/pybricks/iodevices.py @@ -262,19 +262,34 @@ class UARTDevice: """Generic UART device.""" def __init__( - self, port: _Port, baudrate: int = 115200, timeout: Optional[int] = None + self, + port: _Port, + baudrate: int = 115200, + timeout: Optional[int] = None, + power_pin: int = 0, ): - """UARTDevice(port, baudrate=115200, timeout=None) + """UARTDevice(port, baudrate=115200, timeout=None, power_pin=0) Arguments: - port (Port): Port to which the device is connected. + port (Port): Port to which the device is connected. On Powered UP + hubs, all ports are supported. On EV3, only the sensor ports + are supported. baudrate (int): Baudrate of the UART device. - timeout (Number, ms): How long to wait - during ``read`` before giving up. If you choose ``None``, - it will wait forever. + timeout (Number, ms): How long to wait during ``read`` and + ``write`` before giving up. If you choose ``None``, it will + wait forever. + power_pin (int): Power requirements for the device. Use ``0`` + (default) for no power on the pins. On Powered UP hubs, use + ``1`` or ``2`` for pin 1 or 2, respectively. This will apply + battery power to the pin, equivalent to powering a motor. + On EV3, use ``1`` to apply battery power to pin 1, though only + minimal current is available. + + Raises: + ValueError: If ``timeout`` is 0 or negative. """ - def read(self, length: int = 1) -> bytes: + def read(self, length: int = 1) -> MaybeAwaitableBytes: """read(length=1) -> bytes Reads a given number of bytes from the buffer. @@ -284,28 +299,38 @@ class UARTDevice: exception is raised. Arguments: - length (int): How many bytes to read. + length (int): How many bytes to read. Must be at least 1. Returns: Bytes returned from the device. + + Raises: + ValueError: If ``length`` is less than 1. + OSError: If the read takes longer than ``timeout``. """ def read_all(self) -> bytes: """read_all() -> bytes - Reads all bytes from the buffer. + Reads all bytes currently in the buffer. Returns immediately without + waiting, even if the buffer is empty. Returns: - Bytes returned from the device. + Bytes currently in the buffer, or an empty bytes object if there + is nothing to read. """ - def write(self, data: bytes) -> None: + def write(self, data: bytes) -> MaybeAwaitable: """write(data) - Writes bytes. + Writes bytes to the device. Arguments: data (bytes): Bytes to be written. + + Raises: + TypeError: If ``data`` is not ``bytes``, ``bytearray``, or ``str``. + OSError: If the write takes longer than ``timeout``. """ def waiting(self) -> int: @@ -317,10 +342,36 @@ class UARTDevice: Number of bytes in the buffer. """ + def set_baudrate(self, baudrate: int) -> None: + """set_baudrate(baudrate) + + Changes the baud rate of the UART device. + + Arguments: + baudrate (int): Not all values may be supported. + + Raises: + ValueError: If ``baudrate`` is less than 1. + """ + + def wait_until(self, pattern: bytes) -> MaybeAwaitable: + """wait_until(pattern) + + Waits until a specific byte sequence is received. Bytes that do not + match the pattern are discarded. + + Arguments: + pattern (bytes): Byte sequence to wait for. Must not be empty. + + Raises: + ValueError: If ``pattern`` is empty. + OSError: If this method is already in progress. + """ + def clear(self) -> None: """clear() - Empties the buffer.""" + Empties the receive buffer.""" class LWP3Device: