Rework the API to use descriptors.

This makes Advertisement and Service definitions declarative by
factoring out parsing logic out into shareable descriptor classes
similar to how the Register library works.

This also introduces SmartAdapter and SmartConnection which will
auto-create the correct Advertisements and Services without requiring
any direct use of UUIDs. Instead, classes are used to identify
relevant objects to "recognize".

This requires adafruit/circuitpython#2236 and
relates to adafruit/circuitpython#586.

Author: tannewt

.gitignore

@@ -4,3 +4,4 @@ _build
 .env
 build*
 bundles
+.DS_Store

.travis.yml

@@ -17,10 +17,10 @@ deploy:
 install:
 - pip install -r requirements.txt
 - pip install circuitpython-build-tools Sphinx sphinx-rtd-theme
-- pip install --force-reinstall pylint==1.9.2
+- pip install --force-reinstall "pylint<3"
 
 script:
-- pylint adafruit_ble/*.py
+- pylint --disable=too-few-public-methods adafruit_ble/**/*.py adafruit_ble/*.py
 - ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace
   examples/*.py)
 - circuitpython-build-bundles --filename_prefix adafruit-circuitpython-ble

README.rst

@@ -31,16 +31,18 @@ Usage Example
 
 .. code-block:: python
 
-    from adafruit_ble.uart import UARTServer
-
-    uart_server = UARTServer()
-    uart_server.start_advertising()
-
-    # Wait for a connection.
-    while not uart_server.connected:
-        pass
-
-    uart_server.write('abc')
+    from adafruit_ble import SmartAdapter
+
+    adapter = SmartAdapter()
+    print("scanning")
+    found = set()
+    for entry in adapter.start_scan(timeout=60, minimum_rssi=-80):
+        addr = entry.address
+        if addr not in found:
+            print(entry)
+        found.add(addr)
+
+    print("scan done")
 
 
 Contributing

adafruit_ble/__init__.py

@@ -1,6 +1,7 @@
 # The MIT License (MIT)
 #
 # Copyright (c) 2019 Dan Halbert for Adafruit Industries
+# Copyright (c) 2019 Scott Shawcroft for Adafruit Industries
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -26,7 +27,7 @@
 This module provides higher-level BLE (Bluetooth Low Energy) functionality,
 building on the native `_bleio` module.
 
-* Author(s): Dan Halbert for Adafruit Industries
+* Author(s): Dan Halbert and Scott Shawcroft for Adafruit Industries
 
 Implementation Notes
 --------------------
@@ -42,7 +43,163 @@
 
 """
 
-# imports
+import _bleio
+import board
+
+from .services.core import Service
+from .advertising import Advertisement
 
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_BLE.git"
+
+# These are internal data structures used throughout the library to recognize certain Services and
+# Advertisements.
+# pylint: disable=invalid-name
+all_services_by_name = {}
+all_services_by_uuid = {}
+known_advertisements = set()
+# pylint: enable=invalid-name
+
+def recognize_services(*service_classes):
+    """Instruct the adafruit_ble library to recognize the given Services.
+
+       This will cause the Service related advertisements to show the corresponding class.
+       `SmartConnection` will automatically have attributes for any recognized service available
+       from the peer."""
+    for service_class in service_classes:
+        if not issubclass(service_class, Service):
+            raise ValueError("Can only detect subclasses of Service")
+        all_services_by_name[service_class.default_field_name] = service_class
+        all_services_by_uuid[service_class.uuid] = service_class
+
+def recognize_advertisement(*advertisements):
+    """Instruct the adafruit_ble library to recognize the given `Advertisement` types.
+
+       When an advertisement is recognized by the `SmartAdapter`, it will be returned from the
+       start_scan iterator instead of a generic `Advertisement`."""
+    known_advertisements.add(*advertisements)
+
+class SmartConnection:
+    """This represents a connection to a peer BLE device.
+
+       Its smarts come from its ability to recognize Services available on the peer and make them
+       available as attributes on the Connection. Use `recognize_services` to register all services
+       of interest. All subsequent Connections will then recognize the service.
+
+       ``dir(connection)`` will show all attributes including recognized Services.
+       """
+    def __init__(self, connection):
+        self._connection = connection
+
+    def __dir__(self):
+        discovered = []
+        results = self._connection.discover_remote_services()
+        for service in results:
+            uuid = service.uuid
+            if uuid in all_services_by_uuid:
+                service = all_services_by_uuid[uuid]
+                discovered.append(service.default_field_name)
+        super_dir = dir(super())
+        super_dir.extend(discovered)
+        return super_dir
+
+    def __getattr__(self, name):
+        if name in self.__dict__:
+            return self.__dict__[name]
+        if name in all_services_by_name:
+            service = all_services_by_name[name]
+            uuid = service.uuid._uuid
+            results = self._connection.discover_remote_services((uuid,))
+            if results:
+                remote_service = service(service=results[0])
+                setattr(self, name, remote_service)
+                return remote_service
+        raise AttributeError()
+
+    @property
+    def connected(self):
+        """True if the connection to the peer is still active."""
+        return self._connection.connected
+
+    def disconnect(self):
+        """Disconnect from peer."""
+        self._connection.disconnect()
+
+class SmartAdapter:
+    """This BLE Adapter class enhances the normal `_bleio.Adapter`.
+
+       It uses the library's `Advertisement` classes and the `SmartConnection` class."""
+    def __init__(self, adapter=None):
+        if not adapter:
+            adapter = _bleio.adapter
+        self._adapter = adapter
+        self._current_advertisement = None
+        self._connection_cache = {}
+
+    def start_advertising(self, advertisement, scan_response=None, **kwargs):
+        """Starts advertising the given advertisement.
+
+            It takes most kwargs of `_bleio.Adapter.start_advertising`."""
+        scan_response_data = None
+        if scan_response:
+            scan_response_data = bytes(scan_response)
+        print(advertisement.connectable)
+        self._adapter.start_advertising(bytes(advertisement),
+                                        scan_response=scan_response_data,
+                                        connectable=advertisement.connectable,
+                                        **kwargs)
+
+    def stop_advertising(self):
+        """Stops advertising."""
+        self._adapter.stop_advertising()
+
+    def start_scan(self, advertisement_types=None, **kwargs):
+        """Starts scanning. Returns an iterator of Advertisements that are either recognized or
+           in advertisment_types (which will be subsequently recognized.) The iterator will block
+           until an advertisement is heard or the scan times out.
+
+           If a list ``advertisement_types`` is given, only Advertisements of that type are produced
+           by the returned iterator."""
+        prefixes = b""
+        if advertisement_types:
+            recognize_advertisement(*advertisement_types)
+            if len(advertisement_types) == 1:
+                prefixes = advertisement_types[0].prefix
+        for entry in self._adapter.start_scan(prefixes=prefixes, **kwargs):
+            adv_type = Advertisement
+            for possible_type in known_advertisements:
+                if possible_type.matches(entry) and issubclass(possible_type, adv_type):
+                    adv_type = possible_type
+            advertisement = adv_type.from_entry(entry)
+            if advertisement:
+                yield advertisement
+
+    def stop_scan(self):
+        """Stops any active scan.
+
+           The scan results iterator will return any buffered results and then raise StopIteration
+           once empty."""
+        self._adapter.stop_scan()
+
+    def connect(self, advertisement, *, timeout=4):
+        """Initiates a `SmartConnection` to the peer that advertised the given advertisement."""
+        connection = self._adapter.connect(advertisement.address, timeout=timeout)
+        self._connection_cache[connection] = SmartConnection(connection)
+        return self._connection_cache[connection]
+
+    @property
+    def connected(self):
+        """True if any peers are connected to the adapter."""
+        return self._adapter.connected
+
+    @property
+    def connections(self):
+        """A tuple of active `SmartConnection` objects."""
+        connections = self._adapter.connections
+        smart_connections = [None] * len(connections)
+        for i, connection in enumerate(self._adapter.connections):
+            if connection not in self._connection_cache:
+                self._connection_cache[connection] = SmartConnection(connection)
+            smart_connections[i] = self._connection_cache[connection]
+
+        return tuple(smart_connections)