Add pybricks.iodevices.NUSDevice Nordic UART Service peripheral - #486
Open
antonvh wants to merge 2 commits into
Open
Add pybricks.iodevices.NUSDevice Nordic UART Service peripheral#486antonvh wants to merge 2 commits into
antonvh wants to merge 2 commits into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
pybricks.iodevices.NUSDeviceso a Powered Up hub can act as a BLE Nordic UART Service (NUS) peripheral: receive writes on the RX characteristic and send notifications on TX.write()follows the same awaitable pattern asUARTDevice.write(). Incoming data is a last-packet mailbox viaread_all(), not a UART-style FIFO.Unrelated drive-bys in this change (not user-facing):
bluetooth.cnow includes<string.h>for existingmemcpy/memset, and its#endifcomment matchesPBDRV_CONFIG_BLUETOOTH;iodevices.hincludes<pbio/port.h>for existing I2C helper types.Documentation draft
Copy from here if useful for
iodevicesdocs.Nordic UART Service
Use
NUSDeviceto exchange raw bytes with a phone, computer, or microcontroller over Bluetooth Low Energy, using the Nordic UART Service. The hub is the GATT peripheral. The other device is the central (for example nRF Connect).The hub keeps advertising the Pybricks service and the flashed hub name. Connect the NUS client while the hub is idle (no user program running). If already connected to code.pybricks.com, press the Bluetooth button on the hub to make it visible in a BLE scan again - the blue ring starts flashing. Starting a program stops connectable advertising, but an existing connection stays up.
You can have at most one
NUSDeviceat a time.Availability: City Hub, Technic Hub, Prime Hub / Inventor Hub, Essential Hub, and Virtual Hub.
class NUSDevice()
Nordic UART Service peripheral.
Raises:
NUSDevicealready exists.await write(data)
Sends bytes to connected centrals that have Notify enabled on the NUS TX characteristic.
If you use
run_task, you mustawaitthis method. Withoutrun_task, it behaves as a normal blocking call, likeUARTDevice.write().Payloads larger than 20 bytes are sent as successive 20-byte notifications.
Parameters:
Raises:
is_connected()beforewrite().read_all() → bytes
Returns the most recent packet written to the NUS RX characteristic, then clears it. Returns immediately. If nothing has been received since the last call, returns empty
bytes.This is not a UART-style FIFO. Each BLE write replaces the previous unread packet (last packet wins, at most 20 bytes). That matches typical remote-control traffic, where only the latest command matters, and it keeps RAM use bounded on the hub. If you need every packet, call
read_all()often enough that a new write cannot arrive in between.Returns:
The last received packet, or
b"".is_connected() → bool
Checks whether a central is subscribed to NUS TX notifications.
This is not the same as “a BLE device is connected.” A phone can be connected and still fail
write()until Notify is enabled on TX. Incomingread_all()data does not require that subscription.Returns:
Trueif at least one central has NUS TX notifications enabled, otherwiseFalse.Implementation notes
lib/pbio/test/sys/test_bluetooth.c(test_bluetooth_nus), including a 25-byte write that must produce two notifications. UART notify handle in the BTstack test mock is0x0015.IMG_2806.mp4