Merge branch 'micropython:master' into master

Author: mkomon

micropython/bluetooth/aioble/README.md

@@ -3,7 +3,7 @@ aioble
 
 This library provides an object-oriented, asyncio-based wrapper for MicroPython's [ubluetooth](https://docs.micropython.org/en/latest/library/ubluetooth.html) API.
 
-**Note**: aioble requires MicroPython v1.15 or higher.
+**Note**: aioble requires MicroPython v1.17 or higher.
 
 Features
 --------
@@ -118,11 +118,30 @@ temp_char = await temp_service.characteristic(_ENV_SENSE_TEMP_UUID)
 
 data = await temp_char.read(timeout_ms=1000)
 
-temp_char.subscribe(notify=True)
+await temp_char.subscribe(notify=True)
 while True:
     data = await temp_char.notified()
 ```
 
+Open L2CAP channels: (Listener)
+
+```py
+channel = await connection.l2cap_accept(_L2CAP_PSN, _L2CAP_MTU)
+buf = bytearray(64)
+n = channel.recvinto(buf)
+channel.send(b'response')
+```
+
+Open L2CAP channels: (Initiator)
+
+```py
+channel = await connection.l2cap_connect(_L2CAP_PSN, _L2CAP_MTU)
+channel.send(b'request')
+buf = bytearray(64)
+n = channel.recvinto(buf)
+```
+
+
 Examples
 --------
 

micropython/bluetooth/aioble/aioble/central.py

@@ -86,7 +86,13 @@ def _central_irq(event, data):
             connection._event.set()
 
 
-register_irq_handler(_central_irq)
+def _central_shutdown():
+    global _active_scanner, _connecting
+    _active_scanner = None
+    _connecting = set()
+
+
+register_irq_handler(_central_irq, _central_shutdown)
 
 
 # Cancel an in-progress scan.

micropython/bluetooth/aioble/aioble/client.py

@@ -2,6 +2,7 @@
 # MIT license; Copyright (c) 2021 Jim Mussared
 
 from micropython import const
+from collections import deque
 import uasyncio as asyncio
 import struct
 
@@ -27,6 +28,12 @@
 _CCCD_NOTIFY = const(1)
 _CCCD_INDICATE = const(2)
 
+_FLAG_READ = const(0x0002)
+_FLAG_WRITE_NO_RESPONSE = const(0x0004)
+_FLAG_WRITE = const(0x0008)
+_FLAG_NOTIFY = const(0x0010)
+_FLAG_INDICATE = const(0x0020)
+
 # Forward IRQs directly to static methods on the type that handles them and
 # knows how to map handles to instances. Note: We copy all uuid and data
 # params here for safety, but a future optimisation might be able to avoid
@@ -71,7 +78,7 @@ def _client_irq(event, data):
         ClientCharacteristic._on_indicate(conn_handle, value_handle, bytes(indicate_data))
 
 
-register_irq_handler(_client_irq)
+register_irq_handler(_client_irq, None)
 
 
 # Async generator for discovering services, characteristics, descriptors.
@@ -202,8 +209,13 @@ def _find(conn_handle, value_handle):
                 # value handle for the done event.
                 return None
 
+    def _check(self, flag):
+        if not (self.properties & flag):
+            raise ValueError("Unsupported")
+
     # Issue a read to the characteristic.
     async def read(self, timeout_ms=1000):
+        self._check(_FLAG_READ)
         # Make sure this conn_handle/value_handle is known.
         self._register_with_connection()
         # This will be set by the done IRQ.
@@ -235,10 +247,15 @@ def _read_done(conn_handle, value_handle, status):
             characteristic._read_event.set()
 
     async def write(self, data, response=False, timeout_ms=1000):
-        # TODO: default response to True if properties includes WRITE and is char.
-        # Something like:
-        # if response is None and self.properties & _FLAGS_WRITE:
-        #   response = True
+        self._check(_FLAG_WRITE | _FLAG_WRITE_NO_RESPONSE)
+
+        # If we only support write-with-response, then force sensible default.
+        if (
+            response is None
+            and (self.properties & _FLAGS_WRITE)
+            and not (self.properties & _FLAG_WRITE_NO_RESPONSE)
+        ):
+            response = True
 
         if response:
             # Same as read.
@@ -281,28 +298,32 @@ def __init__(self, service, def_handle, value_handle, properties, uuid):
         # Allows comparison to a known uuid.
         self.uuid = uuid
 
-        # Fired for each read result and read done IRQ.
-        self._read_event = None
-        self._read_data = None
-        # Used to indicate that the read is complete.
-        self._read_status = None
-
-        # Fired for the write done IRQ.
-        self._write_event = None
-        # Used to indicate that the write is complete.
-        self._write_status = None
+        if properties & _FLAG_READ:
+            # Fired for each read result and read done IRQ.
+            self._read_event = None
+            self._read_data = None
+            # Used to indicate that the read is complete.
+            self._read_status = None
+
+        if (properties & _FLAG_WRITE) or (properties & _FLAG_WRITE_NO_RESPONSE):
+            # Fired for the write done IRQ.
+            self._write_event = None
+            # Used to indicate that the write is complete.
+            self._write_status = None
 
-        # Fired when a notification arrives.
-        self._notify_event = None
-        # Data for the most recent notification.
-        self._notify_data = None
-        # Same for indications.
-        self._indicate_event = None
-        self._indicate_data = None
+        if properties & _FLAG_NOTIFY:
+            # Fired when a notification arrives.
+            self._notify_event = asyncio.ThreadSafeFlag()
+            # Data for the most recent notification.
+            self._notify_queue = deque((), 1)
+        if properties & _FLAG_INDICATE:
+            # Same for indications.
+            self._indicate_event = asyncio.ThreadSafeFlag()
+            self._indicate_queue = deque((), 1)
 
     def __str__(self):
         return "Characteristic: {} {} {} {}".format(
-            self._def_handle, self._value_handle, self._properties, self.uuid
+            self._def_handle, self._value_handle, self.properties, self.uuid
         )
 
     def _connection(self):
@@ -334,49 +355,72 @@ def _start_discovery(service, uuid=None):
             uuid,
         )
 
+    # Helper for notified() and indicated().
+    async def _notified_indicated(self, queue, event, timeout_ms):
+        # Ensure that events for this connection can route to this characteristic.
+        self._register_with_connection()
+
+        # If the queue is empty, then we need to wait. However, if the queue
+        # has a single item, we also need to do a no-op wait in order to
+        # clear the event flag (because the queue will become empty and
+        # therefore the event should be cleared).
+        if len(queue) <= 1:
+            with self._connection().timeout(timeout_ms):
+                await event.wait()
+
+        # Either we started > 1 item, or the wait completed successfully, return
+        # the front of the queue.
+        return queue.popleft()
+
     # Wait for the next notification.
     # Will return immediately if a notification has already been received.
     async def notified(self, timeout_ms=None):
-        self._register_with_connection()
-        data = self._notify_data
-        if data is None:
-            self._notify_event = self._notify_event or asyncio.ThreadSafeFlag()
-            with self._connection().timeout(timeout_ms):
-                await self._notify_event.wait()
-                data = self._notify_data
-        self._notify_data = None
-        return data
+        self._check(_FLAG_NOTIFY)
+        return await self._notified_indicated(self._notify_queue, self._notify_event, timeout_ms)
+
+    def _on_notify_indicate(self, queue, event, data):
+        # If we've gone from empty to one item, then wake something
+        # blocking on `await char.notified()` (or `await char.indicated()`).
+        wake = len(queue) == 0
+        # Append the data. By default this is a deque with max-length==1, so it
+        # replaces. But if capture is enabled then it will append.
+        queue.append(data)
+        if wake:
+            # Queue is now non-empty. If something is waiting, it will be
+            # worken. If something isn't waiting right now, then a future
+            # caller to `await char.written()` will see the queue is
+            # non-empty, and wait on the event if it's going to empty the
+            # queue.
+            event.set()
 
     # Map an incoming notify IRQ to a registered characteristic.
     def _on_notify(conn_handle, value_handle, notify_data):
         if characteristic := ClientCharacteristic._find(conn_handle, value_handle):
-            characteristic._notify_data = notify_data
-            if characteristic._notify_event:
-                characteristic._notify_event.set()
+            characteristic._on_notify_indicate(
+                characteristic._notify_queue, characteristic._notify_event, notify_data
+            )
 
     # Wait for the next indication.
     # Will return immediately if an indication has already been received.
     async def indicated(self, timeout_ms=None):
-        self._register_with_connection()
-        data = self._indicate_data
-        if data is None:
-            self._indicate_event = self._indicate_event or asyncio.ThreadSafeFlag()
-            with self._connection().timeout(timeout_ms):
-                await self._indicate_event.wait()
-                data = self._indicate_data
-        self._indicate_data = None
-        return data
+        self._check(_FLAG_INDICATE)
+        return await self._notified_indicated(
+            self._indicate_queue, self._indicate_event, timeout_ms
+        )
 
     # Map an incoming indicate IRQ to a registered characteristic.
     def _on_indicate(conn_handle, value_handle, indicate_data):
         if characteristic := ClientCharacteristic._find(conn_handle, value_handle):
-            characteristic._indicate_data = indicate_data
-            if characteristic._indicate_event:
-                characteristic._indicate_event.set()
+            characteristic._on_notify_indicate(
+                characteristic._indicate_queue, characteristic._indicate_event, indicate_data
+            )
 
     # Write to the Client Characteristic Configuration to subscribe to
     # notify/indications for this characteristic.
     async def subscribe(self, notify=True, indicate=False):
+        # Ensure that the generated notifications are dispatched in case the app
+        # hasn't awaited on notified/indicated yet.
+        self._register_with_connection()
         if cccd := await self.descriptor(bluetooth.UUID(_CCCD_UUID)):
             await cccd.write(struct.pack("<H", _CCCD_NOTIFY * notify + _CCCD_INDICATE * indicate))
         else:
@@ -396,9 +440,12 @@ def __init__(self, characteristic, dsc_handle, uuid):
         # Used for read/write.
         self._value_handle = dsc_handle
 
+        # Default flags
+        self.properties = _FLAG_READ | _FLAG_WRITE_NO_RESPONSE
+
     def __str__(self):
         return "Descriptor: {} {} {} {}".format(
-            self._def_handle, self._value_handle, self._properties, self.uuid
+            self._def_handle, self._value_handle, self.properties, self.uuid
         )
 
     def _connection(self):

micropython/bluetooth/aioble/aioble/core.py

@@ -43,17 +43,24 @@ def config(*args, **kwargs):
     return ble.config(*args, **kwargs)
 
 
-def stop():
-    ble.active(False)
+# Because different functionality is enabled by which files are available the
+# different modules can register their IRQ handlers and shutdown handlers
+# dynamically.
+_irq_handlers = []
+_shutdown_handlers = []
 
 
-# Because different functionality is enabled by which files are available
-# the different modules can register their IRQ handlers dynamically.
-_irq_handlers = []
+def register_irq_handler(irq, shutdown):
+    if irq:
+        _irq_handlers.append(irq)
+    if shutdown:
+        _shutdown_handlers.append(shutdown)
 
 
-def register_irq_handler(handler):
-    _irq_handlers.append(handler)
+def stop():
+    ble.active(False)
+    for handler in _shutdown_handlers:
+        handler()
 
 
 # Dispatch IRQs to the registered sub-modules.

micropython/bluetooth/aioble/aioble/device.py

@@ -26,7 +26,7 @@ def _device_irq(event, data):
                 device._mtu_event.set()
 
 
-register_irq_handler(_device_irq)
+register_irq_handler(_device_irq, None)
 
 
 # Context manager to allow an operation to be cancelled by timeout or device

micropython/bluetooth/aioble/aioble/l2cap.py

@@ -44,6 +44,7 @@ def _l2cap_irq(event, data):
                 _, _, psm, status = data
                 channel._status = status
                 channel._cid = None
+                connection._l2cap_channel = None
             elif event == _IRQ_L2CAP_RECV:
                 channel._data_ready = True
             elif event == _IRQ_L2CAP_SEND_READY:
@@ -53,7 +54,12 @@ def _l2cap_irq(event, data):
             channel._event.set()
 
 
-register_irq_handler(_l2cap_irq)
+def _l2cap_shutdown():
+    global _listening
+    _listening = False
+
+
+register_irq_handler(_l2cap_irq, _l2cap_shutdown)
 
 
 # The channel was disconnected during a send/recvinto/flush.
@@ -155,8 +161,11 @@ async def disconnect(self, timeout_ms=1000):
             return
 
         # Wait for the cid to be cleared by the disconnect IRQ.
+        ble.l2cap_disconnect(self._connection._conn_handle, self._cid)
+        await self.disconnected(timeout_ms)
+
+    async def disconnected(self, timeout_ms=1000):
         with self._connection.timeout(timeout_ms):
-            ble.l2cap_disconnect(self._connection._conn_handle, self._cid)
             while self._cid is not None:
                 await self._event.wait()
 

micropython/bluetooth/aioble/aioble/peripheral.py

@@ -63,7 +63,13 @@ def _peripheral_irq(event, data):
             connection._event.set()
 
 
-register_irq_handler(_peripheral_irq)
+def _peripheral_shutdown():
+    global _incoming_connection, _connect_event
+    _incoming_connection = None
+    _connect_event = None
+
+
+register_irq_handler(_peripheral_irq, _peripheral_shutdown)
 
 
 # Advertising payloads are repeated packets of the following form:

micropython/bluetooth/aioble/aioble/security.py

@@ -149,7 +149,14 @@ def _security_irq(event, data):
         #     log_warn("unknown passkey action")
 
 
-register_irq_handler(_security_irq)
+def _security_shutdown():
+    global _secrets, _modified, _path
+    _secrets = {}
+    _modified = False
+    _path = None
+
+
+register_irq_handler(_security_irq, _security_shutdown)
 
 
 # Use device.pair() rather than calling this directly.