From 7ca306463aa0513486282e5f2bdb31f797f9b5df Mon Sep 17 00:00:00 2001 From: Lasse Deleuran Date: Mon, 13 Apr 2026 11:40:42 +0200 Subject: [PATCH 1/2] Added missing functions and parameters to documentation. - AnalogSensor: Missing parameter "custom". - I2CDevice: Missing parameters "port", "address", "custom", "powered", and "nxt_quirk" with attempted explanation of parameters. - UARTDevice: Missing default parameter value. - LWP3Device: Missing "connect" parameter. - Added missing connect and disconnnect methods. - XboxController: Missing documentation in constructor and missing methods. --- src/pybricks/iodevices.py | 79 ++++++++++++++++++++++++++++++++++----- 1 file changed, 70 insertions(+), 9 deletions(-) diff --git a/src/pybricks/iodevices.py b/src/pybricks/iodevices.py index 522c555..2552ed1 100644 --- a/src/pybricks/iodevices.py +++ b/src/pybricks/iodevices.py @@ -117,11 +117,13 @@ def read(self, mode: str) -> MaybeAwaitableTuple: class AnalogSensor: """Generic or custom analog sensor.""" - def __init__(self, port: _Port): - """AnalogSensor(port) + def __init__(self, port: _Port, custom: bool = False): + """AnalogSensor(port, custom=False) Arguments: port (Port): Port to which the sensor is connected. + custom (bool): Set to ``True`` if you are using a custom analog + sensor, such as a passive RCX sensor. """ def voltage(self) -> int: @@ -173,13 +175,18 @@ def passive(self) -> None: class I2CDevice: """Generic or custom I2C device.""" - def __init__(self, port: _Port, address: int): - """I2CDevice(port, address) + def __init__(self, port: _Port, address: int, custom: bool = False, powered: bool = False, nxt_quirk: bool = False): + """I2CDevice(port, address, custom=False, powered=False, nxt_quirk=False) Arguments: port (Port): Port to which the device is connected. address(int): I2C address of the client device. See :ref:`I2C Addresses `. + custom (bool): Set to ``True`` if you are using a custom I2C device. + powered (bool): Set to ``True`` to power the I2C device. + nxt_quirk (bool): Set to ``True`` for older NXT I2C sensors that + need slower compatibility timing to communicate reliably, + such as the old NXT Ultrasonic Sensor. """ def read(self, reg: Optional[int], length: Optional[int] = 1) -> bytes: @@ -211,8 +218,8 @@ def write(self, reg: Optional[int], data: Optional[bytes] = None) -> None: class UARTDevice: """Generic UART device.""" - def __init__(self, port: _Port, baudrate: int, timeout: Optional[int] = None): - """UARTDevice(port, baudrate, timeout=None) + def __init__(self, port: _Port, baudrate: int = 115200, timeout: Optional[int] = None): + """UARTDevice(port, baudrate=115200, timeout=None) Arguments: port (Port): Port to which the device is connected. @@ -287,8 +294,9 @@ def __init__( timeout: int = 10000, pair: bool = False, num_notifications: int = 8, + connect: bool = True, ): - """LWP3Device(hub_kind, name=None, timeout=10000, pair=False, num_notifications=8) + """LWP3Device(hub_kind, name=None, timeout=10000, pair=False, num_notifications=8, connect=True) Arguments: hub_kind (int): @@ -303,6 +311,8 @@ def __init__( This is required for some newer hubs. num_notifications (int): Number of incoming messages from the remote hub to store before discarding older messages. + connect (bool): Choose ``True`` to connect to the device when the + object is created. Choose ``False`` to skip connecting. .. versionchanged:: 3.6 @@ -316,6 +326,13 @@ def __init__( https://github.com/pybricks/technical-info/blob/master/assigned-numbers.md#hub-type-ids """ + def connect(self) -> MaybeAwaitable: + """connect() + + Connects to the remote LWP3Device. Only needed if you initialized the + device with ``connect=False``. + """ + @overload def name(self, name: str) -> MaybeAwaitable: ... @@ -377,8 +394,52 @@ class XboxController: buttons = _common.Keypad([]) - def __init__(self): - """""" + def __init__(self, joystick_deadzone: int = 10, name: Optional[str] = None, timeout: int = 10000, connect: bool = True): + """__init__(joystick_deadzone=10, name=None, timeout=10000, connect=True) + + Arguments: + joystick_deadzone (Number, %): Joystick deadzone (0 to 100). Values + below this threshold will be reported as 0. + name (str): The Bluetooth name of the Xbox controller to connect to, + or ``None`` to connect to any available controller. + timeout (Number, ms): How long to wait for a connection before + giving up. + connect (bool): Choose ``True`` to connect to the controller when + the object is created. Choose ``False`` to skip connecting. + """ + + def connect(self) -> MaybeAwaitable: + """connect() + + Connects to the Xbox controller. Only needed if you initialized the + controller with ``connect=False``. + """ + + def disconnect(self) -> MaybeAwaitable: + """disconnect() + + Disconnects the Xbox controller. + """ + + def name(self) -> str: + """name() -> str + + Gets the Bluetooth name of the connected controller. + + Returns: + Bluetooth name of the controller. + """ + + def state(self) -> Tuple: + """state() -> Tuple + + Gets all raw controller input values as a single tuple. This gives + access to values not exposed by the other methods. + + Returns: + Tuple of ``(x, y, z, rz, left_trigger, right_trigger, dpad, + buttons, upload, profile, trigger_switches, paddles)``. + """ def joystick_left(self) -> Tuple[int, int]: """joystick_left() -> Tuple From ea73e07ed6df5d3f5cb397120d24426d673ad965 Mon Sep 17 00:00:00 2001 From: Lasse Deleuran Date: Mon, 13 Apr 2026 14:10:29 +0200 Subject: [PATCH 2/2] Minor changes to the documentation Made it more clear and less verbose when to skip connect to bluetooth devices. --- src/pybricks/iodevices.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pybricks/iodevices.py b/src/pybricks/iodevices.py index 2552ed1..fec76cf 100644 --- a/src/pybricks/iodevices.py +++ b/src/pybricks/iodevices.py @@ -311,8 +311,8 @@ def __init__( This is required for some newer hubs. num_notifications (int): Number of incoming messages from the remote hub to store before discarding older messages. - connect (bool): Choose ``True`` to connect to the device when the - object is created. Choose ``False`` to skip connecting. + connect (bool): Choose ``False`` to skip connecting. + ``connect()`` can be called later to connect. .. versionchanged:: 3.6 @@ -404,8 +404,8 @@ def __init__(self, joystick_deadzone: int = 10, name: Optional[str] = None, time or ``None`` to connect to any available controller. timeout (Number, ms): How long to wait for a connection before giving up. - connect (bool): Choose ``True`` to connect to the controller when - the object is created. Choose ``False`` to skip connecting. + connect (bool): Choose ``False`` to skip connecting to the controller. + ``connect()`` can be called later to connect. """ def connect(self) -> MaybeAwaitable: