From 81f2162ca0e926c9a4a1787a3863d94d86be0b36 Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 23 Sep 2020 23:18:16 +1000 Subject: extmod/modbluetooth: Change module-owned bytes objects to memoryview. A read-only memoryview object is a better representation of the data, which is owned by the ubluetooth module and may change between calls to the user's irq callback function. Signed-off-by: Damien George --- docs/library/ubluetooth.rst | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/library/ubluetooth.rst b/docs/library/ubluetooth.rst index 03d03583a..f94ad3a61 100644 --- a/docs/library/ubluetooth.rst +++ b/docs/library/ubluetooth.rst @@ -88,12 +88,22 @@ Event Handling arguments, ``event`` (which will be one of the codes below) and ``data`` (which is an event-specific tuple of values). - **Note:** the ``addr``, ``adv_data``, ``char_data``, ``notify_data``, and - ``uuid`` entries in the tuples are references to data managed by the - :mod:`ubluetooth` module (i.e. the same instance will be re-used across - multiple calls to the event handler). If your program wants to use this - data outside of the handler, then it must copy them first, e.g. by using - ``bytes(addr)`` or ``bluetooth.UUID(uuid)``. + **Note:** As an optimisation to prevent unnecessary allocations, the ``addr``, + ``adv_data``, ``char_data``, ``notify_data``, and ``uuid`` entries in the + tuples are read-only memoryview instances pointing to ubluetooth's internal + ringbuffer, and are only valid during the invocation of the IRQ handler + function. If your program needs to save one of these values to access after + the IRQ handler has returned (e.g. by saving it in a class instance or global + variable), then it needs to take a copy of the data, either by using ``bytes()`` + or ``bluetooth.UUID()``, like this:: + + connected_addr = bytes(addr) # equivalently: adv_data, char_data, or notify_data + matched_uuid = bluetooth.UUID(uuid) + + For example, the IRQ handler for a scan result might inspect the ``adv_data`` + to decide if it's the correct device, and only then copy the address data to be + used elsewhere in the program. And to print data from within the IRQ handler, + ``print(bytes(addr))`` will be needed. An event handler showing all possible events:: -- cgit v1.2.3