1. To accomodate scan response packets:

dhalbert · dhalbert · commit bc8b7f3b2056 · 2019-06-02T23:22:45.000-04:00
Rename Advertisement to AdvertisingPacket.
   Make adding advertising flags is now done explicitly by callers.

2. ServerAdvertisement creates a scan response packet to send the
the full name, if it doesn't fit in the initial advertising data packet.

3. Allow UARTServer to specify peripheral name.
diff --git a/adafruit_ble/advertising.py b/adafruit_ble/advertising.py
@@ -31,8 +31,8 @@
 
 import struct
 
-class Advertisement:
-    """Build up a BLE advertising data packet."""
+class AdvertisingPacket:
+    """Build up a BLE advertising data or scan response packet."""
     # BR/EDR flags not included here, since we don't support BR/EDR.
     FLAG_LIMITED_DISCOVERY = 0x01
     """Discoverable only for a limited time period."""
@@ -81,28 +81,38 @@ class Advertisement:
     MAX_DATA_SIZE = 31
     """Data size in a regular BLE packet."""
 
-    def __init__(self, flags=(FLAG_GENERAL_DISCOVERY | FLAG_LE_ONLY), max_length=MAX_DATA_SIZE):
-        """Initalize an advertising packet, with the given flags, no larger than max_length."""
-        self.data = bytearray((2, self.FLAGS, flags))
+    def __init__(self, *, max_length=MAX_DATA_SIZE):
+        """Create an empty advertising packet, no larger than max_length."""
+        self._packet_bytes = bytearray()
         self._max_length = max_length
         self._check_length()
 
+    @property
+    def packet_bytes(self):
+        """The raw packet bytes."""
+        return self._packet_bytes
+
     @property
     def bytes_remaining(self):
-        return self._max_length - len(self.data)
+        """Number of bytes still available for use in the packet."""
+        return self._max_length - len(self._packet_bytes)
 
     def _check_length(self):
-        if len(self.data) > self._max_length:
+        if len(self._packet_bytes) > self._max_length:
             raise IndexError("Advertising data too long")
 
     def add_field(self, field_type, field_data):
         """Append an advertising data field to the current packet, of the given type.
         The length field is calculated from the length of field_data."""
-        self.data.append(1 + len(field_data))
-        self.data.append(field_type)
-        self.data.extend(field_data)
+        self._packet_bytes.append(1 + len(field_data))
+        self._packet_bytes.append(field_type)
+        self._packet_bytes.extend(field_data)
         self._check_length()
 
+    def add_flags(self, flags=(FLAG_GENERAL_DISCOVERY | FLAG_LE_ONLY)):
+        """Add default or custom advertising flags."""
+        self.add_field(self.FLAGS, struct.pack("<B", flags))
+
     def add_16_bit_uuids(self, uuids):
         """Add a complete list of 16 bit service UUIDs."""
         for uuid in uuids:
@@ -119,43 +129,64 @@ def add_mfr_specific_data(self, mfr_id, data):
 
 
 class ServerAdvertisement:
-    def __init__(self, peripheral, *, tx_power=0):
-        """Create an advertisement to advertise a peripheral's services.
+    """
+    Data to advertise a peripheral's services.
 
-        :param peripheral Peripheral the Peripheral to advertise. Use its services and name
-        :param int tx_power: transmit power in dBm at 0 meters (8 bit signed value). Default 0 dBm
-        """
+    The advertisement consists of an advertising data packet and an optional scan response packet,
+    The scan response packet is created only if there is not room in the
+    advertising data packet for the complete peripheral name.
 
+    :param peripheral Peripheral the Peripheral to advertise. Use its services and name
+    :param int tx_power: transmit power in dBm at 0 meters (8 bit signed value). Default 0 dBm
+    """
+
+    def __init__(self, peripheral, *, tx_power=0):
         self._peripheral = peripheral
 
-        adv = Advertisement()
+        packet = AdvertisingPacket()
+        packet.add_flags()
+        self._scan_response_packet = None
 
         # Need to check service.secondary
         uuids_16_bits = [service.uuid for service in peripheral.services
                          if service.uuid.size == 16 and not service.secondary]
         if uuids_16_bits:
-            adv.add_16_bit_uuids(uuids_16_bits)
+            packet.add_16_bit_uuids(uuids_16_bits)
 
         uuids_128_bits = [service.uuid for service in peripheral.services
-                         if service.uuid.size == 128 and not service.secondary]
+                          if service.uuid.size == 128 and not service.secondary]
         if uuids_128_bits:
-            adv.add_128_bit_uuids(uuids_128_bits)
+            packet.add_128_bit_uuids(uuids_128_bits)
 
-        adv.add_field(Advertisement.TX_POWER, struct.pack("<b", tx_power))
+        packet.add_field(AdvertisingPacket.TX_POWER, struct.pack("<b", tx_power))
 
         # 2 bytes needed for field length and type.
-        bytes_available = adv.bytes_remaining - 2
+        bytes_available = packet.bytes_remaining - 2
         if bytes_available <= 0:
             raise IndexError("No room for name")
 
         name_bytes = bytes(peripheral.name, 'utf-8')
         if bytes_available >= len(name_bytes):
-            adv.add_field(Advertisement.COMPLETE_LOCAL_NAME, name_bytes)
+            packet.add_field(AdvertisingPacket.COMPLETE_LOCAL_NAME, name_bytes)
         else:
-            adv.add_field(Advertisement.SHORT_LOCAL_NAME, name_bytes[:bytes_available])
+            packet.add_field(AdvertisingPacket.SHORT_LOCAL_NAME, name_bytes[:bytes_available])
+            self._scan_response_packet = AdvertisingPacket()
+            try:
+                self._scan_response_packet.add_field(AdvertisingPacket.COMPLETE_LOCAL_NAME,
+                                                     name_bytes)
+            except IndexError:
+                raise IndexError("Name too long")
 
-        self._advertisement = adv
+        self._advertising_data_packet = packet
+
+    @property
+    def advertising_data_bytes(self):
+        """The raw bytes for the initial advertising data packet."""
+        return self._advertising_data_packet.packet_bytes
 
     @property
-    def data(self):
-        return self._advertisement.data
+    def scan_response_bytes(self):
+        """The raw bytes for the scan response packet. None if there is no response packet."""
+        if self._scan_response_packet:
+            return self._scan_response_packet.packet_bytes
+        return None
diff --git a/adafruit_ble/beacon.py b/adafruit_ble/beacon.py
@@ -32,26 +32,26 @@
 import struct
 import bleio
 
-from .advertising import Advertisement
+from .advertising import AdvertisingPacket
 
 class Beacon:
     """Base class for Beacon advertisers."""
-    def __init__(self, advertisement, interval=1.0):
-        """Set up a beacon with the given Advertisement.
+    def __init__(self, advertising_packet, interval=1.0):
+        """Set up a beacon with the given AdvertisingPacket.
 
-        :param Advertisement advertisement: The advertising packet
+        :param AdvertisingPacket advertising_packet
         :param float interval: Advertising interval in seconds
         """
-        self.broadcaster = bleio.Broadcaster(interval)
-        self.advertisement = advertisement
+        self._broadcaster = bleio.Broadcaster(interval)
+        self._advertising_packet = advertising_packet
 
     def start(self):
         """Turn on beacon."""
-        self.broadcaster.start_advertising(self.advertisement.data)
+        self._broadcaster.start_advertising(self._advertising_packet.packet_bytes)
 
     def stop(self):
         """Turn off beacon."""
-        self.broadcaster.stop_advertising()
+        self._broadcaster.stop_advertising()
 
 
 
@@ -81,7 +81,8 @@ def __init__(self, company_id, uuid, major, minor, rssi, interval=1.0):
         b.start()
         """
 
-        adv = Advertisement()
+        adv = AdvertisingPacket()
+        adv.add_flags()
         adv.add_mfr_specific_data(
             company_id,
             b''.join((
@@ -131,11 +132,12 @@ def __init__(self, url, tx_power=0, interval=1.0):
 
         :param url URL to encode. Must be short enough to fit after encoding.
         :param int tx_power: transmit power in dBm at 0 meters (8 bit signed value)
-        :param float interval: Advertising interval in seconds
+        :param float interval: advertising interval in seconds
         """
 
-        adv = Advertisement()
-        adv.add_field(Advertisement.ALL_16_BIT_SERVICE_UUIDS, self._EDDYSTONE_ID)
+        adv = AdvertisingPacket()
+        adv.add_flags()
+        adv.add_field(AdvertisingPacket.ALL_16_BIT_SERVICE_UUIDS, self._EDDYSTONE_ID)
         short_url = None
         for idx, prefix in enumerate(self._URL_SCHEMES):
             if url.startswith(prefix):
@@ -148,7 +150,7 @@ def __init__(self, url, tx_power=0, interval=1.0):
             short_url = short_url.replace(subst + '/', chr(code))
         for code, subst in enumerate(self._SUBSTITUTIONS, 7):
             short_url = short_url.replace(subst, chr(code))
-        adv.add_field(Advertisement.SERVICE_DATA_16_BIT_UUID,
+        adv.add_field(AdvertisingPacket.SERVICE_DATA_16_BIT_UUID,
                       b''.join((self._EDDYSTONE_ID,
                                 b'\x10',
                                 struct.pack("<bB", tx_power, url_scheme_num),
diff --git a/adafruit_ble/uart.py b/adafruit_ble/uart.py
@@ -39,6 +39,7 @@ class UARTServer:
       for the first character and between subsequent characters.
     :param int buffer_size: buffer up to this many bytes.
       If more bytes are received, older bytes will be discarded.
+    :param str name: Name to advertise for server. If None, use default Peripheral name.
 
     Example::
 
@@ -57,15 +58,14 @@ class UARTServer:
     NUS_RX_CHAR_UUID = UUID("6E400002-B5A3-F393-E0A9-E50E24DCCA9E")
     NUS_TX_CHAR_UUID = UUID("6E400003-B5A3-F393-E0A9-E50E24DCCA9E")
 
-    def __init__(self, timeout=1.0, buffer_size=64):
-        """Define the NUS service and start advertising it."""
+    def __init__(self, *, timeout=1.0, buffer_size=64, name=None):
         self._nus_tx_char = Characteristic(self.NUS_TX_CHAR_UUID, notify=True)
         self._nus_rx_char = Characteristic(self.NUS_RX_CHAR_UUID,
                                            write=True, write_no_response=True)
 
         nus_uart_service = Service(self.NUS_SERVICE_UUID, (self._nus_tx_char, self._nus_rx_char))
 
-        self._periph = Peripheral((nus_uart_service,))
+        self._periph = Peripheral((nus_uart_service,), name=name)
         self._rx_buffer = CharacteristicBuffer(self._nus_rx_char,
                                                timeout=timeout, buffer_size=buffer_size)
         self._advertisement = ServerAdvertisement(self._periph)
@@ -74,7 +74,8 @@ def start_advertising(self):
         """Start advertising the service. When a client connects, advertising will stop.
         When the client disconnects, restart advertising by calling ``start_advertising()`` again.
         """
-        self._periph.start_advertising(data=self._advertisement.data)
+        self._periph.start_advertising(data=self._advertisement.advertising_data_bytes,
+                                       scan_response=self._advertisement.scan_response_bytes)
 
     def stop_advertising(self):
         """Stop advertising the service."""
