merge from upstream; working; includes debug_out code for debugging via Saleae for posterity

8 files changed, 49 insertions, 39 deletions

diff --git a/shared-bindings/_bleio/Adapter.c b/shared-bindings/_bleio/Adapter.c
index 3d5781ef9..6942f3709 100644
--- a/shared-bindings/_bleio/Adapter.c
+++ b/shared-bindings/_bleio/Adapter.c
@@ -147,7 +147,7 @@ const mp_obj_property_t bleio_adapter_enabled_obj = {
 };
 
 //|     address: Address
-//|     """MAC address of the BLE adapter. (read-only)"""
+//|     """MAC address of the BLE adapter."""
 //|
 STATIC mp_obj_t bleio_adapter_get_address(mp_obj_t self) {
     return MP_OBJ_FROM_PTR(common_hal_bleio_adapter_get_address(self));
@@ -155,10 +155,18 @@ STATIC mp_obj_t bleio_adapter_get_address(mp_obj_t self) {
 }
 MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_get_address_obj, bleio_adapter_get_address);
 
+STATIC mp_obj_t bleio_adapter_set_address(mp_obj_t self, mp_obj_t new_address) {
+    if (!common_hal_bleio_adapter_set_address(self, new_address)) {
+        mp_raise_bleio_BluetoothError(translate("Could not set address"));
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(bleio_adapter_set_address_obj, bleio_adapter_set_address);
+
 const mp_obj_property_t bleio_adapter_address_obj = {
     .base.type = &mp_type_property,
     .proxy = { (mp_obj_t)&bleio_adapter_get_address_obj,
-               (mp_obj_t)&mp_const_none_obj,
+               (mp_obj_t)&bleio_adapter_set_address_obj,
                (mp_obj_t)&mp_const_none_obj },
 };
 
@@ -196,8 +204,8 @@ const mp_obj_property_t bleio_adapter_name_obj = {
 //|         .. note: If you set ``anonymous=True``, then a timeout must be specified. If no timeout is
 //|            specified, then the maximum allowed timeout will be selected automatically.
 //|
-//|         :param buf data: advertising data packet bytes
-//|         :param buf scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
+//|         :param ~_typing.ReadableBuffer data: advertising data packet bytes
+//|         :param ~_typing.ReadableBuffer scan_response: scan response data packet bytes. ``None`` if no scan response is needed.
 //|         :param bool connectable:  If `True` then other devices are allowed to connect to this peripheral.
 //|         :param bool anonymous:  If `True` then this device's MAC address is randomized before advertising.
 //|         :param int timeout:  If set, we will only advertise for this many seconds.
@@ -270,7 +278,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(bleio_adapter_stop_advertising_obj, bleio_adapt
 //|         """Starts a BLE scan and returns an iterator of results. Advertisements and scan responses are
 //|         filtered and returned separately.
 //|
-//|         :param sequence prefixes: Sequence of byte string prefixes to filter advertising packets
+//|         :param ~_typing.ReadableBuffer prefixes: Sequence of byte string prefixes to filter advertising packets
 //|             with. A packet without an advertising structure that matches one of the prefixes is
 //|             ignored. Format is one byte for length (n) and n bytes of prefix and can be repeated.
 //|         :param int buffer_size: the maximum number of advertising bytes to buffer.
@@ -385,7 +393,7 @@ const mp_obj_property_t bleio_adapter_connected_obj = {
                (mp_obj_t)&mp_const_none_obj },
 };
 
-//|     connections: tuple
+//|     connections: Tuple[Connection]
 //|     """Tuple of active connections including those initiated through
 //|     :py:meth:`_bleio.Adapter.connect`. (read-only)"""
 //|
diff --git a/shared-bindings/_bleio/Adapter.h b/shared-bindings/_bleio/Adapter.h
index 0cce55ca8..62a1d1c76 100644
--- a/shared-bindings/_bleio/Adapter.h
+++ b/shared-bindings/_bleio/Adapter.h
@@ -41,27 +41,28 @@ const mp_obj_type_t bleio_adapter_type;
 void common_hal_bleio_adapter_hci_uart_init(bleio_adapter_obj_t *self, busio_uart_obj_t *uart, digitalio_digitalinout_obj_t *rts, digitalio_digitalinout_obj_t *cts);
 #endif // CIRCUITPY_BLEIO_HCI
 
-bool common_hal_bleio_adapter_get_advertising(bleio_adapter_obj_t *self);
-bool common_hal_bleio_adapter_get_enabled(bleio_adapter_obj_t *self);
-void common_hal_bleio_adapter_set_enabled(bleio_adapter_obj_t *self, bool enabled);
-bool common_hal_bleio_adapter_get_connected(bleio_adapter_obj_t *self);
-bleio_address_obj_t *common_hal_bleio_adapter_get_address(bleio_adapter_obj_t *self);
+extern bool common_hal_bleio_adapter_get_advertising(bleio_adapter_obj_t *self);
+extern bool common_hal_bleio_adapter_get_enabled(bleio_adapter_obj_t *self);
+extern void common_hal_bleio_adapter_set_enabled(bleio_adapter_obj_t *self, bool enabled);
+extern bool common_hal_bleio_adapter_get_connected(bleio_adapter_obj_t *self);
+extern bleio_address_obj_t *common_hal_bleio_adapter_get_address(bleio_adapter_obj_t *self);
+extern bool common_hal_bleio_adapter_set_address(bleio_adapter_obj_t *self, bleio_address_obj_t *address);
 
-mp_obj_str_t* common_hal_bleio_adapter_get_name(bleio_adapter_obj_t *self);
-void common_hal_bleio_adapter_set_name(bleio_adapter_obj_t *self, const char* name);
+extern mp_obj_str_t* common_hal_bleio_adapter_get_name(bleio_adapter_obj_t *self);
+extern void common_hal_bleio_adapter_set_name(bleio_adapter_obj_t *self, const char* name);
 
-uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self, bool connectable, bool anonymous, uint32_t timeout, float interval, uint8_t *advertising_data, uint16_t advertising_data_len, uint8_t *scan_response_data, uint16_t scan_response_data_len);
+extern uint32_t _common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self, bool connectable, bool anonymous, uint32_t timeout, float interval, uint8_t *advertising_data, uint16_t advertising_data_len, uint8_t *scan_response_data, uint16_t scan_response_data_len);
 
-void common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self, bool connectable, bool anonymous, uint32_t timeout, mp_float_t interval, mp_buffer_info_t *advertising_data_bufinfo, mp_buffer_info_t *scan_response_data_bufinfo);
-void common_hal_bleio_adapter_stop_advertising(bleio_adapter_obj_t *self);
+extern void common_hal_bleio_adapter_start_advertising(bleio_adapter_obj_t *self, bool connectable, bool anonymous, uint32_t timeout, mp_float_t interval, mp_buffer_info_t *advertising_data_bufinfo, mp_buffer_info_t *scan_response_data_bufinfo);
+extern void common_hal_bleio_adapter_stop_advertising(bleio_adapter_obj_t *self);
 
-mp_obj_t common_hal_bleio_adapter_start_scan(bleio_adapter_obj_t *self, uint8_t* prefixes, size_t prefix_length, bool extended, mp_int_t buffer_size, mp_float_t timeout, mp_float_t interval, mp_float_t window, mp_int_t minimum_rssi, bool active);
-void common_hal_bleio_adapter_stop_scan(bleio_adapter_obj_t *self);
+extern mp_obj_t common_hal_bleio_adapter_start_scan(bleio_adapter_obj_t *self, uint8_t* prefixes, size_t prefix_length, bool extended, mp_int_t buffer_size, mp_float_t timeout, mp_float_t interval, mp_float_t window, mp_int_t minimum_rssi, bool active);
+extern void common_hal_bleio_adapter_stop_scan(bleio_adapter_obj_t *self);
 
-bool common_hal_bleio_adapter_get_connected(bleio_adapter_obj_t *self);
-mp_obj_t common_hal_bleio_adapter_get_connections(bleio_adapter_obj_t *self);
-mp_obj_t common_hal_bleio_adapter_connect(bleio_adapter_obj_t *self, bleio_address_obj_t *address, mp_float_t timeout);
+extern bool common_hal_bleio_adapter_get_connected(bleio_adapter_obj_t *self);
+extern mp_obj_t common_hal_bleio_adapter_get_connections(bleio_adapter_obj_t *self);
+extern mp_obj_t common_hal_bleio_adapter_connect(bleio_adapter_obj_t *self, bleio_address_obj_t *address, mp_float_t timeout);
 
-void common_hal_bleio_adapter_erase_bonding(bleio_adapter_obj_t *self);
+extern void common_hal_bleio_adapter_erase_bonding(bleio_adapter_obj_t *self);
 
 #endif // MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_ADAPTER_H
diff --git a/shared-bindings/_bleio/Address.c b/shared-bindings/_bleio/Address.c
index 94994fb70..1f168d31a 100644
--- a/shared-bindings/_bleio/Address.c
+++ b/shared-bindings/_bleio/Address.c
@@ -42,7 +42,7 @@
 //|         """Create a new Address object encapsulating the address value.
 //|         The value itself can be one of:
 //|
-//|         :param buf address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
+//|         :param ~_typing.ReadableBuffer address: The address value to encapsulate. A buffer object (bytearray, bytes) of 6 bytes.
 //|         :param int address_type: one of the integer values: `PUBLIC`, `RANDOM_STATIC`,
 //|           `RANDOM_PRIVATE_RESOLVABLE`, or `RANDOM_PRIVATE_NON_RESOLVABLE`."""
 //|         ...
@@ -128,7 +128,7 @@ const mp_obj_property_t bleio_address_type_obj = {
               (mp_obj_t)&mp_const_none_obj},
 };
 
-//|     def __eq__(self, other: Address) -> bool:
+//|     def __eq__(self, other: object) -> bool:
 //|         """Two Address objects are equal if their addresses and address types are equal."""
 //|         ...
 //|
diff --git a/shared-bindings/_bleio/Characteristic.c b/shared-bindings/_bleio/Characteristic.c
index 8372321fb..5e384a44c 100644
--- a/shared-bindings/_bleio/Characteristic.c
+++ b/shared-bindings/_bleio/Characteristic.c
@@ -63,7 +63,7 @@
 //|          is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum
 //|          number of data bytes that fit in a single BLE 4.x ATT packet.
 //|         :param bool fixed_length: True if the characteristic value is of fixed length.
-//|         :param buf initial_value: The initial value for this characteristic. If not given, will be
+//|         :param ~_typing.ReadableBuffer initial_value: The initial value for this characteristic. If not given, will be
 //|          filled with zeros.
 //|
 //|         :return: the new Characteristic."""
diff --git a/shared-bindings/_bleio/Connection.c b/shared-bindings/_bleio/Connection.c
index 8cfd96c8c..b5eeaa906 100644
--- a/shared-bindings/_bleio/Connection.c
+++ b/shared-bindings/_bleio/Connection.c
@@ -110,12 +110,12 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_pair_obj, 1, bleio_connection
 
 //|     def discover_remote_services(self, service_uuids_whitelist: Optional[Iterable[UUID]] = None) -> Tuple[Service, ...]:
 //|         """Do BLE discovery for all services or for the given service UUIDS,
-//|          to find their handles and characteristics, and return the discovered services.
-//|          `Connection.connected` must be True.
+//|         to find their handles and characteristics, and return the discovered services.
+//|         `Connection.connected` must be True.
 //|
 //|         :param iterable service_uuids_whitelist:
 //|
-//|           an iterable of :py:class:~`UUID` objects for the services provided by the peripheral
+//|           an iterable of :py:class:`UUID` objects for the services provided by the peripheral
 //|           that you want to use.
 //|
 //|           The peripheral may provide more services, but services not listed are ignored
@@ -125,7 +125,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_connection_pair_obj, 1, bleio_connection
 //|           slow.
 //|
 //|           If the service UUID is 128-bit, or its characteristic UUID's are 128-bit, you
-//|           you must have already created a :py:class:~`UUID` object for that UUID in order for the
+//|           you must have already created a :py:class:`UUID` object for that UUID in order for the
 //|           service or characteristic to be discovered. Creating the UUID causes the UUID to be
 //|           registered for use. (This restriction may be lifted in the future.)
 //|
diff --git a/shared-bindings/_bleio/Descriptor.c b/shared-bindings/_bleio/Descriptor.c
index dce618ece..c313007c6 100644
--- a/shared-bindings/_bleio/Descriptor.c
+++ b/shared-bindings/_bleio/Descriptor.c
@@ -46,7 +46,7 @@
 //|         as part of remote Characteristics in the remote Services that are discovered."""
 //|
 //|     @classmethod
-//|     def add_to_characteristic(characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length = 20, fixed_length: bool = False, initial_value: ReadableBuffer = b'') -> Descriptor:
+//|     def add_to_characteristic(cls, characteristic: Characteristic, uuid: UUID, *, read_perm: int = Attribute.OPEN, write_perm: int = Attribute.OPEN, max_length: int = 20, fixed_length: bool = False, initial_value: ReadableBuffer = b'') -> Descriptor:
 //|         """Create a new Descriptor object, and add it to this Service.
 //|
 //|         :param Characteristic characteristic: The characteristic that will hold this descriptor
@@ -61,7 +61,7 @@
 //|            is 512, or possibly 510 if ``fixed_length`` is False. The default, 20, is the maximum
 //|            number of data bytes that fit in a single BLE 4.x ATT packet.
 //|         :param bool fixed_length: True if the descriptor value is of fixed length.
-//|         :param buf initial_value: The initial value for this descriptor.
+//|         :param ~_typing.ReadableBuffer initial_value: The initial value for this descriptor.
 //|
 //|         :return: the new Descriptor."""
 //|         ...
diff --git a/shared-bindings/_bleio/UUID.c b/shared-bindings/_bleio/UUID.c
index 93f89403b..fe045f385 100644
--- a/shared-bindings/_bleio/UUID.c
+++ b/shared-bindings/_bleio/UUID.c
@@ -48,7 +48,7 @@
 //|         temporary 16-bit UUID that can be used in place of the full 128-bit UUID.
 //|
 //|         :param value: The uuid value to encapsulate
-//|         :type value: int or typing.ByteString"""
+//|         :type value: int, ~_typing.ReadableBuffer or str"""
 //|         ...
 //|
 STATIC mp_obj_t bleio_uuid_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
@@ -248,7 +248,7 @@ STATIC mp_obj_t bleio_uuid_unary_op(mp_unary_op_t op, mp_obj_t self_in) {
     }
 }
 
-//|     def __eq__(self, other: UUID) -> bool:
+//|     def __eq__(self, other: object) -> bool:
 //|         """Two UUID objects are equal if their values match and they are both 128-bit or both 16-bit."""
 //|         ...
 //|
diff --git a/shared-bindings/_bleio/__init__.c b/shared-bindings/_bleio/__init__.c
index f2fb181e6..f3fdc517e 100644
--- a/shared-bindings/_bleio/__init__.c
+++ b/shared-bindings/_bleio/__init__.c
@@ -41,7 +41,8 @@
 #include "shared-bindings/_bleio/Service.h"
 #include "shared-bindings/_bleio/UUID.h"
 
-//| """
+//| """Bluetooth Low Energy (BLE) communication
+//|
 //| The `_bleio` module provides necessary low-level functionality for communicating
 //| using Bluetooth Low Energy (BLE). The '_' prefix indicates this module is meant
 //| for internal use by libraries but not by the end user. Its API may change incompatibly
@@ -50,12 +51,12 @@
 //| `adafruit_ble <https://circuitpython.readthedocs.io/projects/ble/en/latest/>`_
 //| CircuitPython library instead, which builds on `_bleio`, and
 //| provides higher-level convenience functionality, including predefined beacons, clients,
-//| servers.
-//|
-//| .. attribute:: adapter
+//| servers."""
 //|
-//|   BLE Adapter used to manage device discovery and connections.
-//|   This object is the sole instance of `_bleio.Adapter`."""
+
+//| adapter: Adapter
+//| """BLE Adapter used to manage device discovery and connections.
+//| This object is the sole instance of `_bleio.Adapter`."""
 //|
 
 //| class BluetoothError(Exception):