Merge pull request #2092 from dhalbert/bleio-api-revamp5.0.0-alpha.1

Bleio attribute api revamp

26 files changed, 342 insertions, 299 deletions

diff --git a/shared-bindings/bleio/Adapter.c b/shared-bindings/_bleio/Adapter.c
index 2bb7f3465..0caca96b8 100644
--- a/shared-bindings/bleio/Adapter.c
+++ b/shared-bindings/_bleio/Adapter.c
@@ -26,10 +26,10 @@
  */
 
 #include "py/objproperty.h"
-#include "shared-bindings/bleio/Address.h"
-#include "shared-bindings/bleio/Adapter.h"
+#include "shared-bindings/_bleio/Address.h"
+#include "shared-bindings/_bleio/Adapter.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Adapter` --- BLE adapter information
 //| ----------------------------------------------------
@@ -38,15 +38,15 @@
 //|
 //| Usage::
 //|
-//|    import bleio
-//|    bleio.adapter.enabled = True
-//|    print(bleio.adapter.address)
+//|    import _bleio
+//|    _bleio.adapter.enabled = True
+//|    print(_bleio.adapter.address)
 //|
 
 //| .. class:: Adapter()
 //|
-//|     You cannot create an instance of `bleio.Adapter`.
-//|     Use `bleio.adapter` to access the sole instance available.
+//|     You cannot create an instance of `_bleio.Adapter`.
+//|     Use `_bleio.adapter` to access the sole instance available.
 //|
 
 //|     .. attribute:: adapter.enabled
diff --git a/shared-bindings/bleio/Adapter.h b/shared-bindings/_bleio/Adapter.h
index 72382616c..932fc9c95 100644
--- a/shared-bindings/bleio/Adapter.h
+++ b/shared-bindings/_bleio/Adapter.h
@@ -28,7 +28,7 @@
 #ifndef MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_ADAPTER_H
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_ADAPTER_H
 
-#include "shared-module/bleio/Address.h"
+#include "shared-module/_bleio/Address.h"
 
 const mp_obj_type_t bleio_adapter_type;
 
diff --git a/shared-bindings/bleio/Address.c b/shared-bindings/_bleio/Address.c
index baeb6d7c0..cdee02b5d 100644
--- a/shared-bindings/bleio/Address.c
+++ b/shared-bindings/_bleio/Address.c
@@ -31,10 +31,10 @@
 #include "py/objproperty.h"
 #include "py/objstr.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/Address.h"
-#include "shared-module/bleio/Address.h"
+#include "shared-bindings/_bleio/Address.h"
+#include "shared-module/_bleio/Address.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Address` -- BLE address
 //| =========================================================
@@ -88,15 +88,15 @@ STATIC mp_obj_t bleio_address_make_new(const mp_obj_type_t *type, size_t n_args,
 //|     Note that the ``bytes`` object returned is in little-endian order:
 //|     The least significant byte is ``address_bytes[0]``. So the address will
 //|     appear to be reversed if you print the raw ``bytes`` object. If you print
-//|     or use `str()` on the :py:class:`~bleio.Attribute` object itself, the address will be printed
+//|     or use `str()` on the :py:class:`~_bleio.Attribute` object itself, the address will be printed
 //|     in the expected order. For example:
 //|
 //|     .. code-block:: pycon
 //|
-//|       >>> import bleio
-//|       >>> bleio.adapter.address
+//|       >>> import _bleio
+//|       >>> _bleio.adapter.address
 //|       <Address c8:1d:f5:ed:a8:35>
-//|       >>> bleio.adapter.address.address_bytes
+//|       >>> _bleio.adapter.address.address_bytes
 //|       b'5\xa8\xed\xf5\x1d\xc8'
 //|
 STATIC mp_obj_t bleio_address_get_address_bytes(mp_obj_t self_in) {
diff --git a/shared-bindings/bleio/Address.h b/shared-bindings/_bleio/Address.h
index 5e02ee210..98b6f80e0 100644
--- a/shared-bindings/bleio/Address.h
+++ b/shared-bindings/_bleio/Address.h
@@ -29,7 +29,7 @@
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_ADDRESS_H
 
 #include "py/objtype.h"
-#include "shared-module/bleio/Address.h"
+#include "shared-module/_bleio/Address.h"
 
 #define BLEIO_ADDRESS_TYPE_PUBLIC (0)
 #define BLEIO_ADDRESS_TYPE_RANDOM_STATIC (1)
diff --git a/shared-bindings/bleio/Attribute.c b/shared-bindings/_bleio/Attribute.c
index 2cc9ef6d0..2d8b15b9f 100644
--- a/shared-bindings/bleio/Attribute.c
+++ b/shared-bindings/_bleio/Attribute.c
@@ -26,24 +26,24 @@
 
 #include "py/objproperty.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/Characteristic.h"
-#include "shared-bindings/bleio/UUID.h"
+#include "shared-bindings/_bleio/Characteristic.h"
+#include "shared-bindings/_bleio/UUID.h"
 
 //
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Attribute` -- BLE Attribute
 //| =========================================================
 //|
 //| Definitions associated with all BLE attributes: characteristics, descriptors, etc.
-//| :py:class:`~bleio.Attribute` is, notionally, a superclass of
+//| :py:class:`~_bleio.Attribute` is, notionally, a superclass of
 //| :py:class:`~Characteristic` and :py:class:`~Descriptor`,
 //| but is not defined as a Python superclass of those classes.
 //|
 //| .. class:: Attribute()
 //|
-//|   You cannot create an instance of :py:class:`~bleio.Attribute`.
+//|   You cannot create an instance of :py:class:`~_bleio.Attribute`.
 //|
 
 STATIC const mp_rom_map_elem_t bleio_attribute_locals_dict_table[] = {
diff --git a/shared-bindings/bleio/Attribute.h b/shared-bindings/_bleio/Attribute.h
index 06a6eb5a9..a0ce04500 100644
--- a/shared-bindings/bleio/Attribute.h
+++ b/shared-bindings/_bleio/Attribute.h
@@ -29,7 +29,8 @@
 
 #include "py/obj.h"
 
-#include "shared-module/bleio/Attribute.h"
+#include "common-hal/_bleio/Attribute.h"
+#include "shared-module/_bleio/Attribute.h"
 
 extern const mp_obj_type_t bleio_attribute_type;
 
diff --git a/shared-bindings/bleio/Central.c b/shared-bindings/_bleio/Central.c
index 1fc455d8d..084f40cd6 100644
--- a/shared-bindings/bleio/Central.c
+++ b/shared-bindings/_bleio/Central.c
@@ -34,13 +34,13 @@
 #include "py/objproperty.h"
 #include "py/objstr.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/Adapter.h"
-#include "shared-bindings/bleio/Address.h"
-#include "shared-bindings/bleio/Characteristic.h"
-#include "shared-bindings/bleio/Central.h"
-#include "shared-bindings/bleio/Service.h"
+#include "shared-bindings/_bleio/Adapter.h"
+#include "shared-bindings/_bleio/Address.h"
+#include "shared-bindings/_bleio/Characteristic.h"
+#include "shared-bindings/_bleio/Central.h"
+#include "shared-bindings/_bleio/Service.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Central` -- A BLE central device
 //| =========================================================
@@ -49,9 +49,9 @@
 //|
 //| Usage::
 //|
-//|    import bleio
+//|    import _bleio
 //|
-//|    scanner = bleio.Scanner()
+//|    scanner = _bleio.Scanner()
 //|    entries = scanner.scan(2.5)
 //|
 //|    my_entry = None
@@ -63,7 +63,7 @@
 //|    if not my_entry:
 //|        raise Exception("'InterestingPeripheral' not found")
 //|
-//|    central = bleio.Central()
+//|    central = _bleio.Central()
 //|    central.connect(my_entry.address, 10)  # timeout after 10 seconds
 //|    remote_services = central.discover_remote_services()
 //|
@@ -86,7 +86,7 @@ STATIC mp_obj_t bleio_central_make_new(const mp_obj_type_t *type, size_t n_args,
 //|   .. method:: connect(address, timeout, *, service_uuids_whitelist=None)
 //|     Attempts a connection to the remote peripheral.
 //|
-//|   :param bleio.Address address: The address of the peripheral to connect to
+//|   :param Address address: The address of the peripheral to connect to
 //|   :param float/int timeout: Try to connect for timeout seconds.
 //|
 STATIC mp_obj_t bleio_central_connect(mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
diff --git a/shared-bindings/bleio/Central.h b/shared-bindings/_bleio/Central.h
index cbc437087..85d788654 100644
--- a/shared-bindings/bleio/Central.h
+++ b/shared-bindings/_bleio/Central.h
@@ -29,8 +29,8 @@
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_CENTRAL_H
 
 #include "py/objtuple.h"
-#include "common-hal/bleio/Central.h"
-#include "common-hal/bleio/Service.h"
+#include "common-hal/_bleio/Central.h"
+#include "common-hal/_bleio/Service.h"
 
 extern const mp_obj_type_t bleio_central_type;
 
diff --git a/shared-bindings/bleio/Characteristic.c b/shared-bindings/_bleio/Characteristic.c
index 4894ad114..198155589 100644
--- a/shared-bindings/bleio/Characteristic.c
+++ b/shared-bindings/_bleio/Characteristic.c
@@ -28,12 +28,12 @@
 
 #include "py/objproperty.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/Attribute.h"
-#include "shared-bindings/bleio/Characteristic.h"
-#include "shared-bindings/bleio/Descriptor.h"
-#include "shared-bindings/bleio/UUID.h"
+#include "shared-bindings/_bleio/Attribute.h"
+#include "shared-bindings/_bleio/Characteristic.h"
+#include "shared-bindings/_bleio/Service.h"
+#include "shared-bindings/_bleio/UUID.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Characteristic` -- BLE service characteristic
 //| =========================================================
@@ -41,48 +41,66 @@
 //| Stores information about a BLE service characteristic and allows reading
 //| and writing of the characteristic's value.
 //|
+//| .. class:: Characteristic
 //|
-//| .. class:: Characteristic(uuid, *, properties=0, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, descriptors=None)
+//|   There is no regular constructor for a Characteristic. A new local Characteristic can be created
+//|   and attached to a Service by calling `add_to_service()`.
+//|   Remote Characteristic objects are created by `Central.discover_remote_services()`
+//|   or `Peripheral.discover_remote_services()` as part of remote Services.
 //|
-//|   Create a new Characteristic object identified by the specified UUID.
+
+//|   .. method:: add_to_service(service, uuid, *, properties=0, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, initial_value=None)
+//|
+//|     Create a new Characteristic object, and add it to this Service.
 //|
-//|   :param bleio.UUID uuid: The uuid of the characteristic
-//|   :param int properties: bitmask of these values bitwise-or'd together: `BROADCAST`, `INDICATE`,
-//|     `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`
-//|   :param int read_perm: Specifies whether the characteristic can be read by a client, and if so, which
-//|      security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
-//|      `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
-//|      `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
-//|   :param int write_perm: Specifies whether the characteristic can be written by a client, and if so, which
-//|      security mode is required. Values allowed are the same as ``read_perm``.
-//|   :param int max_length: Maximum length in bytes of the characteristic value. The maximum allowed is
+//|     :param Service service: The service that will provide this characteristic
+//|     :param UUID uuid: The uuid of the characteristic
+//|     :param int properties: The properties of the characteristic,
+//|        specified as a bitmask of these values bitwise-or'd together:
+//|        `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`.
+//|     :param int read_perm: Specifies whether the characteristic can be read by a client, and if so, which
+//|        security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
+//|        `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
+//|        `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
+//|     :param int write_perm: Specifies whether the characteristic can be written by a client, and if so, which
+//|        security mode is required. Values allowed are the same as ``read_perm``.
+//|     :param int max_length: Maximum length in bytes of the characteristic value. The maximum allowed is
 //|      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 iterable descriptors: BLE descriptors for this characteristic.
+//|     :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
+//|      filled with zeros.
+//|
+//|     :return: the new Characteristic.
 //|
-STATIC mp_obj_t bleio_characteristic_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum { ARG_uuid, ARG_properties, ARG_read_perm, ARG_write_perm,
-           ARG_max_length, ARG_fixed_length, ARG_descriptors };
+STATIC mp_obj_t bleio_characteristic_add_to_service(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    // class is arg[0], which we can ignore.
+
+    enum { ARG_service, ARG_uuid, ARG_properties, ARG_read_perm, ARG_write_perm,
+           ARG_max_length, ARG_fixed_length, ARG_initial_value };
     static const mp_arg_t allowed_args[] = {
-        { MP_QSTR_uuid,  MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = mp_const_none} },
+        { MP_QSTR_service,  MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_uuid,  MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_properties, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = 0} },
         { MP_QSTR_read_perm, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = SECURITY_MODE_OPEN} },
         { MP_QSTR_write_perm, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = SECURITY_MODE_OPEN} },
         { MP_QSTR_max_length, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = 20} },
         { MP_QSTR_fixed_length, MP_ARG_KW_ONLY| MP_ARG_BOOL, {.u_bool = false} },
-        { MP_QSTR_descriptors, MP_ARG_KW_ONLY| MP_ARG_OBJ, {.u_obj = mp_const_none} },
+        { MP_QSTR_initial_value, MP_ARG_KW_ONLY| MP_ARG_OBJ, {.u_obj = mp_const_none} },
     };
 
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
-    mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
-    const mp_obj_t uuid_obj = args[ARG_uuid].u_obj;
+    const mp_obj_t service_obj = args[ARG_service].u_obj;
+    if (!MP_OBJ_IS_TYPE(service_obj, &bleio_service_type)) {
+        mp_raise_ValueError(translate("Expected a Service"));
+    }
 
+    const mp_obj_t uuid_obj = args[ARG_uuid].u_obj;
     if (!MP_OBJ_IS_TYPE(uuid_obj, &bleio_uuid_type)) {
         mp_raise_ValueError(translate("Expected a UUID"));
     }
-    bleio_uuid_obj_t *uuid = MP_OBJ_TO_PTR(uuid_obj);
 
     const bleio_characteristic_properties_t properties = args[ARG_properties].u_int;
     if (properties & ~CHAR_PROP_ALL) {
@@ -95,47 +113,45 @@ STATIC mp_obj_t bleio_characteristic_make_new(const mp_obj_type_t *type, size_t
     const bleio_attribute_security_mode_t write_perm = args[ARG_write_perm].u_int;
     common_hal_bleio_attribute_security_mode_check_valid(write_perm);
 
-    mp_obj_t descriptors = args[ARG_descriptors].u_obj;
-    if (descriptors == mp_const_none) {
-        descriptors = mp_const_empty_tuple;
-    }
-
-    bleio_characteristic_obj_t *self = m_new_obj(bleio_characteristic_obj_t);
-    self->base.type = &bleio_characteristic_type;
-
-    // Copy the descriptors list and validate its items.
-    mp_obj_t desc_list_obj = mp_obj_new_list(0, NULL);
-    mp_obj_list_t *desc_list = MP_OBJ_TO_PTR(desc_list_obj);
-
-    // If descriptors is not an iterable, an exception will be thrown.
-    mp_obj_iter_buf_t iter_buf;
-    mp_obj_t descriptors_iter = mp_getiter(descriptors, &iter_buf);
-
-    mp_obj_t descriptor_obj;
-    while ((descriptor_obj = mp_iternext(descriptors_iter)) != MP_OBJ_STOP_ITERATION) {
-        if (!MP_OBJ_IS_TYPE(descriptor_obj, &bleio_descriptor_type)) {
-            mp_raise_ValueError(translate("descriptors includes an object that is not a Descriptors"));
-        }
-        bleio_descriptor_obj_t *descriptor = MP_OBJ_TO_PTR(descriptor_obj);
-        if (common_hal_bleio_descriptor_get_characteristic(descriptor) != MP_OBJ_NULL) {
-            mp_raise_ValueError(translate("Descriptor is already attached to a Characteristic"));
+    const mp_int_t max_length = args[ARG_max_length].u_int;
+    const bool fixed_length =  args[ARG_fixed_length].u_bool;
+    mp_obj_t initial_value = args[ARG_initial_value].u_obj;
+
+    // Length will be validated in common_hal.
+    mp_buffer_info_t initial_value_bufinfo;
+    if (initial_value == mp_const_none) {
+        if (fixed_length && max_length > 0) {
+            initial_value = mp_obj_new_bytes_of_zeros(max_length);
+        } else {
+            initial_value = mp_const_empty_bytes;
         }
-        mp_obj_list_append(desc_list_obj, descriptor_obj);
     }
+    mp_get_buffer_raise(initial_value, &initial_value_bufinfo, MP_BUFFER_READ);
+
+    bleio_characteristic_obj_t *characteristic = m_new_obj(bleio_characteristic_obj_t);
+    characteristic->base.type = &bleio_characteristic_type;
 
     // Range checking on max_length arg is done by the common_hal layer, because
     // it may vary depending on underlying BLE implementation.
-    common_hal_bleio_characteristic_construct(self, uuid, properties,
-                                              read_perm, write_perm,
-                                              args[ARG_max_length].u_int, args[ARG_fixed_length].u_bool,
-                                              desc_list);
+    common_hal_bleio_characteristic_construct(
+        characteristic, MP_OBJ_TO_PTR(service_obj), MP_OBJ_TO_PTR(uuid_obj),
+        properties, read_perm, write_perm,
+        max_length, fixed_length, &initial_value_bufinfo);
+
+    common_hal_bleio_service_add_characteristic(service_obj, characteristic);
 
-    return MP_OBJ_FROM_PTR(self);
+    return MP_OBJ_FROM_PTR(characteristic);
 }
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_characteristic_add_to_service_fun_obj, 3, bleio_characteristic_add_to_service);
+STATIC MP_DEFINE_CONST_CLASSMETHOD_OBJ(bleio_characteristic_add_to_service_obj, MP_ROM_PTR(&bleio_characteristic_add_to_service_fun_obj));
+
+
 
 //|   .. attribute:: properties
 //|
-//|     An int bitmask representing which properties are set.
+//|     An int bitmask representing which properties are set, specified as bitwise or'ing of
+//|     of these possible values.
+//|     `BROADCAST`, `INDICATE`, `NOTIFY`, `READ`, `WRITE`, `WRITE_NO_RESPONSE`.
 //|
 STATIC mp_obj_t bleio_characteristic_get_properties(mp_obj_t self_in) {
     bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -203,7 +219,7 @@ const mp_obj_property_t bleio_characteristic_value_obj = {
 
 //|   .. attribute:: descriptors
 //|
-//|     A tuple of `bleio.Descriptor` that describe this characteristic. (read-only)
+//|     A tuple of :py:class:`Descriptor` that describe this characteristic. (read-only)
 //|
 STATIC mp_obj_t bleio_characteristic_get_descriptors(mp_obj_t self_in) {
     bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -222,7 +238,7 @@ const mp_obj_property_t bleio_characteristic_descriptors_obj = {
 
 //|   .. attribute:: service (read-only)
 //|
-//|     The Service this Characteristic is a part of. None if not yet assigned to a Service.
+//|     The Service this Characteristic is a part of.
 //|
 STATIC mp_obj_t bleio_characteristic_get_service(mp_obj_t self_in) {
     bleio_characteristic_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -265,10 +281,11 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_characteristic_set_cccd_obj, 1, bleio_ch
 
 
 STATIC const mp_rom_map_elem_t bleio_characteristic_locals_dict_table[] = {
-    { MP_ROM_QSTR(MP_QSTR_properties), MP_ROM_PTR(&bleio_characteristic_get_properties) },
-    { MP_ROM_QSTR(MP_QSTR_set_cccd),   MP_ROM_PTR(&bleio_characteristic_set_cccd_obj) },
-    { MP_ROM_QSTR(MP_QSTR_uuid),       MP_ROM_PTR(&bleio_characteristic_uuid_obj) },
-    { MP_ROM_QSTR(MP_QSTR_value),      MP_ROM_PTR(&bleio_characteristic_value_obj) },
+    { MP_ROM_QSTR(MP_QSTR_add_to_service), MP_ROM_PTR(&bleio_characteristic_add_to_service_obj) },
+    { MP_ROM_QSTR(MP_QSTR_properties),     MP_ROM_PTR(&bleio_characteristic_get_properties_obj) },
+    { MP_ROM_QSTR(MP_QSTR_uuid),           MP_ROM_PTR(&bleio_characteristic_uuid_obj) },
+    { MP_ROM_QSTR(MP_QSTR_value),          MP_ROM_PTR(&bleio_characteristic_value_obj) },
+    { MP_ROM_QSTR(MP_QSTR_set_cccd),       MP_ROM_PTR(&bleio_characteristic_set_cccd_obj) },
 
     // Bitmask constants to represent properties
 //|   .. data:: BROADCAST
@@ -319,7 +336,6 @@ STATIC void bleio_characteristic_print(const mp_print_t *print, mp_obj_t self_in
 const mp_obj_type_t bleio_characteristic_type = {
     { &mp_type_type },
     .name = MP_QSTR_Characteristic,
-    .make_new = bleio_characteristic_make_new,
     .print = bleio_characteristic_print,
     .locals_dict = (mp_obj_dict_t*)&bleio_characteristic_locals_dict,
 };
diff --git a/shared-bindings/bleio/Characteristic.h b/shared-bindings/_bleio/Characteristic.h
index 87942c8e9..a816c6050 100644
--- a/shared-bindings/bleio/Characteristic.h
+++ b/shared-bindings/_bleio/Characteristic.h
@@ -28,19 +28,22 @@
 #ifndef MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_CHARACTERISTIC_H
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_CHARACTERISTIC_H
 
-#include "shared-bindings/bleio/Attribute.h"
-#include "shared-module/bleio/Characteristic.h"
-#include "common-hal/bleio/Characteristic.h"
+#include "shared-bindings/_bleio/Attribute.h"
+#include "shared-bindings/_bleio/Descriptor.h"
+#include "shared-module/_bleio/Characteristic.h"
+#include "common-hal/_bleio/Characteristic.h"
+#include "common-hal/_bleio/Service.h"
 
 extern const mp_obj_type_t bleio_characteristic_type;
 
-extern void common_hal_bleio_characteristic_construct(bleio_characteristic_obj_t *self, bleio_uuid_obj_t *uuid, bleio_characteristic_properties_t props, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length, mp_obj_list_t *descriptor_list);
+extern void common_hal_bleio_characteristic_construct(bleio_characteristic_obj_t *self, bleio_service_obj_t *service, bleio_uuid_obj_t *uuid, bleio_characteristic_properties_t props, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length, mp_buffer_info_t *initial_value_bufinfo);
 extern mp_obj_t common_hal_bleio_characteristic_get_value(bleio_characteristic_obj_t *self);
 extern void common_hal_bleio_characteristic_set_value(bleio_characteristic_obj_t *self, mp_buffer_info_t *bufinfo);
 extern bleio_characteristic_properties_t common_hal_bleio_characteristic_get_properties(bleio_characteristic_obj_t *self);
 extern bleio_uuid_obj_t *common_hal_bleio_characteristic_get_uuid(bleio_characteristic_obj_t *self);
 extern mp_obj_list_t *common_hal_bleio_characteristic_get_descriptor_list(bleio_characteristic_obj_t *self);
 extern bleio_service_obj_t *common_hal_bleio_characteristic_get_service(bleio_characteristic_obj_t *self);
+extern void common_hal_bleio_characteristic_add_descriptor(bleio_characteristic_obj_t *self, bleio_descriptor_obj_t *descriptor);
 extern void common_hal_bleio_characteristic_set_cccd(bleio_characteristic_obj_t *self, bool notify, bool indicate);
 
 #endif // MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_CHARACTERISTIC_H
diff --git a/shared-bindings/bleio/CharacteristicBuffer.c b/shared-bindings/_bleio/CharacteristicBuffer.c
index 26f9e012b..9cc708eb7 100644
--- a/shared-bindings/bleio/CharacteristicBuffer.c
+++ b/shared-bindings/_bleio/CharacteristicBuffer.c
@@ -30,8 +30,8 @@
 #include "py/runtime.h"
 #include "py/stream.h"
 
-#include "shared-bindings/bleio/CharacteristicBuffer.h"
-#include "shared-bindings/bleio/UUID.h"
+#include "shared-bindings/_bleio/CharacteristicBuffer.h"
+#include "shared-bindings/_bleio/UUID.h"
 #include "shared-bindings/util.h"
 
 STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self) {
@@ -40,7 +40,7 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self
     }
 }
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`CharacteristicBuffer` -- BLE Service incoming values buffer.
 //| =====================================================================
@@ -52,7 +52,7 @@ STATIC void raise_error_if_not_connected(bleio_characteristic_buffer_obj_t *self
 //|   Monitor the given Characteristic. Each time a new value is written to the Characteristic
 //|   add the newly-written bytes to a FIFO buffer.
 //|
-//|   :param bleio.Characteristic characteristic: The Characteristic to monitor.
+//|   :param Characteristic characteristic: The Characteristic to monitor.
 //|     It may be a local Characteristic provided by a Peripheral Service, or a remote Characteristic
 //|     in a remote Service that a Central has connected to.
 //|   :param int timeout:  the timeout in seconds to wait for the first character and between subsequent characters.
diff --git a/shared-bindings/bleio/CharacteristicBuffer.h b/shared-bindings/_bleio/CharacteristicBuffer.h
index b45835ff3..83e6fef02 100644
--- a/shared-bindings/bleio/CharacteristicBuffer.h
+++ b/shared-bindings/_bleio/CharacteristicBuffer.h
@@ -27,7 +27,7 @@
 #ifndef MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_CHARACTERISTICBUFFER_H
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_CHARACTERISTICBUFFER_H
 
-#include "common-hal/bleio/CharacteristicBuffer.h"
+#include "common-hal/_bleio/CharacteristicBuffer.h"
 
 extern const mp_obj_type_t bleio_characteristic_buffer_type;
 
diff --git a/shared-bindings/bleio/Descriptor.c b/shared-bindings/_bleio/Descriptor.c
index d7c2a85c7..0ab9fe8e9 100644
--- a/shared-bindings/bleio/Descriptor.c
+++ b/shared-bindings/_bleio/Descriptor.c
@@ -28,52 +28,73 @@
 
 #include "py/objproperty.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/Attribute.h"
-#include "shared-bindings/bleio/Descriptor.h"
-#include "shared-bindings/bleio/UUID.h"
+#include "shared-bindings/_bleio/Attribute.h"
+#include "shared-bindings/_bleio/Characteristic.h"
+#include "shared-bindings/_bleio/Descriptor.h"
+#include "shared-bindings/_bleio/UUID.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Descriptor` -- BLE descriptor
 //| =========================================================
 //|
 //| Stores information about a BLE descriptor.
-//| Descriptors are encapsulated by BLE characteristics and provide contextual
+//| Descriptors are attached to BLE characteristics and provide contextual
 //| information about the characteristic.
 //|
-
-//| .. class:: Descriptor(uuid, *, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`)
+//| .. class:: Descriptor
+//|
+//|   There is no regular constructor for a Descriptor. A new local Descriptor can be created
+//|   and attached to a Characteristic by calling `add_to_characteristic()`.
+//|   Remote Descriptor objects are created by `Central.discover_remote_services()`
+//|   or `Peripheral.discover_remote_services()` as part of remote Characteristics
+//|   in the remote Services that are discovered.
+//|
+//|   .. classmethod:: add_to_characteristic(characteristic, uuid, *, read_perm=`Attribute.OPEN`, write_perm=`Attribute.OPEN`, max_length=20, fixed_length=False, initial_value=b'')
 //|
-//|   Create a new descriptor object with the UUID uuid
+//|     Create a new Descriptor object, and add it to this Service.
 //|
-//|   :param bleio.UUID uuid: The uuid of the descriptor
-//|   :param int read_perm: Specifies whether the descriptor can be read by a client, and if so, which
-//|      security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
-//|      `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
-//|      `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
-//|   :param int write_perm: Specifies whether the descriptor can be written by a client, and if so, which
-//|      security mode is required. Values allowed are the same as ``read_perm``.
-//|   :param int max_length: Maximum length in bytes of the characteristic value. The maximum allowed is
-//|      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 Characteristic characteristic: The characteristic that will hold this descriptor
+//|     :param UUID uuid: The uuid of the descriptor
+//|     :param int read_perm: Specifies whether the descriptor can be read by a client, and if so, which
+//|        security mode is required. Must be one of the integer values `Attribute.NO_ACCESS`, `Attribute.OPEN`,
+//|        `Attribute.ENCRYPT_NO_MITM`, `Attribute.ENCRYPT_WITH_MITM`, `Attribute.LESC_ENCRYPT_WITH_MITM`,
+//|        `Attribute.SIGNED_NO_MITM`, or `Attribute.SIGNED_WITH_MITM`.
+//|     :param int write_perm: Specifies whether the descriptor can be written by a client, and if so, which
+//|        security mode is required. Values allowed are the same as ``read_perm``.
+//|     :param int max_length: Maximum length in bytes of the descriptor value. The maximum allowed is
+//|        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.
 //|
-STATIC mp_obj_t bleio_descriptor_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum { ARG_uuid, ARG_read_perm, ARG_write_perm, ARG_max_length, ARG_fixed_length };
+//|     :return: the new Descriptor.
+//|
+STATIC mp_obj_t bleio_descriptor_add_to_characteristic(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    // class is arg[0], which we can ignore.
+
+    enum { ARG_characteristic, ARG_uuid, ARG_read_perm, ARG_write_perm,
+           ARG_max_length, ARG_fixed_length, ARG_initial_value };
     static const mp_arg_t allowed_args[] = {
-        { MP_QSTR_uuid, MP_ARG_REQUIRED | MP_ARG_OBJ },
-        { MP_QSTR_read_perm, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = SECURITY_MODE_OPEN } },
-        { MP_QSTR_write_perm, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = SECURITY_MODE_OPEN } },
+        { MP_QSTR_characteristic,  MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_uuid,  MP_ARG_REQUIRED | MP_ARG_OBJ },
+        { MP_QSTR_read_perm, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = SECURITY_MODE_OPEN} },
+        { MP_QSTR_write_perm, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = SECURITY_MODE_OPEN} },
         { MP_QSTR_max_length, MP_ARG_KW_ONLY| MP_ARG_INT, {.u_int = 20} },
         { MP_QSTR_fixed_length, MP_ARG_KW_ONLY| MP_ARG_BOOL, {.u_bool = false} },
+        { MP_QSTR_initial_value, MP_ARG_KW_ONLY| MP_ARG_OBJ, {.u_obj = mp_const_empty_bytes} },
     };
 
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
-    mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
-    const mp_obj_t uuid_arg = args[ARG_uuid].u_obj;
+    const mp_obj_t characteristic_obj = args[ARG_characteristic].u_obj;
+    if (!MP_OBJ_IS_TYPE(characteristic_obj, &bleio_characteristic_type)) {
+        mp_raise_ValueError(translate("Expected a Characteristic"));
+    }
 
-    if (!MP_OBJ_IS_TYPE(uuid_arg, &bleio_uuid_type)) {
+    const mp_obj_t uuid_obj = args[ARG_uuid].u_obj;
+    if (!MP_OBJ_IS_TYPE(uuid_obj, &bleio_uuid_type)) {
         mp_raise_ValueError(translate("Expected a UUID"));
     }
 
@@ -83,17 +104,37 @@ STATIC mp_obj_t bleio_descriptor_make_new(const mp_obj_type_t *type, size_t n_ar
     const bleio_attribute_security_mode_t write_perm = args[ARG_write_perm].u_int;
     common_hal_bleio_attribute_security_mode_check_valid(write_perm);
 
-    bleio_descriptor_obj_t *self = m_new_obj(bleio_descriptor_obj_t);
-    self->base.type = type;
-    bleio_uuid_obj_t *uuid = MP_OBJ_TO_PTR(uuid_arg);
+    const mp_int_t max_length = args[ARG_max_length].u_int;
+    const bool fixed_length =  args[ARG_fixed_length].u_bool;
+    mp_obj_t initial_value = args[ARG_initial_value].u_obj;
+
+    // Length will be validated in common_hal.
+    mp_buffer_info_t initial_value_bufinfo;
+    if (initial_value == mp_const_none) {
+        if (fixed_length && max_length > 0) {
+            initial_value = mp_obj_new_bytes_of_zeros(max_length);
+        } else {
+            initial_value = mp_const_empty_bytes;
+        }
+    }
+    mp_get_buffer_raise(initial_value, &initial_value_bufinfo, MP_BUFFER_READ);
+
+    bleio_descriptor_obj_t *descriptor = m_new_obj(bleio_descriptor_obj_t);
+    descriptor->base.type = &bleio_descriptor_type;
 
     // Range checking on max_length arg is done by the common_hal layer, because
     // it may vary depending on underlying BLE implementation.
-    common_hal_bleio_descriptor_construct(self, uuid, read_perm, write_perm,
-                                          args[ARG_max_length].u_int, args[ARG_fixed_length].u_bool);
+    common_hal_bleio_descriptor_construct(
+        descriptor, MP_OBJ_TO_PTR(characteristic_obj), MP_OBJ_TO_PTR(uuid_obj),
+        read_perm, write_perm,
+        max_length, fixed_length, &initial_value_bufinfo);
+
+    common_hal_bleio_characteristic_add_descriptor(characteristic_obj, descriptor);
 
-    return MP_OBJ_FROM_PTR(self);
+    return MP_OBJ_FROM_PTR(descriptor);
 }
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_descriptor_add_to_characteristic_fun_obj, 3, bleio_descriptor_add_to_characteristic);
+STATIC MP_DEFINE_CONST_CLASSMETHOD_OBJ(bleio_descriptor_add_to_characteristic_obj, MP_ROM_PTR(&bleio_descriptor_add_to_characteristic_fun_obj));
 
 //|   .. attribute:: uuid
 //|
@@ -116,7 +157,7 @@ const mp_obj_property_t bleio_descriptor_uuid_obj = {
 
 //|   .. attribute:: characteristic (read-only)
 //|
-//|     The Characteristic this Descriptor is a part of. None if not yet assigned to a Characteristic.
+//|     The Characteristic this Descriptor is a part of.
 //|
 STATIC mp_obj_t bleio_descriptor_get_characteristic(mp_obj_t self_in) {
     bleio_descriptor_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -163,7 +204,7 @@ const mp_obj_property_t bleio_descriptor_value_obj = {
 };
 
 STATIC const mp_rom_map_elem_t bleio_descriptor_locals_dict_table[] = {
-    // Properties
+    { MP_ROM_QSTR(MP_QSTR_add_to_characteristic), MP_ROM_PTR(&bleio_descriptor_add_to_characteristic_obj) },
     { MP_ROM_QSTR(MP_QSTR_uuid), MP_ROM_PTR(&bleio_descriptor_uuid_obj) },
     { MP_ROM_QSTR(MP_QSTR_characteristic), MP_ROM_PTR(&bleio_descriptor_characteristic_obj) },
     { MP_ROM_QSTR(MP_QSTR_value), MP_ROM_PTR(&bleio_descriptor_value_obj) },
@@ -185,7 +226,6 @@ STATIC void bleio_descriptor_print(const mp_print_t *print, mp_obj_t self_in, mp
 const mp_obj_type_t bleio_descriptor_type = {
     { &mp_type_type },
     .name = MP_QSTR_Descriptor,
-    .make_new = bleio_descriptor_make_new,
     .print = bleio_descriptor_print,
     .locals_dict = (mp_obj_dict_t*)&bleio_descriptor_locals_dict
 };
diff --git a/shared-bindings/bleio/Descriptor.h b/shared-bindings/_bleio/Descriptor.h
index 430c0d0b6..7544bdb17 100644
--- a/shared-bindings/bleio/Descriptor.h
+++ b/shared-bindings/_bleio/Descriptor.h
@@ -28,13 +28,14 @@
 #ifndef MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_DESCRIPTOR_H
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_DESCRIPTOR_H
 
-#include "shared-module/bleio/Attribute.h"
-#include "common-hal/bleio/Descriptor.h"
-#include "common-hal/bleio/UUID.h"
+#include "shared-module/_bleio/Attribute.h"
+#include "common-hal/_bleio/Characteristic.h"
+#include "common-hal/_bleio/Descriptor.h"
+#include "common-hal/_bleio/UUID.h"
 
 extern const mp_obj_type_t bleio_descriptor_type;
 
-extern void common_hal_bleio_descriptor_construct(bleio_descriptor_obj_t *self, bleio_uuid_obj_t *uuid, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length);
+extern void common_hal_bleio_descriptor_construct(bleio_descriptor_obj_t *self, bleio_characteristic_obj_t *characteristic, bleio_uuid_obj_t *uuid, bleio_attribute_security_mode_t read_perm, bleio_attribute_security_mode_t write_perm, mp_int_t max_length, bool fixed_length, mp_buffer_info_t *initial_value_bufinfo);
 extern bleio_uuid_obj_t *common_hal_bleio_descriptor_get_uuid(bleio_descriptor_obj_t *self);
 extern bleio_characteristic_obj_t *common_hal_bleio_descriptor_get_characteristic(bleio_descriptor_obj_t *self);
 extern mp_obj_t common_hal_bleio_descriptor_get_value(bleio_descriptor_obj_t *self);
diff --git a/shared-bindings/bleio/Peripheral.c b/shared-bindings/_bleio/Peripheral.c
index 630e6ed36..0bf292744 100644
--- a/shared-bindings/bleio/Peripheral.c
+++ b/shared-bindings/_bleio/Peripheral.c
@@ -35,22 +35,23 @@
 #include "py/objstr.h"
 #include "py/runtime.h"
 
-#include "shared-bindings/bleio/Adapter.h"
-#include "shared-bindings/bleio/Characteristic.h"
-#include "shared-bindings/bleio/Peripheral.h"
-#include "shared-bindings/bleio/Service.h"
-#include "shared-bindings/bleio/UUID.h"
-#include "shared-module/bleio/ScanEntry.h"
+#include "shared-bindings/_bleio/Adapter.h"
+#include "shared-bindings/_bleio/Characteristic.h"
+#include "shared-bindings/_bleio/Peripheral.h"
+#include "shared-bindings/_bleio/Service.h"
+#include "shared-bindings/_bleio/UUID.h"
+#include "shared-module/_bleio/ScanEntry.h"
 
-#include "common-hal/bleio/Peripheral.h"
+#include "common-hal/_bleio/Peripheral.h"
 
-#define ADV_INTERVAL_DEFAULT (1.0f)
 #define ADV_INTERVAL_MIN (0.0020f)
 #define ADV_INTERVAL_MIN_STRING "0.0020"
 #define ADV_INTERVAL_MAX (10.24f)
 #define ADV_INTERVAL_MAX_STRING "10.24"
+// 20ms is recommended by Apple
+#define ADV_INTERVAL_DEFAULT (0.1f)
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Peripheral` -- A BLE peripheral device
 //| =========================================================
@@ -60,70 +61,53 @@
 //|
 //| Usage::
 //|
-//|    import bleio
+//|    from _bleio import Characteristic, Peripheral, Service
 //|    from adafruit_ble.advertising import ServerAdvertisement
 //|
-//|    # Create a Characteristic.
-//|    chara = bleio.Characteristic(bleio.UUID(0x2919), read=True, notify=True)
+//|    # Create a peripheral and start it up.
+//|    peripheral = _bleio.Peripheral()
 //|
-//|    # Create a Service providing that one Characteristic.
-//|    serv = bleio.Service(bleio.UUID(0x180f), [chara])
+//|    # Create a Service and add it to this Peripheral.
+//|    service = Service.add_to_peripheral(peripheral, _bleio.UUID(0x180f))
 //|
-//|    # Create a peripheral and start it up.
-//|    periph = bleio.Peripheral([serv])
-//|    adv = ServerAdvertisement(periph)
-//|    periph.start_advertising(adv.advertising_data_bytes, adv.scan_response_bytes)
+//|    # Create a Characteristic and add it to the Service.
+//|    characteristic = Characteristic.add_to_service(service,
+//|        _bleio.UUID(0x2919), properties=Characteristic.READ | Characteristic.NOTIFY)
 //|
-//|    while not periph.connected:
+//|    adv = ServerAdvertisement(peripheral)
+//|    peripheral.start_advertising(adv.advertising_data_bytes, scan_response=adv.scan_response_bytes)
+//|
+//|    while not peripheral.connected:
 //|        # Wait for connection.
 //|        pass
 //|
-//| .. class:: Peripheral(services=(), \*, name=None)
+//| .. class:: Peripheral(name=None)
 //|
 //|   Create a new Peripheral object.
 //|
-//|   :param iterable services: the Service objects representing services available from this peripheral, if any.
-//|     A non-connectable peripheral will have no services.
 //|   :param str name: The name used when advertising this peripheral. If name is None,
-//|     bleio.adapter.default_name will be used.
+//|     _bleio.adapter.default_name will be used.
 //|
 STATIC mp_obj_t bleio_peripheral_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum { ARG_services, ARG_name };
+    enum { ARG_name };
     static const mp_arg_t allowed_args[] = {
-        { MP_QSTR_services, MP_ARG_OBJ, {.u_obj = mp_const_empty_tuple} },
-        { MP_QSTR_name, MP_ARG_OBJ | MP_ARG_KW_ONLY, {.u_obj = MP_OBJ_NULL} },
+        { MP_QSTR_name, MP_ARG_OBJ, {.u_obj = mp_const_none} },
     };
 
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
     mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
-    // If services is not an iterable, an exception will be thrown.
-    mp_obj_iter_buf_t iter_buf;
-    mp_obj_t iterable = mp_getiter(args[ARG_services].u_obj, &iter_buf);
-
     bleio_peripheral_obj_t *self = m_new_obj(bleio_peripheral_obj_t);
     self->base.type = &bleio_peripheral_type;
 
-    // Copy the services list and validate its items.
-    mp_obj_t services_list_obj = mp_obj_new_list(0, NULL);
-    mp_obj_list_t *services_list = MP_OBJ_FROM_PTR(services_list_obj);
-
-    mp_obj_t service;
-    while ((service = mp_iternext(iterable)) != MP_OBJ_STOP_ITERATION) {
-        if (!MP_OBJ_IS_TYPE(service, &bleio_service_type)) {
-            mp_raise_ValueError(translate("non-Service found in services"));
-        }
-        mp_obj_list_append(services_list, service);
-    }
-
     mp_obj_t name = args[ARG_name].u_obj;
-    if (name == MP_OBJ_NULL || name == mp_const_none) {
+    if (name == mp_const_none) {
         name = common_hal_bleio_adapter_get_default_name();
     } else if (!MP_OBJ_IS_STR(name)) {
         mp_raise_ValueError(translate("name must be a string"));
     }
 
-    common_hal_bleio_peripheral_construct(self, services_list, name);
+    common_hal_bleio_peripheral_construct(self, name);
 
     return MP_OBJ_FROM_PTR(self);
 }
@@ -148,7 +132,7 @@ const mp_obj_property_t bleio_peripheral_connected_obj = {
 
 //|   .. attribute:: services
 //|
-//|     A `tuple` of `bleio.Service` that are offered by this peripheral. (read-only)
+//|     A tuple of :py:class:`Service` objects offered by this peripheral. (read-only)
 //|
 STATIC mp_obj_t bleio_peripheral_get_services(mp_obj_t self_in) {
     bleio_peripheral_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -183,7 +167,7 @@ const mp_obj_property_t bleio_peripheral_name_obj = {
                (mp_obj_t)&mp_const_none_obj },
 };
 
-//|   .. method:: start_advertising(data, *, scan_response=None, connectable=True, interval=1)
+//|   .. method:: start_advertising(data, *, scan_response=None, connectable=True, interval=0.1)
 //|
 //|     Starts advertising the peripheral. The peripheral's name and
 //|     services are included in the advertisement packets.
@@ -217,7 +201,7 @@ STATIC mp_obj_t bleio_peripheral_start_advertising(mp_uint_t n_args, const mp_ob
     }
 
     if (args[ARG_interval].u_obj == MP_OBJ_NULL) {
-        args[ARG_interval].u_obj = mp_obj_new_float(1.0F);
+        args[ARG_interval].u_obj = mp_obj_new_float(ADV_INTERVAL_DEFAULT);
     }
 
     const mp_float_t interval = mp_obj_float_get(args[ARG_interval].u_obj);
@@ -323,7 +307,7 @@ STATIC const mp_rom_map_elem_t bleio_peripheral_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_stop_advertising),         MP_ROM_PTR(&bleio_peripheral_stop_advertising_obj) },
     { MP_ROM_QSTR(MP_QSTR_disconnect),               MP_ROM_PTR(&bleio_peripheral_disconnect_obj) },
     { MP_ROM_QSTR(MP_QSTR_discover_remote_services), MP_ROM_PTR(&bleio_peripheral_discover_remote_services_obj) },
-    { MP_ROM_QSTR(MP_QSTR_pair)                    , MP_ROM_PTR(&bleio_peripheral_pair_obj) },
+    { MP_ROM_QSTR(MP_QSTR_pair),                     MP_ROM_PTR(&bleio_peripheral_pair_obj) },
 
     // Properties
     { MP_ROM_QSTR(MP_QSTR_connected),       MP_ROM_PTR(&bleio_peripheral_connected_obj) },
diff --git a/shared-bindings/bleio/Peripheral.h b/shared-bindings/_bleio/Peripheral.h
index 597b65ce2..bc56a9338 100644
--- a/shared-bindings/bleio/Peripheral.h
+++ b/shared-bindings/_bleio/Peripheral.h
@@ -29,11 +29,13 @@
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_PERIPHERAL_H
 
 #include "py/objtuple.h"
-#include "common-hal/bleio/Peripheral.h"
+#include "common-hal/_bleio/Peripheral.h"
+#include "common-hal/_bleio/Service.h"
 
 extern const mp_obj_type_t bleio_peripheral_type;
 
-extern void common_hal_bleio_peripheral_construct(bleio_peripheral_obj_t *self, mp_obj_list_t *service_list, mp_obj_t name);
+extern void common_hal_bleio_peripheral_construct(bleio_peripheral_obj_t *self, mp_obj_t name);
+extern void common_hal_bleio_peripheral_add_service(bleio_peripheral_obj_t *self, bleio_service_obj_t *service);
 extern mp_obj_list_t *common_hal_bleio_peripheral_get_services(bleio_peripheral_obj_t *self);
 extern bool common_hal_bleio_peripheral_get_connected(bleio_peripheral_obj_t *self);
 extern mp_obj_t common_hal_bleio_peripheral_get_name(bleio_peripheral_obj_t *self);
diff --git a/shared-bindings/bleio/ScanEntry.c b/shared-bindings/_bleio/ScanEntry.c
index 6eb02c716..bec380d03 100644
--- a/shared-bindings/bleio/ScanEntry.c
+++ b/shared-bindings/_bleio/ScanEntry.c
@@ -29,24 +29,24 @@
 #include <string.h>
 
 #include "py/objproperty.h"
-#include "shared-bindings/bleio/Address.h"
-#include "shared-bindings/bleio/ScanEntry.h"
-#include "shared-bindings/bleio/UUID.h"
-#include "shared-module/bleio/ScanEntry.h"
+#include "shared-bindings/_bleio/Address.h"
+#include "shared-bindings/_bleio/ScanEntry.h"
+#include "shared-bindings/_bleio/UUID.h"
+#include "shared-module/_bleio/ScanEntry.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`ScanEntry` -- BLE scan response entry
 //| =========================================================
 //|
 //| Encapsulates information about a device that was received as a
 //| response to a BLE scan request. This object may only be created
-//| by a `bleio.Scanner`: it has no user-visible constructor.
+//| by a `_bleio.Scanner`: it has no user-visible constructor.
 //|
 
 //|   .. attribute:: address
 //|
-//|   The address of the device (read-only), of type `bleio.Address`.
+//|   The address of the device (read-only), of type `_bleio.Address`.
 //|
 STATIC mp_obj_t bleio_scanentry_get_address(mp_obj_t self_in) {
     bleio_scanentry_obj_t *self = MP_OBJ_TO_PTR(self_in);
diff --git a/shared-bindings/bleio/ScanEntry.h b/shared-bindings/_bleio/ScanEntry.h
index 77e93175f..8af1f050a 100644
--- a/shared-bindings/bleio/ScanEntry.h
+++ b/shared-bindings/_bleio/ScanEntry.h
@@ -30,7 +30,7 @@
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_SCANENTRY_H
 
 #include "py/obj.h"
-#include "shared-module/bleio/ScanEntry.h"
+#include "shared-module/_bleio/ScanEntry.h"
 
 extern const mp_obj_type_t bleio_scanentry_type;
 
diff --git a/shared-bindings/bleio/Scanner.c b/shared-bindings/_bleio/Scanner.c
index 269c42591..94cec9752 100644
--- a/shared-bindings/bleio/Scanner.c
+++ b/shared-bindings/_bleio/Scanner.c
@@ -27,8 +27,8 @@
 
 #include "py/objproperty.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/ScanEntry.h"
-#include "shared-bindings/bleio/Scanner.h"
+#include "shared-bindings/_bleio/ScanEntry.h"
+#include "shared-bindings/_bleio/Scanner.h"
 
 #define INTERVAL_DEFAULT (0.1f)
 #define INTERVAL_MIN (0.0025f)
@@ -37,7 +37,7 @@
 #define INTERVAL_MAX_STRING "40.959375"
 #define WINDOW_DEFAULT (0.1f)
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Scanner` -- scan for nearby BLE devices
 //| =========================================================
@@ -46,8 +46,8 @@
 //|
 //| Usage::
 //|
-//|    import bleio
-//|    scanner = bleio.Scanner()
+//|    import _bleio
+//|    scanner = _bleio.Scanner()
 //|    entries = scanner.scan(2.5)  # Scan for 2.5 seconds
 //|
 
diff --git a/shared-bindings/bleio/Scanner.h b/shared-bindings/_bleio/Scanner.h
index 3a0ce7eae..cbaa77866 100644
--- a/shared-bindings/bleio/Scanner.h
+++ b/shared-bindings/_bleio/Scanner.h
@@ -29,7 +29,7 @@
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_SCANNER_H
 
 #include "py/objtype.h"
-#include "common-hal/bleio/Scanner.h"
+#include "common-hal/_bleio/Scanner.h"
 
 extern const mp_obj_type_t bleio_scanner_type;
 
diff --git a/shared-bindings/bleio/Service.c b/shared-bindings/_bleio/Service.c
index 6961b0b52..da5633f2a 100644
--- a/shared-bindings/bleio/Service.c
+++ b/shared-bindings/_bleio/Service.c
@@ -28,88 +28,79 @@
 
 #include "py/objproperty.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/Characteristic.h"
-#include "shared-bindings/bleio/Service.h"
-#include "shared-bindings/bleio/UUID.h"
+#include "shared-bindings/_bleio/Characteristic.h"
+#include "shared-bindings/_bleio/Peripheral.h"
+#include "shared-bindings/_bleio/Service.h"
+#include "shared-bindings/_bleio/UUID.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`Service` -- BLE service
 //| =========================================================
 //|
 //| Stores information about a BLE service and its characteristics.
 //|
-
-//| .. class:: Service(uuid, characteristics, *, secondary=False)
+//| .. class:: Service
+//|
+//|   There is no regular constructor for a Service. A new local Service can be created
+//|   and attached to a Peripheral by calling `add_to_peripheral()`.
+//|   Remote Service objects are created by `Central.discover_remote_services()`
+//|   or `Peripheral.discover_remote_services()`.
 //|
-//|   Create a new Service object identified by the specified UUID.
+//|   .. classmethod:: add_to_peripheral(peripheral, uuid, *, secondary=False)
 //|
-//|   To mark the service as secondary, pass `True` as :py:data:`secondary`.
+//|     Create a new Service object, identitied by the specified UUID, and add it
+//|     to the given Peripheral.
 //|
-//|   :param bleio.UUID uuid: The uuid of the service
-//|   :param iterable characteristics: the Characteristic objects for this service
-//|   :param bool secondary: If the service is a secondary one
+//|     To mark the service as secondary, pass `True` as :py:data:`secondary`.
 //|
-//|   A Service may be remote (:py:data:`remote` is ``True``), but a remote Service
-//|   cannot be constructed directly. It is created by `Central.discover_remote_services()`
-//|   or `Peripheral.discover_remote_services()`.
+//|     :param Peripheral peripheral: The peripheral that will provide this service
+//|     :param UUID uuid: The uuid of the service
+//|     :param bool secondary: If the service is a secondary one
+//
+//|     :return: the new Service
+//|
+STATIC mp_obj_t bleio_service_add_to_peripheral(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    // class is arg[0], which we can ignore.
 
-STATIC mp_obj_t bleio_service_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
-    enum { ARG_uuid, ARG_characteristics, ARG_secondary };
+    enum { ARG_peripheral, ARG_uuid, ARG_secondary };
     static const mp_arg_t allowed_args[] = {
-        { MP_QSTR_uuid, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = mp_const_none} },
-        { MP_QSTR_characteristics, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = mp_const_none} },
+        { MP_QSTR_peripheral, MP_ARG_REQUIRED | MP_ARG_OBJ,},
+        { MP_QSTR_uuid, MP_ARG_REQUIRED | MP_ARG_OBJ },
         { MP_QSTR_secondary, MP_ARG_KW_ONLY | MP_ARG_BOOL, {.u_bool = false} },
     };
 
     mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
-    mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+    mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
 
-    const mp_obj_t uuid_obj = args[ARG_uuid].u_obj;
+    const mp_obj_t peripheral_obj = args[ARG_peripheral].u_obj;
+    if (!MP_OBJ_IS_TYPE(peripheral_obj, &bleio_peripheral_type)) {
+        mp_raise_ValueError(translate("Expected a Peripheral"));
+    }
 
+    const mp_obj_t uuid_obj = args[ARG_uuid].u_obj;
     if (!MP_OBJ_IS_TYPE(uuid_obj, &bleio_uuid_type)) {
         mp_raise_ValueError(translate("Expected a UUID"));
     }
 
-    bleio_service_obj_t *self = m_new_obj(bleio_service_obj_t);
-    self->base.type = &bleio_service_type;
-
     const bool is_secondary = args[ARG_secondary].u_bool;
-    bleio_uuid_obj_t *uuid = MP_OBJ_TO_PTR(uuid_obj);
-
-    // If characteristics is not an iterable, an exception will be thrown.
-    mp_obj_iter_buf_t iter_buf;
-    mp_obj_t iterable = mp_getiter(args[ARG_characteristics].u_obj, &iter_buf);
-    mp_obj_t characteristic_obj;
-
-    // Copy the characteristics list and validate its items.
-    mp_obj_t char_list_obj = mp_obj_new_list(0, NULL);
-    mp_obj_list_t *char_list = MP_OBJ_TO_PTR(char_list_obj);
-
-    while ((characteristic_obj = mp_iternext(iterable)) != MP_OBJ_STOP_ITERATION) {
-        if (!MP_OBJ_IS_TYPE(characteristic_obj, &bleio_characteristic_type)) {
-            mp_raise_ValueError(translate("characteristics includes an object that is not a Characteristic"));
-        }
-        bleio_characteristic_obj_t *characteristic = MP_OBJ_TO_PTR(characteristic_obj);
-        if (common_hal_bleio_uuid_get_uuid128_reference(uuid) !=
-            common_hal_bleio_uuid_get_uuid128_reference(characteristic->uuid)) {
-            // The descriptor base UUID doesn't match the characteristic base UUID.
-            mp_raise_ValueError(translate("Characteristic UUID doesn't match Service UUID"));
-        }
-        if (common_hal_bleio_characteristic_get_service(characteristic) != MP_OBJ_NULL) {
-            mp_raise_ValueError(translate("Characteristic is already attached to a Service"));
-        }
-        mp_obj_list_append(char_list_obj, characteristic_obj);
-    }
 
-    common_hal_bleio_service_construct(self, uuid, char_list, is_secondary);
+    bleio_service_obj_t *service = m_new_obj(bleio_service_obj_t);
+    service->base.type = &bleio_service_type;
 
-    return MP_OBJ_FROM_PTR(self);
+    common_hal_bleio_service_construct(
+        service, MP_OBJ_TO_PTR(peripheral_obj), MP_OBJ_TO_PTR(uuid_obj), is_secondary);
+
+    common_hal_bleio_peripheral_add_service(peripheral_obj, service);
+
+    return MP_OBJ_FROM_PTR(service);
 }
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bleio_service_add_to_peripheral_fun_obj, 3, bleio_service_add_to_peripheral);
+STATIC MP_DEFINE_CONST_CLASSMETHOD_OBJ(bleio_service_add_to_peripheral_obj, MP_ROM_PTR(&bleio_service_add_to_peripheral_fun_obj));
 
 //|   .. attribute:: characteristics
 //|
-//|     A tuple of `bleio.Characteristic` that are offered by this service. (read-only)
+//|     A tuple of :py:class:`Characteristic` designating the characteristics that are offered by this service. (read-only)
 //|
 STATIC mp_obj_t bleio_service_get_characteristics(mp_obj_t self_in) {
     bleio_service_obj_t *self = MP_OBJ_TO_PTR(self_in);
@@ -182,10 +173,12 @@ const mp_obj_property_t bleio_service_uuid_obj = {
                (mp_obj_t)&mp_const_none_obj },
 };
 
+
 STATIC const mp_rom_map_elem_t bleio_service_locals_dict_table[] = {
-    { MP_ROM_QSTR(MP_QSTR_characteristics),    MP_ROM_PTR(&bleio_service_characteristics_obj) },
-    { MP_ROM_QSTR(MP_QSTR_secondary),          MP_ROM_PTR(&bleio_service_secondary_obj) },
-    { MP_ROM_QSTR(MP_QSTR_uuid),               MP_ROM_PTR(&bleio_service_uuid_obj) },
+    { MP_ROM_QSTR(MP_QSTR_add_to_peripheral), MP_ROM_PTR(&bleio_service_add_to_peripheral_obj) },
+    { MP_ROM_QSTR(MP_QSTR_characteristics),   MP_ROM_PTR(&bleio_service_characteristics_obj) },
+    { MP_ROM_QSTR(MP_QSTR_secondary),         MP_ROM_PTR(&bleio_service_secondary_obj) },
+    { MP_ROM_QSTR(MP_QSTR_uuid),              MP_ROM_PTR(&bleio_service_uuid_obj) },
 };
 STATIC MP_DEFINE_CONST_DICT(bleio_service_locals_dict, bleio_service_locals_dict_table);
 
@@ -203,7 +196,6 @@ STATIC void bleio_service_print(const mp_print_t *print, mp_obj_t self_in, mp_pr
 const mp_obj_type_t bleio_service_type = {
     { &mp_type_type },
     .name = MP_QSTR_Service,
-    .make_new = bleio_service_make_new,
     .print = bleio_service_print,
     .locals_dict = (mp_obj_dict_t*)&bleio_service_locals_dict
 };
diff --git a/shared-bindings/bleio/Service.h b/shared-bindings/_bleio/Service.h
index 716c2e8a9..e061bcffc 100644
--- a/shared-bindings/bleio/Service.h
+++ b/shared-bindings/_bleio/Service.h
@@ -28,15 +28,16 @@
 #ifndef MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_SERVICE_H
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_SERVICE_H
 
-#include "common-hal/bleio/Service.h"
+#include "common-hal/_bleio/Peripheral.h"
+#include "common-hal/_bleio/Service.h"
 
 const mp_obj_type_t bleio_service_type;
 
-extern void common_hal_bleio_service_construct(bleio_service_obj_t *self, bleio_uuid_obj_t *uuid, mp_obj_list_t *characteristic_list, bool is_secondary);
+extern void common_hal_bleio_service_construct(bleio_service_obj_t *self, bleio_peripheral_obj_t *peripheral, bleio_uuid_obj_t *uuid, bool is_secondary);
 extern bleio_uuid_obj_t *common_hal_bleio_service_get_uuid(bleio_service_obj_t *self);
 extern mp_obj_list_t *common_hal_bleio_service_get_characteristic_list(bleio_service_obj_t *self);
 extern bool common_hal_bleio_service_get_is_remote(bleio_service_obj_t *self);
 extern bool common_hal_bleio_service_get_is_secondary(bleio_service_obj_t *self);
-extern void common_hal_bleio_service_add_all_characteristics(bleio_service_obj_t *self);
+extern void common_hal_bleio_service_add_characteristic(bleio_service_obj_t *self, bleio_characteristic_obj_t *characteristic);
 
 #endif // MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_SERVICE_H
diff --git a/shared-bindings/bleio/UUID.c b/shared-bindings/_bleio/UUID.c
index dca7ea010..3c0889aad 100644
--- a/shared-bindings/bleio/UUID.c
+++ b/shared-bindings/_bleio/UUID.c
@@ -31,9 +31,9 @@
 #include "py/objproperty.h"
 #include "py/objstr.h"
 #include "py/runtime.h"
-#include "shared-bindings/bleio/UUID.h"
+#include "shared-bindings/_bleio/UUID.h"
 
-//| .. currentmodule:: bleio
+//| .. currentmodule:: _bleio
 //|
 //| :class:`UUID` -- BLE UUID
 //| =========================================================
diff --git a/shared-bindings/bleio/UUID.h b/shared-bindings/_bleio/UUID.h
index caf039aec..46ac54ff3 100644
--- a/shared-bindings/bleio/UUID.h
+++ b/shared-bindings/_bleio/UUID.h
@@ -28,7 +28,7 @@
 #ifndef MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_UUID_H
 #define MICROPY_INCLUDED_SHARED_BINDINGS_BLEIO_UUID_H
 
-#include "common-hal/bleio/UUID.h"
+#include "common-hal/_bleio/UUID.h"
 
 void bleio_uuid_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind);
 
diff --git a/shared-bindings/bleio/__init__.c b/shared-bindings/_bleio/__init__.c
index 739f461a5..f207be8cf 100644
--- a/shared-bindings/bleio/__init__.c
+++ b/shared-bindings/_bleio/__init__.c
@@ -26,30 +26,33 @@
  * THE SOFTWARE.
  */
 
-#include "shared-bindings/bleio/__init__.h"
-#include "shared-bindings/bleio/Address.h"
-#include "shared-bindings/bleio/Attribute.h"
-#include "shared-bindings/bleio/Central.h"
-#include "shared-bindings/bleio/Characteristic.h"
-#include "shared-bindings/bleio/CharacteristicBuffer.h"
-#include "shared-bindings/bleio/Descriptor.h"
-#include "shared-bindings/bleio/Peripheral.h"
-#include "shared-bindings/bleio/ScanEntry.h"
-#include "shared-bindings/bleio/Scanner.h"
-#include "shared-bindings/bleio/Service.h"
-#include "shared-bindings/bleio/UUID.h"
+#include "shared-bindings/_bleio/__init__.h"
+#include "shared-bindings/_bleio/Address.h"
+#include "shared-bindings/_bleio/Attribute.h"
+#include "shared-bindings/_bleio/Central.h"
+#include "shared-bindings/_bleio/Characteristic.h"
+#include "shared-bindings/_bleio/CharacteristicBuffer.h"
+#include "shared-bindings/_bleio/Descriptor.h"
+#include "shared-bindings/_bleio/Peripheral.h"
+#include "shared-bindings/_bleio/ScanEntry.h"
+#include "shared-bindings/_bleio/Scanner.h"
+#include "shared-bindings/_bleio/Service.h"
+#include "shared-bindings/_bleio/UUID.h"
 
-//| :mod:`bleio` --- Bluetooth Low Energy (BLE) communication
+//| :mod:`_bleio` --- Bluetooth Low Energy (BLE) communication
 //| ================================================================
 //|
-//| .. module:: bleio
+//| .. module:: _bleio
 //|   :synopsis: Bluetooth Low Energy functionality
 //|   :platform: nRF
 //|
-//| The `bleio` module provides necessary low-level functionality for communicating
-//| using Bluetooth Low Energy (BLE). We recommend you use `bleio` in conjunction
-//| with the `adafruit_ble <https://circuitpython.readthedocs.io/projects/ble/en/latest/>`_
-//| CircuitPython library, which builds on `bleio`, and
+//| 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
+//| between minor versions of CircuitPython.
+//| Please use the
+//| `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.
 //|
@@ -75,11 +78,11 @@
 //|
 //|   BLE Adapter information, such as enabled state as well as MAC
 //|   address.
-//|   This object is the sole instance of `bleio.Adapter`.
+//|   This object is the sole instance of `_bleio.Adapter`.
 //|
 
 STATIC const mp_rom_map_elem_t bleio_module_globals_table[] = {
-    { MP_ROM_QSTR(MP_QSTR___name__),             MP_ROM_QSTR(MP_QSTR_bleio) },
+    { MP_ROM_QSTR(MP_QSTR___name__),             MP_ROM_QSTR(MP_QSTR__bleio) },
     { MP_ROM_QSTR(MP_QSTR_Address),              MP_ROM_PTR(&bleio_address_type) },
     { MP_ROM_QSTR(MP_QSTR_Attribute),            MP_ROM_PTR(&bleio_attribute_type) },
     { MP_ROM_QSTR(MP_QSTR_Central),              MP_ROM_PTR(&bleio_central_type) },
diff --git a/shared-bindings/bleio/__init__.h b/shared-bindings/_bleio/__init__.h
index 6a4c804f5..67379ae2e 100644
--- a/shared-bindings/bleio/__init__.h
+++ b/shared-bindings/_bleio/__init__.h
@@ -31,17 +31,17 @@
 
 #include "py/objlist.h"
 
-#include "shared-bindings/bleio/__init__.h"
-#include "shared-bindings/bleio/Adapter.h"
+#include "shared-bindings/_bleio/Adapter.h"
 
-#include "common-hal/bleio/Adapter.h"
+#include "common-hal/_bleio/__init__.h"
+#include "common-hal/_bleio/Adapter.h"
 
 extern const super_adapter_obj_t common_hal_bleio_adapter_obj;
 
 extern void common_hal_bleio_check_connected(uint16_t conn_handle);
 
 extern uint16_t common_hal_bleio_device_get_conn_handle(mp_obj_t device);
-extern mp_obj_list_t *common_hal_bleio_device_get_remote_services_list(mp_obj_t device);
+extern mp_obj_list_t *common_hal_bleio_device_get_remote_service_list(mp_obj_t device);
 extern void common_hal_bleio_device_discover_remote_services(mp_obj_t device, mp_obj_t service_uuids_whitelist);
 
 extern mp_obj_t common_hal_bleio_gatts_read(uint16_t handle, uint16_t conn_handle);