Pybricks GATT Service

This module is used for Bluetooth Low Energy communications with devices that provide the Pybricks GATT service.

Device identification and connection

Devices that support this protocol MUST advertise the PYBRICKS_SERVICE_UUID. Connecting devices SHOULD then filter on this UUID to identify compatible devices.

After connecting, programs SHOULD read the Software Revision characteristic of the Device Information Service to determine the Pybricks protocol version. This version can be used to determine the capabilities of the device.

Additional information about the Pybricks Profile can be found at https://github.com/pybricks/technical-info/blob/master/pybricks-ble-profile.md.

class Command(value)

Command for Pybricks BLE protocol.

Commands are sent to a device running Pybricks firmware.

COMMAND_WRITE_USER_RAM = 4

Requests to write data to user RAM.

Parameters:
  • offset – The offset from the base user RAM address (32-bit unsigned integer).

  • payload – The data to write to this address (0 to max_char_size - 5 bytes).

Hub responds with CommandError.VALUE_NOT_ALLOWED if the offset and size exceeded the user RAM area. Hub responds with CommandError.BUSY if a user program is currently running.

Availability: Since Pybricks protocol v1.2.0.

PBIO_PYBRICKS_COMMAND_REBOOT_TO_UPDATE_MODE = 5

Requests for the hub to reboot in firmware update mode.

If this command was successful, the hub will reboot immediately, which means the GATT write request will fail because Bluetooth became disconnected.

Availability: Since Pybricks protocol v1.2.0.

START_REPL = 2

Requests that the interactive REPL should be started.

Hub responds with CommandError.INVALID_COMMAND if the hub does not support the REPL. Hub responds with CommandError.BUSY if a user program is currently running.

Availability: Since Pybricks protocol v1.2.0.

START_USER_PROGRAM = 1

Requests that the user program should be started.

Hub responds with CommandError.BUSY if a user program is currently running.

Availability: Since Pybricks protocol v1.2.0.

STOP_USER_PROGRAM = 0

Requests that the user program should be stopped.

Availability: Since Pybricks protocol v1.0.0.

WRITE_STDIN = 6

Requests to write to stdin on the hub.

Parameters:

payload – Variable number of bytes to write (0 to max_char_size bytes).

Availability: Since Pybricks protocol v1.3.0.

WRITE_USER_PROGRAM_META = 3

Requests to write user program metadata.

Parameters:

size – The size of the user program in bytes (32-bit unsigned integer).

Hub responds with CommandError.BUSY if a user program is currently running.

Availability: Since Pybricks protocol v1.2.0.

class CommandError(value)

GATT Attribute error codes that can be sent in response to command write requests.

BUSY = 129

The command cannot be completed now because the required resources are busy.

Availability: Since Pybricks protocol v1.2.0.

INVALID_COMMAND = 128

An invalid command was requested.

Availability: Since Pybricks protocol v1.2.0.

INVALID_HANDLE = 1

The attribute handle given was not valid on this server.

NOT_SUPPORTED = 6

Attribute server does not support the request received from the client.

VALUE_NOT_ALLOWED = 19

The attribute parameter value was not allowed.

DI_SERVICE_UUID = '0000180a-0000-1000-8000-00805f9b34fb'

Standard Device Information Service UUID.

Availability: Since Pybricks protocol v1.0.0.

class Event(value)

Event for Pybricks BLE protocol.

Events are received from a device running Pybricks firmware.

STATUS_REPORT = 0

Status report event.

The payload is a 32-bit little-endian unsigned integer containing StatusFlag flags.

Availability: Since Pybricks protocol v1.0.0.

WRITE_STDOUT = 1

Hub write to stdout event.

The payload is a variable number of bytes that was written to stdout by the hub.

Availability: Since Pybricks protocol v1.3.0.

FW_REV_UUID = '00002a26-0000-1000-8000-00805f9b34fb'

Standard Firmware Revision String characteristic UUID

Availability: Since Pybricks protocol v1.0.0.

class HubCapabilityFlag(value)

Hub capability flags.

HAS_REPL = 1

Indicates that the hub has an interactive REPL.

Availability: Since Pybricks protocol v1.2.0.

USER_PROG_MULTI_FILE_MPY6 = 2

Hub supports user programs using a multi-file blob with MicroPython MPY (ABI V6) files.

Native module support is not implied by this flag but may be indicated by additional flags.

Availability: Since Pybricks protocol v1.2.0.

USER_PROG_MULTI_FILE_MPY6_1_NATIVE = 4

Hub supports user programs using a multi-file blob with MicroPython MPY (ABI V6.1) files including native module support.

Availability: Since Pybricks protocol v1.3.0.

PNP_ID_UUID = '00002a50-0000-1000-8000-00805f9b34fb'

Standard PnP ID UUID

Vendor ID is pybricksdev.ble.lwp3.LEGO_CID. Product ID is one of pybricksdev.ble.lwp3.bytecodes.HubKind. Revision is 0 for most hubs or 1 for MINDSTORMS Robot Inventor Hub.

Availability: Since Pybricks protocol v1.1.0.

PYBRICKS_COMMAND_EVENT_UUID = 'c5f50002-8280-46da-89f4-6d8051e4aeef'

The Pybricks command/event GATT characteristic UUID.

Commands are written to this characteristic and events are received via notifications.

See Command and Event.

Availability: Since Pybricks protocol v1.0.0.

PYBRICKS_HUB_CAPABILITIES_UUID = 'c5f50003-8280-46da-89f4-6d8051e4aeef'

The Pybricks hub capabilities GATT characteristic UUID.

Availability: Since Pybricks protocol v1.2.0.

PYBRICKS_PROTOCOL_VERSION = 1

The minimum required Pybricks protocol version supported by this library.

PYBRICKS_SERVICE_UUID = 'c5f50001-8280-46da-89f4-6d8051e4aeef'

The Pybricks GATT service UUID.

SW_REV_UUID = '00002a28-0000-1000-8000-00805f9b34fb'

Standard Software Revision String UUID (Pybricks protocol version)

Availability: Since Pybricks protocol v1.0.0.

class StatusFlag(value)

Hub status indicators.

BATTERY_HIGH_CURRENT = 4

Battery current is too high.

Availability: Since Pybricks protocol v1.0.0.

BATTERY_LOW_VOLTAGE_SHUTDOWN = 2

Battery voltage is critically low.

Availability: Since Pybricks protocol v1.0.0.

BATTERY_LOW_VOLTAGE_WARNING = 1

Battery voltage is low.

Availability: Since Pybricks protocol v1.0.0.

BLE_ADVERTISING = 8

Bluetooth Low Energy is advertising/discoverable.

Availability: Since Pybricks protocol v1.0.0.

BLE_LOW_SIGNAL = 16

Bluetooth Low Energy has low signal.

Availability: Since Pybricks protocol v1.0.0.

POWER_BUTTON_PRESSED = 32

Power button is currently pressed.

Availability: Since Pybricks protocol v1.0.0.

SHUTDOWN = 128

Hub has entered shutdown state.

Availability: Since Pybricks protocol v1.1.0.

SHUTDOWN_REQUESTED = 256

Hub shutdown was requested.

Availability: Since Pybricks protocol v1.2.0.

USER_PROGRAM_RUNNING = 64

User program is currently running.

Availability: Since Pybricks protocol v1.0.0.

unpack_hub_capabilities(data: bytes) Tuple[int, HubCapabilityFlag, int]

Unpacks the value read from the hub capabilities characteristic.

Parameters:

data – The raw characteristic value.

Returns:

A tuple of the maximum characteristic write size in bytes, the hub capability flags and the max user program size in bytes.

unpack_pnp_id(data: bytes) Tuple[Literal['BT', 'USB'], int, int, int]

Unpacks raw data from the PnP ID characteristic.

Parameters:

data – The raw data

Returns:

Tuple containing the vendor ID type ('BT' or 'USB'), the vendor ID, the product ID and the product revision.