Merge pull request #262 from whitevegagabriel/l2cap

Port l2cap_bridge sample to Rust

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# Migrate code style to Black
+135df0dcc01ab765f432e19b1a5202d29bd55545

.github/workflows/code-check.yml

@@ -0,0 +1,35 @@
+# Check the code against the formatter and linter
+name: Code format and lint check
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check Code
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Check out from Git
+      uses: actions/checkout@v3
+    - name: Get history and tags for SCM versioning to work
+      run: |
+        git fetch --prune --unshallow
+        git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.10'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install ".[build,test,development]"
+    - name: Check
+      run: |
+        invoke project.pre-commit

.github/workflows/python-build-test.yml

@@ -14,6 +14,10 @@ jobs:
   build:
 
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+      fail-fast: false
 
     steps:
     - name: Check out from Git
@@ -21,19 +25,53 @@ jobs:
     - name: Get history and tags for SCM versioning to work
       run: |
         git fetch --prune --unshallow
-        git fetch --depth=1 origin +refs/tags/*:refs/tags/*      
-    - name: Set up Python 3.10
-      uses: actions/setup-python@v3
+        git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
       with:
-        python-version: "3.10"
+        python-version: ${{ matrix.python-version }}
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         python -m pip install ".[build,test,development,documentation]"
-    - name: Test with pytest
+    - name: Test
       run: |
-        pytest
+        invoke test
     - name: Build
       run: |
         inv build
         inv build.mkdocs
+  build-rust:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.8", "3.9", "3.10", "3.11" ]
+        rust-version: [ "1.70.0", "stable" ]
+      fail-fast: false
+    steps:
+      - name: Check out from Git
+        uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[build,test,development,documentation]"
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: clippy,rustfmt
+          toolchain: ${{ matrix.rust-version }}
+      - name: Rust Build
+        run: cd rust && cargo build --all-targets && cargo build --all-features --all-targets
+      # Lints after build so what clippy needs is already built
+      - name: Rust Lints
+        run: cd rust && cargo fmt --check && cargo clippy --all-targets -- --deny warnings && cargo clippy --all-features --all-targets -- --deny warnings
+      - name: Rust Tests
+        run: cd rust && cargo test
+      # At some point, hook up publishing the binary. For now, just make sure it builds.
+      # Once we're ready to publish binaries, this should be built with `--release`.
+      - name: Build Bumble CLI
+        run: cd rust && cargo build --features bumble-tools --bin bumble

.gitignore

@@ -3,9 +3,10 @@ build/
 dist/
 *.egg-info/
 *~
-bumble/__pycache__
 docs/mkdocs/site
-tests/__pycache__
 test-results.xml
-bumble/transport/__pycache__
-bumble/profiles/__pycache__
+__pycache__
+# generated by setuptools_scm
+bumble/_version.py
+.vscode/launch.json
+/.idea

.vscode/settings.json

@@ -0,0 +1,80 @@
+{
+    "cSpell.words": [
+        "Abortable",
+        "altsetting",
+        "ansiblue",
+        "ansicyan",
+        "ansigreen",
+        "ansimagenta",
+        "ansired",
+        "ansiyellow",
+        "appendleft",
+        "ASHA",
+        "asyncio",
+        "ATRAC",
+        "avdtp",
+        "bitpool",
+        "bitstruct",
+        "BSCP",
+        "BTPROTO",
+        "CCCD",
+        "cccds",
+        "cmac",
+        "CONNECTIONLESS",
+        "csrcs",
+        "datagram",
+        "DATALINK",
+        "delayreport",
+        "deregisters",
+        "deregistration",
+        "dhkey",
+        "diversifier",
+        "Fitbit",
+        "GATTLINK",
+        "HANDSFREE",
+        "keydown",
+        "keyup",
+        "levelname",
+        "libc",
+        "libusb",
+        "MITM",
+        "NDIS",
+        "NONBLOCK",
+        "NONCONN",
+        "OXIMETER",
+        "popleft",
+        "psms",
+        "pyee",
+        "pyusb",
+        "rfcomm",
+        "ROHC",
+        "rssi",
+        "SEID",
+        "seids",
+        "SERV",
+        "ssrc",
+        "strerror",
+        "subband",
+        "subbands",
+        "subevent",
+        "Subrating",
+        "substates",
+        "tobytes",
+        "tsep",
+        "usbmodem",
+        "vhci",
+        "websockets",
+        "xcursor",
+        "ycursor"
+    ],
+    "[python]": {
+        "editor.rulers": [88]
+    },
+    "python.formatting.provider": "black",
+    "pylint.importStrategy": "useBundled",
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

LICENSE

@@ -199,4 +199,23 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.
+
+
+---
+
+
+Files: bumble/colors.py
+Copyright (c) 2012 Giorgos Verigakis <verigak@gmail.com>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -15,10 +15,10 @@ Bumble is a full-featured Bluetooth stack written entirely in Python. It support
 
 ## Documentation
 
-Browse the pre-built [Online Documentation](https://google.github.io/bumble/), 
+Browse the pre-built [Online Documentation](https://google.github.io/bumble/),
 or see the documentation source under `docs/mkdocs/src`, or build the static HTML site from the markdown text with:
 ```
-mkdocs build -f docs/mkdocs/mkdocs.yml 
+mkdocs build -f docs/mkdocs/mkdocs.yml
 ```
 
 ## Usage
@@ -29,7 +29,7 @@ For a quick start to using Bumble, see the [Getting Started](docs/mkdocs/src/get
 
 ### Dependencies
 
-To install package dependencies needed to run the bumble examples execute the following commands:
+To install package dependencies needed to run the bumble examples, execute the following commands:
 
 ```
 python -m pip install --upgrade pip
@@ -50,7 +50,7 @@ Bumble is easiest to use with a dedicated USB dongle.
 This is because internal Bluetooth interfaces tend to be locked down by the operating system.
 You can use the [usb_probe](/docs/mkdocs/src/apps_and_tools/usb_probe.md) tool (all platforms) or `lsusb` (Linux or macOS) to list the available USB devices on your system.
 
-See the [USB Transport](/docs/mkdocs/src/transports/usb.md) page for details on how to refer to USB devices.
+See the [USB Transport](/docs/mkdocs/src/transports/usb.md) page for details on how to refer to USB devices. Also, if your are on a mac, see [these instructions](docs/mkdocs/src/platforms/macos.md).
 
 ## License
 

apps/README.md

@@ -47,5 +47,3 @@ NOTE: this assumes you're running a Link Relay on port `10723`.
 
 ## `console.py`
 A simple text-based-ui interactive Bluetooth device with GATT client capabilities.
-
-

apps/controller_info.py

@@ -19,9 +19,9 @@ import asyncio
 import os
 import logging
 import click
-from colors import color
 from bumble.company_ids import COMPANY_IDENTIFIERS
 
+from bumble.colors import color
 from bumble.core import name_or_number
 from bumble.hci import (
     map_null_terminated_utf8_string,
@@ -30,6 +30,8 @@ from bumble.hci import (
     HCI_VERSION_NAMES,
     LMP_VERSION_NAMES,
     HCI_Command,
+    HCI_Command_Complete_Event,
+    HCI_Command_Status_Event,
     HCI_READ_BD_ADDR_COMMAND,
     HCI_Read_BD_ADDR_Command,
     HCI_READ_LOCAL_NAME_COMMAND,
@@ -39,25 +41,39 @@ from bumble.hci import (
     HCI_LE_READ_NUMBER_OF_SUPPORTED_ADVERTISING_SETS_COMMAND,
     HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command,
     HCI_LE_READ_MAXIMUM_ADVERTISING_DATA_LENGTH_COMMAND,
-    HCI_LE_Read_Maximum_Advertising_Data_Length_Command
+    HCI_LE_Read_Maximum_Advertising_Data_Length_Command,
 )
 from bumble.host import Host
 from bumble.transport import open_transport_or_link
 
 
+# -----------------------------------------------------------------------------
+def command_succeeded(response):
+    if isinstance(response, HCI_Command_Status_Event):
+        return response.status == HCI_SUCCESS
+    if isinstance(response, HCI_Command_Complete_Event):
+        return response.return_parameters.status == HCI_SUCCESS
+    return False
+
+
 # -----------------------------------------------------------------------------
 async def get_classic_info(host):
     if host.supports_command(HCI_READ_BD_ADDR_COMMAND):
         response = await host.send_command(HCI_Read_BD_ADDR_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print()
-            print(color('Classic Address:', 'yellow'), response.return_parameters.bd_addr)
+            print(
+                color('Classic Address:', 'yellow'), response.return_parameters.bd_addr
+            )
 
     if host.supports_command(HCI_READ_LOCAL_NAME_COMMAND):
         response = await host.send_command(HCI_Read_Local_Name_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print()
-            print(color('Local Name:', 'yellow'), map_null_terminated_utf8_string(response.return_parameters.local_name))
+            print(
+                color('Local Name:', 'yellow'),
+                map_null_terminated_utf8_string(response.return_parameters.local_name),
+            )
 
 
 # -----------------------------------------------------------------------------
@@ -65,26 +81,30 @@ async def get_le_info(host):
     print()
 
     if host.supports_command(HCI_LE_READ_NUMBER_OF_SUPPORTED_ADVERTISING_SETS_COMMAND):
-        response = await host.send_command(HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        response = await host.send_command(
+            HCI_LE_Read_Number_Of_Supported_Advertising_Sets_Command()
+        )
+        if command_succeeded(response):
             print(
                 color('LE Number Of Supported Advertising Sets:', 'yellow'),
                 response.return_parameters.num_supported_advertising_sets,
-                '\n'
+                '\n',
             )
 
     if host.supports_command(HCI_LE_READ_MAXIMUM_ADVERTISING_DATA_LENGTH_COMMAND):
-        response = await host.send_command(HCI_LE_Read_Maximum_Advertising_Data_Length_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        response = await host.send_command(
+            HCI_LE_Read_Maximum_Advertising_Data_Length_Command()
+        )
+        if command_succeeded(response):
             print(
                 color('LE Maximum Advertising Data Length:', 'yellow'),
                 response.return_parameters.max_advertising_data_length,
-                '\n'
+                '\n',
             )
 
     if host.supports_command(HCI_LE_READ_MAXIMUM_DATA_LENGTH_COMMAND):
         response = await host.send_command(HCI_LE_Read_Maximum_Data_Length_Command())
-        if response.return_parameters.status == HCI_SUCCESS:
+        if command_succeeded(response):
             print(
                 color('Maximum Data Length:', 'yellow'),
                 (
@@ -93,7 +113,7 @@ async def get_le_info(host):
                     f'rx:{response.return_parameters.supported_max_rx_octets}/'
                     f'{response.return_parameters.supported_max_rx_time}'
                 ),
-                '\n'
+                '\n',
             )
 
     print(color('LE Features:', 'yellow'))
@@ -112,10 +132,19 @@ async def async_main(transport):
 
         # Print version
         print(color('Version:', 'yellow'))
-        print(color('  Manufacturer:  ', 'green'), name_or_number(COMPANY_IDENTIFIERS, host.local_version.company_identifier))
-        print(color('  HCI Version:   ', 'green'), name_or_number(HCI_VERSION_NAMES, host.local_version.hci_version))
+        print(
+            color('  Manufacturer:  ', 'green'),
+            name_or_number(COMPANY_IDENTIFIERS, host.local_version.company_identifier),
+        )
+        print(
+            color('  HCI Version:   ', 'green'),
+            name_or_number(HCI_VERSION_NAMES, host.local_version.hci_version),
+        )
         print(color('  HCI Subversion:', 'green'), host.local_version.hci_subversion)
-        print(color('  LMP Version:   ', 'green'), name_or_number(LMP_VERSION_NAMES, host.local_version.lmp_version))
+        print(
+            color('  LMP Version:   ', 'green'),
+            name_or_number(LMP_VERSION_NAMES, host.local_version.lmp_version),
+        )
         print(color('  LMP Subversion:', 'green'), host.local_version.lmp_subversion)
 
         # Get the Classic info
@@ -135,7 +164,7 @@ async def async_main(transport):
 @click.command()
 @click.argument('transport')
 def main(transport):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
     asyncio.run(async_main(transport))
 
 

apps/controllers.py

@@ -28,11 +28,14 @@ from bumble.transport import open_transport_or_link
 # -----------------------------------------------------------------------------
 async def async_main():
     if len(sys.argv) != 3:
-        print('Usage: controllers.py <hci-transport-1> <hci-transport-2> [<hci-transport-3> ...]')
+        print(
+            'Usage: controllers.py <hci-transport-1> <hci-transport-2> '
+            '[<hci-transport-3> ...]'
+        )
         print('example: python controllers.py pty:ble1 pty:ble2')
         return
 
-    # Create a loccal link to attach the controllers to
+    # Create a local link to attach the controllers to
     link = LocalLink()
 
     # Create a transport and controller for all requested names
@@ -41,7 +44,12 @@ async def async_main():
     for index, transport_name in enumerate(sys.argv[1:]):
         transport = await open_transport_or_link(transport_name)
         transports.append(transport)
-        controller = Controller(f'C{index}', host_source = transport.source, host_sink = transport.sink, link = link)
+        controller = Controller(
+            f'C{index}',
+            host_source=transport.source,
+            host_sink=transport.sink,
+            link=link,
+        )
         controllers.append(controller)
 
     # Wait until the user interrupts
@@ -54,7 +62,7 @@ async def async_main():
 
 # -----------------------------------------------------------------------------
 def main():
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     asyncio.run(async_main())
 
 

apps/gatt_dump.py

@@ -19,9 +19,9 @@ import asyncio
 import os
 import logging
 import click
-from colors import color
 
-from bumble.core import ProtocolError, TimeoutError
+import bumble.core
+from bumble.colors import color
 from bumble.device import Device, Peer
 from bumble.gatt import show_services
 from bumble.transport import open_transport_or_link
@@ -49,9 +49,9 @@ async def dump_gatt_db(peer, done):
         try:
             value = await attribute.read_value()
             print(color(f'{value.hex()}', 'green'))
-        except ProtocolError as error:
+        except bumble.core.ProtocolError as error:
             print(color(error, 'red'))
-        except TimeoutError:
+        except bumble.core.TimeoutError:
             print(color('read timeout', 'red'))
 
     if done is not None:
@@ -64,9 +64,13 @@ async def async_main(device_config, encrypt, transport, address_or_name):
 
         # Create a device
         if device_config:
-            device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
+            device = Device.from_config_file_with_hci(
+                device_config, hci_source, hci_sink
+            )
         else:
-            device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
+            device = Device.with_hci(
+                'Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink
+            )
         await device.power_on()
 
         if address_or_name:
@@ -81,7 +85,12 @@ async def async_main(device_config, encrypt, transport, address_or_name):
         else:
             # Wait for a connection
             done = asyncio.get_running_loop().create_future()
-            device.on('connection', lambda connection: asyncio.create_task(dump_gatt_db(Peer(connection), done)))
+            device.on(
+                'connection',
+                lambda connection: asyncio.create_task(
+                    dump_gatt_db(Peer(connection), done)
+                ),
+            )
             await device.start_advertising(auto_restart=True)
 
             print(color('### Waiting for connection...', 'blue'))
@@ -99,7 +108,7 @@ def main(device_config, encrypt, transport, address_or_name):
     Dump the GATT database on a remote device. If ADDRESS_OR_NAME is not specified,
     wait for an incoming connection.
     """
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     asyncio.run(async_main(device_config, encrypt, transport, address_or_name))
 
 

apps/gg_bridge.py

@@ -20,8 +20,8 @@ import os
 import struct
 import logging
 import click
-from colors import color
 
+from bumble.colors import color
 from bumble.device import Device, Peer
 from bumble.core import AdvertisingData
 from bumble.gatt import Service, Characteristic, CharacteristicValue
@@ -33,10 +33,12 @@ from bumble.hci import HCI_Constant
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
-GG_GATTLINK_SERVICE_UUID                          = 'ABBAFF00-E56A-484C-B832-8B17CF6CBFE8'
-GG_GATTLINK_RX_CHARACTERISTIC_UUID                = 'ABBAFF01-E56A-484C-B832-8B17CF6CBFE8'
-GG_GATTLINK_TX_CHARACTERISTIC_UUID                = 'ABBAFF02-E56A-484C-B832-8B17CF6CBFE8'
-GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID = 'ABBAFF03-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_SERVICE_UUID = 'ABBAFF00-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_RX_CHARACTERISTIC_UUID = 'ABBAFF01-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_TX_CHARACTERISTIC_UUID = 'ABBAFF02-E56A-484C-B832-8B17CF6CBFE8'
+GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID = (
+    'ABBAFF03-E56A-484C-B832-8B17CF6CBFE8'
+)
 
 GG_PREFERRED_MTU = 256
 
@@ -44,8 +46,8 @@ GG_PREFERRED_MTU = 256
 # -----------------------------------------------------------------------------
 class GattlinkL2capEndpoint:
     def __init__(self):
-        self.l2cap_channel     = None
-        self.l2cap_packet      = b''
+        self.l2cap_channel = None
+        self.l2cap_packet = b''
         self.l2cap_packet_size = 0
 
     # Called when an L2CAP SDU has been received
@@ -71,12 +73,12 @@ class GattlinkL2capEndpoint:
 class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
     def __init__(self, device, peer_address):
         super().__init__()
-        self.device                   = device
-        self.peer_address             = peer_address
-        self.peer                     = None
-        self.tx_socket                = None
-        self.rx_characteristic        = None
-        self.tx_characteristic        = None
+        self.device = device
+        self.peer_address = peer_address
+        self.peer = None
+        self.tx_socket = None
+        self.rx_characteristic = None
+        self.tx_characteristic = None
         self.l2cap_psm_characteristic = None
 
         device.listener = self
@@ -97,6 +99,7 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
             print(color(f'!!! Connection failed: {error}', 'red'))
 
     @AsyncRunner.run_in_task()
+    # pylint: disable=invalid-overridden-method
     async def on_connection(self, connection):
         print(f'=== Connected to {connection}')
         self.peer = Peer(connection)
@@ -127,7 +130,9 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
                 self.rx_characteristic = characteristic
             elif characteristic.uuid == GG_GATTLINK_TX_CHARACTERISTIC_UUID:
                 self.tx_characteristic = characteristic
-            elif characteristic.uuid == GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID:
+            elif (
+                characteristic.uuid == GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID
+            ):
                 self.l2cap_psm_characteristic = characteristic
         print('RX:', self.rx_characteristic)
         print('TX:', self.tx_characteristic)
@@ -135,7 +140,9 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
 
         if self.l2cap_psm_characteristic:
             # Subscribe to and then read the PSM value
-            await self.peer.subscribe(self.l2cap_psm_characteristic, self.on_l2cap_psm_received)
+            await self.peer.subscribe(
+                self.l2cap_psm_characteristic, self.on_l2cap_psm_received
+            )
             psm_bytes = await self.peer.read_value(self.l2cap_psm_characteristic)
             psm = struct.unpack('<H', psm_bytes)[0]
             await self.connect_l2cap(psm)
@@ -150,7 +157,13 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
         print(color(f'!!! Connection failed: {error}'))
 
     def on_disconnection(self, reason):
-        print(color(f'!!! Disconnected from {self.peer}, reason={HCI_Constant.error_name(reason)}', 'red'))
+        print(
+            color(
+                f'!!! Disconnected from {self.peer}, '
+                f'reason={HCI_Constant.error_name(reason)}',
+                'red',
+            )
+        )
         self.tx_characteristic = None
         self.rx_characteristic = None
         self.peer = None
@@ -178,7 +191,7 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
         pass
 
     # Called by asyncio when a UDP datagram is received
-    def datagram_received(self, data, address):
+    def datagram_received(self, data, _address):
         print(color(f'<<< [UDP]: {len(data)} bytes', 'green'))
 
         if self.l2cap_channel:
@@ -193,11 +206,12 @@ class GattlinkHubBridge(GattlinkL2capEndpoint, Device.Listener):
 class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
     def __init__(self, device):
         super().__init__()
-        self.device            = device
-        self.peer              = None
-        self.tx_socket         = None
-        self.tx_subscriber     = None
+        self.device = device
+        self.peer = None
+        self.tx_socket = None
+        self.tx_subscriber = None
         self.rx_characteristic = None
+        self.transport = None
 
         # Register as a listener
         device.listener = self
@@ -212,35 +226,37 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
             GG_GATTLINK_RX_CHARACTERISTIC_UUID,
             Characteristic.WRITE_WITHOUT_RESPONSE,
             Characteristic.WRITEABLE,
-            CharacteristicValue(write=self.on_rx_write)
+            CharacteristicValue(write=self.on_rx_write),
         )
         self.tx_characteristic = Characteristic(
             GG_GATTLINK_TX_CHARACTERISTIC_UUID,
-            Characteristic.NOTIFY,
-            Characteristic.READABLE
+            Characteristic.Properties.NOTIFY,
+            Characteristic.READABLE,
         )
         self.tx_characteristic.on('subscription', self.on_tx_subscription)
         self.psm_characteristic = Characteristic(
             GG_GATTLINK_L2CAP_CHANNEL_PSM_CHARACTERISTIC_UUID,
-            Characteristic.READ | Characteristic.NOTIFY,
+            Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
             Characteristic.READABLE,
-            bytes([psm, 0])
+            bytes([psm, 0]),
         )
         gattlink_service = Service(
             GG_GATTLINK_SERVICE_UUID,
-            [
-                self.rx_characteristic,
-                self.tx_characteristic,
-                self.psm_characteristic
-            ]
+            [self.rx_characteristic, self.tx_characteristic, self.psm_characteristic],
         )
         device.add_services([gattlink_service])
         device.advertising_data = bytes(
-            AdvertisingData([
-                (AdvertisingData.COMPLETE_LOCAL_NAME, bytes('Bumble GG', 'utf-8')),
-                (AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
-                 bytes(reversed(bytes.fromhex('ABBAFF00E56A484CB8328B17CF6CBFE8'))))
-            ])
+            AdvertisingData(
+                [
+                    (AdvertisingData.COMPLETE_LOCAL_NAME, bytes('Bumble GG', 'utf-8')),
+                    (
+                        AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+                        bytes(
+                            reversed(bytes.fromhex('ABBAFF00E56A484CB8328B17CF6CBFE8'))
+                        ),
+                    ),
+                ]
+            )
         )
 
     async def start(self):
@@ -251,7 +267,7 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
         self.transport = transport
 
     # Called by asyncio when a UDP datagram is received
-    def datagram_received(self, data, address):
+    def datagram_received(self, data, _address):
         print(color(f'<<< [UDP]: {len(data)} bytes', 'green'))
 
         if self.l2cap_channel:
@@ -263,14 +279,17 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
             asyncio.create_task(self.device.notify_subscribers(self.tx_characteristic))
 
     # Called when a write to the RX characteristic has been received
-    def on_rx_write(self, connection, data):
+    def on_rx_write(self, _connection, data):
         print(color(f'<<< [GATT RX]: {len(data)} bytes', 'cyan'))
         print(color('>>> [UDP]', 'magenta'))
         self.tx_socket.sendto(data)
 
     # Called when the subscription to the TX characteristic has changed
     def on_tx_subscription(self, peer, enabled):
-        print(f'### [GATT TX] subscription from {peer}: {"enabled" if enabled else "disabled"}')
+        print(
+            f'### [GATT TX] subscription from {peer}: '
+            f'{"enabled" if enabled else "disabled"}'
+        )
         if enabled:
             self.tx_subscriber = peer
         else:
@@ -290,7 +309,15 @@ class GattlinkNodeBridge(GattlinkL2capEndpoint, Device.Listener):
 
 
 # -----------------------------------------------------------------------------
-async def run(hci_transport, device_address, role_or_peer_address, send_host, send_port, receive_host, receive_port):
+async def run(
+    hci_transport,
+    device_address,
+    role_or_peer_address,
+    send_host,
+    send_port,
+    receive_host,
+    receive_port,
+):
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
@@ -307,14 +334,13 @@ async def run(hci_transport, device_address, role_or_peer_address, send_host, se
         # Create a UDP to RX bridge (receive from UDP, send to RX)
         loop = asyncio.get_running_loop()
         await loop.create_datagram_endpoint(
-            lambda: bridge,
-            local_addr=(receive_host, receive_port)
+            lambda: bridge, local_addr=(receive_host, receive_port)
         )
 
         # Create a UDP to TX bridge (receive from TX, send to UDP)
         bridge.tx_socket, _ = await loop.create_datagram_endpoint(
-            lambda: asyncio.DatagramProtocol(),
-            remote_addr=(send_host, send_port)
+            asyncio.DatagramProtocol,
+            remote_addr=(send_host, send_port),
         )
 
         await device.power_on()
@@ -328,15 +354,43 @@ async def run(hci_transport, device_address, role_or_peer_address, send_host, se
 @click.argument('hci_transport')
 @click.argument('device_address')
 @click.argument('role_or_peer_address')
-@click.option('-sh', '--send-host', type=str, default='127.0.0.1', help='UDP host to send to')
+@click.option(
+    '-sh', '--send-host', type=str, default='127.0.0.1', help='UDP host to send to'
+)
 @click.option('-sp', '--send-port', type=int, default=9001, help='UDP port to send to')
-@click.option('-rh', '--receive-host', type=str, default='127.0.0.1', help='UDP host to receive on')
-@click.option('-rp', '--receive-port', type=int, default=9000, help='UDP port to receive on')
-def main(hci_transport, device_address, role_or_peer_address, send_host, send_port, receive_host, receive_port):
-    asyncio.run(run(hci_transport, device_address, role_or_peer_address, send_host, send_port, receive_host, receive_port))
+@click.option(
+    '-rh',
+    '--receive-host',
+    type=str,
+    default='127.0.0.1',
+    help='UDP host to receive on',
+)
+@click.option(
+    '-rp', '--receive-port', type=int, default=9000, help='UDP port to receive on'
+)
+def main(
+    hci_transport,
+    device_address,
+    role_or_peer_address,
+    send_host,
+    send_port,
+    receive_host,
+    receive_port,
+):
+    asyncio.run(
+        run(
+            hci_transport,
+            device_address,
+            role_or_peer_address,
+            send_host,
+            send_port,
+            receive_host,
+            receive_port,
+        )
+    )
 
 
 # -----------------------------------------------------------------------------
-logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 if __name__ == '__main__':
     main()

apps/hci_bridge.py

@@ -34,16 +34,29 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 async def async_main():
     if len(sys.argv) < 3:
-        print('Usage: hci_bridge.py <host-transport-spec> <controller-transport-spec> [command-short-circuit-list]')
-        print('example: python hci_bridge.py udp:0.0.0.0:9000,127.0.0.1:9001 serial:/dev/tty.usbmodem0006839912171,1000000 0x3f:0x0070,0x3f:0x0074,0x3f:0x0077,0x3f:0x0078')
+        print(
+            'Usage: hci_bridge.py <host-transport-spec> <controller-transport-spec> '
+            '[command-short-circuit-list]'
+        )
+        print(
+            'example: python hci_bridge.py udp:0.0.0.0:9000,127.0.0.1:9001 '
+            'serial:/dev/tty.usbmodem0006839912171,1000000 '
+            '0x3f:0x0070,0x3f:0x0074,0x3f:0x0077,0x3f:0x0078'
+        )
         return
 
     print('>>> connecting to HCI...')
-    async with await transport.open_transport_or_link(sys.argv[1]) as (hci_host_source, hci_host_sink):
+    async with await transport.open_transport_or_link(sys.argv[1]) as (
+        hci_host_source,
+        hci_host_sink,
+    ):
         print('>>> connected')
 
         print('>>> connecting to HCI...')
-        async with await transport.open_transport_or_link(sys.argv[2]) as (hci_controller_source, hci_controller_sink):
+        async with await transport.open_transport_or_link(sys.argv[2]) as (
+            hci_controller_source,
+            hci_controller_sink,
+        ):
             print('>>> connected')
 
             command_short_circuits = []
@@ -51,36 +64,43 @@ async def async_main():
                 for op_code_str in sys.argv[3].split(','):
                     if ':' in op_code_str:
                         ogf, ocf = op_code_str.split(':')
-                        command_short_circuits.append(hci.hci_command_op_code(int(ogf, 16), int(ocf, 16)))
+                        command_short_circuits.append(
+                            hci.hci_command_op_code(int(ogf, 16), int(ocf, 16))
+                        )
                     else:
                         command_short_circuits.append(int(op_code_str, 16))
 
             def host_to_controller_filter(hci_packet):
-                if hci_packet.hci_packet_type == hci.HCI_COMMAND_PACKET and hci_packet.op_code in command_short_circuits:
+                if (
+                    hci_packet.hci_packet_type == hci.HCI_COMMAND_PACKET
+                    and hci_packet.op_code in command_short_circuits
+                ):
                     # Respond with a success response
                     logger.debug('short-circuiting packet')
                     response = hci.HCI_Command_Complete_Event(
-                        num_hci_command_packets = 1,
-                        command_opcode          = hci_packet.op_code,
-                        return_parameters       = bytes([hci.HCI_SUCCESS])
+                        num_hci_command_packets=1,
+                        command_opcode=hci_packet.op_code,
+                        return_parameters=bytes([hci.HCI_SUCCESS]),
                     )
                     # Return a packet with 'respond to sender' set to True
                     return (response.to_bytes(), True)
 
+                return None
+
             _ = HCI_Bridge(
                 hci_host_source,
                 hci_host_sink,
                 hci_controller_source,
                 hci_controller_sink,
                 host_to_controller_filter,
-                None
+                None,
             )
             await asyncio.get_running_loop().create_future()
 
 
 # -----------------------------------------------------------------------------
 def main():
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
     asyncio.run(async_main())
 
 

apps/l2cap_bridge.py

@@ -16,11 +16,11 @@
 # Imports
 # -----------------------------------------------------------------------------
 import asyncio
-import click
 import logging
 import os
-from colors import color
+import click
 
+from bumble.colors import color
 from bumble.transport import open_transport_or_link
 from bumble.device import Device
 from bumble.utils import FlowControlAsyncPipe
@@ -38,36 +38,32 @@ class ServerBridge:
     and waits for a new L2CAP CoC channel to be connected.
     When the TCP connection is closed by the TCP server, XXXX
     """
-    def __init__(
-        self,
-        psm,
-        max_credits,
-        mtu,
-        mps,
-        tcp_host,
-        tcp_port
-    ):
-        self.psm         = psm
+
+    def __init__(self, psm, max_credits, mtu, mps, tcp_host, tcp_port):
+        self.psm = psm
         self.max_credits = max_credits
-        self.mtu         = mtu
-        self.mps         = mps
-        self.tcp_host    = tcp_host
-        self.tcp_port    = tcp_port
+        self.mtu = mtu
+        self.mps = mps
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
 
     async def start(self, device):
         # Listen for incoming L2CAP CoC connections
         device.register_l2cap_channel_server(
-            psm         = self.psm,
-            server      = self.on_coc,
-            max_credits = self.max_credits,
-            mtu         = self.mtu,
-            mps         = self.mps
+            psm=self.psm,
+            server=self.on_coc,
+            max_credits=self.max_credits,
+            mtu=self.mtu,
+            mps=self.mps,
         )
         print(color(f'### Listening for CoC connection on PSM {self.psm}', 'yellow'))
 
         def on_ble_connection(connection):
             def on_ble_disconnection(reason):
-                print(color('@@@ Bluetooth disconnection:', 'red'), HCI_Constant.error_name(reason))
+                print(
+                    color('@@@ Bluetooth disconnection:', 'red'),
+                    HCI_Constant.error_name(reason),
+                )
 
             print(color('@@@ Bluetooth connection:', 'green'), connection)
             connection.on('disconnection', on_ble_disconnection)
@@ -82,7 +78,7 @@ class ServerBridge:
 
         class Pipe:
             def __init__(self, bridge, l2cap_channel):
-                self.bridge        = bridge
+                self.bridge = bridge
                 self.tcp_transport = None
                 self.l2cap_channel = l2cap_channel
 
@@ -91,23 +87,32 @@ class ServerBridge:
 
             async def connect_to_tcp(self):
                 # Connect to the TCP server
-                print(color(f'### Connecting to TCP {self.bridge.tcp_host}:{self.bridge.tcp_port}...', 'yellow'))
+                print(
+                    color(
+                        f'### Connecting to TCP {self.bridge.tcp_host}:'
+                        f'{self.bridge.tcp_port}...',
+                        'yellow',
+                    )
+                )
 
                 class TcpClientProtocol(asyncio.Protocol):
                     def __init__(self, pipe):
                         self.pipe = pipe
 
-                    def connection_lost(self, error):
-                        print(color(f'!!! TCP connection lost: {error}', 'red'))
+                    def connection_lost(self, exc):
+                        print(color(f'!!! TCP connection lost: {exc}', 'red'))
                         if self.pipe.l2cap_channel is not None:
                             asyncio.create_task(self.pipe.l2cap_channel.disconnect())
 
                     def data_received(self, data):
-                        print(f'<<< Received on TCP: {len(data)}')
+                        print(color(f'<<< [TCP DATA]: {len(data)} bytes', 'blue'))
                         self.pipe.l2cap_channel.write(data)
 
                 try:
-                    self.tcp_transport, _ = await asyncio.get_running_loop().create_connection(
+                    (
+                        self.tcp_transport,
+                        _,
+                    ) = await asyncio.get_running_loop().create_connection(
                         lambda: TcpClientProtocol(self),
                         host=self.bridge.tcp_host,
                         port=self.bridge.tcp_port,
@@ -118,6 +123,7 @@ class ServerBridge:
                     await self.l2cap_channel.disconnect()
 
             def on_l2cap_close(self):
+                print(color('*** L2CAP channel closed', 'red'))
                 self.l2cap_channel = None
                 if self.tcp_transport is not None:
                     self.tcp_transport.close()
@@ -149,23 +155,14 @@ class ClientBridge:
 
     READ_CHUNK_SIZE = 4096
 
-    def __init__(
-        self,
-        psm,
-        max_credits,
-        mtu,
-        mps,
-        address,
-        tcp_host,
-        tcp_port
-    ):
-        self.psm         = psm
+    def __init__(self, psm, max_credits, mtu, mps, address, tcp_host, tcp_port):
+        self.psm = psm
         self.max_credits = max_credits
-        self.mtu         = mtu
-        self.mps         = mps
-        self.address     = address
-        self.tcp_host    = tcp_host
-        self.tcp_port    = tcp_port
+        self.mtu = mtu
+        self.mps = mps
+        self.address = address
+        self.tcp_host = tcp_host
+        self.tcp_port = tcp_port
 
     async def start(self, device):
         print(color(f'### Connecting to {self.address}...', 'yellow'))
@@ -174,14 +171,17 @@ class ClientBridge:
 
         # Called when the BLE connection is disconnected
         def on_ble_disconnection(reason):
-            print(color('@@@ Bluetooth disconnection:', 'red'), HCI_Constant.error_name(reason))
+            print(
+                color('@@@ Bluetooth disconnection:', 'red'),
+                HCI_Constant.error_name(reason),
+            )
 
         connection.on('disconnection', on_ble_disconnection)
 
         # Called when a TCP connection is established
         async def on_tcp_connection(reader, writer):
-            peername = writer.get_extra_info('peername')
-            print(color(f'<<< TCP connection from {peername}', 'magenta'))
+            peer_name = writer.get_extra_info('peer_name')
+            print(color(f'<<< TCP connection from {peer_name}', 'magenta'))
 
             def on_coc_sdu(sdu):
                 print(color(f'<<< [L2CAP SDU]: {len(sdu)} bytes', 'cyan'))
@@ -196,10 +196,10 @@ class ClientBridge:
             print(color(f'>>> Opening L2CAP channel on PSM = {self.psm}', 'yellow'))
             try:
                 l2cap_channel = await connection.open_l2cap_channel(
-                    psm         = self.psm,
-                    max_credits = self.max_credits,
-                    mtu         = self.mtu,
-                    mps         = self.mps
+                    psm=self.psm,
+                    max_credits=self.max_credits,
+                    mtu=self.mtu,
+                    mps=self.mps,
                 )
                 print(color('*** L2CAP channel:', 'cyan'), l2cap_channel)
             except Exception as error:
@@ -215,7 +215,7 @@ class ClientBridge:
                 l2cap_channel.pause_reading,
                 l2cap_channel.resume_reading,
                 writer.write,
-                writer.drain
+                writer.drain,
             )
             l2cap_to_tcp_pipe.start()
 
@@ -242,9 +242,13 @@ class ClientBridge:
         await asyncio.start_server(
             on_tcp_connection,
             host=self.tcp_host if self.tcp_host != '_' else None,
-            port=self.tcp_port
+            port=self.tcp_port,
+        )
+        print(
+            color(
+                f'### Listening for TCP connections on port {self.tcp_port}', 'magenta'
+            )
         )
-        print(color(f'### Listening for TCP connections on port {self.tcp_port}', 'magenta'))
 
 
 # -----------------------------------------------------------------------------
@@ -266,20 +270,43 @@ async def run(device_config, hci_transport, bridge):
 # -----------------------------------------------------------------------------
 @click.group()
 @click.pass_context
-@click.option('--device-config',         help='Device configuration file', required=True)
-@click.option('--hci-transport',         help='HCI transport', required=True)
-@click.option('--psm',                   help='PSM for L2CAP CoC', type=int, default=1234)
-@click.option('--l2cap-coc-max-credits', help='Maximum L2CAP CoC Credits', type=click.IntRange(1, 65535), default=128)
-@click.option('--l2cap-coc-mtu',         help='L2CAP CoC MTU', type=click.IntRange(23, 65535), default=1022)
-@click.option('--l2cap-coc-mps',         help='L2CAP CoC MPS', type=click.IntRange(23, 65533), default=1024)
-def cli(context, device_config, hci_transport, psm, l2cap_coc_max_credits, l2cap_coc_mtu, l2cap_coc_mps):
+@click.option('--device-config', help='Device configuration file', required=True)
+@click.option('--hci-transport', help='HCI transport', required=True)
+@click.option('--psm', help='PSM for L2CAP CoC', type=int, default=1234)
+@click.option(
+    '--l2cap-coc-max-credits',
+    help='Maximum L2CAP CoC Credits',
+    type=click.IntRange(1, 65535),
+    default=128,
+)
+@click.option(
+    '--l2cap-coc-mtu',
+    help='L2CAP CoC MTU',
+    type=click.IntRange(23, 65535),
+    default=1022,
+)
+@click.option(
+    '--l2cap-coc-mps',
+    help='L2CAP CoC MPS',
+    type=click.IntRange(23, 65533),
+    default=1024,
+)
+def cli(
+    context,
+    device_config,
+    hci_transport,
+    psm,
+    l2cap_coc_max_credits,
+    l2cap_coc_mtu,
+    l2cap_coc_mps,
+):
     context.ensure_object(dict)
     context.obj['device_config'] = device_config
     context.obj['hci_transport'] = hci_transport
-    context.obj['psm']           = psm
-    context.obj['max_credits']   = l2cap_coc_max_credits
-    context.obj['mtu']           = l2cap_coc_mtu
-    context.obj['mps']           = l2cap_coc_mps
+    context.obj['psm'] = psm
+    context.obj['max_credits'] = l2cap_coc_max_credits
+    context.obj['mtu'] = l2cap_coc_mtu
+    context.obj['mps'] = l2cap_coc_mps
 
 
 # -----------------------------------------------------------------------------
@@ -294,12 +321,9 @@ def server(context, tcp_host, tcp_port):
         context.obj['mtu'],
         context.obj['mps'],
         tcp_host,
-        tcp_port)
-    asyncio.run(run(
-        context.obj['device_config'],
-        context.obj['hci_transport'],
-        bridge
-    ))
+        tcp_port,
+    )
+    asyncio.run(run(context.obj['device_config'], context.obj['hci_transport'], bridge))
 
 
 # -----------------------------------------------------------------------------
@@ -316,16 +340,12 @@ def client(context, bluetooth_address, tcp_host, tcp_port):
         context.obj['mps'],
         bluetooth_address,
         tcp_host,
-        tcp_port
+        tcp_port,
     )
-    asyncio.run(run(
-        context.obj['device_config'],
-        context.obj['hci_transport'],
-        bridge
-    ))
+    asyncio.run(run(context.obj['device_config'], context.obj['hci_transport'], bridge))
 
 
 # -----------------------------------------------------------------------------
-logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 if __name__ == '__main__':
-    cli(obj={})
+    cli(obj={})  # pylint: disable=no-value-for-parameter

apps/link_relay/link_relay.py

@@ -16,7 +16,6 @@
 # Imports
 # ----------------------------------------------------------------------------
 import sys
-import websockets
 import logging
 import json
 import asyncio
@@ -24,7 +23,9 @@ import argparse
 import uuid
 import os
 from urllib.parse import urlparse
-from colors import color
+import websockets
+
+from bumble.colors import color
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -65,9 +66,9 @@ class Connection:
     """
 
     def __init__(self, room, websocket):
-        self.room      = room
+        self.room = room
         self.websocket = websocket
-        self.address   = str(uuid.uuid4())
+        self.address = str(uuid.uuid4())
 
     async def send_message(self, message):
         try:
@@ -98,7 +99,11 @@ class Connection:
         self.address = address
 
     def __str__(self):
-        return f'Connection(address="{self.address}", client={self.websocket.remote_address[0]}:{self.websocket.remote_address[1]})'
+        return (
+            f'Connection(address="{self.address}", '
+            f'client={self.websocket.remote_address[0]}:'
+            f'{self.websocket.remote_address[1]})'
+        )
 
 
 # ----------------------------------------------------------------------------
@@ -110,9 +115,9 @@ class Room:
     """
 
     def __init__(self, relay, name):
-        self.relay       = relay
-        self.name        = name
-        self.observers   = []
+        self.relay = relay
+        self.name = name
+        self.observers = []
         self.connections = []
 
     async def add_connection(self, connection):
@@ -139,13 +144,15 @@ class Room:
 
             # Parse the message to decide how to handle it
             if message.startswith('@'):
-                # This is a targetted message
-                await self.on_targetted_message(connection, message)
+                # This is a targeted message
+                await self.on_targeted_message(connection, message)
             elif message.startswith('/'):
                 # This is an RPC request
                 await self.on_rpc_request(connection, message)
             else:
-                await connection.send_message(f'result:{error_to_json("error: invalid message")}')
+                await connection.send_message(
+                    f'result:{error_to_json("error: invalid message")}'
+                )
 
     async def broadcast_message(self, sender, message):
         '''
@@ -155,7 +162,9 @@ class Room:
 
     async def on_rpc_request(self, connection, message):
         command, *params = message.split(' ', 1)
-        if handler := getattr(self, f'on_{command[1:].lower().replace("-","_")}_command', None):
+        if handler := getattr(
+            self, f'on_{command[1:].lower().replace("-","_")}_command', None
+        ):
             try:
                 result = await handler(connection, params)
             except Exception as error:
@@ -165,7 +174,7 @@ class Room:
 
         await connection.send_message(result or 'result:{}')
 
-    async def on_targetted_message(self, connection, message):
+    async def on_targeted_message(self, connection, message):
         target, *payload = message.split(' ', 1)
         if not payload:
             return error_to_json('missing arguments')
@@ -174,7 +183,8 @@ class Room:
 
         # Determine what targets to send to
         if target == '*':
-            # Send to all connections in the room except the connection from which the message was received
+            # Send to all connections in the room except the connection from which the
+            # message was received
             connections = [c for c in self.connections if c != connection]
         else:
             connections = self.find_connections_by_address(target)
@@ -192,7 +202,9 @@ class Room:
         current_address = connection.address
         new_address = params[0]
         connection.set_address(new_address)
-        await self.broadcast_message(connection, f'address-changed:from={current_address},to={new_address}')
+        await self.broadcast_message(
+            connection, f'address-changed:from={current_address},to={new_address}'
+        )
 
 
 # ----------------------------------------------------------------------------
@@ -210,9 +222,10 @@ class Relay:
     def start(self):
         logger.info(f'Starting Relay on port {self.port}')
 
+        # pylint: disable-next=no-member
         return websockets.serve(self.serve, '0.0.0.0', self.port, ping_interval=None)
 
-    async def serve_as_controller(connection):
+    async def serve_as_controller(self, connection):
         pass
 
     async def serve(self, websocket, path):
@@ -246,24 +259,24 @@ def main():
         print('ERROR: Python 3.6.1 or higher is required')
         sys.exit(1)
 
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
 
     # Parse arguments
     arg_parser = argparse.ArgumentParser(description='Bumble Link Relay')
     arg_parser.add_argument('--log-level', default='INFO', help='logger level')
     arg_parser.add_argument('--log-config', help='logger config file (YAML)')
-    arg_parser.add_argument('--port',
-                            type = int,
-                            default = DEFAULT_RELAY_PORT,
-                            help = 'Port to listen on')
+    arg_parser.add_argument(
+        '--port', type=int, default=DEFAULT_RELAY_PORT, help='Port to listen on'
+    )
     args = arg_parser.parse_args()
 
     # Setup logger
     if args.log_config:
-        from logging import config
+        from logging import config  # pylint: disable=import-outside-toplevel
+
         config.fileConfig(args.log_config)
     else:
-        logging.basicConfig(level = getattr(logging, args.log_level.upper()))
+        logging.basicConfig(level=getattr(logging, args.log_level.upper()))
 
     # Start a relay
     relay = Relay(args.port)

apps/pair.py

@@ -19,12 +19,12 @@ import asyncio
 import os
 import logging
 import click
-import aioconsole
-from colors import color
+from prompt_toolkit.shortcuts import PromptSession
 
+from bumble.colors import color
 from bumble.device import Device, Peer
 from bumble.transport import open_transport_or_link
-from bumble.smp import PairingDelegate, PairingConfig
+from bumble.pairing import PairingDelegate, PairingConfig
 from bumble.smp import error_name as smp_error_name
 from bumble.keys import JsonKeyStore
 from bumble.core import ProtocolError
@@ -33,30 +33,57 @@ from bumble.gatt import (
     GATT_GENERIC_ACCESS_SERVICE,
     Service,
     Characteristic,
-    CharacteristicValue
+    CharacteristicValue,
 )
 from bumble.att import (
     ATT_Error,
     ATT_INSUFFICIENT_AUTHENTICATION_ERROR,
-    ATT_INSUFFICIENT_ENCRYPTION_ERROR
+    ATT_INSUFFICIENT_ENCRYPTION_ERROR,
 )
 
 
 # -----------------------------------------------------------------------------
-class Delegate(PairingDelegate):
-    def __init__(self, mode, connection, capability_string, prompt):
-        super().__init__({
-            'keyboard':         PairingDelegate.KEYBOARD_INPUT_ONLY,
-            'display':          PairingDelegate.DISPLAY_OUTPUT_ONLY,
-            'display+keyboard': PairingDelegate.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT,
-            'display+yes/no':   PairingDelegate.DISPLAY_OUTPUT_AND_YES_NO_INPUT,
-            'none':             PairingDelegate.NO_OUTPUT_NO_INPUT
-        }[capability_string.lower()])
+class Waiter:
+    instance = None
 
-        self.mode      = mode
-        self.peer      = Peer(connection)
+    def __init__(self):
+        self.done = asyncio.get_running_loop().create_future()
+
+    def terminate(self):
+        self.done.set_result(None)
+
+    async def wait_until_terminated(self):
+        return await self.done
+
+
+# -----------------------------------------------------------------------------
+class Delegate(PairingDelegate):
+    def __init__(self, mode, connection, capability_string, do_prompt):
+        super().__init__(
+            {
+                'keyboard': PairingDelegate.KEYBOARD_INPUT_ONLY,
+                'display': PairingDelegate.DISPLAY_OUTPUT_ONLY,
+                'display+keyboard': PairingDelegate.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT,
+                'display+yes/no': PairingDelegate.DISPLAY_OUTPUT_AND_YES_NO_INPUT,
+                'none': PairingDelegate.NO_OUTPUT_NO_INPUT,
+            }[capability_string.lower()]
+        )
+
+        self.mode = mode
+        self.peer = Peer(connection)
         self.peer_name = None
-        self.prompt    = prompt
+        self.do_prompt = do_prompt
+
+    def print(self, message):
+        print(color(message, 'yellow'))
+
+    async def prompt(self, message):
+        # Wait a bit to allow some of the log lines to print before we prompt
+        await asyncio.sleep(1)
+
+        session = PromptSession(message)
+        response = await session.prompt_async()
+        return response.lower().strip()
 
     async def update_peer_name(self):
         if self.peer_name is not None:
@@ -71,87 +98,103 @@ class Delegate(PairingDelegate):
             self.peer_name = '[?]'
 
     async def accept(self):
-        if self.prompt:
+        if self.do_prompt:
             await self.update_peer_name()
 
-            # Wait a bit to allow some of the log lines to print before we prompt
-            await asyncio.sleep(1)
-
             # Prompt for acceptance
-            print(color('###-----------------------------------', 'yellow'))
-            print(color(f'### Pairing request from {self.peer_name}', 'yellow'))
-            print(color('###-----------------------------------', 'yellow'))
+            self.print('###-----------------------------------')
+            self.print(f'### Pairing request from {self.peer_name}')
+            self.print('###-----------------------------------')
             while True:
-                response = await aioconsole.ainput(color('>>> Accept? ', 'yellow'))
-                response = response.lower().strip()
+                response = await self.prompt('>>> Accept? ')
+
                 if response == 'yes':
                     return True
-                elif response == 'no':
+
+                if response == 'no':
                     return False
-        else:
-            # Accept silently
-            return True
+
+        # Accept silently
+        return True
 
     async def compare_numbers(self, number, digits):
         await self.update_peer_name()
 
-        # Wait a bit to allow some of the log lines to print before we prompt
-        await asyncio.sleep(1)
-
         # Prompt for a numeric comparison
-        print(color('###-----------------------------------', 'yellow'))
-        print(color(f'### Pairing with {self.peer_name}', 'yellow'))
-        print(color('###-----------------------------------', 'yellow'))
+        self.print('###-----------------------------------')
+        self.print(f'### Pairing with {self.peer_name}')
+        self.print('###-----------------------------------')
         while True:
-            response = await aioconsole.ainput(color(f'>>> Does the other device display {number:0{digits}}? ', 'yellow'))
-            response = response.lower().strip()
+            response = await self.prompt(
+                f'>>> Does the other device display {number:0{digits}}? '
+            )
+
             if response == 'yes':
                 return True
-            elif response == 'no':
+
+            if response == 'no':
                 return False
 
     async def get_number(self):
         await self.update_peer_name()
 
-        # Wait a bit to allow some of the log lines to print before we prompt
-        await asyncio.sleep(1)
-
         # Prompt for a PIN
         while True:
             try:
-                print(color('###-----------------------------------', 'yellow'))
-                print(color(f'### Pairing with {self.peer_name}', 'yellow'))
-                print(color('###-----------------------------------', 'yellow'))
-                return int(await aioconsole.ainput(color('>>> Enter PIN: ', 'yellow')))
+                self.print('###-----------------------------------')
+                self.print(f'### Pairing with {self.peer_name}')
+                self.print('###-----------------------------------')
+                return int(await self.prompt('>>> Enter PIN: '))
             except ValueError:
                 pass
 
     async def display_number(self, number, digits):
         await self.update_peer_name()
 
-        # Wait a bit to allow some of the log lines to print before we prompt
-        await asyncio.sleep(1)
-
         # Display a PIN code
-        print(color('###-----------------------------------', 'yellow'))
-        print(color(f'### Pairing with {self.peer_name}', 'yellow'))
-        print(color(f'### PIN: {number:0{digits}}', 'yellow'))
-        print(color('###-----------------------------------', 'yellow'))
+        self.print('###-----------------------------------')
+        self.print(f'### Pairing with {self.peer_name}')
+        self.print(f'### PIN: {number:0{digits}}')
+        self.print('###-----------------------------------')
+
+    async def get_string(self, max_length: int):
+        await self.update_peer_name()
+
+        # Prompt a PIN (for legacy pairing in classic)
+        self.print('###-----------------------------------')
+        self.print(f'### Pairing with {self.peer_name}')
+        self.print('###-----------------------------------')
+        count = 0
+        while True:
+            response = await self.prompt('>>> Enter PIN (1-6 chars):')
+            if len(response) == 0:
+                count += 1
+                if count > 3:
+                    self.print('too many tries, stopping the pairing')
+                    return None
+
+                self.print('no PIN was entered, try again')
+                continue
+            return response
 
 
 # -----------------------------------------------------------------------------
 async def get_peer_name(peer, mode):
     if mode == 'classic':
         return await peer.request_name()
-    else:
-        # Try to get the peer name from GATT
-        services = await peer.discover_service(GATT_GENERIC_ACCESS_SERVICE)
-        if not services:
-            return None
 
-        values = await peer.read_characteristics_by_uuid(GATT_DEVICE_NAME_CHARACTERISTIC, services[0])
-        if values:
-            return values[0].decode('utf-8')
+    # Try to get the peer name from GATT
+    services = await peer.discover_service(GATT_GENERIC_ACCESS_SERVICE)
+    if not services:
+        return None
+
+    values = await peer.read_characteristics_by_uuid(
+        GATT_DEVICE_NAME_CHARACTERISTIC, services[0]
+    )
+    if values:
+        return values[0].decode('utf-8')
+
+    return None
 
 
 # -----------------------------------------------------------------------------
@@ -164,12 +207,12 @@ def read_with_error(connection):
 
     if AUTHENTICATION_ERROR_RETURNED[0]:
         return bytes([1])
-    else:
-        AUTHENTICATION_ERROR_RETURNED[0] = True
-        raise ATT_Error(ATT_INSUFFICIENT_AUTHENTICATION_ERROR)
+
+    AUTHENTICATION_ERROR_RETURNED[0] = True
+    raise ATT_Error(ATT_INSUFFICIENT_AUTHENTICATION_ERROR)
 
 
-def write_with_error(connection, value):
+def write_with_error(connection, _value):
     if not connection.is_encrypted:
         raise ATT_Error(ATT_INSUFFICIENT_ENCRYPTION_ERROR)
 
@@ -183,14 +226,14 @@ def on_connection(connection, request):
     print(color(f'<<< Connection: {connection}', 'green'))
 
     # Listen for pairing events
-    connection.on('pairing_start',   on_pairing_start)
-    connection.on('pairing',         on_pairing)
+    connection.on('pairing_start', on_pairing_start)
+    connection.on('pairing', lambda keys: on_pairing(connection.peer_address, keys))
     connection.on('pairing_failure', on_pairing_failure)
 
     # Listen for encryption changes
     connection.on(
         'connection_encryption_change',
-        lambda: on_connection_encryption_change(connection)
+        lambda: on_connection_encryption_change(connection),
     )
 
     # Request pairing if needed
@@ -202,7 +245,12 @@ def on_connection(connection, request):
 # -----------------------------------------------------------------------------
 def on_connection_encryption_change(connection):
     print(color('@@@-----------------------------------', 'blue'))
-    print(color(f'@@@ Connection is {"" if connection.is_encrypted else "not"}encrypted', 'blue'))
+    print(
+        color(
+            f'@@@ Connection is {"" if connection.is_encrypted else "not"}encrypted',
+            'blue',
+        )
+    )
     print(color('@@@-----------------------------------', 'blue'))
 
 
@@ -214,11 +262,12 @@ def on_pairing_start():
 
 
 # -----------------------------------------------------------------------------
-def on_pairing(keys):
+def on_pairing(address, keys):
     print(color('***-----------------------------------', 'cyan'))
-    print(color('*** Paired!', 'cyan'))
+    print(color(f'*** Paired! (peer identity={address})', 'cyan'))
     keys.print(prefix=color('*** ', 'cyan'))
     print(color('***-----------------------------------', 'cyan'))
+    Waiter.instance.terminate()
 
 
 # -----------------------------------------------------------------------------
@@ -226,6 +275,7 @@ def on_pairing_failure(reason):
     print(color('***-----------------------------------', 'red'))
     print(color(f'*** Pairing failed: {smp_error_name(reason)}', 'red'))
     print(color('***-----------------------------------', 'red'))
+    Waiter.instance.terminate()
 
 
 # -----------------------------------------------------------------------------
@@ -234,6 +284,7 @@ async def pair(
     sc,
     mitm,
     bond,
+    ctkd,
     io,
     prompt,
     request,
@@ -241,8 +292,10 @@ async def pair(
     keystore_file,
     device_config,
     hci_transport,
-    address_or_name
+    address_or_name,
 ):
+    Waiter.instance = Waiter()
+
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(hci_transport) as (hci_source, hci_sink):
         print('<<< connected')
@@ -250,17 +303,6 @@ async def pair(
         # Create a device to manage the host
         device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
 
-        # Set a custom keystore if specified on the command line
-        if keystore_file:
-            device.keystore = JsonKeyStore(namespace=None, filename=keystore_file)
-
-        # Print the existing keys before pairing
-        if print_keys and device.keystore:
-            print(color('@@@-----------------------------------', 'blue'))
-            print(color('@@@ Pairing Keys:', 'blue'))
-            await device.keystore.print(prefix=color('@@@ ', 'blue'))
-            print(color('@@@-----------------------------------', 'blue'))
-
         # Expose a GATT characteristic that can be used to trigger pairing by
         # responding with an authentication error when read
         if mode == 'le':
@@ -270,11 +312,14 @@ async def pair(
                     [
                         Characteristic(
                             '552957FB-CF1F-4A31-9535-E78847E1A714',
-                            Characteristic.READ | Characteristic.WRITE,
+                            Characteristic.Properties.READ
+                            | Characteristic.Properties.WRITE,
                             Characteristic.READABLE | Characteristic.WRITEABLE,
-                            CharacteristicValue(read=read_with_error, write=write_with_error)
+                            CharacteristicValue(
+                                read=read_with_error, write=write_with_error
+                            ),
                         )
-                    ]
+                    ],
                 )
             )
 
@@ -282,16 +327,25 @@ async def pair(
         if mode == 'classic':
             device.classic_enabled = True
             device.le_enabled = False
+            device.classic_smp_enabled = ctkd
 
         # Get things going
         await device.power_on()
 
+        # Set a custom keystore if specified on the command line
+        if keystore_file:
+            device.keystore = JsonKeyStore.from_device(device, filename=keystore_file)
+
+        # Print the existing keys before pairing
+        if print_keys and device.keystore:
+            print(color('@@@-----------------------------------', 'blue'))
+            print(color('@@@ Pairing Keys:', 'blue'))
+            await device.keystore.print(prefix=color('@@@ ', 'blue'))
+            print(color('@@@-----------------------------------', 'blue'))
+
         # Set up a pairing config factory
         device.pairing_config_factory = lambda connection: PairingConfig(
-            sc,
-            mitm,
-            bond,
-            Delegate(mode, connection, io, prompt)
+            sc, mitm, bond, Delegate(mode, connection, io, prompt)
         )
 
         # Connect to a peer or wait for a connection
@@ -311,29 +365,114 @@ async def pair(
                     print(color(f'Pairing failed: {error}', 'red'))
                     return
         else:
-            # Advertise so that peers can find us and connect
-            await device.start_advertising(auto_restart=True)
+            if mode == 'le':
+                # Advertise so that peers can find us and connect
+                await device.start_advertising(auto_restart=True)
+            else:
+                # Become discoverable and connectable
+                await device.set_discoverable(True)
+                await device.set_connectable(True)
 
-        await hci_source.wait_for_termination()
+        # Run until the user asks to exit
+        await Waiter.instance.wait_until_terminated()
+
+
+# -----------------------------------------------------------------------------
+class LogHandler(logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self.setFormatter(logging.Formatter('%(levelname)s:%(name)s:%(message)s'))
+
+    def emit(self, record):
+        message = self.format(record)
+        print(message)
 
 
 # -----------------------------------------------------------------------------
 @click.command()
-@click.option('--mode', type=click.Choice(['le', 'classic']), default='le', show_default=True)
-@click.option('--sc', type=bool, default=True, help='Use the Secure Connections protocol', show_default=True)
-@click.option('--mitm', type=bool, default=True, help='Request MITM protection', show_default=True)
-@click.option('--bond', type=bool, default=True, help='Enable bonding', show_default=True)
-@click.option('--io', type=click.Choice(['keyboard', 'display', 'display+keyboard', 'display+yes/no', 'none']), default='display+keyboard', show_default=True)
+@click.option(
+    '--mode', type=click.Choice(['le', 'classic']), default='le', show_default=True
+)
+@click.option(
+    '--sc',
+    type=bool,
+    default=True,
+    help='Use the Secure Connections protocol',
+    show_default=True,
+)
+@click.option(
+    '--mitm', type=bool, default=True, help='Request MITM protection', show_default=True
+)
+@click.option(
+    '--bond', type=bool, default=True, help='Enable bonding', show_default=True
+)
+@click.option(
+    '--ctkd',
+    type=bool,
+    default=True,
+    help='Enable CTKD',
+    show_default=True,
+)
+@click.option(
+    '--io',
+    type=click.Choice(
+        ['keyboard', 'display', 'display+keyboard', 'display+yes/no', 'none']
+    ),
+    default='display+keyboard',
+    show_default=True,
+)
 @click.option('--prompt', is_flag=True, help='Prompt to accept/reject pairing request')
-@click.option('--request', is_flag=True, help='Request that the connecting peer initiate pairing')
+@click.option(
+    '--request', is_flag=True, help='Request that the connecting peer initiate pairing'
+)
 @click.option('--print-keys', is_flag=True, help='Print the bond keys before pairing')
-@click.option('--keystore-file', help='File in which to store the pairing keys')
+@click.option(
+    '--keystore-file',
+    metavar='<filename>',
+    help='File in which to store the pairing keys',
+)
 @click.argument('device-config')
 @click.argument('hci_transport')
 @click.argument('address-or-name', required=False)
-def main(mode, sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, hci_transport, address_or_name):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
-    asyncio.run(pair(mode, sc, mitm, bond, io, prompt, request, print_keys, keystore_file, device_config, hci_transport, address_or_name))
+def main(
+    mode,
+    sc,
+    mitm,
+    bond,
+    ctkd,
+    io,
+    prompt,
+    request,
+    print_keys,
+    keystore_file,
+    device_config,
+    hci_transport,
+    address_or_name,
+):
+    # Setup logging
+    log_handler = LogHandler()
+    root_logger = logging.getLogger()
+    root_logger.addHandler(log_handler)
+    root_logger.setLevel(os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+
+    # Pair
+    asyncio.run(
+        pair(
+            mode,
+            sc,
+            mitm,
+            bond,
+            ctkd,
+            io,
+            prompt,
+            request,
+            print_keys,
+            keystore_file,
+            device_config,
+            hci_transport,
+            address_or_name,
+        )
+    )
 
 
 # -----------------------------------------------------------------------------

apps/pandora_server.py

@@ -0,0 +1,49 @@
+import asyncio
+import click
+import logging
+import json
+
+from bumble.pandora import PandoraDevice, serve
+from typing import Dict, Any
+
+BUMBLE_SERVER_GRPC_PORT = 7999
+ROOTCANAL_PORT_CUTTLEFISH = 7300
+
+
+@click.command()
+@click.option('--grpc-port', help='gRPC port to serve', default=BUMBLE_SERVER_GRPC_PORT)
+@click.option(
+    '--rootcanal-port', help='Rootcanal TCP port', default=ROOTCANAL_PORT_CUTTLEFISH
+)
+@click.option(
+    '--transport',
+    help='HCI transport',
+    default=f'tcp-client:127.0.0.1:<rootcanal-port>',
+)
+@click.option(
+    '--config',
+    help='Bumble json configuration file',
+)
+def main(grpc_port: int, rootcanal_port: int, transport: str, config: str) -> None:
+    if '<rootcanal-port>' in transport:
+        transport = transport.replace('<rootcanal-port>', str(rootcanal_port))
+
+    bumble_config = retrieve_config(config)
+    if 'transport' not in bumble_config.keys():
+        bumble_config.update({'transport': transport})
+    device = PandoraDevice(bumble_config)
+
+    logging.basicConfig(level=logging.DEBUG)
+    asyncio.run(serve(device, port=grpc_port))
+
+
+def retrieve_config(config: str) -> Dict[str, Any]:
+    if not config:
+        return {}
+
+    with open(config, 'r') as f:
+        return json.load(f)
+
+
+if __name__ == '__main__':
+    main()  # pylint: disable=no-value-for-parameter

apps/scan.py

@@ -19,8 +19,8 @@ import asyncio
 import os
 import logging
 import click
-from colors import color
 
+from bumble.colors import color
 from bumble.device import Device
 from bumble.transport import open_transport_or_link
 from bumble.keys import JsonKeyStore
@@ -31,8 +31,8 @@ from bumble.hci import HCI_Constant, HCI_LE_1M_PHY, HCI_LE_CODED_PHY
 
 # -----------------------------------------------------------------------------
 def make_rssi_bar(rssi):
-    DISPLAY_MIN_RSSI       = -105
-    DISPLAY_MAX_RSSI       = -30
+    DISPLAY_MIN_RSSI = -105
+    DISPLAY_MAX_RSSI = -30
     DEFAULT_RSSI_BAR_WIDTH = 30
 
     blocks = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']
@@ -63,7 +63,9 @@ class AdvertisementPrinter:
                 resolution_qualifier = f'(resolved from {advertisement.address})'
                 address = resolved
 
-        address_type_string = ('PUBLIC', 'RANDOM', 'PUBLIC_ID', 'RANDOM_ID')[address.address_type]
+        address_type_string = ('PUBLIC', 'RANDOM', 'PUBLIC_ID', 'RANDOM_ID')[
+            address.address_type
+        ]
         if address.is_public:
             type_color = 'cyan'
         else:
@@ -90,10 +92,12 @@ class AdvertisementPrinter:
 
         print(
             f'>>> {color(address, address_color)} '
-            f'[{color(address_type_string, type_color)}]{address_qualifier}{resolution_qualifier}:{separator}'
+            f'[{color(address_type_string, type_color)}]{address_qualifier}'
+            f'{resolution_qualifier}:{separator}'
             f'{phy_info}'
             f'RSSI:{advertisement.rssi:4} {rssi_bar}{separator}'
-            f'{advertisement.data.to_string(separator)}\n')
+            f'{advertisement.data.to_string(separator)}\n'
+        )
 
     def on_advertisement(self, advertisement):
         self.print_advertisement(advertisement)
@@ -114,26 +118,31 @@ async def scan(
     raw,
     keystore_file,
     device_config,
-    transport
+    transport,
 ):
     print('<<< connecting to HCI...')
     async with await open_transport_or_link(transport) as (hci_source, hci_sink):
         print('<<< connected')
 
         if device_config:
-            device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
+            device = Device.from_config_file_with_hci(
+                device_config, hci_source, hci_sink
+            )
         else:
-            device = Device.with_hci('Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink)
+            device = Device.with_hci(
+                'Bumble', 'F0:F1:F2:F3:F4:F5', hci_source, hci_sink
+            )
+
+        await device.power_on()
 
         if keystore_file:
-            keystore = JsonKeyStore(namespace=None, filename=keystore_file)
-            device.keystore = keystore
-        else:
-            resolver = None
+            device.keystore = JsonKeyStore.from_device(device, filename=keystore_file)
 
         if device.keystore:
             resolving_keys = await device.keystore.get_resolving_keys()
             resolver = AddressResolver(resolving_keys)
+        else:
+            resolver = None
 
         printer = AdvertisementPrinter(min_rssi, resolver)
         if raw:
@@ -141,8 +150,6 @@ async def scan(
         else:
             device.on('advertisement', printer.on_advertisement)
 
-        await device.power_on()
-
         if phy is None:
             scanning_phys = [HCI_LE_1M_PHY, HCI_LE_CODED_PHY]
         else:
@@ -153,7 +160,7 @@ async def scan(
             scan_interval=scan_interval,
             scan_window=scan_window,
             filter_duplicates=filter_duplicates,
-            scanning_phys=scanning_phys
+            scanning_phys=scanning_phys,
         )
 
         await hci_source.wait_for_termination()
@@ -165,15 +172,51 @@ async def scan(
 @click.option('--passive', is_flag=True, default=False, help='Perform passive scanning')
 @click.option('--scan-interval', type=int, default=60, help='Scan interval')
 @click.option('--scan-window', type=int, default=60, help='Scan window')
-@click.option('--phy', type=click.Choice(['1m', 'coded']), help='Only scan on the specified PHY')
-@click.option('--filter-duplicates', type=bool, default=True, help='Filter duplicates at the controller level')
-@click.option('--raw', is_flag=True, default=False, help='Listen for raw advertising reports instead of processed ones')
+@click.option(
+    '--phy', type=click.Choice(['1m', 'coded']), help='Only scan on the specified PHY'
+)
+@click.option(
+    '--filter-duplicates',
+    type=bool,
+    default=True,
+    help='Filter duplicates at the controller level',
+)
+@click.option(
+    '--raw',
+    is_flag=True,
+    default=False,
+    help='Listen for raw advertising reports instead of processed ones',
+)
 @click.option('--keystore-file', help='Keystore file to use when resolving addresses')
 @click.option('--device-config', help='Device config file for the scanning device')
 @click.argument('transport')
-def main(min_rssi, passive, scan_interval, scan_window, phy, filter_duplicates, raw, keystore_file, device_config, transport):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
-    asyncio.run(scan(min_rssi, passive, scan_interval, scan_window, phy, filter_duplicates, raw, keystore_file, device_config, transport))
+def main(
+    min_rssi,
+    passive,
+    scan_interval,
+    scan_window,
+    phy,
+    filter_duplicates,
+    raw,
+    keystore_file,
+    device_config,
+    transport,
+):
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    asyncio.run(
+        scan(
+            min_rssi,
+            passive,
+            scan_interval,
+            scan_window,
+            phy,
+            filter_duplicates,
+            raw,
+            keystore_file,
+            device_config,
+            transport,
+        )
+    )
 
 
 # -----------------------------------------------------------------------------

apps/show.py

@@ -17,8 +17,8 @@
 # -----------------------------------------------------------------------------
 import struct
 import click
-from colors import color
 
+from bumble.colors import color
 from bumble import hci
 from bumble.transport.common import PacketReader
 from bumble.helpers import PacketTracer
@@ -27,13 +27,14 @@ from bumble.helpers import PacketTracer
 # -----------------------------------------------------------------------------
 class SnoopPacketReader:
     '''
-    Reader that reads HCI packets from a "snoop" file (based on RFC 1761, but not exactly the same...)
+    Reader that reads HCI packets from a "snoop" file (based on RFC 1761, but not
+    exactly the same...)
     '''
 
-    DATALINK_H1   = 1001
-    DATALINK_H4   = 1002
+    DATALINK_H1 = 1001
+    DATALINK_H4 = 1002
     DATALINK_BSCP = 1003
-    DATALINK_H5   = 1004
+    DATALINK_H5 = 1004
 
     def __init__(self, source):
         self.source = source
@@ -41,9 +42,13 @@ class SnoopPacketReader:
         # Read the header
         identification_pattern = source.read(8)
         if identification_pattern.hex().lower() != '6274736e6f6f7000':
-            raise ValueError('not a valid snoop file, unexpected identification pattern')
-        (self.version_number, self.data_link_type) = struct.unpack('>II', source.read(8))
-        if self.data_link_type != self.DATALINK_H4 and self.data_link_type != self.DATALINK_H1:
+            raise ValueError(
+                'not a valid snoop file, unexpected identification pattern'
+            )
+        (self.version_number, self.data_link_type) = struct.unpack(
+            '>II', source.read(8)
+        )
+        if self.data_link_type not in (self.DATALINK_H4, self.DATALINK_H1):
             raise ValueError(f'datalink type {self.data_link_type} not supported')
 
     def next_packet(self):
@@ -55,9 +60,9 @@ class SnoopPacketReader:
             original_length,
             included_length,
             packet_flags,
-            cumulative_drops,
-            timestamp_seconds,
-            timestamp_microsecond
+            _cumulative_drops,
+            _timestamp_seconds,
+            _timestamp_microsecond,
         ) = struct.unpack('>IIIIII', header)
 
         # Abort on truncated packets
@@ -79,24 +84,34 @@ class SnoopPacketReader:
                 else:
                     packet_type = hci.HCI_ACL_DATA_PACKET
 
-            return (packet_flags & 1, bytes([packet_type]) + self.source.read(included_length))
-        else:
-            return (packet_flags & 1, self.source.read(included_length))
+            return (
+                packet_flags & 1,
+                bytes([packet_type]) + self.source.read(included_length),
+            )
+
+        return (packet_flags & 1, self.source.read(included_length))
 
 
 # -----------------------------------------------------------------------------
 # Main
 # -----------------------------------------------------------------------------
 @click.command()
-@click.option('--format', type=click.Choice(['h4', 'snoop']), default='h4', help='Format of the input file')
+@click.option(
+    '--format',
+    type=click.Choice(['h4', 'snoop']),
+    default='h4',
+    help='Format of the input file',
+)
 @click.argument('filename')
+# pylint: disable=redefined-builtin
 def main(format, filename):
     input = open(filename, 'rb')
     if format == 'h4':
         packet_reader = PacketReader(input)
 
         def read_next_packet():
-            (0, packet_reader.next_packet())
+            return (0, packet_reader.next_packet())
+
     else:
         packet_reader = SnoopPacketReader(input)
         read_next_packet = packet_reader.next_packet
@@ -112,9 +127,8 @@ def main(format, filename):
 
         except Exception as error:
             print(color(f'!!! {error}', 'red'))
-            pass
 
 
 # -----------------------------------------------------------------------------
 if __name__ == '__main__':
-    main()
+    main()  # pylint: disable=no-value-for-parameter

apps/speaker/logo.svg

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!-- Created with Vectornator for iOS (http://vectornator.io/) --><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg height="100%" style="fill-rule:nonzero;clip-rule:evenodd;stroke-linecap:round;stroke-linejoin:round;" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="100%" xmlns:vectornator="http://vectornator.io" version="1.1" viewBox="0 0 745 744.634">
+<metadata>
+<vectornator:setting key="DimensionsVisible" value="1"/>
+<vectornator:setting key="PencilOnly" value="0"/>
+<vectornator:setting key="SnapToPoints" value="0"/>
+<vectornator:setting key="OutlineMode" value="0"/>
+<vectornator:setting key="CMYKEnabledKey" value="0"/>
+<vectornator:setting key="RulersVisible" value="1"/>
+<vectornator:setting key="SnapToEdges" value="0"/>
+<vectornator:setting key="GuidesVisible" value="1"/>
+<vectornator:setting key="DisplayWhiteBackground" value="0"/>
+<vectornator:setting key="doHistoryDisabled" value="0"/>
+<vectornator:setting key="SnapToGuides" value="1"/>
+<vectornator:setting key="TimeLapseWatermarkDisabled" value="0"/>
+<vectornator:setting key="Units" value="Pixels"/>
+<vectornator:setting key="DynamicGuides" value="0"/>
+<vectornator:setting key="IsolateActiveLayer" value="0"/>
+<vectornator:setting key="SnapToGrid" value="0"/>
+</metadata>
+<defs/>
+<g id="Layer 1" vectornator:layerName="Layer 1">
+<path stroke="#000000" stroke-width="18.6464" d="M368.753+729.441L58.8847+550.539L58.8848+192.734L368.753+13.8313L678.621+192.734L678.621+550.539L368.753+729.441Z" fill="#0082fc" stroke-linecap="butt" fill-opacity="0.307489" opacity="1" stroke-linejoin="round"/>
+<g opacity="1">
+<g opacity="1">
+<path stroke="#000000" stroke-width="20" d="M292.873+289.256L442.872+289.256L442.872+539.254L292.873+539.254L292.873+289.256Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="20" d="M292.873+289.256C292.873+247.835+326.452+214.257+367.873+214.257C409.294+214.257+442.872+247.835+442.872+289.256C442.872+330.677+409.294+364.256+367.873+364.256C326.452+364.256+292.873+330.677+292.873+289.256Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="20" d="M292.873+539.254C292.873+497.833+326.452+464.255+367.873+464.255C409.294+464.255+442.872+497.833+442.872+539.254C442.872+580.675+409.294+614.254+367.873+614.254C326.452+614.254+292.873+580.675+292.873+539.254Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#0082fc" stroke-width="0.1" d="M302.873+289.073L432.872+289.073L432.872+539.072L302.873+539.072L302.873+289.073Z" fill="#fcd100" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+</g>
+<path stroke="#000000" stroke-width="0.1" d="M103.161+309.167L226.956+443.903L366.671+309.604L103.161+309.167Z" fill="#0082fc" stroke-linecap="round" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="0.1" d="M383.411+307.076L508.887+440.112L650.5+307.507L383.411+307.076Z" fill="#0082fc" stroke-linecap="round" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="20" d="M522.045+154.808L229.559+448.882L83.8397+300.104L653.666+302.936L511.759+444.785L223.101+156.114" fill="none" stroke-linecap="round" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="61.8698" d="M295.857+418.738L438.9+418.738" fill="none" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#000000" stroke-width="61.8698" d="M295.857+521.737L438.9+521.737" fill="none" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<g opacity="1">
+<path stroke="#0082fc" stroke-width="0.1" d="M367.769+667.024L367.821+616.383L403.677+616.336C383.137+626.447+368.263+638.69+367.769+667.024Z" fill="#000000" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+<path stroke="#0082fc" stroke-width="0.1" d="M367.836+667.024L367.784+616.383L331.928+616.336C352.468+626.447+367.341+638.69+367.836+667.024Z" fill="#000000" stroke-linecap="butt" opacity="1" stroke-linejoin="round"/>
+</g>
+</g>
+</g>
+</svg>

apps/speaker/speaker.css

@@ -0,0 +1,76 @@
+body, h1, h2, h3, h4, h5, h6 {
+    font-family: sans-serif;
+}
+
+#controlsDiv {
+    margin: 6px;
+}
+
+#connectionText {
+    background-color: rgb(239, 89, 75);
+    border: none;
+    border-radius: 4px;
+    padding: 8px;
+    display: inline-block;
+    margin: 4px;
+}
+
+#startButton {
+    padding: 4px;
+    margin: 6px;
+}
+
+#fftCanvas {
+    border-radius: 16px;
+    margin: 6px;
+}
+
+#bandwidthCanvas {
+    border: grey;
+    border-style: solid;
+    border-radius: 8px;
+    margin: 6px;
+}
+
+#streamStateText {
+    background-color: rgb(93, 165, 93);
+    border: none;
+    border-radius: 8px;
+    padding: 10px 20px;
+    display: inline-block;
+    margin: 6px;
+}
+
+#connectionStateText {
+    background-color: rgb(112, 146, 206);
+    border: none;
+    border-radius: 8px;
+    padding: 10px 20px;
+    display: inline-block;
+    margin: 6px;
+}
+
+#propertiesTable {
+    border: grey;
+    border-style: solid;
+    border-radius: 4px;
+    padding: 4px;
+    margin: 6px;
+    margin-left: 0px;
+}
+
+th, td {
+    padding-left: 6px;
+    padding-right: 6px;
+}
+
+.properties td:nth-child(even) {
+    background-color: #D6EEEE;
+    font-family: monospace;
+}
+
+.properties td:nth-child(odd) {
+    font-weight: bold;
+}
+
+.properties tr td:nth-child(2) { width: 150px; }

apps/speaker/speaker.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Bumble Speaker</title>
+  <script type="text/javascript" src="speaker.js"></script>
+  <link rel="stylesheet" href="speaker.css">
+</head>
+<body>
+  <h1><img src="logo.svg" width=100 height=100 style="vertical-align:middle" alt=""/>Bumble Virtual Speaker</h1>
+  <div id="connectionText"></div>
+  <div id="speaker">
+    <table><tr>
+      <td>
+        <table id="propertiesTable" class="properties">
+          <tr><td>Codec</td><td><span id="codecText"></span></td></tr>
+          <tr><td>Packets</td><td><span id="packetsReceivedText"></span></td></tr>
+          <tr><td>Bytes</td><td><span id="bytesReceivedText"></span></td></tr>
+        </table>
+      </td>
+      <td>
+        <canvas id="bandwidthCanvas" width="500", height="100">Bandwidth Graph</canvas>
+      </td>
+    </tr></table>
+    <span id="streamStateText">IDLE</span>
+    <span id="connectionStateText">NOT CONNECTED</span>
+    <div id="controlsDiv">
+        <button id="audioOnButton">Audio On</button>
+        <span id="audioSupportMessageText"></span>
+    </div>
+    <canvas id="fftCanvas" width="1024", height="300">Audio Frequencies Animation</canvas>
+    <audio id="audio"></audio>
+  </div>
+</body>
+</html>

apps/speaker/speaker.js

@@ -0,0 +1,315 @@
+(function () {
+    'use strict';
+
+const channelUrl = ((window.location.protocol === "https:") ? "wss://" : "ws://") + window.location.host + "/channel";
+let channelSocket;
+let connectionText;
+let codecText;
+let packetsReceivedText;
+let bytesReceivedText;
+let streamStateText;
+let connectionStateText;
+let controlsDiv;
+let audioOnButton;
+let mediaSource;
+let sourceBuffer;
+let audioElement;
+let audioContext;
+let audioAnalyzer;
+let audioFrequencyBinCount;
+let audioFrequencyData;
+let packetsReceived = 0;
+let bytesReceived = 0;
+let audioState = "stopped";
+let streamState = "IDLE";
+let audioSupportMessageText;
+let fftCanvas;
+let fftCanvasContext;
+let bandwidthCanvas;
+let bandwidthCanvasContext;
+let bandwidthBinCount;
+let bandwidthBins = [];
+
+const FFT_WIDTH = 800;
+const FFT_HEIGHT = 256;
+const BANDWIDTH_WIDTH = 500;
+const BANDWIDTH_HEIGHT = 100;
+
+function hexToBytes(hex) {
+    return Uint8Array.from(hex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16)));
+}
+
+function init() {
+    initUI();
+    initMediaSource();
+    initAudioElement();
+    initAnalyzer();
+
+    connect();
+}
+
+function initUI() {
+    controlsDiv = document.getElementById("controlsDiv");
+    controlsDiv.style.visibility = "hidden";
+    connectionText = document.getElementById("connectionText");
+    audioOnButton = document.getElementById("audioOnButton");
+    codecText = document.getElementById("codecText");
+    packetsReceivedText = document.getElementById("packetsReceivedText");
+    bytesReceivedText = document.getElementById("bytesReceivedText");
+    streamStateText = document.getElementById("streamStateText");
+    connectionStateText = document.getElementById("connectionStateText");
+    audioSupportMessageText = document.getElementById("audioSupportMessageText");
+
+    audioOnButton.onclick = () => startAudio();
+
+    setConnectionText("");
+
+    requestAnimationFrame(onAnimationFrame);
+}
+
+function initMediaSource() {
+    mediaSource = new MediaSource();
+    mediaSource.onsourceopen = onMediaSourceOpen;
+    mediaSource.onsourceclose = onMediaSourceClose;
+    mediaSource.onsourceended = onMediaSourceEnd;
+}
+
+function initAudioElement() {
+    audioElement = document.getElementById("audio");
+    audioElement.src = URL.createObjectURL(mediaSource);
+    // audioElement.controls = true;
+}
+
+function initAnalyzer() {
+    fftCanvas = document.getElementById("fftCanvas");
+    fftCanvas.width = FFT_WIDTH
+    fftCanvas.height = FFT_HEIGHT
+    fftCanvasContext = fftCanvas.getContext('2d');
+    fftCanvasContext.fillStyle = "rgb(0, 0, 0)";
+    fftCanvasContext.fillRect(0, 0, FFT_WIDTH, FFT_HEIGHT);
+
+    bandwidthCanvas = document.getElementById("bandwidthCanvas");
+    bandwidthCanvas.width = BANDWIDTH_WIDTH
+    bandwidthCanvas.height = BANDWIDTH_HEIGHT
+    bandwidthCanvasContext = bandwidthCanvas.getContext('2d');
+    bandwidthCanvasContext.fillStyle = "rgb(255, 255, 255)";
+    bandwidthCanvasContext.fillRect(0, 0, BANDWIDTH_WIDTH, BANDWIDTH_HEIGHT);
+}
+
+function startAnalyzer() {
+    // FFT
+    if (audioElement.captureStream !== undefined) {
+        audioContext = new AudioContext();
+        audioAnalyzer = audioContext.createAnalyser();
+        audioAnalyzer.fftSize = 128;
+        audioFrequencyBinCount = audioAnalyzer.frequencyBinCount;
+        audioFrequencyData = new Uint8Array(audioFrequencyBinCount);
+        const stream = audioElement.captureStream();
+        const source = audioContext.createMediaStreamSource(stream);
+        source.connect(audioAnalyzer);
+    }
+
+    // Bandwidth
+    bandwidthBinCount = BANDWIDTH_WIDTH / 2;
+    bandwidthBins = [];
+}
+
+function setConnectionText(message) {
+    connectionText.innerText = message;
+    if (message.length == 0) {
+        connectionText.style.display = "none";
+    } else {
+        connectionText.style.display = "inline-block";
+    }
+}
+
+function setStreamState(state) {
+    streamState = state;
+    streamStateText.innerText = streamState;
+}
+
+function onAnimationFrame() {
+    // FFT
+    if (audioAnalyzer !== undefined) {
+        audioAnalyzer.getByteFrequencyData(audioFrequencyData);
+        fftCanvasContext.fillStyle = "rgb(0, 0, 0)";
+        fftCanvasContext.fillRect(0, 0, FFT_WIDTH, FFT_HEIGHT);
+        const barCount = audioFrequencyBinCount;
+        const barWidth = (FFT_WIDTH / audioFrequencyBinCount) - 1;
+        for (let bar = 0; bar < barCount; bar++) {
+            const barHeight = audioFrequencyData[bar];
+            fftCanvasContext.fillStyle = `rgb(${barHeight / 256 * 200 + 50}, 50, ${50 + 2 * bar})`;
+            fftCanvasContext.fillRect(bar * (barWidth + 1), FFT_HEIGHT - barHeight, barWidth, barHeight);
+        }
+    }
+
+    // Bandwidth
+    bandwidthCanvasContext.fillStyle = "rgb(255, 255, 255)";
+    bandwidthCanvasContext.fillRect(0, 0, BANDWIDTH_WIDTH, BANDWIDTH_HEIGHT);
+    bandwidthCanvasContext.fillStyle = `rgb(100, 100, 100)`;
+    for (let t = 0; t < bandwidthBins.length; t++) {
+        const lineHeight = (bandwidthBins[t] / 1000) * BANDWIDTH_HEIGHT;
+        bandwidthCanvasContext.fillRect(t * 2, BANDWIDTH_HEIGHT - lineHeight, 2, lineHeight);
+    }
+
+    // Display again at the next frame
+    requestAnimationFrame(onAnimationFrame);
+}
+
+function onMediaSourceOpen() {
+    console.log(this.readyState);
+    sourceBuffer = mediaSource.addSourceBuffer("audio/aac");
+}
+
+function onMediaSourceClose() {
+    console.log(this.readyState);
+}
+
+function onMediaSourceEnd() {
+    console.log(this.readyState);
+}
+
+async function startAudio() {
+    try {
+        console.log("starting audio...");
+        audioOnButton.disabled = true;
+        audioState = "starting";
+        await audioElement.play();
+        console.log("audio started");
+        audioState = "playing";
+        startAnalyzer();
+    } catch(error) {
+        console.error(`play failed: ${error}`);
+        audioState = "stopped";
+        audioOnButton.disabled = false;
+    }
+}
+
+function onAudioPacket(packet) {
+    if (audioState != "stopped") {
+        // Queue the audio packet.
+        sourceBuffer.appendBuffer(packet);
+    }
+
+    packetsReceived += 1;
+    packetsReceivedText.innerText = packetsReceived;
+    bytesReceived += packet.byteLength;
+    bytesReceivedText.innerText = bytesReceived;
+
+    bandwidthBins[bandwidthBins.length] = packet.byteLength;
+    if (bandwidthBins.length > bandwidthBinCount) {
+        bandwidthBins.shift();
+    }
+}
+
+function onChannelOpen() {
+    console.log('channel OPEN');
+    setConnectionText("");
+    controlsDiv.style.visibility = "visible";
+
+    // Handshake with the backend.
+    sendMessage({
+        type: "hello"
+    });
+}
+
+function onChannelClose() {
+    console.log('channel CLOSED');
+    setConnectionText("Connection to CLI app closed, restart it and reload this page.");
+    controlsDiv.style.visibility = "hidden";
+}
+
+function onChannelError(error) {
+    console.log(`channel ERROR: ${error}`);
+    setConnectionText(`Connection to CLI app error ({${error}}), restart it and reload this page.`);
+    controlsDiv.style.visibility = "hidden";
+}
+
+function onChannelMessage(message) {
+    if (typeof message.data === 'string' || message.data instanceof String) {
+        // JSON message.
+        const jsonMessage = JSON.parse(message.data);
+        console.log(`channel MESSAGE: ${message.data}`);
+
+        // Dispatch the message.
+        const handlerName = `on${jsonMessage.type.charAt(0).toUpperCase()}${jsonMessage.type.slice(1)}Message`
+        const handler = messageHandlers[handlerName];
+        if (handler !== undefined) {
+            const params = jsonMessage.params;
+            if (params === undefined) {
+                params = {};
+            }
+            handler(params);
+        } else {
+            console.warn(`unhandled message: ${jsonMessage.type}`)
+        }
+    } else {
+        // BINARY audio data.
+        onAudioPacket(message.data);
+    }
+}
+
+function onHelloMessage(params) {
+    codecText.innerText = params.codec;
+    if (params.codec != "aac") {
+        audioOnButton.disabled = true;
+        audioSupportMessageText.innerText = "Only AAC can be played, audio will be disabled";
+        audioSupportMessageText.style.display = "inline-block";
+    } else {
+        audioSupportMessageText.innerText = "";
+        audioSupportMessageText.style.display = "none";
+    }
+    if (params.streamState) {
+        setStreamState(params.streamState);
+    }
+}
+
+function onStartMessage(params) {
+    setStreamState("STARTED");
+}
+
+function onStopMessage(params) {
+    setStreamState("STOPPED");
+}
+
+function onSuspendMessage(params) {
+    setStreamState("SUSPENDED");
+}
+
+function onConnectionMessage(params) {
+    connectionStateText.innerText = `CONNECTED: ${params.peer_name} (${params.peer_address})`;
+}
+
+function onDisconnectionMessage(params) {
+    connectionStateText.innerText = "DISCONNECTED";
+}
+
+function sendMessage(message) {
+    channelSocket.send(JSON.stringify(message));
+}
+
+function connect() {
+    console.log("connecting to CLI app");
+
+    channelSocket = new WebSocket(channelUrl);
+    channelSocket.binaryType = "arraybuffer";
+    channelSocket.onopen = onChannelOpen;
+    channelSocket.onclose = onChannelClose;
+    channelSocket.onerror = onChannelError;
+    channelSocket.onmessage = onChannelMessage;
+}
+
+const messageHandlers = {
+    onHelloMessage,
+    onStartMessage,
+    onStopMessage,
+    onSuspendMessage,
+    onConnectionMessage,
+    onDisconnectionMessage
+}
+
+window.onload = (event) => {
+    init();
+}
+
+}());

apps/speaker/speaker.py

@@ -0,0 +1,737 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
+import asyncio.subprocess
+from importlib import resources
+import enum
+import json
+import os
+import logging
+import pathlib
+import subprocess
+from typing import Dict, List, Optional
+import weakref
+
+import click
+import aiohttp
+from aiohttp import web
+
+import bumble
+from bumble.colors import color
+from bumble.core import BT_BR_EDR_TRANSPORT, CommandTimeoutError
+from bumble.device import Connection, Device, DeviceConfiguration
+from bumble.hci import HCI_StatusError
+from bumble.pairing import PairingConfig
+from bumble.sdp import ServiceAttribute
+from bumble.transport import open_transport
+from bumble.avdtp import (
+    AVDTP_AUDIO_MEDIA_TYPE,
+    Listener,
+    MediaCodecCapabilities,
+    MediaPacket,
+    Protocol,
+)
+from bumble.a2dp import (
+    MPEG_2_AAC_LC_OBJECT_TYPE,
+    make_audio_sink_service_sdp_records,
+    A2DP_SBC_CODEC_TYPE,
+    A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+    SBC_MONO_CHANNEL_MODE,
+    SBC_DUAL_CHANNEL_MODE,
+    SBC_SNR_ALLOCATION_METHOD,
+    SBC_LOUDNESS_ALLOCATION_METHOD,
+    SBC_STEREO_CHANNEL_MODE,
+    SBC_JOINT_STEREO_CHANNEL_MODE,
+    SbcMediaCodecInformation,
+    AacMediaCodecInformation,
+)
+from bumble.utils import AsyncRunner
+from bumble.codecs import AacAudioRtpPacket
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_UI_PORT = 7654
+
+# -----------------------------------------------------------------------------
+class AudioExtractor:
+    @staticmethod
+    def create(codec: str):
+        if codec == 'aac':
+            return AacAudioExtractor()
+        if codec == 'sbc':
+            return SbcAudioExtractor()
+
+    def extract_audio(self, packet: MediaPacket) -> bytes:
+        raise NotImplementedError()
+
+
+# -----------------------------------------------------------------------------
+class AacAudioExtractor:
+    def extract_audio(self, packet: MediaPacket) -> bytes:
+        return AacAudioRtpPacket(packet.payload).to_adts()
+
+
+# -----------------------------------------------------------------------------
+class SbcAudioExtractor:
+    def extract_audio(self, packet: MediaPacket) -> bytes:
+        # header = packet.payload[0]
+        # fragmented = header >> 7
+        # start = (header >> 6) & 0x01
+        # last = (header >> 5) & 0x01
+        # number_of_frames = header & 0x0F
+
+        # TODO: support fragmented payloads
+        return packet.payload[1:]
+
+
+# -----------------------------------------------------------------------------
+class Output:
+    async def start(self) -> None:
+        pass
+
+    async def stop(self) -> None:
+        pass
+
+    async def suspend(self) -> None:
+        pass
+
+    async def on_connection(self, connection: Connection) -> None:
+        pass
+
+    async def on_disconnection(self, reason: int) -> None:
+        pass
+
+    def on_rtp_packet(self, packet: MediaPacket) -> None:
+        pass
+
+
+# -----------------------------------------------------------------------------
+class FileOutput(Output):
+    filename: str
+    codec: str
+    extractor: AudioExtractor
+
+    def __init__(self, filename, codec):
+        self.filename = filename
+        self.codec = codec
+        self.file = open(filename, 'wb')
+        self.extractor = AudioExtractor.create(codec)
+
+    def on_rtp_packet(self, packet: MediaPacket) -> None:
+        self.file.write(self.extractor.extract_audio(packet))
+
+
+# -----------------------------------------------------------------------------
+class QueuedOutput(Output):
+    MAX_QUEUE_SIZE = 32768
+
+    packets: asyncio.Queue
+    extractor: AudioExtractor
+    packet_pump_task: Optional[asyncio.Task]
+    started: bool
+
+    def __init__(self, extractor):
+        self.extractor = extractor
+        self.packets = asyncio.Queue()
+        self.packet_pump_task = None
+        self.started = False
+
+    async def start(self):
+        if self.started:
+            return
+
+        self.packet_pump_task = asyncio.create_task(self.pump_packets())
+
+    async def pump_packets(self):
+        while True:
+            packet = await self.packets.get()
+            await self.on_audio_packet(packet)
+
+    async def on_audio_packet(self, packet: bytes) -> None:
+        pass
+
+    def on_rtp_packet(self, packet: MediaPacket) -> None:
+        if self.packets.qsize() > self.MAX_QUEUE_SIZE:
+            logger.debug("queue full, dropping")
+            return
+
+        self.packets.put_nowait(self.extractor.extract_audio(packet))
+
+
+# -----------------------------------------------------------------------------
+class WebSocketOutput(QueuedOutput):
+    def __init__(self, codec, send_audio, send_message):
+        super().__init__(AudioExtractor.create(codec))
+        self.send_audio = send_audio
+        self.send_message = send_message
+
+    async def on_connection(self, connection: Connection) -> None:
+        try:
+            await connection.request_remote_name()
+        except HCI_StatusError:
+            pass
+        peer_name = '' if connection.peer_name is None else connection.peer_name
+        peer_address = str(connection.peer_address).replace('/P', '')
+        await self.send_message(
+            'connection',
+            peer_address=peer_address,
+            peer_name=peer_name,
+        )
+
+    async def on_disconnection(self, reason) -> None:
+        await self.send_message('disconnection')
+
+    async def on_audio_packet(self, packet: bytes) -> None:
+        await self.send_audio(packet)
+
+    async def start(self):
+        await super().start()
+        await self.send_message('start')
+
+    async def stop(self):
+        await super().stop()
+        await self.send_message('stop')
+
+    async def suspend(self):
+        await super().suspend()
+        await self.send_message('suspend')
+
+
+# -----------------------------------------------------------------------------
+class FfplayOutput(QueuedOutput):
+    MAX_QUEUE_SIZE = 32768
+
+    subprocess: Optional[asyncio.subprocess.Process]
+    ffplay_task: Optional[asyncio.Task]
+
+    def __init__(self, codec: str) -> None:
+        super().__init__(AudioExtractor.create(codec))
+        self.subprocess = None
+        self.ffplay_task = None
+        self.codec = codec
+
+    async def start(self):
+        if self.started:
+            return
+
+        await super().start()
+
+        self.subprocess = await asyncio.create_subprocess_shell(
+            f'ffplay -f {self.codec} pipe:0',
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        self.ffplay_task = asyncio.create_task(self.monitor_ffplay())
+
+    async def stop(self):
+        # TODO
+        pass
+
+    async def suspend(self):
+        # TODO
+        pass
+
+    async def monitor_ffplay(self):
+        async def read_stream(name, stream):
+            while True:
+                data = await stream.read()
+                logger.debug(f'{name}:', data)
+
+        await asyncio.wait(
+            [
+                asyncio.create_task(
+                    read_stream('[ffplay stdout]', self.subprocess.stdout)
+                ),
+                asyncio.create_task(
+                    read_stream('[ffplay stderr]', self.subprocess.stderr)
+                ),
+                asyncio.create_task(self.subprocess.wait()),
+            ]
+        )
+        logger.debug("FFPLAY done")
+
+    async def on_audio_packet(self, packet):
+        try:
+            self.subprocess.stdin.write(packet)
+        except Exception:
+            logger.warning('!!!! exception while sending audio to ffplay pipe')
+
+
+# -----------------------------------------------------------------------------
+class UiServer:
+    speaker: weakref.ReferenceType[Speaker]
+    port: int
+
+    def __init__(self, speaker: Speaker, port: int) -> None:
+        self.speaker = weakref.ref(speaker)
+        self.port = port
+        self.channel_socket = None
+
+    async def start_http(self) -> None:
+        """Start the UI HTTP server."""
+
+        app = web.Application()
+        app.add_routes(
+            [
+                web.get('/', self.get_static),
+                web.get('/speaker.html', self.get_static),
+                web.get('/speaker.js', self.get_static),
+                web.get('/speaker.css', self.get_static),
+                web.get('/logo.svg', self.get_static),
+                web.get('/channel', self.get_channel),
+            ]
+        )
+
+        runner = web.AppRunner(app)
+        await runner.setup()
+        site = web.TCPSite(runner, 'localhost', self.port)
+        print('UI HTTP server at ' + color(f'http://127.0.0.1:{self.port}', 'green'))
+        await site.start()
+
+    async def get_static(self, request):
+        path = request.path
+        if path == '/':
+            path = '/speaker.html'
+        if path.endswith('.html'):
+            content_type = 'text/html'
+        elif path.endswith('.js'):
+            content_type = 'text/javascript'
+        elif path.endswith('.css'):
+            content_type = 'text/css'
+        elif path.endswith('.svg'):
+            content_type = 'image/svg+xml'
+        else:
+            content_type = 'text/plain'
+        text = (
+            resources.files("bumble.apps.speaker")
+            .joinpath(pathlib.Path(path).relative_to('/'))
+            .read_text(encoding="utf-8")
+        )
+        return aiohttp.web.Response(text=text, content_type=content_type)
+
+    async def get_channel(self, request):
+        ws = web.WebSocketResponse()
+        await ws.prepare(request)
+
+        # Process messages until the socket is closed.
+        self.channel_socket = ws
+        async for message in ws:
+            if message.type == aiohttp.WSMsgType.TEXT:
+                logger.debug(f'<<< received message: {message.data}')
+                await self.on_message(message.data)
+            elif message.type == aiohttp.WSMsgType.ERROR:
+                logger.debug(
+                    f'channel connection closed with exception {ws.exception()}'
+                )
+
+        self.channel_socket = None
+        logger.debug('--- channel connection closed')
+
+        return ws
+
+    async def on_message(self, message_str: str):
+        # Parse the message as JSON
+        message = json.loads(message_str)
+
+        # Dispatch the message
+        message_type = message['type']
+        message_params = message.get('params', {})
+        handler = getattr(self, f'on_{message_type}_message')
+        if handler:
+            await handler(**message_params)
+
+    async def on_hello_message(self):
+        await self.send_message(
+            'hello',
+            bumble_version=bumble.__version__,
+            codec=self.speaker().codec,
+            streamState=self.speaker().stream_state.name,
+        )
+        if connection := self.speaker().connection:
+            await self.send_message(
+                'connection',
+                peer_address=str(connection.peer_address).replace('/P', ''),
+                peer_name=connection.peer_name,
+            )
+
+    async def send_message(self, message_type: str, **kwargs) -> None:
+        if self.channel_socket is None:
+            return
+
+        message = {'type': message_type, 'params': kwargs}
+        await self.channel_socket.send_json(message)
+
+    async def send_audio(self, data: bytes) -> None:
+        if self.channel_socket is None:
+            return
+
+        try:
+            await self.channel_socket.send_bytes(data)
+        except Exception as error:
+            logger.warning(f'exception while sending audio packet: {error}')
+
+
+# -----------------------------------------------------------------------------
+class Speaker:
+    class StreamState(enum.Enum):
+        IDLE = 0
+        STOPPED = 1
+        STARTED = 2
+        SUSPENDED = 3
+
+    def __init__(self, device_config, transport, codec, discover, outputs, ui_port):
+        self.device_config = device_config
+        self.transport = transport
+        self.codec = codec
+        self.discover = discover
+        self.ui_port = ui_port
+        self.device = None
+        self.connection = None
+        self.listener = None
+        self.packets_received = 0
+        self.bytes_received = 0
+        self.stream_state = Speaker.StreamState.IDLE
+        self.outputs = []
+        for output in outputs:
+            if output == '@ffplay':
+                self.outputs.append(FfplayOutput(codec))
+                continue
+
+            # Default to FileOutput
+            self.outputs.append(FileOutput(output, codec))
+
+        # Create an HTTP server for the UI
+        self.ui_server = UiServer(speaker=self, port=ui_port)
+
+    def sdp_records(self) -> Dict[int, List[ServiceAttribute]]:
+        service_record_handle = 0x00010001
+        return {
+            service_record_handle: make_audio_sink_service_sdp_records(
+                service_record_handle
+            )
+        }
+
+    def codec_capabilities(self) -> MediaCodecCapabilities:
+        if self.codec == 'aac':
+            return self.aac_codec_capabilities()
+
+        if self.codec == 'sbc':
+            return self.sbc_codec_capabilities()
+
+        raise RuntimeError('unsupported codec')
+
+    def aac_codec_capabilities(self) -> MediaCodecCapabilities:
+        return MediaCodecCapabilities(
+            media_type=AVDTP_AUDIO_MEDIA_TYPE,
+            media_codec_type=A2DP_MPEG_2_4_AAC_CODEC_TYPE,
+            media_codec_information=AacMediaCodecInformation.from_lists(
+                object_types=[MPEG_2_AAC_LC_OBJECT_TYPE],
+                sampling_frequencies=[48000, 44100],
+                channels=[1, 2],
+                vbr=1,
+                bitrate=256000,
+            ),
+        )
+
+    def sbc_codec_capabilities(self) -> MediaCodecCapabilities:
+        return MediaCodecCapabilities(
+            media_type=AVDTP_AUDIO_MEDIA_TYPE,
+            media_codec_type=A2DP_SBC_CODEC_TYPE,
+            media_codec_information=SbcMediaCodecInformation.from_lists(
+                sampling_frequencies=[48000, 44100, 32000, 16000],
+                channel_modes=[
+                    SBC_MONO_CHANNEL_MODE,
+                    SBC_DUAL_CHANNEL_MODE,
+                    SBC_STEREO_CHANNEL_MODE,
+                    SBC_JOINT_STEREO_CHANNEL_MODE,
+                ],
+                block_lengths=[4, 8, 12, 16],
+                subbands=[4, 8],
+                allocation_methods=[
+                    SBC_LOUDNESS_ALLOCATION_METHOD,
+                    SBC_SNR_ALLOCATION_METHOD,
+                ],
+                minimum_bitpool_value=2,
+                maximum_bitpool_value=53,
+            ),
+        )
+
+    async def dispatch_to_outputs(self, function):
+        for output in self.outputs:
+            await function(output)
+
+    def on_bluetooth_connection(self, connection):
+        print(f'Connection: {connection}')
+        self.connection = connection
+        connection.on('disconnection', self.on_bluetooth_disconnection)
+        AsyncRunner.spawn(
+            self.dispatch_to_outputs(lambda output: output.on_connection(connection))
+        )
+
+    def on_bluetooth_disconnection(self, reason):
+        print(f'Disconnection ({reason})')
+        self.connection = None
+        AsyncRunner.spawn(self.advertise())
+        AsyncRunner.spawn(
+            self.dispatch_to_outputs(lambda output: output.on_disconnection(reason))
+        )
+
+    def on_avdtp_connection(self, protocol):
+        print('Audio Stream Open')
+
+        # Add a sink endpoint to the server
+        sink = protocol.add_sink(self.codec_capabilities())
+        sink.on('start', self.on_sink_start)
+        sink.on('stop', self.on_sink_stop)
+        sink.on('suspend', self.on_sink_suspend)
+        sink.on('configuration', lambda: self.on_sink_configuration(sink.configuration))
+        sink.on('rtp_packet', self.on_rtp_packet)
+        sink.on('rtp_channel_open', self.on_rtp_channel_open)
+        sink.on('rtp_channel_close', self.on_rtp_channel_close)
+
+        # Listen for close events
+        protocol.on('close', self.on_avdtp_close)
+
+        # Discover all endpoints on the remote device is requested
+        if self.discover:
+            AsyncRunner.spawn(self.discover_remote_endpoints(protocol))
+
+    def on_avdtp_close(self):
+        print("Audio Stream Closed")
+
+    def on_sink_start(self):
+        print("Sink Started\u001b[0K")
+        self.stream_state = self.StreamState.STARTED
+        AsyncRunner.spawn(self.dispatch_to_outputs(lambda output: output.start()))
+
+    def on_sink_stop(self):
+        print("Sink Stopped\u001b[0K")
+        self.stream_state = self.StreamState.STOPPED
+        AsyncRunner.spawn(self.dispatch_to_outputs(lambda output: output.stop()))
+
+    def on_sink_suspend(self):
+        print("Sink Suspended\u001b[0K")
+        self.stream_state = self.StreamState.SUSPENDED
+        AsyncRunner.spawn(self.dispatch_to_outputs(lambda output: output.suspend()))
+
+    def on_sink_configuration(self, config):
+        print("Sink Configuration:")
+        print('\n'.join(["  " + str(capability) for capability in config]))
+
+    def on_rtp_channel_open(self):
+        print("RTP Channel Open")
+
+    def on_rtp_channel_close(self):
+        print("RTP Channel Closed")
+        self.stream_state = self.StreamState.IDLE
+
+    def on_rtp_packet(self, packet):
+        self.packets_received += 1
+        self.bytes_received += len(packet.payload)
+        print(
+            f'[{self.bytes_received} bytes in {self.packets_received} packets] {packet}',
+            end='\r',
+        )
+
+        for output in self.outputs:
+            output.on_rtp_packet(packet)
+
+    async def advertise(self):
+        await self.device.set_discoverable(True)
+        await self.device.set_connectable(True)
+
+    async def connect(self, address):
+        # Connect to the source
+        print(f'=== Connecting to {address}...')
+        connection = await self.device.connect(address, transport=BT_BR_EDR_TRANSPORT)
+        print(f'=== Connected to {connection.peer_address}')
+
+        # Request authentication
+        print('*** Authenticating...')
+        await connection.authenticate()
+        print('*** Authenticated')
+
+        # Enable encryption
+        print('*** Enabling encryption...')
+        await connection.encrypt()
+        print('*** Encryption on')
+
+        protocol = await Protocol.connect(connection)
+        self.listener.set_server(connection, protocol)
+        self.on_avdtp_connection(protocol)
+
+    async def discover_remote_endpoints(self, protocol):
+        endpoints = await protocol.discover_remote_endpoints()
+        print(f'@@@ Found {len(endpoints)} endpoints')
+        for endpoint in endpoints:
+            print('@@@', endpoint)
+
+    async def run(self, connect_address):
+        await self.ui_server.start_http()
+        self.outputs.append(
+            WebSocketOutput(
+                self.codec, self.ui_server.send_audio, self.ui_server.send_message
+            )
+        )
+
+        async with await open_transport(self.transport) as (hci_source, hci_sink):
+            # Create a device
+            device_config = DeviceConfiguration()
+            if self.device_config:
+                device_config.load_from_file(self.device_config)
+            else:
+                device_config.name = "Bumble Speaker"
+                device_config.class_of_device = 0x240414
+                device_config.keystore = "JsonKeyStore"
+
+            device_config.classic_enabled = True
+            device_config.le_enabled = False
+            self.device = Device.from_config_with_hci(
+                device_config, hci_source, hci_sink
+            )
+
+            # Setup the SDP to expose the sink service
+            self.device.sdp_service_records = self.sdp_records()
+
+            # Don't require MITM when pairing.
+            self.device.pairing_config_factory = lambda connection: PairingConfig(
+                mitm=False
+            )
+
+            # Start the controller
+            await self.device.power_on()
+
+            # Print some of the config/properties
+            print("Speaker Name:", color(device_config.name, 'yellow'))
+            print(
+                "Speaker Bluetooth Address:",
+                color(
+                    self.device.public_address.to_string(with_type_qualifier=False),
+                    'yellow',
+                ),
+            )
+
+            # Listen for Bluetooth connections
+            self.device.on('connection', self.on_bluetooth_connection)
+
+            # Create a listener to wait for AVDTP connections
+            self.listener = Listener(Listener.create_registrar(self.device))
+            self.listener.on('connection', self.on_avdtp_connection)
+
+            print(f'Speaker ready to play, codec={color(self.codec, "cyan")}')
+
+            if connect_address:
+                # Connect to the source
+                try:
+                    await self.connect(connect_address)
+                except CommandTimeoutError:
+                    print(color("Connection timed out", "red"))
+                    return
+            else:
+                # Start being discoverable and connectable
+                print("Waiting for connection...")
+                await self.advertise()
+
+            await hci_source.wait_for_termination()
+
+        for output in self.outputs:
+            await output.stop()
+
+
+# -----------------------------------------------------------------------------
+@click.group()
+@click.pass_context
+def speaker_cli(ctx, device_config):
+    ctx.ensure_object(dict)
+    ctx.obj['device_config'] = device_config
+
+
+@click.command()
+@click.option(
+    '--codec', type=click.Choice(['sbc', 'aac']), default='aac', show_default=True
+)
+@click.option(
+    '--discover', is_flag=True, help='Discover remote endpoints once connected'
+)
+@click.option(
+    '--output',
+    multiple=True,
+    metavar='NAME',
+    help=(
+        'Send audio to this named output '
+        '(may be used more than once for multiple outputs)'
+    ),
+)
+@click.option(
+    '--ui-port',
+    'ui_port',
+    metavar='HTTP_PORT',
+    default=DEFAULT_UI_PORT,
+    show_default=True,
+    help='HTTP port for the UI server',
+)
+@click.option(
+    '--connect',
+    'connect_address',
+    metavar='ADDRESS_OR_NAME',
+    help='Address or name to connect to',
+)
+@click.option('--device-config', metavar='FILENAME', help='Device configuration file')
+@click.argument('transport')
+def speaker(
+    transport, codec, connect_address, discover, output, ui_port, device_config
+):
+    """Run the speaker."""
+
+    if '@ffplay' in output:
+        # Check if ffplay is installed
+        try:
+            subprocess.run(['ffplay', '-version'], capture_output=True, check=True)
+        except FileNotFoundError:
+            print(
+                color('ffplay not installed, @ffplay output will be disabled', 'yellow')
+            )
+            output = list(filter(lambda x: x != '@ffplay', output))
+
+    asyncio.run(
+        Speaker(device_config, transport, codec, discover, output, ui_port).run(
+            connect_address
+        )
+    )
+
+
+# -----------------------------------------------------------------------------
+def main():
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    speaker()
+
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    main()  # pylint: disable=no-value-for-parameter

apps/unbond.py

@@ -22,40 +22,58 @@ import click
 
 from bumble.device import Device
 from bumble.keys import JsonKeyStore
+from bumble.transport import open_transport
+
+# -----------------------------------------------------------------------------
+async def unbond_with_keystore(keystore, address):
+    if address is None:
+        return await keystore.print()
+
+    try:
+        await keystore.delete(address)
+    except KeyError:
+        print('!!! pairing not found')
 
 
 # -----------------------------------------------------------------------------
-async def unbond(keystore_file, device_config, address):
-    # Create a device to manage the host
-    device = Device.from_config_file(device_config)
-
-    # Get all entries in the keystore
+async def unbond(keystore_file, device_config, hci_transport, address):
+    # With a keystore file, we can instantiate the keystore directly
     if keystore_file:
-        keystore = JsonKeyStore(None, keystore_file)
-    else:
-        keystore = device.keystore
+        return await unbond_with_keystore(JsonKeyStore(None, keystore_file), address)
 
-    if keystore is None:
-        print('no keystore')
-        return
+    # Without a keystore file, we need to obtain the keystore from the device
+    async with await open_transport(hci_transport) as (hci_source, hci_sink):
+        # Create a device to manage the host
+        device = Device.from_config_file_with_hci(device_config, hci_source, hci_sink)
 
-    if address is None:
-        await keystore.print()
-    else:
-        try:
-            await keystore.delete(address)
-        except KeyError:
-            print('!!! pairing not found')
+        # Power-on the device to ensure we have a key store
+        await device.power_on()
+
+        return await unbond_with_keystore(device.keystore, address)
 
 
 # -----------------------------------------------------------------------------
 @click.command()
-@click.option('--keystore-file', help='File in which to store the pairing keys')
-@click.argument('device-config')
+@click.option('--keystore-file', help='File in which the pairing keys are stored')
+@click.option('--hci-transport', help='HCI transport for the controller')
+@click.argument('device-config', required=False)
 @click.argument('address', required=False)
-def main(keystore_file, device_config, address):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
-    asyncio.run(unbond(keystore_file, device_config, address))
+def main(keystore_file, hci_transport, device_config, address):
+    """
+    Remove pairing keys for a device, given its address.
+
+    If no keystore file is specified, the --hci-transport option must be used to
+    connect to a controller, so that the keystore for that controller can be
+    instantiated.
+    If no address is passed, the existing pairing keys for all addresses are printed.
+    """
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'INFO').upper())
+
+    if not keystore_file and not hci_transport:
+        print('either --keystore-file or --hci-transport must be specified.')
+        return
+
+    asyncio.run(unbond(keystore_file, device_config, hci_transport, address))
 
 
 # -----------------------------------------------------------------------------

apps/usb_probe.py

@@ -28,18 +28,19 @@
 # -----------------------------------------------------------------------------
 import os
 import logging
-import sys
 import click
 import usb1
-from colors import color
+
+from bumble.colors import color
+from bumble.transport.usb import load_libusb
 
 
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
-USB_DEVICE_CLASS_DEVICE                          = 0x00
-USB_DEVICE_CLASS_WIRELESS_CONTROLLER             = 0xE0
-USB_DEVICE_SUBCLASS_RF_CONTROLLER                = 0x01
+USB_DEVICE_CLASS_DEVICE = 0x00
+USB_DEVICE_CLASS_WIRELESS_CONTROLLER = 0xE0
+USB_DEVICE_SUBCLASS_RF_CONTROLLER = 0x01
 USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER = 0x01
 
 USB_DEVICE_CLASSES = {
@@ -69,22 +70,22 @@ USB_DEVICE_CLASSES = {
                 0x01: 'Bluetooth',
                 0x02: 'UWB',
                 0x03: 'Remote NDIS',
-                0x04: 'Bluetooth AMP'
+                0x04: 'Bluetooth AMP',
             }
-        }
+        },
     ),
     0xEF: 'Miscellaneous',
     0xFE: 'Application Specific',
-    0xFF: 'Vendor Specific'
+    0xFF: 'Vendor Specific',
 }
 
-USB_ENDPOINT_IN    = 0x80
+USB_ENDPOINT_IN = 0x80
 USB_ENDPOINT_TYPES = ['CONTROL', 'ISOCHRONOUS', 'BULK', 'INTERRUPT']
 
 USB_BT_HCI_CLASS_TUPLE = (
     USB_DEVICE_CLASS_WIRELESS_CONTROLLER,
     USB_DEVICE_SUBCLASS_RF_CONTROLLER,
-    USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER
+    USB_DEVICE_PROTOCOL_BLUETOOTH_PRIMARY_CONTROLLER,
 )
 
 
@@ -94,19 +95,26 @@ def show_device_details(device):
         print(f'  Configuration {configuration.getConfigurationValue()}')
         for interface in configuration:
             for setting in interface:
-                alternateSetting = setting.getAlternateSetting()
-                suffix = f'/{alternateSetting}' if interface.getNumSettings() > 1 else ''
+                alternate_setting = setting.getAlternateSetting()
+                suffix = (
+                    f'/{alternate_setting}' if interface.getNumSettings() > 1 else ''
+                )
                 (class_string, subclass_string) = get_class_info(
-                    setting.getClass(),
-                    setting.getSubClass(),
-                    setting.getProtocol()
+                    setting.getClass(), setting.getSubClass(), setting.getProtocol()
                 )
                 details = f'({class_string}, {subclass_string})'
                 print(f'      Interface: {setting.getNumber()}{suffix} {details}')
                 for endpoint in setting:
                     endpoint_type = USB_ENDPOINT_TYPES[endpoint.getAttributes() & 3]
-                    endpoint_direction = 'OUT' if (endpoint.getAddress() & USB_ENDPOINT_IN == 0) else 'IN'
-                    print(f'        Endpoint 0x{endpoint.getAddress():02X}: {endpoint_type} {endpoint_direction}')
+                    endpoint_direction = (
+                        'OUT'
+                        if (endpoint.getAddress() & USB_ENDPOINT_IN == 0)
+                        else 'IN'
+                    )
+                    print(
+                        f'        Endpoint 0x{endpoint.getAddress():02X}: '
+                        f'{endpoint_type} {endpoint_direction}'
+                    )
 
 
 # -----------------------------------------------------------------------------
@@ -116,7 +124,7 @@ def get_class_info(cls, subclass, protocol):
     if class_info is None:
         class_string = f'0x{cls:02X}'
     else:
-        if type(class_info) is tuple:
+        if isinstance(class_info, tuple):
             class_string = class_info[0]
             subclass_info = class_info[1].get(subclass)
             if subclass_info:
@@ -135,7 +143,11 @@ def get_class_info(cls, subclass, protocol):
 # -----------------------------------------------------------------------------
 def is_bluetooth_hci(device):
     # Check if the device class indicates a match
-    if (device.getDeviceClass(), device.getDeviceSubClass(), device.getDeviceProtocol()) == USB_BT_HCI_CLASS_TUPLE:
+    if (
+        device.getDeviceClass(),
+        device.getDeviceSubClass(),
+        device.getDeviceProtocol(),
+    ) == USB_BT_HCI_CLASS_TUPLE:
         return True
 
     # If the device class is 'Device', look for a matching interface
@@ -143,7 +155,11 @@ def is_bluetooth_hci(device):
         for configuration in device:
             for interface in configuration:
                 for setting in interface:
-                    if (setting.getClass(), setting.getSubClass(), setting.getProtocol()) == USB_BT_HCI_CLASS_TUPLE:
+                    if (
+                        setting.getClass(),
+                        setting.getSubClass(),
+                        setting.getProtocol(),
+                    ) == USB_BT_HCI_CLASS_TUPLE:
                         return True
 
     return False
@@ -153,23 +169,22 @@ def is_bluetooth_hci(device):
 @click.command()
 @click.option('--verbose', is_flag=True, default=False, help='Print more details')
 def main(verbose):
-    logging.basicConfig(level = os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
+    logging.basicConfig(level=os.environ.get('BUMBLE_LOGLEVEL', 'WARNING').upper())
 
+    load_libusb()
     with usb1.USBContext() as context:
         bluetooth_device_count = 0
         devices = {}
 
         for device in context.getDeviceIterator(skip_on_error=True):
-            device_class    = device.getDeviceClass()
+            device_class = device.getDeviceClass()
             device_subclass = device.getDeviceSubClass()
             device_protocol = device.getDeviceProtocol()
 
             device_id = (device.getVendorID(), device.getProductID())
 
             (device_class_string, device_subclass_string) = get_class_info(
-                device_class,
-                device_subclass,
-                device_protocol
+                device_class, device_subclass, device_protocol
             )
 
             try:
@@ -198,7 +213,9 @@ def main(verbose):
 
             # Compute the different ways this can be referenced as a Bumble transport
             bumble_transport_names = []
-            basic_transport_name = f'usb:{device.getVendorID():04X}:{device.getProductID():04X}'
+            basic_transport_name = (
+                f'usb:{device.getVendorID():04X}:{device.getProductID():04X}'
+            )
 
             if device_is_bluetooth_hci:
                 bumble_transport_names.append(f'usb:{bluetooth_device_count - 1}')
@@ -206,17 +223,39 @@ def main(verbose):
             if device_id not in devices:
                 bumble_transport_names.append(basic_transport_name)
             else:
-                bumble_transport_names.append(f'{basic_transport_name}#{len(devices[device_id])}')
+                bumble_transport_names.append(
+                    f'{basic_transport_name}#{len(devices[device_id])}'
+                )
 
             if device_serial_number is not None:
-                if device_id not in devices or device_serial_number not in devices[device_id]:
-                    bumble_transport_names.append(f'{basic_transport_name}/{device_serial_number}')
+                if (
+                    device_id not in devices
+                    or device_serial_number not in devices[device_id]
+                ):
+                    bumble_transport_names.append(
+                        f'{basic_transport_name}/{device_serial_number}'
+                    )
 
             # Print the results
-            print(color(f'ID {device.getVendorID():04X}:{device.getProductID():04X}', fg=fg_color, bg=bg_color))
+            print(
+                color(
+                    f'ID {device.getVendorID():04X}:{device.getProductID():04X}',
+                    fg=fg_color,
+                    bg=bg_color,
+                )
+            )
             if bumble_transport_names:
-                print(color('  Bumble Transport Names:', 'blue'), ' or '.join(color(x, 'cyan' if device_is_bluetooth_hci else 'red') for x in bumble_transport_names))
-            print(color('  Bus/Device:            ', 'green'), f'{device.getBusNumber():03}/{device.getDeviceAddress():03}')
+                print(
+                    color('  Bumble Transport Names:', 'blue'),
+                    ' or '.join(
+                        color(x, 'cyan' if device_is_bluetooth_hci else 'red')
+                        for x in bumble_transport_names
+                    ),
+                )
+            print(
+                color('  Bus/Device:            ', 'green'),
+                f'{device.getBusNumber():03}/{device.getDeviceAddress():03}',
+            )
             print(color('  Class:                 ', 'green'), device_class_string)
             print(color('  Subclass/Protocol:     ', 'green'), device_subclass_string)
             if device_serial_number is not None:
@@ -236,4 +275,4 @@ def main(verbose):
 
 # -----------------------------------------------------------------------------
 if __name__ == '__main__':
-    main()
+    main()  # pylint: disable=no-value-for-parameter

bumble/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown version"

bumble/a2dp.py

@@ -16,10 +16,8 @@
 # Imports
 # -----------------------------------------------------------------------------
 import struct
-import bitstruct
 import logging
 from collections import namedtuple
-from colors import color
 
 from .company_ids import COMPANY_IDENTIFIERS
 from .sdp import (
@@ -30,7 +28,7 @@ from .sdp import (
     SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
     SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
     SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
-    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID
+    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
 )
 from .core import (
     BT_L2CAP_PROTOCOL_ID,
@@ -38,7 +36,7 @@ from .core import (
     BT_AUDIO_SINK_SERVICE,
     BT_AVDTP_PROTOCOL_ID,
     BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE,
-    name_or_number
+    name_or_number,
 )
 
 
@@ -51,6 +49,7 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+# fmt: off
 
 A2DP_SBC_CODEC_TYPE            = 0x00
 A2DP_MPEG_1_2_AUDIO_CODEC_TYPE = 0x01
@@ -127,71 +126,115 @@ MPEG_2_4_OBJECT_TYPE_NAMES = {
     MPEG_4_AAC_SCALABLE_OBJECT_TYPE: 'MPEG_4_AAC_SCALABLE_OBJECT_TYPE'
 }
 
+# fmt: on
+
 
 # -----------------------------------------------------------------------------
 def flags_to_list(flags, values):
     result = []
-    for i in range(len(values)):
+    for i, value in enumerate(values):
         if flags & (1 << (len(values) - i - 1)):
-            result.append(values[i])
+            result.append(value)
     return result
 
 
 # -----------------------------------------------------------------------------
 def make_audio_source_service_sdp_records(service_record_handle, version=(1, 3)):
+    # pylint: disable=import-outside-toplevel
     from .avdtp import AVDTP_PSM
+
     version_int = version[0] << 8 | version[1]
     return [
-        ServiceAttribute(SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID, DataElement.unsigned_integer_32(service_record_handle)),
-        ServiceAttribute(SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)
-        ])),
-        ServiceAttribute(SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.uuid(BT_AUDIO_SOURCE_SERVICE)
-        ])),
-        ServiceAttribute(SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.sequence([
-                DataElement.uuid(BT_L2CAP_PROTOCOL_ID),
-                DataElement.unsigned_integer_16(AVDTP_PSM)
-            ]),
-            DataElement.sequence([
-                DataElement.uuid(BT_AVDTP_PROTOCOL_ID),
-                DataElement.unsigned_integer_16(version_int)
-            ])
-        ])),
-        ServiceAttribute(SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
-            DataElement.unsigned_integer_16(version_int)
-        ])),
+        ServiceAttribute(
+            SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_32(service_record_handle),
+        ),
+        ServiceAttribute(
+            SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+            DataElement.sequence([DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)]),
+        ),
+        ServiceAttribute(
+            SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+            DataElement.sequence([DataElement.uuid(BT_AUDIO_SOURCE_SERVICE)]),
+        ),
+        ServiceAttribute(
+            SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_L2CAP_PROTOCOL_ID),
+                            DataElement.unsigned_integer_16(AVDTP_PSM),
+                        ]
+                    ),
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_AVDTP_PROTOCOL_ID),
+                            DataElement.unsigned_integer_16(version_int),
+                        ]
+                    ),
+                ]
+            ),
+        ),
+        ServiceAttribute(
+            SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
+                    DataElement.unsigned_integer_16(version_int),
+                ]
+            ),
+        ),
     ]
 
 
 # -----------------------------------------------------------------------------
 def make_audio_sink_service_sdp_records(service_record_handle, version=(1, 3)):
+    # pylint: disable=import-outside-toplevel
     from .avdtp import AVDTP_PSM
+
     version_int = version[0] << 8 | version[1]
     return [
-        ServiceAttribute(SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID, DataElement.unsigned_integer_32(service_record_handle)),
-        ServiceAttribute(SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)
-        ])),
-        ServiceAttribute(SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.uuid(BT_AUDIO_SINK_SERVICE)
-        ])),
-        ServiceAttribute(SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.sequence([
-                DataElement.uuid(BT_L2CAP_PROTOCOL_ID),
-                DataElement.unsigned_integer_16(AVDTP_PSM)
-            ]),
-            DataElement.sequence([
-                DataElement.uuid(BT_AVDTP_PROTOCOL_ID),
-                DataElement.unsigned_integer_16(version_int)
-            ])
-        ])),
-        ServiceAttribute(SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID, DataElement.sequence([
-            DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
-            DataElement.unsigned_integer_16(version_int)
-        ])),
+        ServiceAttribute(
+            SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_32(service_record_handle),
+        ),
+        ServiceAttribute(
+            SDP_BROWSE_GROUP_LIST_ATTRIBUTE_ID,
+            DataElement.sequence([DataElement.uuid(SDP_PUBLIC_BROWSE_ROOT)]),
+        ),
+        ServiceAttribute(
+            SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+            DataElement.sequence([DataElement.uuid(BT_AUDIO_SINK_SERVICE)]),
+        ),
+        ServiceAttribute(
+            SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_L2CAP_PROTOCOL_ID),
+                            DataElement.unsigned_integer_16(AVDTP_PSM),
+                        ]
+                    ),
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_AVDTP_PROTOCOL_ID),
+                            DataElement.unsigned_integer_16(version_int),
+                        ]
+                    ),
+                ]
+            ),
+        ),
+        ServiceAttribute(
+            SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.uuid(BT_ADVANCED_AUDIO_DISTRIBUTION_SERVICE),
+                    DataElement.unsigned_integer_16(version_int),
+                ]
+            ),
+        ),
     ]
 
 
@@ -206,45 +249,46 @@ class SbcMediaCodecInformation(
             'subbands',
             'allocation_method',
             'minimum_bitpool_value',
-            'maximum_bitpool_value'
-        ]
+            'maximum_bitpool_value',
+        ],
     )
 ):
     '''
     A2DP spec - 4.3.2 Codec Specific Information Elements
     '''
 
-    BIT_FIELDS = 'u4u4u4u2u2u8u8'
-    SAMPLING_FREQUENCY_BITS = {
-        16000: 1 << 3,
-        32000: 1 << 2,
-        44100: 1 << 1,
-        48000: 1
-    }
+    SAMPLING_FREQUENCY_BITS = {16000: 1 << 3, 32000: 1 << 2, 44100: 1 << 1, 48000: 1}
     CHANNEL_MODE_BITS = {
-        SBC_MONO_CHANNEL_MODE:         1 << 3,
-        SBC_DUAL_CHANNEL_MODE:         1 << 2,
-        SBC_STEREO_CHANNEL_MODE:       1 << 1,
-        SBC_JOINT_STEREO_CHANNEL_MODE: 1
-    }
-    BLOCK_LENGTH_BITS = {
-        4:  1 << 3,
-        8:  1 << 2,
-        12: 1 << 1,
-        16: 1
-    }
-    SUBBANDS_BITS = {
-        4: 1 << 1,
-        8: 1
+        SBC_MONO_CHANNEL_MODE: 1 << 3,
+        SBC_DUAL_CHANNEL_MODE: 1 << 2,
+        SBC_STEREO_CHANNEL_MODE: 1 << 1,
+        SBC_JOINT_STEREO_CHANNEL_MODE: 1,
     }
+    BLOCK_LENGTH_BITS = {4: 1 << 3, 8: 1 << 2, 12: 1 << 1, 16: 1}
+    SUBBANDS_BITS = {4: 1 << 1, 8: 1}
     ALLOCATION_METHOD_BITS = {
-        SBC_SNR_ALLOCATION_METHOD:      1 << 1,
-        SBC_LOUDNESS_ALLOCATION_METHOD: 1
+        SBC_SNR_ALLOCATION_METHOD: 1 << 1,
+        SBC_LOUDNESS_ALLOCATION_METHOD: 1,
     }
 
     @staticmethod
-    def from_bytes(data):
-        return SbcMediaCodecInformation(*bitstruct.unpack(SbcMediaCodecInformation.BIT_FIELDS, data))
+    def from_bytes(data: bytes) -> 'SbcMediaCodecInformation':
+        sampling_frequency = (data[0] >> 4) & 0x0F
+        channel_mode = (data[0] >> 0) & 0x0F
+        block_length = (data[1] >> 4) & 0x0F
+        subbands = (data[1] >> 2) & 0x03
+        allocation_method = (data[1] >> 0) & 0x03
+        minimum_bitpool_value = (data[2] >> 0) & 0xFF
+        maximum_bitpool_value = (data[3] >> 0) & 0xFF
+        return SbcMediaCodecInformation(
+            sampling_frequency,
+            channel_mode,
+            block_length,
+            subbands,
+            allocation_method,
+            minimum_bitpool_value,
+            maximum_bitpool_value,
+        )
 
     @classmethod
     def from_discrete_values(
@@ -255,16 +299,16 @@ class SbcMediaCodecInformation(
         subbands,
         allocation_method,
         minimum_bitpool_value,
-        maximum_bitpool_value
+        maximum_bitpool_value,
     ):
         return SbcMediaCodecInformation(
-            sampling_frequency    = cls.SAMPLING_FREQUENCY_BITS[sampling_frequency],
-            channel_mode          = cls.CHANNEL_MODE_BITS[channel_mode],
-            block_length          = cls.BLOCK_LENGTH_BITS[block_length],
-            subbands              = cls.SUBBANDS_BITS[subbands],
-            allocation_method     = cls.ALLOCATION_METHOD_BITS[allocation_method],
-            minimum_bitpool_value = minimum_bitpool_value,
-            maximum_bitpool_value = maximum_bitpool_value
+            sampling_frequency=cls.SAMPLING_FREQUENCY_BITS[sampling_frequency],
+            channel_mode=cls.CHANNEL_MODE_BITS[channel_mode],
+            block_length=cls.BLOCK_LENGTH_BITS[block_length],
+            subbands=cls.SUBBANDS_BITS[subbands],
+            allocation_method=cls.ALLOCATION_METHOD_BITS[allocation_method],
+            minimum_bitpool_value=minimum_bitpool_value,
+            maximum_bitpool_value=maximum_bitpool_value,
         )
 
     @classmethod
@@ -276,63 +320,71 @@ class SbcMediaCodecInformation(
         subbands,
         allocation_methods,
         minimum_bitpool_value,
-        maximum_bitpool_value
+        maximum_bitpool_value,
     ):
         return SbcMediaCodecInformation(
-            sampling_frequency    = sum(cls.SAMPLING_FREQUENCY_BITS[x] for x in sampling_frequencies),
-            channel_mode          = sum(cls.CHANNEL_MODE_BITS[x] for x in channel_modes),
-            block_length          = sum(cls.BLOCK_LENGTH_BITS[x] for x in block_lengths),
-            subbands              = sum(cls.SUBBANDS_BITS[x] for x in subbands),
-            allocation_method     = sum(cls.ALLOCATION_METHOD_BITS[x] for x in allocation_methods),
-            minimum_bitpool_value = minimum_bitpool_value,
-            maximum_bitpool_value = maximum_bitpool_value
+            sampling_frequency=sum(
+                cls.SAMPLING_FREQUENCY_BITS[x] for x in sampling_frequencies
+            ),
+            channel_mode=sum(cls.CHANNEL_MODE_BITS[x] for x in channel_modes),
+            block_length=sum(cls.BLOCK_LENGTH_BITS[x] for x in block_lengths),
+            subbands=sum(cls.SUBBANDS_BITS[x] for x in subbands),
+            allocation_method=sum(
+                cls.ALLOCATION_METHOD_BITS[x] for x in allocation_methods
+            ),
+            minimum_bitpool_value=minimum_bitpool_value,
+            maximum_bitpool_value=maximum_bitpool_value,
         )
 
-    def __bytes__(self):
-        return bitstruct.pack(self.BIT_FIELDS, *self)
+    def __bytes__(self) -> bytes:
+        return bytes(
+            [
+                (self.sampling_frequency << 4) | self.channel_mode,
+                (self.block_length << 4)
+                | (self.subbands << 2)
+                | self.allocation_method,
+                self.minimum_bitpool_value,
+                self.maximum_bitpool_value,
+            ]
+        )
 
     def __str__(self):
         channel_modes = ['MONO', 'DUAL_CHANNEL', 'STEREO', 'JOINT_STEREO']
         allocation_methods = ['SNR', 'Loudness']
-        return '\n'.join([
-            'SbcMediaCodecInformation(',
-            f'  sampling_frequency:    {",".join([str(x) for x in flags_to_list(self.sampling_frequency, SBC_SAMPLING_FREQUENCIES)])}',
-            f'  channel_mode:          {",".join([str(x) for x in flags_to_list(self.channel_mode, channel_modes)])}',
-            f'  block_length:          {",".join([str(x) for x in flags_to_list(self.block_length, SBC_BLOCK_LENGTHS)])}',
-            f'  subbands:              {",".join([str(x) for x in flags_to_list(self.subbands, SBC_SUBBANDS)])}',
-            f'  allocation_method:     {",".join([str(x) for x in flags_to_list(self.allocation_method, allocation_methods)])}',
-            f'  minimum_bitpool_value: {self.minimum_bitpool_value}',
-            f'  maximum_bitpool_value: {self.maximum_bitpool_value}'
-            ')'
-        ])
+        return '\n'.join(
+            # pylint: disable=line-too-long
+            [
+                'SbcMediaCodecInformation(',
+                f'  sampling_frequency:    {",".join([str(x) for x in flags_to_list(self.sampling_frequency, SBC_SAMPLING_FREQUENCIES)])}',
+                f'  channel_mode:          {",".join([str(x) for x in flags_to_list(self.channel_mode, channel_modes)])}',
+                f'  block_length:          {",".join([str(x) for x in flags_to_list(self.block_length, SBC_BLOCK_LENGTHS)])}',
+                f'  subbands:              {",".join([str(x) for x in flags_to_list(self.subbands, SBC_SUBBANDS)])}',
+                f'  allocation_method:     {",".join([str(x) for x in flags_to_list(self.allocation_method, allocation_methods)])}',
+                f'  minimum_bitpool_value: {self.minimum_bitpool_value}',
+                f'  maximum_bitpool_value: {self.maximum_bitpool_value}' ')',
+            ]
+        )
 
 
 # -----------------------------------------------------------------------------
 class AacMediaCodecInformation(
     namedtuple(
         'AacMediaCodecInformation',
-        [
-            'object_type',
-            'sampling_frequency',
-            'channels',
-            'vbr',
-            'bitrate'
-        ]
+        ['object_type', 'sampling_frequency', 'channels', 'rfa', 'vbr', 'bitrate'],
     )
 ):
     '''
     A2DP spec - 4.5.2 Codec Specific Information Elements
     '''
 
-    BIT_FIELDS = 'u8u12u2p2u1u23'
     OBJECT_TYPE_BITS = {
-        MPEG_2_AAC_LC_OBJECT_TYPE:       1 << 7,
-        MPEG_4_AAC_LC_OBJECT_TYPE:       1 << 6,
-        MPEG_4_AAC_LTP_OBJECT_TYPE:      1 << 5,
-        MPEG_4_AAC_SCALABLE_OBJECT_TYPE: 1 << 4
+        MPEG_2_AAC_LC_OBJECT_TYPE: 1 << 7,
+        MPEG_4_AAC_LC_OBJECT_TYPE: 1 << 6,
+        MPEG_4_AAC_LTP_OBJECT_TYPE: 1 << 5,
+        MPEG_4_AAC_SCALABLE_OBJECT_TYPE: 1 << 4,
     }
     SAMPLING_FREQUENCY_BITS = {
-        8000:  1 << 11,
+        8000: 1 << 11,
         11025: 1 << 10,
         12000: 1 << 9,
         16000: 1 << 8,
@@ -343,66 +395,83 @@ class AacMediaCodecInformation(
         48000: 1 << 3,
         64000: 1 << 2,
         88200: 1 << 1,
-        96000: 1
-    }
-    CHANNELS_BITS = {
-        1: 1 << 1,
-        2: 1
+        96000: 1,
     }
+    CHANNELS_BITS = {1: 1 << 1, 2: 1}
 
     @staticmethod
-    def from_bytes(data):
-        return AacMediaCodecInformation(*bitstruct.unpack(AacMediaCodecInformation.BIT_FIELDS, data))
+    def from_bytes(data: bytes) -> 'AacMediaCodecInformation':
+        object_type = data[0]
+        sampling_frequency = (data[1] << 4) | ((data[2] >> 4) & 0x0F)
+        channels = (data[2] >> 2) & 0x03
+        rfa = 0
+        vbr = (data[3] >> 7) & 0x01
+        bitrate = ((data[3] & 0x7F) << 16) | (data[4] << 8) | data[5]
+        return AacMediaCodecInformation(
+            object_type, sampling_frequency, channels, rfa, vbr, bitrate
+        )
 
     @classmethod
     def from_discrete_values(
-        cls,
-        object_type,
-        sampling_frequency,
-        channels,
-        vbr,
-        bitrate
+        cls, object_type, sampling_frequency, channels, vbr, bitrate
     ):
         return AacMediaCodecInformation(
-            object_type           = cls.OBJECT_TYPE_BITS[object_type],
-            sampling_frequency    = cls.SAMPLING_FREQUENCY_BITS[sampling_frequency],
-            channels              = cls.CHANNELS_BITS[channels],
-            vbr                   = vbr,
-            bitrate               = bitrate
+            object_type=cls.OBJECT_TYPE_BITS[object_type],
+            sampling_frequency=cls.SAMPLING_FREQUENCY_BITS[sampling_frequency],
+            channels=cls.CHANNELS_BITS[channels],
+            rfa=0,
+            vbr=vbr,
+            bitrate=bitrate,
         )
 
     @classmethod
-    def from_lists(
-        cls,
-        object_types,
-        sampling_frequencies,
-        channels,
-        vbr,
-        bitrate
-    ):
+    def from_lists(cls, object_types, sampling_frequencies, channels, vbr, bitrate):
         return AacMediaCodecInformation(
-            object_type           = sum(cls.OBJECT_TYPE_BITS[x] for x in object_types),
-            sampling_frequency    = sum(cls.SAMPLING_FREQUENCY_BITS[x] for x in sampling_frequencies),
-            channels              = sum(cls.CHANNELS_BITS[x] for x in channels),
-            vbr                   = vbr,
-            bitrate               = bitrate
+            object_type=sum(cls.OBJECT_TYPE_BITS[x] for x in object_types),
+            sampling_frequency=sum(
+                cls.SAMPLING_FREQUENCY_BITS[x] for x in sampling_frequencies
+            ),
+            channels=sum(cls.CHANNELS_BITS[x] for x in channels),
+            rfa=0,
+            vbr=vbr,
+            bitrate=bitrate,
         )
 
-    def __bytes__(self):
-        return bitstruct.pack(self.BIT_FIELDS, *self)
+    def __bytes__(self) -> bytes:
+        return bytes(
+            [
+                self.object_type & 0xFF,
+                (self.sampling_frequency >> 4) & 0xFF,
+                (((self.sampling_frequency & 0x0F) << 4) | (self.channels << 2)) & 0xFF,
+                ((self.vbr << 7) | ((self.bitrate >> 16) & 0x7F)) & 0xFF,
+                ((self.bitrate >> 8) & 0xFF) & 0xFF,
+                self.bitrate & 0xFF,
+            ]
+        )
 
     def __str__(self):
-        object_types = ['MPEG_2_AAC_LC', 'MPEG_4_AAC_LC', 'MPEG_4_AAC_LTP', 'MPEG_4_AAC_SCALABLE', '[4]', '[5]', '[6]', '[7]']
+        object_types = [
+            'MPEG_2_AAC_LC',
+            'MPEG_4_AAC_LC',
+            'MPEG_4_AAC_LTP',
+            'MPEG_4_AAC_SCALABLE',
+            '[4]',
+            '[5]',
+            '[6]',
+            '[7]',
+        ]
         channels = [1, 2]
-        return '\n'.join([
-            'AacMediaCodecInformation(',
-            f'  object_type:        {",".join([str(x) for x in flags_to_list(self.object_type, object_types)])}',
-            f'  sampling_frequency: {",".join([str(x) for x in flags_to_list(self.sampling_frequency, MPEG_2_4_AAC_SAMPLING_FREQUENCIES)])}',
-            f'  channels:           {",".join([str(x) for x in flags_to_list(self.channels, channels)])}',
-            f'  vbr:                {self.vbr}',
-            f'  bitrate:            {self.bitrate}'
-            ')'
-        ])
+        # pylint: disable=line-too-long
+        return '\n'.join(
+            [
+                'AacMediaCodecInformation(',
+                f'  object_type:        {",".join([str(x) for x in flags_to_list(self.object_type, object_types)])}',
+                f'  sampling_frequency: {",".join([str(x) for x in flags_to_list(self.sampling_frequency, MPEG_2_4_AAC_SAMPLING_FREQUENCIES)])}',
+                f'  channels:           {",".join([str(x) for x in flags_to_list(self.channels, channels)])}',
+                f'  vbr:                {self.vbr}',
+                f'  bitrate:            {self.bitrate}' ')',
+            ]
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -418,37 +487,34 @@ class VendorSpecificMediaCodecInformation:
 
     def __init__(self, vendor_id, codec_id, value):
         self.vendor_id = vendor_id
-        self.codec_id  = codec_id
-        self.value     = value
+        self.codec_id = codec_id
+        self.value = value
 
     def __bytes__(self):
         return struct.pack('<IH', self.vendor_id, self.codec_id, self.value)
 
     def __str__(self):
-        return '\n'.join([
-            'VendorSpecificMediaCodecInformation(',
-            f'  vendor_id: {self.vendor_id:08X} ({name_or_number(COMPANY_IDENTIFIERS, self.vendor_id & 0xFFFF)})',
-            f'  codec_id:  {self.codec_id:04X}',
-            f'  value:     {self.value.hex()}'
-            ')'
-        ])
+        # pylint: disable=line-too-long
+        return '\n'.join(
+            [
+                'VendorSpecificMediaCodecInformation(',
+                f'  vendor_id: {self.vendor_id:08X} ({name_or_number(COMPANY_IDENTIFIERS, self.vendor_id & 0xFFFF)})',
+                f'  codec_id:  {self.codec_id:04X}',
+                f'  value:     {self.value.hex()}' ')',
+            ]
+        )
 
 
 # -----------------------------------------------------------------------------
 class SbcFrame:
     def __init__(
-        self,
-        sampling_frequency,
-        block_count,
-        channel_mode,
-        subband_count,
-        payload
+        self, sampling_frequency, block_count, channel_mode, subband_count, payload
     ):
         self.sampling_frequency = sampling_frequency
-        self.block_count        = block_count
-        self.channel_mode       = channel_mode
-        self.subband_count      = subband_count
-        self.payload            = payload
+        self.block_count = block_count
+        self.channel_mode = channel_mode
+        self.subband_count = subband_count
+        self.payload = payload
 
     @property
     def sample_count(self):
@@ -463,7 +529,13 @@ class SbcFrame:
         return self.sample_count / self.sampling_frequency
 
     def __str__(self):
-        return f'SBC(sf={self.sampling_frequency},cm={self.channel_mode},br={self.bitrate},sc={self.sample_count},size={len(self.payload)})'
+        return (
+            f'SBC(sf={self.sampling_frequency},'
+            f'cm={self.channel_mode},'
+            f'br={self.bitrate},'
+            f'sc={self.sample_count},'
+            f'size={len(self.payload)})'
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -487,24 +559,30 @@ class SbcParser:
 
                 # Extract some of the header fields
                 sampling_frequency = SBC_SAMPLING_FREQUENCIES[(header[1] >> 6) & 3]
-                blocks             = 4 * (1 + ((header[1] >> 4) & 3))
-                channel_mode       = (header[1] >> 2) & 3
-                channels           = 1 if channel_mode == SBC_MONO_CHANNEL_MODE else 2
-                subbands           = 8 if ((header[1]) & 1) else 4
-                bitpool            = header[2]
+                blocks = 4 * (1 + ((header[1] >> 4) & 3))
+                channel_mode = (header[1] >> 2) & 3
+                channels = 1 if channel_mode == SBC_MONO_CHANNEL_MODE else 2
+                subbands = 8 if ((header[1]) & 1) else 4
+                bitpool = header[2]
 
                 # Compute the frame length
                 frame_length = 4 + (4 * subbands * channels) // 8
                 if channel_mode in (SBC_MONO_CHANNEL_MODE, SBC_DUAL_CHANNEL_MODE):
                     frame_length += (blocks * channels * bitpool) // 8
                 else:
-                    frame_length += ((1 if channel_mode == SBC_JOINT_STEREO_CHANNEL_MODE else 0) * subbands + blocks * bitpool) // 8
+                    frame_length += (
+                        (1 if channel_mode == SBC_JOINT_STEREO_CHANNEL_MODE else 0)
+                        * subbands
+                        + blocks * bitpool
+                    ) // 8
 
                 # Read the rest of the frame
                 payload = header + await self.read(frame_length - 4)
 
                 # Emit the next frame
-                yield SbcFrame(sampling_frequency, blocks, channel_mode, subbands, payload)
+                yield SbcFrame(
+                    sampling_frequency, blocks, channel_mode, subbands, payload
+                )
 
         return generate_frames()
 
@@ -512,19 +590,20 @@ class SbcParser:
 # -----------------------------------------------------------------------------
 class SbcPacketSource:
     def __init__(self, read, mtu, codec_capabilities):
-        self.read               = read
-        self.mtu                = mtu
+        self.read = read
+        self.mtu = mtu
         self.codec_capabilities = codec_capabilities
 
     @property
     def packets(self):
         async def generate_packets():
+            # pylint: disable=import-outside-toplevel
             from .avdtp import MediaPacket  # Import here to avoid a circular reference
 
             sequence_number = 0
-            timestamp       = 0
-            frames          = []
-            frames_size     = 0
+            timestamp = 0
+            frames = []
+            frames_size = 0
             max_rtp_payload = self.mtu - 12 - 1
 
             # NOTE: this doesn't support frame fragments
@@ -532,18 +611,25 @@ class SbcPacketSource:
             async for frame in sbc_parser.frames:
                 print(frame)
 
-                if frames_size + len(frame.payload) > max_rtp_payload or len(frames) == 16:
+                if (
+                    frames_size + len(frame.payload) > max_rtp_payload
+                    or len(frames) == 16
+                ):
                     # Need to flush what has been accumulated so far
 
                     # Emit a packet
-                    sbc_payload = bytes([len(frames)]) + b''.join([frame.payload for frame in frames])
-                    packet = MediaPacket(2, 0, 0, 0, sequence_number, timestamp, 0, [], 96, sbc_payload)
+                    sbc_payload = bytes([len(frames)]) + b''.join(
+                        [frame.payload for frame in frames]
+                    )
+                    packet = MediaPacket(
+                        2, 0, 0, 0, sequence_number, timestamp, 0, [], 96, sbc_payload
+                    )
                     packet.timestamp_seconds = timestamp / frame.sampling_frequency
                     yield packet
 
                     # Prepare for next packets
                     sequence_number += 1
-                    timestamp += sum([frame.sample_count for frame in frames])
+                    timestamp += sum((frame.sample_count for frame in frames))
                     frames = [frame]
                     frames_size = len(frame.payload)
                 else:

bumble/at.py

@@ -0,0 +1,85 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from typing import List, Union
+
+
+def tokenize_parameters(buffer: bytes) -> List[bytes]:
+    """Split input parameters into tokens.
+    Removes space characters outside of double quote blocks:
+    T-rec-V-25 - 5.2.1 Command line general format: "Space characters (IA5 2/0)
+    are ignored [..], unless they are embedded in numeric or string constants"
+    Raises ValueError in case of invalid input string."""
+
+    tokens = []
+    in_quotes = False
+    token = bytearray()
+    for b in buffer:
+        char = bytearray([b])
+
+        if in_quotes:
+            token.extend(char)
+            if char == b'\"':
+                in_quotes = False
+                tokens.append(token[1:-1])
+                token = bytearray()
+        else:
+            if char == b' ':
+                pass
+            elif char == b',' or char == b')':
+                tokens.append(token)
+                tokens.append(char)
+                token = bytearray()
+            elif char == b'(':
+                if len(token) > 0:
+                    raise ValueError("open_paren following regular character")
+                tokens.append(char)
+            elif char == b'"':
+                if len(token) > 0:
+                    raise ValueError("quote following regular character")
+                in_quotes = True
+                token.extend(char)
+            else:
+                token.extend(char)
+
+    tokens.append(token)
+    return [bytes(token) for token in tokens if len(token) > 0]
+
+
+def parse_parameters(buffer: bytes) -> List[Union[bytes, list]]:
+    """Parse the parameters using the comma and parenthesis separators.
+    Raises ValueError in case of invalid input string."""
+
+    tokens = tokenize_parameters(buffer)
+    accumulator: List[list] = [[]]
+    current: Union[bytes, list] = bytes()
+
+    for token in tokens:
+        if token == b',':
+            accumulator[-1].append(current)
+            current = bytes()
+        elif token == b'(':
+            accumulator.append([])
+        elif token == b')':
+            if len(accumulator) < 2:
+                raise ValueError("close_paren without matching open_paren")
+            accumulator[-1].append(current)
+            current = accumulator.pop()
+        else:
+            current = token
+
+    accumulator[-1].append(current)
+    if len(accumulator) > 1:
+        raise ValueError("missing close_paren")
+    return accumulator[0]

bumble/att.py

@@ -22,15 +22,25 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
-from colors import color
+from __future__ import annotations
+import functools
+import struct
 from pyee import EventEmitter
+from typing import Dict, Type, TYPE_CHECKING
 
-from .core import *
-from .hci import *
+from bumble.core import UUID, name_or_number, get_dict_key_by_value, ProtocolError
+from bumble.hci import HCI_Object, key_with_value, HCI_Constant
+from bumble.colors import color
+
+if TYPE_CHECKING:
+    from bumble.device import Connection
 
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+# fmt: off
+# pylint: disable=line-too-long
+
 ATT_CID = 0x04
 
 ATT_ERROR_RESPONSE              = 0x01
@@ -163,30 +173,30 @@ ATT_ERROR_NAMES = {
 ATT_DEFAULT_MTU = 23
 
 HANDLE_FIELD_SPEC    = {'size': 2, 'mapper': lambda x: f'0x{x:04X}'}
-UUID_2_16_FIELD_SPEC = lambda x, y: UUID.parse_uuid(x, y)    # noqa: E731
+# pylint: disable-next=unnecessary-lambda-assignment,unnecessary-lambda
+UUID_2_16_FIELD_SPEC = lambda x, y: UUID.parse_uuid(x, y)
+# pylint: disable-next=unnecessary-lambda-assignment,unnecessary-lambda
 UUID_2_FIELD_SPEC    = lambda x, y: UUID.parse_uuid_2(x, y)  # noqa: E731
 
-
-# -----------------------------------------------------------------------------
-# Utils
-# -----------------------------------------------------------------------------
-def key_with_value(dictionary, target_value):
-    for key, value in dictionary.items():
-        if value == target_value:
-            return key
-    return None
-
+# fmt: on
+# pylint: enable=line-too-long
+# pylint: disable=invalid-name
 
 # -----------------------------------------------------------------------------
 # Exceptions
 # -----------------------------------------------------------------------------
-class ATT_Error(Exception):
-    def __init__(self, error_code, att_handle=0x0000):
-        self.error_code = error_code
+class ATT_Error(ProtocolError):
+    def __init__(self, error_code, att_handle=0x0000, message=''):
+        super().__init__(
+            error_code,
+            error_namespace='att',
+            error_name=ATT_PDU.error_name(error_code),
+        )
         self.att_handle = att_handle
+        self.message = message
 
     def __str__(self):
-        return f'ATT_Error({ATT_PDU.error_name(self.error_code)})'
+        return f'ATT_Error(error={self.error_name}, handle={self.att_handle:04X}): {self.message}'
 
 
 # -----------------------------------------------------------------------------
@@ -196,8 +206,10 @@ class ATT_PDU:
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.3 ATTRIBUTE PDU
     '''
-    pdu_classes = {}
+
+    pdu_classes: Dict[int, Type[ATT_PDU]] = {}
     op_code = 0
+    name = None
 
     @staticmethod
     def from_bytes(pdu):
@@ -274,11 +286,13 @@ class ATT_PDU:
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('request_opcode_in_error',   {'size': 1, 'mapper': ATT_PDU.pdu_name}),
-    ('attribute_handle_in_error', HANDLE_FIELD_SPEC),
-    ('error_code',                {'size': 1, 'mapper': ATT_PDU.error_name})
-])
+@ATT_PDU.subclass(
+    [
+        ('request_opcode_in_error', {'size': 1, 'mapper': ATT_PDU.pdu_name}),
+        ('attribute_handle_in_error', HANDLE_FIELD_SPEC),
+        ('error_code', {'size': 1, 'mapper': ATT_PDU.error_name}),
+    ]
+)
 class ATT_Error_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.1.1 Error Response
@@ -286,9 +300,7 @@ class ATT_Error_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('client_rx_mtu', 2)
-])
+@ATT_PDU.subclass([('client_rx_mtu', 2)])
 class ATT_Exchange_MTU_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.2.1 Exchange MTU Request
@@ -296,9 +308,7 @@ class ATT_Exchange_MTU_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('server_rx_mtu', 2)
-])
+@ATT_PDU.subclass([('server_rx_mtu', 2)])
 class ATT_Exchange_MTU_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.2.2 Exchange MTU Response
@@ -306,10 +316,9 @@ class ATT_Exchange_MTU_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle', HANDLE_FIELD_SPEC),
-    ('ending_handle',   HANDLE_FIELD_SPEC)
-])
+@ATT_PDU.subclass(
+    [('starting_handle', HANDLE_FIELD_SPEC), ('ending_handle', HANDLE_FIELD_SPEC)]
+)
 class ATT_Find_Information_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.1 Find Information Request
@@ -317,10 +326,7 @@ class ATT_Find_Information_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('format',           1),
-    ('information_data', '*')
-])
+@ATT_PDU.subclass([('format', 1), ('information_data', '*')])
 class ATT_Find_Information_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.2 Find Information Response
@@ -332,7 +338,7 @@ class ATT_Find_Information_Response(ATT_PDU):
         uuid_size = 2 if self.format == 1 else 16
         while offset + uuid_size <= len(self.information_data):
             handle = struct.unpack_from('<H', self.information_data, offset)[0]
-            uuid   = self.information_data[2 + offset:2 + offset + uuid_size]
+            uuid = self.information_data[2 + offset : 2 + offset + uuid_size]
             self.information.append((handle, uuid))
             offset += 2 + uuid_size
 
@@ -346,20 +352,33 @@ class ATT_Find_Information_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('format',       1),
-            ('information', {'mapper': lambda x: ', '.join([f'0x{handle:04X}:{uuid.hex()}' for handle, uuid in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                ('format', 1),
+                (
+                    'information',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [f'0x{handle:04X}:{uuid.hex()}' for handle, uuid in x]
+                        )
+                    },
+                ),
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle', HANDLE_FIELD_SPEC),
-    ('ending_handle',   HANDLE_FIELD_SPEC),
-    ('attribute_type',  UUID_2_FIELD_SPEC),
-    ('attribute_value', '*')
-])
+@ATT_PDU.subclass(
+    [
+        ('starting_handle', HANDLE_FIELD_SPEC),
+        ('ending_handle', HANDLE_FIELD_SPEC),
+        ('attribute_type', UUID_2_FIELD_SPEC),
+        ('attribute_value', '*'),
+    ]
+)
 class ATT_Find_By_Type_Value_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.3 Find By Type Value Request
@@ -367,9 +386,7 @@ class ATT_Find_By_Type_Value_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('handles_information_list', '*')
-])
+@ATT_PDU.subclass([('handles_information_list', '*')])
 class ATT_Find_By_Type_Value_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.3.4 Find By Type Value Response
@@ -379,7 +396,9 @@ class ATT_Find_By_Type_Value_Response(ATT_PDU):
         self.handles_information = []
         offset = 0
         while offset + 4 <= len(self.handles_information_list):
-            found_attribute_handle, group_end_handle = struct.unpack_from('<HH', self.handles_information_list, offset)
+            found_attribute_handle, group_end_handle = struct.unpack_from(
+                '<HH', self.handles_information_list, offset
+            )
             self.handles_information.append((found_attribute_handle, group_end_handle))
             offset += 4
 
@@ -393,18 +412,34 @@ class ATT_Find_By_Type_Value_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('handles_information', {'mapper': lambda x: ', '.join([f'0x{handle1:04X}-0x{handle2:04X}' for handle1, handle2 in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                (
+                    'handles_information',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [
+                                f'0x{handle1:04X}-0x{handle2:04X}'
+                                for handle1, handle2 in x
+                            ]
+                        )
+                    },
+                )
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle', HANDLE_FIELD_SPEC),
-    ('ending_handle',   HANDLE_FIELD_SPEC),
-    ('attribute_type',  UUID_2_16_FIELD_SPEC)
-])
+@ATT_PDU.subclass(
+    [
+        ('starting_handle', HANDLE_FIELD_SPEC),
+        ('ending_handle', HANDLE_FIELD_SPEC),
+        ('attribute_type', UUID_2_16_FIELD_SPEC),
+    ]
+)
 class ATT_Read_By_Type_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.1 Read By Type Request
@@ -412,10 +447,7 @@ class ATT_Read_By_Type_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('length',              1),
-    ('attribute_data_list', '*')
-])
+@ATT_PDU.subclass([('length', 1), ('attribute_data_list', '*')])
 class ATT_Read_By_Type_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.2 Read By Type Response
@@ -424,9 +456,15 @@ class ATT_Read_By_Type_Response(ATT_PDU):
     def parse_attribute_data_list(self):
         self.attributes = []
         offset = 0
-        while self.length != 0 and offset + self.length <= len(self.attribute_data_list):
-            attribute_handle, = struct.unpack_from('<H', self.attribute_data_list, offset)
-            attribute_value = self.attribute_data_list[offset + 2:offset + self.length]
+        while self.length != 0 and offset + self.length <= len(
+            self.attribute_data_list
+        ):
+            (attribute_handle,) = struct.unpack_from(
+                '<H', self.attribute_data_list, offset
+            )
+            attribute_value = self.attribute_data_list[
+                offset + 2 : offset + self.length
+            ]
             self.attributes.append((attribute_handle, attribute_value))
             offset += self.length
 
@@ -440,17 +478,26 @@ class ATT_Read_By_Type_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('length',     1),
-            ('attributes', {'mapper': lambda x: ', '.join([f'0x{handle:04X}:{value.hex()}' for handle, value in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                ('length', 1),
+                (
+                    'attributes',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [f'0x{handle:04X}:{value.hex()}' for handle, value in x]
+                        )
+                    },
+                ),
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC)
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC)])
 class ATT_Read_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.3 Read Request
@@ -458,9 +505,7 @@ class ATT_Read_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_value', '*')
-])
+@ATT_PDU.subclass([('attribute_value', '*')])
 class ATT_Read_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.4 Read Response
@@ -468,10 +513,7 @@ class ATT_Read_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('value_offset',     2)
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('value_offset', 2)])
 class ATT_Read_Blob_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.5 Read Blob Request
@@ -479,9 +521,7 @@ class ATT_Read_Blob_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('part_attribute_value', '*')
-])
+@ATT_PDU.subclass([('part_attribute_value', '*')])
 class ATT_Read_Blob_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.6 Read Blob Response
@@ -489,9 +529,7 @@ class ATT_Read_Blob_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('set_of_handles', '*')
-])
+@ATT_PDU.subclass([('set_of_handles', '*')])
 class ATT_Read_Multiple_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.7 Read Multiple Request
@@ -499,9 +537,7 @@ class ATT_Read_Multiple_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('set_of_values', '*')
-])
+@ATT_PDU.subclass([('set_of_values', '*')])
 class ATT_Read_Multiple_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.8 Read Multiple Response
@@ -509,11 +545,13 @@ class ATT_Read_Multiple_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('starting_handle',      HANDLE_FIELD_SPEC),
-    ('ending_handle',        HANDLE_FIELD_SPEC),
-    ('attribute_group_type', UUID_2_16_FIELD_SPEC)
-])
+@ATT_PDU.subclass(
+    [
+        ('starting_handle', HANDLE_FIELD_SPEC),
+        ('ending_handle', HANDLE_FIELD_SPEC),
+        ('attribute_group_type', UUID_2_16_FIELD_SPEC),
+    ]
+)
 class ATT_Read_By_Group_Type_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.9 Read by Group Type Request
@@ -521,10 +559,7 @@ class ATT_Read_By_Group_Type_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('length',              1),
-    ('attribute_data_list', '*')
-])
+@ATT_PDU.subclass([('length', 1), ('attribute_data_list', '*')])
 class ATT_Read_By_Group_Type_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.4.10 Read by Group Type Response
@@ -533,10 +568,18 @@ class ATT_Read_By_Group_Type_Response(ATT_PDU):
     def parse_attribute_data_list(self):
         self.attributes = []
         offset = 0
-        while self.length != 0 and offset + self.length <= len(self.attribute_data_list):
-            attribute_handle, end_group_handle = struct.unpack_from('<HH', self.attribute_data_list, offset)
-            attribute_value = self.attribute_data_list[offset + 4:offset + self.length]
-            self.attributes.append((attribute_handle, end_group_handle, attribute_value))
+        while self.length != 0 and offset + self.length <= len(
+            self.attribute_data_list
+        ):
+            attribute_handle, end_group_handle = struct.unpack_from(
+                '<HH', self.attribute_data_list, offset
+            )
+            attribute_value = self.attribute_data_list[
+                offset + 4 : offset + self.length
+            ]
+            self.attributes.append(
+                (attribute_handle, end_group_handle, attribute_value)
+            )
             offset += self.length
 
     def __init__(self, *args, **kwargs):
@@ -549,18 +592,29 @@ class ATT_Read_By_Group_Type_Response(ATT_PDU):
 
     def __str__(self):
         result = color(self.name, 'yellow')
-        result += ':\n' + HCI_Object.format_fields(self.__dict__, [
-            ('length',     1),
-            ('attributes', {'mapper': lambda x: ', '.join([f'0x{handle:04X}-0x{end:04X}:{value.hex()}' for handle, end, value in x])})
-        ], '  ')
+        result += ':\n' + HCI_Object.format_fields(
+            self.__dict__,
+            [
+                ('length', 1),
+                (
+                    'attributes',
+                    {
+                        'mapper': lambda x: ', '.join(
+                            [
+                                f'0x{handle:04X}-0x{end:04X}:{value.hex()}'
+                                for handle, end, value in x
+                            ]
+                        )
+                    },
+                ),
+            ],
+            '  ',
+        )
         return result
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Write_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.5.1 Write Request
@@ -576,10 +630,7 @@ class ATT_Write_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Write_Command(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.5.3 Write Command
@@ -587,11 +638,13 @@ class ATT_Write_Command(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-    # ('authentication_signature', 'TODO')
-])
+@ATT_PDU.subclass(
+    [
+        ('attribute_handle', HANDLE_FIELD_SPEC),
+        ('attribute_value', '*')
+        # ('authentication_signature', 'TODO')
+    ]
+)
 class ATT_Signed_Write_Command(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.5.4 Signed Write Command
@@ -599,11 +652,13 @@ class ATT_Signed_Write_Command(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle',     HANDLE_FIELD_SPEC),
-    ('value_offset',         2),
-    ('part_attribute_value', '*')
-])
+@ATT_PDU.subclass(
+    [
+        ('attribute_handle', HANDLE_FIELD_SPEC),
+        ('value_offset', 2),
+        ('part_attribute_value', '*'),
+    ]
+)
 class ATT_Prepare_Write_Request(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.6.1 Prepare Write Request
@@ -611,11 +666,13 @@ class ATT_Prepare_Write_Request(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle',     HANDLE_FIELD_SPEC),
-    ('value_offset',         2),
-    ('part_attribute_value', '*')
-])
+@ATT_PDU.subclass(
+    [
+        ('attribute_handle', HANDLE_FIELD_SPEC),
+        ('value_offset', 2),
+        ('part_attribute_value', '*'),
+    ]
+)
 class ATT_Prepare_Write_Response(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.6.2 Prepare Write Response
@@ -639,10 +696,7 @@ class ATT_Execute_Write_Response(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Handle_Value_Notification(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.7.1 Handle Value Notification
@@ -650,10 +704,7 @@ class ATT_Handle_Value_Notification(ATT_PDU):
 
 
 # -----------------------------------------------------------------------------
-@ATT_PDU.subclass([
-    ('attribute_handle', HANDLE_FIELD_SPEC),
-    ('attribute_value',  '*')
-])
+@ATT_PDU.subclass([('attribute_handle', HANDLE_FIELD_SPEC), ('attribute_value', '*')])
 class ATT_Handle_Value_Indication(ATT_PDU):
     '''
     See Bluetooth spec @ Vol 3, Part F - 3.4.7.2 Handle Value Indication
@@ -671,31 +722,58 @@ class ATT_Handle_Value_Confirmation(ATT_PDU):
 # -----------------------------------------------------------------------------
 class Attribute(EventEmitter):
     # Permission flags
-    READABLE                      = 0x01
-    WRITEABLE                     = 0x02
-    READ_REQUIRES_ENCRYPTION      = 0x04
-    WRITE_REQUIRES_ENCRYPTION     = 0x08
-    READ_REQUIRES_AUTHENTICATION  = 0x10
+    READABLE = 0x01
+    WRITEABLE = 0x02
+    READ_REQUIRES_ENCRYPTION = 0x04
+    WRITE_REQUIRES_ENCRYPTION = 0x08
+    READ_REQUIRES_AUTHENTICATION = 0x10
     WRITE_REQUIRES_AUTHENTICATION = 0x20
-    READ_REQUIRES_AUTHORIZATION   = 0x40
-    WRITE_REQUIRES_AUTHORIZATION  = 0x80
+    READ_REQUIRES_AUTHORIZATION = 0x40
+    WRITE_REQUIRES_AUTHORIZATION = 0x80
 
-    def __init__(self, attribute_type, permissions, value = b''):
+    PERMISSION_NAMES = {
+        READABLE: 'READABLE',
+        WRITEABLE: 'WRITEABLE',
+        READ_REQUIRES_ENCRYPTION: 'READ_REQUIRES_ENCRYPTION',
+        WRITE_REQUIRES_ENCRYPTION: 'WRITE_REQUIRES_ENCRYPTION',
+        READ_REQUIRES_AUTHENTICATION: 'READ_REQUIRES_AUTHENTICATION',
+        WRITE_REQUIRES_AUTHENTICATION: 'WRITE_REQUIRES_AUTHENTICATION',
+        READ_REQUIRES_AUTHORIZATION: 'READ_REQUIRES_AUTHORIZATION',
+        WRITE_REQUIRES_AUTHORIZATION: 'WRITE_REQUIRES_AUTHORIZATION',
+    }
+
+    @staticmethod
+    def string_to_permissions(permissions_str: str):
+        try:
+            return functools.reduce(
+                lambda x, y: x | get_dict_key_by_value(Attribute.PERMISSION_NAMES, y),
+                permissions_str.split(","),
+                0,
+            )
+        except TypeError as exc:
+            raise TypeError(
+                f"Attribute::permissions error:\nExpected a string containing any of the keys, separated by commas: {','.join(Attribute.PERMISSION_NAMES.values())}\nGot: {permissions_str}"
+            ) from exc
+
+    def __init__(self, attribute_type, permissions, value=b''):
         EventEmitter.__init__(self)
-        self.handle           = 0
+        self.handle = 0
         self.end_group_handle = 0
-        self.permissions      = permissions
+        if isinstance(permissions, str):
+            self.permissions = self.string_to_permissions(permissions)
+        else:
+            self.permissions = permissions
 
         # Convert the type to a UUID object if it isn't already
-        if type(attribute_type) is str:
+        if isinstance(attribute_type, str):
             self.type = UUID(attribute_type)
-        elif type(attribute_type) is bytes:
+        elif isinstance(attribute_type, bytes):
             self.type = UUID.from_bytes(attribute_type)
         else:
             self.type = attribute_type
 
         # Convert the value to a byte array
-        if type(value) is str:
+        if isinstance(value, str):
             self.value = bytes(value, 'utf-8')
         else:
             self.value = value
@@ -706,32 +784,72 @@ class Attribute(EventEmitter):
     def decode_value(self, value_bytes):
         return value_bytes
 
-    def read_value(self, connection):
+    def read_value(self, connection: Connection):
+        if (
+            self.permissions & self.READ_REQUIRES_ENCRYPTION
+        ) and not connection.encryption:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
+            )
+        if (
+            self.permissions & self.READ_REQUIRES_AUTHENTICATION
+        ) and not connection.authenticated:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
+            )
+        if self.permissions & self.READ_REQUIRES_AUTHORIZATION:
+            # TODO: handle authorization better
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
+            )
+
         if read := getattr(self.value, 'read', None):
             try:
-                value = read(connection)
+                value = read(connection)  # pylint: disable=not-callable
             except ATT_Error as error:
-                raise ATT_Error(error_code=error.error_code, att_handle=self.handle)
+                raise ATT_Error(
+                    error_code=error.error_code, att_handle=self.handle
+                ) from error
         else:
             value = self.value
 
         return self.encode_value(value)
 
-    def write_value(self, connection, value_bytes):
+    def write_value(self, connection: Connection, value_bytes):
+        if (
+            self.permissions & self.WRITE_REQUIRES_ENCRYPTION
+        ) and not connection.encryption:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_ENCRYPTION_ERROR, att_handle=self.handle
+            )
+        if (
+            self.permissions & self.WRITE_REQUIRES_AUTHENTICATION
+        ) and not connection.authenticated:
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHENTICATION_ERROR, att_handle=self.handle
+            )
+        if self.permissions & self.WRITE_REQUIRES_AUTHORIZATION:
+            # TODO: handle authorization better
+            raise ATT_Error(
+                error_code=ATT_INSUFFICIENT_AUTHORIZATION_ERROR, att_handle=self.handle
+            )
+
         value = self.decode_value(value_bytes)
 
         if write := getattr(self.value, 'write', None):
             try:
-                write(connection, value)
+                write(connection, value)  # pylint: disable=not-callable
             except ATT_Error as error:
-                raise ATT_Error(error_code=error.error_code, att_handle=self.handle)
+                raise ATT_Error(
+                    error_code=error.error_code, att_handle=self.handle
+                ) from error
         else:
             self.value = value
 
         self.emit('write', connection, value)
 
     def __repr__(self):
-        if type(self.value) is bytes:
+        if isinstance(self.value, bytes):
             value_str = self.value.hex()
         else:
             value_str = str(self.value)
@@ -739,4 +857,8 @@ class Attribute(EventEmitter):
             value_string = f', value={self.value.hex()}'
         else:
             value_string = ''
-        return f'Attribute(handle=0x{self.handle:04X}, type={self.type}, permissions={self.permissions}{value_string})'
+        return (
+            f'Attribute(handle=0x{self.handle:04X}, '
+            f'type={self.type}, '
+            f'permissions={self.permissions}{value_string})'
+        )

bumble/bridge.py

@@ -30,10 +30,10 @@ logger = logging.getLogger(__name__)
 class HCI_Bridge:
     class Forwarder:
         def __init__(self, hci_sink, sender_hci_sink, packet_filter, trace):
-            self.hci_sink        = hci_sink
+            self.hci_sink = hci_sink
             self.sender_hci_sink = sender_hci_sink
-            self.packet_filter   = packet_filter
-            self.trace           = trace
+            self.packet_filter = packet_filter
+            self.trace = trace
 
         def on_packet(self, packet):
             # Convert the packet bytes to an object
@@ -61,15 +61,15 @@ class HCI_Bridge:
         hci_host_sink,
         hci_controller_source,
         hci_controller_sink,
-        host_to_controller_filter = None,
-        controller_to_host_filter = None
+        host_to_controller_filter=None,
+        controller_to_host_filter=None,
     ):
         tracer = PacketTracer(emit_message=logger.info)
         host_to_controller_forwarder = HCI_Bridge.Forwarder(
             hci_controller_sink,
             hci_host_sink,
             host_to_controller_filter,
-            lambda packet: tracer.trace(packet, 0)
+            lambda packet: tracer.trace(packet, 0),
         )
         hci_host_source.set_packet_sink(host_to_controller_forwarder)
 
@@ -77,6 +77,6 @@ class HCI_Bridge:
             hci_host_sink,
             hci_controller_sink,
             controller_to_host_filter,
-            lambda packet: tracer.trace(packet, 1)
+            lambda packet: tracer.trace(packet, 1),
         )
         hci_controller_source.set_packet_sink(controller_to_host_forwarder)

bumble/codecs.py

@@ -0,0 +1,381 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+# -----------------------------------------------------------------------------
+class BitReader:
+    """Simple but not optimized bit stream reader."""
+
+    data: bytes
+    bytes_position: int
+    bit_position: int
+    cache: int
+    bits_cached: int
+
+    def __init__(self, data: bytes):
+        self.data = data
+        self.byte_position = 0
+        self.bit_position = 0
+        self.cache = 0
+        self.bits_cached = 0
+
+    def read(self, bits: int) -> int:
+        """ "Read up to 32 bits."""
+
+        if bits > 32:
+            raise ValueError('maximum read size is 32')
+
+        if self.bits_cached >= bits:
+            # We have enough bits.
+            self.bits_cached -= bits
+            self.bit_position += bits
+            return (self.cache >> self.bits_cached) & ((1 << bits) - 1)
+
+        # Read more cache, up to 32 bits
+        feed_bytes = self.data[self.byte_position : self.byte_position + 4]
+        feed_size = len(feed_bytes)
+        feed_int = int.from_bytes(feed_bytes, byteorder='big')
+        if 8 * feed_size + self.bits_cached < bits:
+            raise ValueError('trying to read past the data')
+        self.byte_position += feed_size
+
+        # Combine the new cache and the old cache
+        cache = self.cache & ((1 << self.bits_cached) - 1)
+        new_bits = bits - self.bits_cached
+        self.bits_cached = 8 * feed_size - new_bits
+        result = (feed_int >> self.bits_cached) | (cache << new_bits)
+        self.cache = feed_int
+
+        self.bit_position += bits
+        return result
+
+    def read_bytes(self, count: int):
+        if self.bit_position + 8 * count > 8 * len(self.data):
+            raise ValueError('not enough data')
+
+        if self.bit_position % 8:
+            # Not byte aligned
+            result = bytearray(count)
+            for i in range(count):
+                result[i] = self.read(8)
+            return bytes(result)
+
+        # Byte aligned
+        self.byte_position = self.bit_position // 8
+        self.bits_cached = 0
+        self.cache = 0
+        offset = self.bit_position // 8
+        self.bit_position += 8 * count
+        return self.data[offset : offset + count]
+
+    def bits_left(self) -> int:
+        return (8 * len(self.data)) - self.bit_position
+
+    def skip(self, bits: int) -> None:
+        # Slow, but simple...
+        while bits:
+            if bits > 32:
+                self.read(32)
+                bits -= 32
+            else:
+                self.read(bits)
+                break
+
+
+# -----------------------------------------------------------------------------
+class AacAudioRtpPacket:
+    """AAC payload encapsulated in an RTP packet payload"""
+
+    @staticmethod
+    def latm_value(reader: BitReader) -> int:
+        bytes_for_value = reader.read(2)
+        value = 0
+        for _ in range(bytes_for_value + 1):
+            value = value * 256 + reader.read(8)
+        return value
+
+    @staticmethod
+    def program_config_element(reader: BitReader):
+        raise ValueError('program_config_element not supported')
+
+    @dataclass
+    class GASpecificConfig:
+        def __init__(
+            self, reader: BitReader, channel_configuration: int, audio_object_type: int
+        ) -> None:
+            # GASpecificConfig - ISO/EIC 14496-3 Table 4.1
+            frame_length_flag = reader.read(1)
+            depends_on_core_coder = reader.read(1)
+            if depends_on_core_coder:
+                self.core_coder_delay = reader.read(14)
+            extension_flag = reader.read(1)
+            if not channel_configuration:
+                AacAudioRtpPacket.program_config_element(reader)
+            if audio_object_type in (6, 20):
+                self.layer_nr = reader.read(3)
+            if extension_flag:
+                if audio_object_type == 22:
+                    num_of_sub_frame = reader.read(5)
+                layer_length = reader.read(11)
+                if audio_object_type in (17, 19, 20, 23):
+                    aac_section_data_resilience_flags = reader.read(1)
+                    aac_scale_factor_data_resilience_flags = reader.read(1)
+                    aac_spectral_data_resilience_flags = reader.read(1)
+                extension_flag_3 = reader.read(1)
+                if extension_flag_3 == 1:
+                    raise ValueError('extensionFlag3 == 1 not supported')
+
+    @staticmethod
+    def audio_object_type(reader: BitReader):
+        # GetAudioObjectType - ISO/EIC 14496-3 Table 1.16
+        audio_object_type = reader.read(5)
+        if audio_object_type == 31:
+            audio_object_type = 32 + reader.read(6)
+
+        return audio_object_type
+
+    @dataclass
+    class AudioSpecificConfig:
+        audio_object_type: int
+        sampling_frequency_index: int
+        sampling_frequency: int
+        channel_configuration: int
+        sbr_present_flag: int
+        ps_present_flag: int
+        extension_audio_object_type: int
+        extension_sampling_frequency_index: int
+        extension_sampling_frequency: int
+        extension_channel_configuration: int
+
+        SAMPLING_FREQUENCIES = [
+            96000,
+            88200,
+            64000,
+            48000,
+            44100,
+            32000,
+            24000,
+            22050,
+            16000,
+            12000,
+            11025,
+            8000,
+            7350,
+        ]
+
+        def __init__(self, reader: BitReader) -> None:
+            # AudioSpecificConfig - ISO/EIC 14496-3 Table 1.15
+            self.audio_object_type = AacAudioRtpPacket.audio_object_type(reader)
+            self.sampling_frequency_index = reader.read(4)
+            if self.sampling_frequency_index == 0xF:
+                self.sampling_frequency = reader.read(24)
+            else:
+                self.sampling_frequency = self.SAMPLING_FREQUENCIES[
+                    self.sampling_frequency_index
+                ]
+            self.channel_configuration = reader.read(4)
+            self.sbr_present_flag = -1
+            self.ps_present_flag = -1
+            if self.audio_object_type in (5, 29):
+                self.extension_audio_object_type = 5
+                self.sbc_present_flag = 1
+                if self.audio_object_type == 29:
+                    self.ps_present_flag = 1
+                self.extension_sampling_frequency_index = reader.read(4)
+                if self.extension_sampling_frequency_index == 0xF:
+                    self.extension_sampling_frequency = reader.read(24)
+                else:
+                    self.extension_sampling_frequency = self.SAMPLING_FREQUENCIES[
+                        self.extension_sampling_frequency_index
+                    ]
+                self.audio_object_type = AacAudioRtpPacket.audio_object_type(reader)
+                if self.audio_object_type == 22:
+                    self.extension_channel_configuration = reader.read(4)
+            else:
+                self.extension_audio_object_type = 0
+
+            if self.audio_object_type in (1, 2, 3, 4, 6, 7, 17, 19, 20, 21, 22, 23):
+                ga_specific_config = AacAudioRtpPacket.GASpecificConfig(
+                    reader, self.channel_configuration, self.audio_object_type
+                )
+            else:
+                raise ValueError(
+                    f'audioObjectType {self.audio_object_type} not supported'
+                )
+
+            # if self.extension_audio_object_type != 5 and bits_to_decode >= 16:
+            #     sync_extension_type = reader.read(11)
+            #     if sync_extension_type == 0x2B7:
+            #         self.extension_audio_object_type = AacAudioRtpPacket.audio_object_type(reader)
+            #         if self.extension_audio_object_type == 5:
+            #             self.sbr_present_flag = reader.read(1)
+            #             if self.sbr_present_flag:
+            #                 self.extension_sampling_frequency_index = reader.read(4)
+            #                 if self.extension_sampling_frequency_index == 0xF:
+            #                     self.extension_sampling_frequency = reader.read(24)
+            #                 else:
+            #                     self.extension_sampling_frequency = self.SAMPLING_FREQUENCIES[self.extension_sampling_frequency_index]
+            #                 if bits_to_decode >= 12:
+            #                     sync_extension_type = reader.read(11)
+            #                     if sync_extension_type == 0x548:
+            #                         self.ps_present_flag = reader.read(1)
+            #         elif self.extension_audio_object_type == 22:
+            #             self.sbr_present_flag = reader.read(1)
+            #             if self.sbr_present_flag:
+            #                 self.extension_sampling_frequency_index = reader.read(4)
+            #                 if self.extension_sampling_frequency_index == 0xF:
+            #                     self.extension_sampling_frequency = reader.read(24)
+            #                 else:
+            #                     self.extension_sampling_frequency = self.SAMPLING_FREQUENCIES[self.extension_sampling_frequency_index]
+            #             self.extension_channel_configuration = reader.read(4)
+
+    @dataclass
+    class StreamMuxConfig:
+        other_data_present: int
+        other_data_len_bits: int
+        audio_specific_config: AacAudioRtpPacket.AudioSpecificConfig
+
+        def __init__(self, reader: BitReader) -> None:
+            # StreamMuxConfig - ISO/EIC 14496-3 Table 1.42
+            audio_mux_version = reader.read(1)
+            if audio_mux_version == 1:
+                audio_mux_version_a = reader.read(1)
+            else:
+                audio_mux_version_a = 0
+            if audio_mux_version_a != 0:
+                raise ValueError('audioMuxVersionA != 0 not supported')
+            if audio_mux_version == 1:
+                tara_buffer_fullness = AacAudioRtpPacket.latm_value(reader)
+            stream_cnt = 0
+            all_streams_same_time_framing = reader.read(1)
+            num_sub_frames = reader.read(6)
+            num_program = reader.read(4)
+            if num_program != 0:
+                raise ValueError('num_program != 0 not supported')
+            num_layer = reader.read(3)
+            if num_layer != 0:
+                raise ValueError('num_layer != 0 not supported')
+            if audio_mux_version == 0:
+                self.audio_specific_config = AacAudioRtpPacket.AudioSpecificConfig(
+                    reader
+                )
+            else:
+                asc_len = AacAudioRtpPacket.latm_value(reader)
+                marker = reader.bit_position
+                self.audio_specific_config = AacAudioRtpPacket.AudioSpecificConfig(
+                    reader
+                )
+                audio_specific_config_len = reader.bit_position - marker
+                if asc_len < audio_specific_config_len:
+                    raise ValueError('audio_specific_config_len > asc_len')
+                asc_len -= audio_specific_config_len
+                reader.skip(asc_len)
+            frame_length_type = reader.read(3)
+            if frame_length_type == 0:
+                latm_buffer_fullness = reader.read(8)
+            elif frame_length_type == 1:
+                frame_length = reader.read(9)
+            else:
+                raise ValueError(f'frame_length_type {frame_length_type} not supported')
+
+            self.other_data_present = reader.read(1)
+            if self.other_data_present:
+                if audio_mux_version == 1:
+                    self.other_data_len_bits = AacAudioRtpPacket.latm_value(reader)
+                else:
+                    self.other_data_len_bits = 0
+                    while True:
+                        self.other_data_len_bits *= 256
+                        other_data_len_esc = reader.read(1)
+                        self.other_data_len_bits += reader.read(8)
+                        if other_data_len_esc == 0:
+                            break
+            crc_check_present = reader.read(1)
+            if crc_check_present:
+                crc_checksum = reader.read(8)
+
+    @dataclass
+    class AudioMuxElement:
+        payload: bytes
+        stream_mux_config: AacAudioRtpPacket.StreamMuxConfig
+
+        def __init__(self, reader: BitReader, mux_config_present: int):
+            if mux_config_present == 0:
+                raise ValueError('muxConfigPresent == 0 not supported')
+
+            # AudioMuxElement - ISO/EIC 14496-3 Table 1.41
+            use_same_stream_mux = reader.read(1)
+            if use_same_stream_mux:
+                raise ValueError('useSameStreamMux == 1 not supported')
+            self.stream_mux_config = AacAudioRtpPacket.StreamMuxConfig(reader)
+
+            # We only support:
+            # allStreamsSameTimeFraming == 1
+            # audioMuxVersionA == 0,
+            # numProgram == 0
+            # numSubFrames == 0
+            # numLayer == 0
+
+            mux_slot_length_bytes = 0
+            while True:
+                tmp = reader.read(8)
+                mux_slot_length_bytes += tmp
+                if tmp != 255:
+                    break
+
+            self.payload = reader.read_bytes(mux_slot_length_bytes)
+
+            if self.stream_mux_config.other_data_present:
+                reader.skip(self.stream_mux_config.other_data_len_bits)
+
+            # ByteAlign
+            while reader.bit_position % 8:
+                reader.read(1)
+
+    def __init__(self, data: bytes) -> None:
+        # Parse the bit stream
+        reader = BitReader(data)
+        self.audio_mux_element = self.AudioMuxElement(reader, mux_config_present=1)
+
+    def to_adts(self):
+        # pylint: disable=line-too-long
+        sampling_frequency_index = (
+            self.audio_mux_element.stream_mux_config.audio_specific_config.sampling_frequency_index
+        )
+        channel_configuration = (
+            self.audio_mux_element.stream_mux_config.audio_specific_config.channel_configuration
+        )
+        frame_size = len(self.audio_mux_element.payload)
+        return (
+            bytes(
+                [
+                    0xFF,
+                    0xF1,  # 0xF9 (MPEG2)
+                    0x40
+                    | (sampling_frequency_index << 2)
+                    | (channel_configuration >> 2),
+                    ((channel_configuration & 0x3) << 6) | ((frame_size + 7) >> 11),
+                    ((frame_size + 7) >> 3) & 0xFF,
+                    (((frame_size + 7) << 5) & 0xFF) | 0x1F,
+                    0xFC,
+                ]
+            )
+            + self.audio_mux_element.payload
+        )

bumble/colors.py

@@ -0,0 +1,103 @@
+# Copyright (c) 2012 Giorgos Verigakis <verigak@gmail.com>
+#
+# Permission to use, copy, modify, and distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+from functools import partial
+from typing import List, Optional, Union
+
+
+# ANSI color names. There is also a "default"
+COLORS = ('black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white')
+
+# ANSI style names
+STYLES = (
+    'none',
+    'bold',
+    'faint',
+    'italic',
+    'underline',
+    'blink',
+    'blink2',
+    'negative',
+    'concealed',
+    'crossed',
+)
+
+
+ColorSpec = Union[str, int]
+
+
+def _join(*values: ColorSpec) -> str:
+    return ';'.join(str(v) for v in values)
+
+
+def _color_code(spec: ColorSpec, base: int) -> str:
+    if isinstance(spec, str):
+        spec = spec.strip().lower()
+
+    if spec == 'default':
+        return _join(base + 9)
+    elif spec in COLORS:
+        return _join(base + COLORS.index(spec))
+    elif isinstance(spec, int) and 0 <= spec <= 255:
+        return _join(base + 8, 5, spec)
+    else:
+        raise ValueError('Invalid color spec "%s"' % spec)
+
+
+def color(
+    s: str,
+    fg: Optional[ColorSpec] = None,
+    bg: Optional[ColorSpec] = None,
+    style: Optional[str] = None,
+) -> str:
+    codes: List[ColorSpec] = []
+
+    if fg:
+        codes.append(_color_code(fg, 30))
+    if bg:
+        codes.append(_color_code(bg, 40))
+    if style:
+        for style_part in style.split('+'):
+            if style_part in STYLES:
+                codes.append(STYLES.index(style_part))
+            else:
+                raise ValueError('Invalid style "%s"' % style_part)
+
+    if codes:
+        return '\x1b[{0}m{1}\x1b[0m'.format(_join(*codes), s)
+    else:
+        return s
+
+
+# Foreground color shortcuts
+black = partial(color, fg='black')
+red = partial(color, fg='red')
+green = partial(color, fg='green')
+yellow = partial(color, fg='yellow')
+blue = partial(color, fg='blue')
+magenta = partial(color, fg='magenta')
+cyan = partial(color, fg='cyan')
+white = partial(color, fg='white')
+
+# Style shortcuts
+bold = partial(color, style='bold')
+none = partial(color, style='none')
+faint = partial(color, style='faint')
+italic = partial(color, style='italic')
+underline = partial(color, style='underline')
+blink = partial(color, style='blink')
+blink2 = partial(color, style='blink2')
+negative = partial(color, style='negative')
+concealed = partial(color, style='concealed')
+crossed = partial(color, style='crossed')

bumble/company_ids.py

@@ -17,6 +17,7 @@
 #  the `generate_company_id_list.py` script
 # -----------------------------------------------------------------------------
 
+# pylint: disable=line-too-long
 COMPANY_IDENTIFIERS = {
     0x0000: "Ericsson Technology Licensing",
     0x0001: "Nokia Mobile Phones",
@@ -196,28 +197,28 @@ COMPANY_IDENTIFIERS = {
     0x00AF: "Cinetix",
     0x00B0: "Passif Semiconductor Corp",
     0x00B1: "Saris Cycling Group, Inc",
-    0x00B2: "​Bekey A/S",
-    0x00B3: "​Clarinox Technologies Pty. Ltd.",
-    0x00B4: "​BDE Technology Co., Ltd.",
+    0x00B2: "Bekey A/S",
+    0x00B3: "Clarinox Technologies Pty. Ltd.",
+    0x00B4: "BDE Technology Co., Ltd.",
     0x00B5: "Swirl Networks",
-    0x00B6: "​Meso international",
-    0x00B7: "​TreLab Ltd",
-    0x00B8: "​Qualcomm Innovation Center, Inc. (QuIC)",
-    0x00B9: "​​Johnson Controls, Inc.",
-    0x00BA: "​Starkey Laboratories Inc.",
-    0x00BB: "​​S-Power Electronics Limited",
-    0x00BC: "​​Ace Sensor Inc",
-    0x00BD: "​​Aplix Corporation",
-    0x00BE: "​​AAMP of America",
-    0x00BF: "​​Stalmart Technology Limited",
-    0x00C0: "​​AMICCOM Electronics Corporation",
-    0x00C1: "​​Shenzhen Excelsecu Data Technology Co.,Ltd",
-    0x00C2: "​​Geneq Inc.",
-    0x00C3: "​​adidas AG",
-    0x00C4: "​​LG Electronics​",
-    0x00C5: "​Onset Computer Corporation",
-    0x00C6: "​Selfly BV",
-    0x00C7: "​Quuppa Oy.",
+    0x00B6: "Meso international",
+    0x00B7: "TreLab Ltd",
+    0x00B8: "Qualcomm Innovation Center, Inc. (QuIC)",
+    0x00B9: "Johnson Controls, Inc.",
+    0x00BA: "Starkey Laboratories Inc.",
+    0x00BB: "S-Power Electronics Limited",
+    0x00BC: "Ace Sensor Inc",
+    0x00BD: "Aplix Corporation",
+    0x00BE: "AAMP of America",
+    0x00BF: "Stalmart Technology Limited",
+    0x00C0: "AMICCOM Electronics Corporation",
+    0x00C1: "Shenzhen Excelsecu Data Technology Co.,Ltd",
+    0x00C2: "Geneq Inc.",
+    0x00C3: "adidas AG",
+    0x00C4: "LG Electronics",
+    0x00C5: "Onset Computer Corporation",
+    0x00C6: "Selfly BV",
+    0x00C7: "Quuppa Oy.",
     0x00C8: "GeLo Inc",
     0x00C9: "Evluma",
     0x00CA: "MC10",
@@ -249,10 +250,10 @@ COMPANY_IDENTIFIERS = {
     0x00E4: "Laird Connectivity, Inc. formerly L.S. Research Inc.",
     0x00E5: "Eden Software Consultants Ltd.",
     0x00E6: "Freshtemp",
-    0x00E7: "​KS Technologies",
-    0x00E8: "​ACTS Technologies",
-    0x00E9: "​Vtrack Systems",
-    0x00EA: "​Nielsen-Kellerman Company",
+    0x00E7: "KS Technologies",
+    0x00E8: "ACTS Technologies",
+    0x00E9: "Vtrack Systems",
+    0x00EA: "Nielsen-Kellerman Company",
     0x00EB: "Server Technology Inc.",
     0x00EC: "BioResearch Associates",
     0x00ED: "Jolly Logic, LLC",
@@ -2704,5 +2705,5 @@ COMPANY_IDENTIFIERS = {
     0x0A7C: "WAFERLOCK",
     0x0A7D: "Freedman Electronics Pty Ltd",
     0x0A7E: "Keba AG",
-    0x0A7F: "Intuity Medical"
-}
+    0x0A7F: "Intuity Medical",
+}

bumble/core.py

@@ -15,7 +15,9 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import struct
+from typing import List, Optional, Tuple, Union, cast, Dict
 
 from .company_ids import COMPANY_IDENTIFIERS
 
@@ -23,6 +25,8 @@ from .company_ids import COMPANY_IDENTIFIERS
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+# fmt: off
+
 BT_CENTRAL_ROLE    = 0
 BT_PERIPHERAL_ROLE = 1
 
@@ -30,6 +34,9 @@ BT_BR_EDR_TRANSPORT = 0
 BT_LE_TRANSPORT     = 1
 
 
+# fmt: on
+
+
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
@@ -46,7 +53,7 @@ def bit_flags_to_strings(bits, bit_flag_names):
     return names
 
 
-def name_or_number(dictionary, number, width=2):
+def name_or_number(dictionary: Dict[int, str], number: int, width: int = 2) -> str:
     name = dictionary.get(number)
     if name is not None:
         return name
@@ -58,17 +65,25 @@ def padded_bytes(buffer, size):
     return buffer + bytes(padding_size)
 
 
+def get_dict_key_by_value(dictionary, value):
+    for key, val in dictionary.items():
+        if val == value:
+            return key
+    return None
+
+
 # -----------------------------------------------------------------------------
 # Exceptions
 # -----------------------------------------------------------------------------
 class BaseError(Exception):
-    """ Base class for errors with an error code, error name and namespace"""
+    """Base class for errors with an error code, error name and namespace"""
+
     def __init__(self, error_code, error_namespace='', error_name='', details=''):
         super().__init__()
-        self.error_code      = error_code
+        self.error_code = error_code
         self.error_namespace = error_namespace
-        self.error_name      = error_name
-        self.details         = details
+        self.error_name = error_name
+        self.details = details
 
     def __str__(self):
         if self.error_namespace:
@@ -84,27 +99,36 @@ class BaseError(Exception):
 
 
 class ProtocolError(BaseError):
-    """ Protocol Error """
+    """Protocol Error"""
 
 
-class TimeoutError(Exception):
-    """ Timeout Error """
+class TimeoutError(Exception):  # pylint: disable=redefined-builtin
+    """Timeout Error"""
 
 
 class CommandTimeoutError(Exception):
-    """ Command Timeout Error """
+    """Command Timeout Error"""
 
 
 class InvalidStateError(Exception):
-    """ Invalid State Error """
+    """Invalid State Error"""
 
 
-class ConnectionError(BaseError):
-    """ Connection Error """
-    FAILURE            = 0x01
+class ConnectionError(BaseError):  # pylint: disable=redefined-builtin
+    """Connection Error"""
+
+    FAILURE = 0x01
     CONNECTION_REFUSED = 0x02
 
-    def __init__(self, error_code, transport, peer_address, error_namespace='', error_name='', details=''):
+    def __init__(
+        self,
+        error_code,
+        transport,
+        peer_address,
+        error_namespace='',
+        error_name='',
+        details='',
+    ):
         super().__init__(error_code, error_namespace, error_name, details)
         self.transport = transport
         self.peer_address = peer_address
@@ -120,27 +144,42 @@ class ConnectionError(BaseError):
 class UUID:
     '''
     See Bluetooth spec Vol 3, Part B - 2.5.1 UUID
-    '''
-    BASE_UUID = bytes.fromhex('00001000800000805F9B34FB')
-    UUIDS = []  # Registry of all instances created
 
-    def __init__(self, uuid_str_or_int, name = None):
-        if type(uuid_str_or_int) is int:
+    Note that this class expects and works in little-endian byte-order throughout.
+    The exception is when interacting with strings, which are in big-endian byte-order.
+    '''
+
+    BASE_UUID = bytes.fromhex('00001000800000805F9B34FB')[::-1]  # little-endian
+    UUIDS: List[UUID] = []  # Registry of all instances created
+
+    uuid_bytes: bytes
+    name: Optional[str]
+
+    def __init__(
+        self, uuid_str_or_int: Union[str, int], name: Optional[str] = None
+    ) -> None:
+        if isinstance(uuid_str_or_int, int):
             self.uuid_bytes = struct.pack('<H', uuid_str_or_int)
         else:
             if len(uuid_str_or_int) == 36:
-                if uuid_str_or_int[8] != '-' or uuid_str_or_int[13] != '-' or uuid_str_or_int[18] != '-' or uuid_str_or_int[23] != '-':
+                if (
+                    uuid_str_or_int[8] != '-'
+                    or uuid_str_or_int[13] != '-'
+                    or uuid_str_or_int[18] != '-'
+                    or uuid_str_or_int[23] != '-'
+                ):
                     raise ValueError('invalid UUID format')
                 uuid_str = uuid_str_or_int.replace('-', '')
             else:
                 uuid_str = uuid_str_or_int
             if len(uuid_str) != 32 and len(uuid_str) != 8 and len(uuid_str) != 4:
-                raise ValueError('invalid UUID format')
+                raise ValueError(f"invalid UUID format: {uuid_str}")
             self.uuid_bytes = bytes(reversed(bytes.fromhex(uuid_str)))
         self.name = name
 
-    def register(self):
-        # Register this object in the class registry, and update the entry's name if it wasn't set already
+    def register(self) -> UUID:
+        # Register this object in the class registry, and update the entry's name if
+        # it wasn't set already
         for uuid in self.UUIDS:
             if self == uuid:
                 if uuid.name is None:
@@ -151,102 +190,102 @@ class UUID:
         return self
 
     @classmethod
-    def from_bytes(cls, uuid_bytes, name = None):
-        if len(uuid_bytes) in {2, 4, 16}:
+    def from_bytes(cls, uuid_bytes: bytes, name: Optional[str] = None) -> UUID:
+        if len(uuid_bytes) in (2, 4, 16):
             self = cls.__new__(cls)
             self.uuid_bytes = uuid_bytes
             self.name = name
 
             return self.register()
-        else:
-            raise ValueError('only 2, 4 and 16 bytes are allowed')
+
+        raise ValueError('only 2, 4 and 16 bytes are allowed')
 
     @classmethod
-    def from_16_bits(cls, uuid_16, name = None):
+    def from_16_bits(cls, uuid_16: int, name: Optional[str] = None) -> UUID:
         return cls.from_bytes(struct.pack('<H', uuid_16), name)
 
     @classmethod
-    def from_32_bits(cls, uuid_32, name = None):
+    def from_32_bits(cls, uuid_32: int, name: Optional[str] = None) -> UUID:
         return cls.from_bytes(struct.pack('<I', uuid_32), name)
 
     @classmethod
-    def parse_uuid(cls, bytes, offset):
-        return len(bytes), cls.from_bytes(bytes[offset:])
+    def parse_uuid(cls, uuid_as_bytes: bytes, offset: int) -> Tuple[int, UUID]:
+        return len(uuid_as_bytes), cls.from_bytes(uuid_as_bytes[offset:])
 
     @classmethod
-    def parse_uuid_2(cls, bytes, offset):
-        return offset + 2, cls.from_bytes(bytes[offset:offset + 2])
+    def parse_uuid_2(cls, uuid_as_bytes: bytes, offset: int) -> Tuple[int, UUID]:
+        return offset + 2, cls.from_bytes(uuid_as_bytes[offset : offset + 2])
 
-    def to_bytes(self, force_128 = False):
-        if len(self.uuid_bytes) == 16 or not force_128:
+    def to_bytes(self, force_128: bool = False) -> bytes:
+        '''
+        Serialize UUID in little-endian byte-order
+        '''
+        if not force_128:
             return self.uuid_bytes
-        elif len(self.uuid_bytes) == 4:
-            return self.uuid_bytes + UUID.BASE_UUID
-        else:
-            return self.uuid_bytes + bytes([0, 0]) + UUID.BASE_UUID
 
-    def to_pdu_bytes(self):
+        if len(self.uuid_bytes) == 2:
+            return self.BASE_UUID + self.uuid_bytes + bytes([0, 0])
+        elif len(self.uuid_bytes) == 4:
+            return self.BASE_UUID + self.uuid_bytes
+        elif len(self.uuid_bytes) == 16:
+            return self.uuid_bytes
+        else:
+            assert False, "unreachable"
+
+    def to_pdu_bytes(self) -> bytes:
         '''
         Convert to bytes for use in an ATT PDU.
         According to Vol 3, Part F - 3.2.1 Attribute Type:
         "All 32-bit Attribute UUIDs shall be converted to 128-bit UUIDs when the
          Attribute UUID is contained in an ATT PDU."
         '''
-        return self.to_bytes(force_128 = (len(self.uuid_bytes) == 4))
+        return self.to_bytes(force_128=(len(self.uuid_bytes) == 4))
 
-    def to_hex_str(self):
+    def to_hex_str(self, separator: str = '') -> str:
         if len(self.uuid_bytes) == 2 or len(self.uuid_bytes) == 4:
             return bytes(reversed(self.uuid_bytes)).hex().upper()
-        else:
-            return ''.join([
+
+        return separator.join(
+            [
                 bytes(reversed(self.uuid_bytes[12:16])).hex(),
                 bytes(reversed(self.uuid_bytes[10:12])).hex(),
                 bytes(reversed(self.uuid_bytes[8:10])).hex(),
                 bytes(reversed(self.uuid_bytes[6:8])).hex(),
-                bytes(reversed(self.uuid_bytes[0:6])).hex()
-            ]).upper()
+                bytes(reversed(self.uuid_bytes[0:6])).hex(),
+            ]
+        ).upper()
 
-    def __bytes__(self):
+    def __bytes__(self) -> bytes:
         return self.to_bytes()
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if isinstance(other, UUID):
-            return self.to_bytes(force_128 = True) == other.to_bytes(force_128 = True)
-        elif type(other) is str:
+            return self.to_bytes(force_128=True) == other.to_bytes(force_128=True)
+
+        if isinstance(other, str):
             return UUID(other) == self
 
         return False
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.uuid_bytes)
 
-    def __str__(self):
+    def __str__(self) -> str:
+        result = self.to_hex_str(separator='-')
         if len(self.uuid_bytes) == 2:
-            v = struct.unpack('<H', self.uuid_bytes)[0]
-            result = f'UUID-16:{v:04X}'
+            result = 'UUID-16:' + result
         elif len(self.uuid_bytes) == 4:
-            v = struct.unpack('<I', self.uuid_bytes)[0]
-            result = f'UUID-32:{v:08X}'
-        else:
-            result = '-'.join([
-                bytes(reversed(self.uuid_bytes[12:16])).hex(),
-                bytes(reversed(self.uuid_bytes[10:12])).hex(),
-                bytes(reversed(self.uuid_bytes[8:10])).hex(),
-                bytes(reversed(self.uuid_bytes[6:8])).hex(),
-                bytes(reversed(self.uuid_bytes[0:6])).hex()
-            ]).upper()
+            result = 'UUID-32:' + result
         if self.name is not None:
-            return result + f' ({self.name})'
-        else:
-            return result
-
-    def __repr__(self):
-        return str(self)
+            result += f' ({self.name})'
+        return result
 
 
 # -----------------------------------------------------------------------------
 # Common UUID constants
 # -----------------------------------------------------------------------------
+# fmt: off
+# pylint: disable=line-too-long
 
 # Protocol Identifiers
 BT_SDP_PROTOCOL_ID                      = UUID.from_16_bits(0x0001, 'SDP')
@@ -352,11 +391,17 @@ BT_HDP_SERVICE                                       = UUID.from_16_bits(0x1400,
 BT_HDP_SOURCE_SERVICE                                = UUID.from_16_bits(0x1401, 'HDP Source')
 BT_HDP_SINK_SERVICE                                  = UUID.from_16_bits(0x1402, 'HDP Sink')
 
+# fmt: on
+# pylint: enable=line-too-long
+
 
 # -----------------------------------------------------------------------------
 # DeviceClass
 # -----------------------------------------------------------------------------
 class DeviceClass:
+    # fmt: off
+    # pylint: disable=line-too-long
+
     # Major Service Classes (flags combined with OR)
     LIMITED_DISCOVERABLE_MODE_SERVICE_CLASS = (1 << 0)
     LE_AUDIO_SERVICE_CLASS                  = (1 << 1)
@@ -517,18 +562,96 @@ class DeviceClass:
         PERIPHERAL_HANDHELD_GESTURAL_INPUT_DEVICE_MINOR_DEVICE_CLASS: 'Handheld gestural input device'
     }
 
+    WEARABLE_UNCATEGORIZED_MINOR_DEVICE_CLASS = 0x00
+    WEARABLE_WRISTWATCH_MINOR_DEVICE_CLASS    = 0x01
+    WEARABLE_PAGER_MINOR_DEVICE_CLASS         = 0x02
+    WEARABLE_JACKET_MINOR_DEVICE_CLASS        = 0x03
+    WEARABLE_HELMET_MINOR_DEVICE_CLASS        = 0x04
+    WEARABLE_GLASSES_MINOR_DEVICE_CLASS       = 0x05
+
+    WEARABLE_MINOR_DEVICE_CLASS_NAMES = {
+        WEARABLE_UNCATEGORIZED_MINOR_DEVICE_CLASS: 'Uncategorized',
+        WEARABLE_WRISTWATCH_MINOR_DEVICE_CLASS:    'Wristwatch',
+        WEARABLE_PAGER_MINOR_DEVICE_CLASS:         'Pager',
+        WEARABLE_JACKET_MINOR_DEVICE_CLASS:        'Jacket',
+        WEARABLE_HELMET_MINOR_DEVICE_CLASS:        'Helmet',
+        WEARABLE_GLASSES_MINOR_DEVICE_CLASS:       'Glasses',
+    }
+
+    TOY_UNCATEGORIZED_MINOR_DEVICE_CLASS      = 0x00
+    TOY_ROBOT_MINOR_DEVICE_CLASS              = 0x01
+    TOY_VEHICLE_MINOR_DEVICE_CLASS            = 0x02
+    TOY_DOLL_ACTION_FIGURE_MINOR_DEVICE_CLASS = 0x03
+    TOY_CONTROLLER_MINOR_DEVICE_CLASS         = 0x04
+    TOY_GAME_MINOR_DEVICE_CLASS               = 0x05
+
+    TOY_MINOR_DEVICE_CLASS_NAMES = {
+        TOY_UNCATEGORIZED_MINOR_DEVICE_CLASS:      'Uncategorized',
+        TOY_ROBOT_MINOR_DEVICE_CLASS:              'Robot',
+        TOY_VEHICLE_MINOR_DEVICE_CLASS:            'Vehicle',
+        TOY_DOLL_ACTION_FIGURE_MINOR_DEVICE_CLASS: 'Doll/Action figure',
+        TOY_CONTROLLER_MINOR_DEVICE_CLASS:         'Controller',
+        TOY_GAME_MINOR_DEVICE_CLASS:               'Game',
+    }
+
+    HEALTH_UNDEFINED_MINOR_DEVICE_CLASS                 = 0x00
+    HEALTH_BLOOD_PRESSURE_MONITOR_MINOR_DEVICE_CLASS    = 0x01
+    HEALTH_THERMOMETER_MINOR_DEVICE_CLASS               = 0x02
+    HEALTH_WEIGHING_SCALE_MINOR_DEVICE_CLASS            = 0x03
+    HEALTH_GLUCOSE_METER_MINOR_DEVICE_CLASS             = 0x04
+    HEALTH_PULSE_OXIMETER_MINOR_DEVICE_CLASS            = 0x05
+    HEALTH_HEART_PULSE_RATE_MONITOR_MINOR_DEVICE_CLASS  = 0x06
+    HEALTH_HEALTH_DATA_DISPLAY_MINOR_DEVICE_CLASS       = 0x07
+    HEALTH_STEP_COUNTER_MINOR_DEVICE_CLASS              = 0x08
+    HEALTH_BODY_COMPOSITION_ANALYZER_MINOR_DEVICE_CLASS = 0x09
+    HEALTH_PEAK_FLOW_MONITOR_MINOR_DEVICE_CLASS         = 0x0A
+    HEALTH_MEDICATION_MONITOR_MINOR_DEVICE_CLASS        = 0x0B
+    HEALTH_KNEE_PROSTHESIS_MINOR_DEVICE_CLASS           = 0x0C
+    HEALTH_ANKLE_PROSTHESIS_MINOR_DEVICE_CLASS          = 0x0D
+    HEALTH_GENERIC_HEALTH_MANAGER_MINOR_DEVICE_CLASS    = 0x0E
+    HEALTH_PERSONAL_MOBILITY_DEVICE_MINOR_DEVICE_CLASS  = 0x0F
+
+    HEALTH_MINOR_DEVICE_CLASS_NAMES = {
+        HEALTH_UNDEFINED_MINOR_DEVICE_CLASS:                 'Undefined',
+        HEALTH_BLOOD_PRESSURE_MONITOR_MINOR_DEVICE_CLASS:    'Blood Pressure Monitor',
+        HEALTH_THERMOMETER_MINOR_DEVICE_CLASS:               'Thermometer',
+        HEALTH_WEIGHING_SCALE_MINOR_DEVICE_CLASS:            'Weighing Scale',
+        HEALTH_GLUCOSE_METER_MINOR_DEVICE_CLASS:             'Glucose Meter',
+        HEALTH_PULSE_OXIMETER_MINOR_DEVICE_CLASS:            'Pulse Oximeter',
+        HEALTH_HEART_PULSE_RATE_MONITOR_MINOR_DEVICE_CLASS:  'Heart/Pulse Rate Monitor',
+        HEALTH_HEALTH_DATA_DISPLAY_MINOR_DEVICE_CLASS:       'Health Data Display',
+        HEALTH_STEP_COUNTER_MINOR_DEVICE_CLASS:              'Step Counter',
+        HEALTH_BODY_COMPOSITION_ANALYZER_MINOR_DEVICE_CLASS: 'Body Composition Analyzer',
+        HEALTH_PEAK_FLOW_MONITOR_MINOR_DEVICE_CLASS:         'Peak Flow Monitor',
+        HEALTH_MEDICATION_MONITOR_MINOR_DEVICE_CLASS:        'Medication Monitor',
+        HEALTH_KNEE_PROSTHESIS_MINOR_DEVICE_CLASS:           'Knee Prosthesis',
+        HEALTH_ANKLE_PROSTHESIS_MINOR_DEVICE_CLASS:          'Ankle Prosthesis',
+        HEALTH_GENERIC_HEALTH_MANAGER_MINOR_DEVICE_CLASS:    'Generic Health Manager',
+        HEALTH_PERSONAL_MOBILITY_DEVICE_MINOR_DEVICE_CLASS:  'Personal Mobility Device',
+    }
+
     MINOR_DEVICE_CLASS_NAMES = {
         COMPUTER_MAJOR_DEVICE_CLASS:    COMPUTER_MINOR_DEVICE_CLASS_NAMES,
         PHONE_MAJOR_DEVICE_CLASS:       PHONE_MINOR_DEVICE_CLASS_NAMES,
         AUDIO_VIDEO_MAJOR_DEVICE_CLASS: AUDIO_VIDEO_MINOR_DEVICE_CLASS_NAMES,
-        PERIPHERAL_MAJOR_DEVICE_CLASS:  PERIPHERAL_MINOR_DEVICE_CLASS_NAMES
+        PERIPHERAL_MAJOR_DEVICE_CLASS:  PERIPHERAL_MINOR_DEVICE_CLASS_NAMES,
+        WEARABLE_MAJOR_DEVICE_CLASS:    WEARABLE_MINOR_DEVICE_CLASS_NAMES,
+        TOY_MAJOR_DEVICE_CLASS:         TOY_MINOR_DEVICE_CLASS_NAMES,
+        HEALTH_MAJOR_DEVICE_CLASS:      HEALTH_MINOR_DEVICE_CLASS_NAMES,
     }
 
+    # fmt: on
+    # pylint: enable=line-too-long
+
     @staticmethod
     def split_class_of_device(class_of_device):
         # Split the bit fields of the composite class of device value into:
         # (service_classes, major_device_class, minor_device_class)
-        return ((class_of_device >> 13 & 0x7FF), (class_of_device >> 8 & 0x1F), (class_of_device >> 2 & 0x3F))
+        return (
+            (class_of_device >> 13 & 0x7FF),
+            (class_of_device >> 8 & 0x1F),
+            (class_of_device >> 2 & 0x3F),
+        )
 
     @staticmethod
     def pack_class_of_device(service_classes, major_device_class, minor_device_class):
@@ -536,7 +659,9 @@ class DeviceClass:
 
     @staticmethod
     def service_class_labels(service_class_flags):
-        return bit_flags_to_strings(service_class_flags, DeviceClass.SERVICE_CLASS_LABELS)
+        return bit_flags_to_strings(
+            service_class_flags, DeviceClass.SERVICE_CLASS_LABELS
+        )
 
     @staticmethod
     def major_device_class_name(device_class):
@@ -553,7 +678,15 @@ class DeviceClass:
 # -----------------------------------------------------------------------------
 # Advertising Data
 # -----------------------------------------------------------------------------
+AdvertisingObject = Union[
+    List[UUID], Tuple[UUID, bytes], bytes, str, int, Tuple[int, int], Tuple[int, bytes]
+]
+
+
 class AdvertisingData:
+    # fmt: off
+    # pylint: disable=line-too-long
+
     # This list is only partial, it still needs to be filled in from the spec
     FLAGS                                          = 0x01
     INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS  = 0x02
@@ -665,7 +798,14 @@ class AdvertisingData:
     BR_EDR_CONTROLLER_FLAG            = 0x08
     BR_EDR_HOST_FLAG                  = 0x10
 
-    def __init__(self, ad_structures = []):
+    ad_structures: List[Tuple[int, bytes]]
+
+    # fmt: on
+    # pylint: enable=line-too-long
+
+    def __init__(self, ad_structures: Optional[List[Tuple[int, bytes]]] = None) -> None:
+        if ad_structures is None:
+            ad_structures = []
         self.ad_structures = ad_structures[:]
 
     @staticmethod
@@ -676,36 +816,36 @@ class AdvertisingData:
 
     @staticmethod
     def flags_to_string(flags, short=False):
-        flag_names = [
-            'LE Limited',
-            'LE General',
-            'No BR/EDR',
-            'BR/EDR C',
-            'BR/EDR H'
-        ] if short else [
-            'LE Limited Discoverable Mode',
-            'LE General Discoverable Mode',
-            'BR/EDR Not Supported',
-            'Simultaneous LE and BR/EDR (Controller)',
-            'Simultaneous LE and BR/EDR (Host)'
-        ]
+        flag_names = (
+            ['LE Limited', 'LE General', 'No BR/EDR', 'BR/EDR C', 'BR/EDR H']
+            if short
+            else [
+                'LE Limited Discoverable Mode',
+                'LE General Discoverable Mode',
+                'BR/EDR Not Supported',
+                'Simultaneous LE and BR/EDR (Controller)',
+                'Simultaneous LE and BR/EDR (Host)',
+            ]
+        )
         return ','.join(bit_flags_to_strings(flags, flag_names))
 
     @staticmethod
-    def uuid_list_to_objects(ad_data, uuid_size):
+    def uuid_list_to_objects(ad_data: bytes, uuid_size: int) -> List[UUID]:
         uuids = []
         offset = 0
-        while (uuid_size * (offset + 1)) <= len(ad_data):
-            uuids.append(UUID.from_bytes(ad_data[offset:offset + uuid_size]))
+        while (offset + uuid_size) <= len(ad_data):
+            uuids.append(UUID.from_bytes(ad_data[offset : offset + uuid_size]))
             offset += uuid_size
         return uuids
 
     @staticmethod
     def uuid_list_to_string(ad_data, uuid_size):
-        return ', '.join([
-            str(uuid)
-            for uuid in AdvertisingData.uuid_list_to_objects(ad_data, uuid_size)
-        ])
+        return ', '.join(
+            [
+                str(uuid)
+                for uuid in AdvertisingData.uuid_list_to_objects(ad_data, uuid_size)
+            ]
+        )
 
     @staticmethod
     def ad_data_to_string(ad_type, ad_data):
@@ -765,56 +905,65 @@ class AdvertisingData:
 
         return f'[{ad_type_str}]: {ad_data_str}'
 
+    # pylint: disable=too-many-return-statements
     @staticmethod
-    def ad_data_to_object(ad_type, ad_data):
-        if ad_type in {
+    def ad_data_to_object(ad_type: int, ad_data: bytes) -> AdvertisingObject:
+        if ad_type in (
             AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
             AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS
-        }:
+            AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS,
+        ):
             return AdvertisingData.uuid_list_to_objects(ad_data, 2)
-        elif ad_type in {
+
+        if ad_type in (
             AdvertisingData.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
             AdvertisingData.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS
-        }:
+            AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS,
+        ):
             return AdvertisingData.uuid_list_to_objects(ad_data, 4)
-        elif ad_type in {
+
+        if ad_type in (
             AdvertisingData.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
             AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
-            AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS
-        }:
+            AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS,
+        ):
             return AdvertisingData.uuid_list_to_objects(ad_data, 16)
-        elif ad_type == AdvertisingData.SERVICE_DATA_16_BIT_UUID:
+
+        if ad_type == AdvertisingData.SERVICE_DATA_16_BIT_UUID:
             return (UUID.from_bytes(ad_data[:2]), ad_data[2:])
-        elif ad_type == AdvertisingData.SERVICE_DATA_32_BIT_UUID:
+
+        if ad_type == AdvertisingData.SERVICE_DATA_32_BIT_UUID:
             return (UUID.from_bytes(ad_data[:4]), ad_data[4:])
-        elif ad_type == AdvertisingData.SERVICE_DATA_128_BIT_UUID:
+
+        if ad_type == AdvertisingData.SERVICE_DATA_128_BIT_UUID:
             return (UUID.from_bytes(ad_data[:16]), ad_data[16:])
-        elif ad_type in {
+
+        if ad_type in (
             AdvertisingData.SHORTENED_LOCAL_NAME,
             AdvertisingData.COMPLETE_LOCAL_NAME,
-            AdvertisingData.URI
-        }:
+            AdvertisingData.URI,
+        ):
             return ad_data.decode("utf-8")
-        elif ad_type in {
-            AdvertisingData.TX_POWER_LEVEL,
-            AdvertisingData.FLAGS
-        }:
-            return ad_data[0]
-        elif ad_type in {
+
+        if ad_type in (AdvertisingData.TX_POWER_LEVEL, AdvertisingData.FLAGS):
+            return cast(int, struct.unpack('B', ad_data)[0])
+
+        if ad_type in (
             AdvertisingData.APPEARANCE,
-            AdvertisingData.ADVERTISING_INTERVAL
-        }:
-            return struct.unpack('<H', ad_data)[0]
-        elif ad_type == AdvertisingData.CLASS_OF_DEVICE:
-            return struct.unpack('<I', bytes([*ad_data, 0]))[0]
-        elif ad_type == AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE:
-            return struct.unpack('<HH', ad_data)
-        elif ad_type == AdvertisingData.MANUFACTURER_SPECIFIC_DATA:
-            return (struct.unpack_from('<H', ad_data, 0)[0], ad_data[2:])
-        else:
-            return ad_data
+            AdvertisingData.ADVERTISING_INTERVAL,
+        ):
+            return cast(int, struct.unpack('<H', ad_data)[0])
+
+        if ad_type == AdvertisingData.CLASS_OF_DEVICE:
+            return cast(int, struct.unpack('<I', bytes([*ad_data, 0]))[0])
+
+        if ad_type == AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE:
+            return cast(Tuple[int, int], struct.unpack('<HH', ad_data))
+
+        if ad_type == AdvertisingData.MANUFACTURER_SPECIFIC_DATA:
+            return (cast(int, struct.unpack_from('<H', ad_data, 0)[0]), ad_data[2:])
+
+        return ad_data
 
     def append(self, data):
         offset = 0
@@ -823,30 +972,41 @@ class AdvertisingData:
             offset += 1
             if length > 0:
                 ad_type = data[offset]
-                ad_data = data[offset + 1:offset + length]
+                ad_data = data[offset + 1 : offset + length]
                 self.ad_structures.append((ad_type, ad_data))
             offset += length
 
-    def get(self, type_id, return_all=False, raw=False):
+    def get_all(self, type_id: int, raw: bool = False) -> List[AdvertisingObject]:
         '''
         Get Advertising Data Structure(s) with a given type
 
-        If return_all is True, returns a (possibly empty) list of matches,
-        else returns the first entry, or None if no structure matches.
+        Returns a (possibly empty) list of matches.
         '''
-        def process_ad_data(ad_data):
+
+        def process_ad_data(ad_data: bytes) -> AdvertisingObject:
             return ad_data if raw else self.ad_data_to_object(type_id, ad_data)
 
-        if return_all:
-            return [process_ad_data(ad[1]) for ad in self.ad_structures if ad[0] == type_id]
-        else:
-            return next((process_ad_data(ad[1]) for ad in self.ad_structures if ad[0] == type_id), None)
+        return [process_ad_data(ad[1]) for ad in self.ad_structures if ad[0] == type_id]
+
+    def get(self, type_id: int, raw: bool = False) -> Optional[AdvertisingObject]:
+        '''
+        Get Advertising Data Structure(s) with a given type
+
+        Returns the first entry, or None if no structure matches.
+        '''
+
+        all = self.get_all(type_id, raw=raw)
+        return all[0] if all else None
 
     def __bytes__(self):
-        return b''.join([bytes([len(x[1]) + 1, x[0]]) + x[1] for x in self.ad_structures])
+        return b''.join(
+            [bytes([len(x[1]) + 1, x[0]]) + x[1] for x in self.ad_structures]
+        )
 
     def to_string(self, separator=', '):
-        return separator.join([AdvertisingData.ad_data_to_string(x[0], x[1]) for x in self.ad_structures])
+        return separator.join(
+            [AdvertisingData.ad_data_to_string(x[0], x[1]) for x in self.ad_structures]
+        )
 
     def __str__(self):
         return self.to_string()
@@ -858,7 +1018,7 @@ class AdvertisingData:
 class ConnectionParameters:
     def __init__(self, connection_interval, peripheral_latency, supervision_timeout):
         self.connection_interval = connection_interval
-        self.peripheral_latency  = peripheral_latency
+        self.peripheral_latency = peripheral_latency
         self.supervision_timeout = supervision_timeout
 
     def __str__(self):

bumble/crypto.py

@@ -23,25 +23,18 @@
 # -----------------------------------------------------------------------------
 import logging
 import operator
-import platform
-if platform.system() != 'Emscripten':
-    import secrets
-    from cryptography.hazmat.primitives.ciphers import (
-        Cipher,
-        algorithms,
-        modes
-    )
-    from cryptography.hazmat.primitives.asymmetric.ec import (
-        generate_private_key,
-        ECDH,
-        EllipticCurvePublicNumbers,
-        EllipticCurvePrivateNumbers,
-        SECP256R1
-    )
-    from cryptography.hazmat.primitives import cmac
-else:
-    # TODO: implement stubs
-    pass
+
+import secrets
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.asymmetric.ec import (
+    generate_private_key,
+    ECDH,
+    EllipticCurvePublicNumbers,
+    EllipticCurvePrivateNumbers,
+    SECP256R1,
+)
+from cryptography.hazmat.primitives import cmac
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -66,16 +59,26 @@ class EccKey:
         d = int.from_bytes(d_bytes, byteorder='big', signed=False)
         x = int.from_bytes(x_bytes, byteorder='big', signed=False)
         y = int.from_bytes(y_bytes, byteorder='big', signed=False)
-        private_key = EllipticCurvePrivateNumbers(d, EllipticCurvePublicNumbers(x, y, SECP256R1())).private_key()
+        private_key = EllipticCurvePrivateNumbers(
+            d, EllipticCurvePublicNumbers(x, y, SECP256R1())
+        ).private_key()
         return cls(private_key)
 
     @property
     def x(self):
-        return self.private_key.public_key().public_numbers().x.to_bytes(32, byteorder='big')
+        return (
+            self.private_key.public_key()
+            .public_numbers()
+            .x.to_bytes(32, byteorder='big')
+        )
 
     @property
     def y(self):
-        return self.private_key.public_key().public_numbers().y.to_bytes(32, byteorder='big')
+        return (
+            self.private_key.public_key()
+            .public_numbers()
+            .y.to_bytes(32, byteorder='big')
+        )
 
     def dh(self, public_key_x, public_key_y):
         x = int.from_bytes(public_key_x, byteorder='big', signed=False)
@@ -92,7 +95,7 @@ class EccKey:
 
 # -----------------------------------------------------------------------------
 def xor(x, y):
-    assert(len(x) == len(y))
+    assert len(x) == len(y)
     return bytes(map(operator.xor, x, y))
 
 
@@ -118,7 +121,7 @@ def e(key, data):
 
 
 # -----------------------------------------------------------------------------
-def ah(k, r):
+def ah(k, r):  # pylint: disable=redefined-outer-name
     '''
     See Bluetooth spec Vol 3, Part H - 2.2.2 Random Address Hash function ah
     '''
@@ -129,9 +132,10 @@ def ah(k, r):
 
 
 # -----------------------------------------------------------------------------
-def c1(k, r, preq, pres, iat, rat, ia, ra):
+def c1(k, r, preq, pres, iat, rat, ia, ra):  # pylint: disable=redefined-outer-name
     '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.3 Confirm value generation function c1 for LE Legacy Pairing
+    See Bluetooth spec, Vol 3, Part H - 2.2.3 Confirm value generation function c1 for
+    LE Legacy Pairing
     '''
 
     p1 = bytes([iat, rat]) + preq + pres
@@ -142,7 +146,8 @@ def c1(k, r, preq, pres, iat, rat, ia, ra):
 # -----------------------------------------------------------------------------
 def s1(k, r1, r2):
     '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.4 Key generation function s1 for LE Legacy Pairing
+    See Bluetooth spec, Vol 3, Part H - 2.2.4 Key generation function s1 for LE Legacy
+    Pairing
     '''
 
     return e(k, r2[0:8] + r1[0:8])
@@ -163,71 +168,95 @@ def aes_cmac(m, k):
 # -----------------------------------------------------------------------------
 def f4(u, v, x, z):
     '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.6 LE Secure Connections Confirm Value Generation Function f4
+    See Bluetooth spec, Vol 3, Part H - 2.2.6 LE Secure Connections Confirm Value
+    Generation Function f4
     '''
-    return bytes(reversed(aes_cmac(bytes(reversed(u)) + bytes(reversed(v)) + z, bytes(reversed(x)))))
+    return bytes(
+        reversed(
+            aes_cmac(bytes(reversed(u)) + bytes(reversed(v)) + z, bytes(reversed(x)))
+        )
+    )
 
 
 # -----------------------------------------------------------------------------
 def f5(w, n1, n2, a1, a2):
     '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.7 LE Secure Connections Key Generation Function f5
+    See Bluetooth spec, Vol 3, Part H - 2.2.7 LE Secure Connections Key Generation
+    Function f5
 
     NOTE: this returns a tuple: (MacKey, LTK) in little-endian byte order
     '''
     salt = bytes.fromhex('6C888391AAF5A53860370BDB5A6083BE')
     t = aes_cmac(bytes(reversed(w)), salt)
-    key_id = bytes([0x62, 0x74, 0x6c, 0x65])
+    key_id = bytes([0x62, 0x74, 0x6C, 0x65])
     return (
-        bytes(reversed(aes_cmac(
-            bytes([0]) +
-            key_id +
-            bytes(reversed(n1)) +
-            bytes(reversed(n2)) +
-            bytes(reversed(a1)) +
-            bytes(reversed(a2)) +
-            bytes([1, 0]),
-            t
-        ))),
-        bytes(reversed(aes_cmac(
-            bytes([1]) +
-            key_id +
-            bytes(reversed(n1)) +
-            bytes(reversed(n2)) +
-            bytes(reversed(a1)) +
-            bytes(reversed(a2)) +
-            bytes([1, 0]),
-            t
-        )))
+        bytes(
+            reversed(
+                aes_cmac(
+                    bytes([0])
+                    + key_id
+                    + bytes(reversed(n1))
+                    + bytes(reversed(n2))
+                    + bytes(reversed(a1))
+                    + bytes(reversed(a2))
+                    + bytes([1, 0]),
+                    t,
+                )
+            )
+        ),
+        bytes(
+            reversed(
+                aes_cmac(
+                    bytes([1])
+                    + key_id
+                    + bytes(reversed(n1))
+                    + bytes(reversed(n2))
+                    + bytes(reversed(a1))
+                    + bytes(reversed(a2))
+                    + bytes([1, 0]),
+                    t,
+                )
+            )
+        ),
     )
 
 
 # -----------------------------------------------------------------------------
-def f6(w, n1, n2, r, io_cap, a1, a2):
+def f6(w, n1, n2, r, io_cap, a1, a2):  # pylint: disable=redefined-outer-name
     '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.8 LE Secure Connections Check Value Generation Function f6
+    See Bluetooth spec, Vol 3, Part H - 2.2.8 LE Secure Connections Check Value
+    Generation Function f6
     '''
-    return bytes(reversed(aes_cmac(
-        bytes(reversed(n1)) +
-        bytes(reversed(n2)) +
-        bytes(reversed(r)) +
-        bytes(reversed(io_cap)) +
-        bytes(reversed(a1)) +
-        bytes(reversed(a2)),
-        bytes(reversed(w))
-    )))
+    return bytes(
+        reversed(
+            aes_cmac(
+                bytes(reversed(n1))
+                + bytes(reversed(n2))
+                + bytes(reversed(r))
+                + bytes(reversed(io_cap))
+                + bytes(reversed(a1))
+                + bytes(reversed(a2)),
+                bytes(reversed(w)),
+            )
+        )
+    )
 
 
 # -----------------------------------------------------------------------------
 def g2(u, v, x, y):
     '''
-    See Bluetooth spec, Vol 3, Part H - 2.2.9 LE Secure Connections Numeric Comparison Value Generation Function g2
+    See Bluetooth spec, Vol 3, Part H - 2.2.9 LE Secure Connections Numeric Comparison
+    Value Generation Function g2
     '''
     return int.from_bytes(
-        aes_cmac(bytes(reversed(u)) + bytes(reversed(v)) + bytes(reversed(y)), bytes(reversed(x)))[-4:],
-        byteorder='big'
+        aes_cmac(
+            bytes(reversed(u)) + bytes(reversed(v)) + bytes(reversed(y)),
+            bytes(reversed(x)),
+        )[-4:],
+        byteorder='big',
     )
 
+
 # -----------------------------------------------------------------------------
 def h6(w, key_id):
     '''
@@ -235,6 +264,7 @@ def h6(w, key_id):
     '''
     return aes_cmac(key_id, w)
 
+
 # -----------------------------------------------------------------------------
 def h7(salt, w):
     '''

bumble/decoder.py

@@ -0,0 +1,416 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+# fmt: off
+
+WL = [-60, -30, 58, 172, 334, 538, 1198, 3042]
+RL42 = [0, 7, 6, 5, 4, 3, 2, 1, 7, 6, 5, 4, 3, 2, 1, 0]
+ILB = [
+    2048,
+    2093,
+    2139,
+    2186,
+    2233,
+    2282,
+    2332,
+    2383,
+    2435,
+    2489,
+    2543,
+    2599,
+    2656,
+    2714,
+    2774,
+    2834,
+    2896,
+    2960,
+    3025,
+    3091,
+    3158,
+    3228,
+    3298,
+    3371,
+    3444,
+    3520,
+    3597,
+    3676,
+    3756,
+    3838,
+    3922,
+    4008,
+]
+WH = [0, -214, 798]
+RH2 = [2, 1, 2, 1]
+# Values in QM2/QM4/QM6 left shift three bits than original g722 specification.
+QM2 = [-7408, -1616, 7408, 1616]
+QM4 = [
+    0,
+    -20456,
+    -12896,
+    -8968,
+    -6288,
+    -4240,
+    -2584,
+    -1200,
+    20456,
+    12896,
+    8968,
+    6288,
+    4240,
+    2584,
+    1200,
+    0,
+]
+QM6 = [
+    -136,
+    -136,
+    -136,
+    -136,
+    -24808,
+    -21904,
+    -19008,
+    -16704,
+    -14984,
+    -13512,
+    -12280,
+    -11192,
+    -10232,
+    -9360,
+    -8576,
+    -7856,
+    -7192,
+    -6576,
+    -6000,
+    -5456,
+    -4944,
+    -4464,
+    -4008,
+    -3576,
+    -3168,
+    -2776,
+    -2400,
+    -2032,
+    -1688,
+    -1360,
+    -1040,
+    -728,
+    24808,
+    21904,
+    19008,
+    16704,
+    14984,
+    13512,
+    12280,
+    11192,
+    10232,
+    9360,
+    8576,
+    7856,
+    7192,
+    6576,
+    6000,
+    5456,
+    4944,
+    4464,
+    4008,
+    3576,
+    3168,
+    2776,
+    2400,
+    2032,
+    1688,
+    1360,
+    1040,
+    728,
+    432,
+    136,
+    -432,
+    -136,
+]
+QMF_COEFFS = [3, -11, 12, 32, -210, 951, 3876, -805, 362, -156, 53, -11]
+
+# fmt: on
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class G722Decoder(object):
+    """G.722 decoder with bitrate 64kbit/s.
+
+    For the Blocks in the sub-band decoders, please refer to the G.722
+    specification for the required information. G722 specification:
+    https://www.itu.int/rec/T-REC-G.722-201209-I
+    """
+
+    def __init__(self):
+        self._x = [0] * 24
+        self._band = [Band(), Band()]
+        # The initial value in BLOCK 3L
+        self._band[0].det = 32
+        # The initial value in BLOCK 3H
+        self._band[1].det = 8
+
+    def decode_frame(self, encoded_data) -> bytearray:
+        result_array = bytearray(len(encoded_data) * 4)
+        self.g722_decode(result_array, encoded_data)
+        return result_array
+
+    def g722_decode(self, result_array, encoded_data) -> int:
+        """Decode the data frame using g722 decoder."""
+        result_length = 0
+
+        for code in encoded_data:
+            higher_bits = (code >> 6) & 0x03
+            lower_bits = code & 0x3F
+
+            rlow = self.lower_sub_band_decoder(lower_bits)
+            rhigh = self.higher_sub_band_decoder(higher_bits)
+
+            # Apply the receive QMF
+            self._x[:22] = self._x[2:]
+            self._x[22] = rlow + rhigh
+            self._x[23] = rlow - rhigh
+
+            xout2 = sum(self._x[2 * i] * QMF_COEFFS[i] for i in range(12))
+            xout1 = sum(self._x[2 * i + 1] * QMF_COEFFS[11 - i] for i in range(12))
+
+            result_length = self.update_decoded_result(
+                xout1, result_length, result_array
+            )
+            result_length = self.update_decoded_result(
+                xout2, result_length, result_array
+            )
+
+        return result_length
+
+    def update_decoded_result(self, xout, byte_length, byte_array) -> int:
+        result = (int)(xout >> 11)
+        bytes_result = result.to_bytes(2, 'little', signed=True)
+        byte_array[byte_length] = bytes_result[0]
+        byte_array[byte_length + 1] = bytes_result[1]
+        return byte_length + 2
+
+    def lower_sub_band_decoder(self, lower_bits) -> int:
+        """Lower sub-band decoder for last six bits."""
+
+        # Block 5L
+        # INVQBL
+        wd1 = lower_bits
+        wd2 = QM6[wd1]
+        wd1 >>= 2
+        wd2 = (self._band[0].det * wd2) >> 15
+        # RECONS
+        rlow = self._band[0].s + wd2
+
+        # Block 6L
+        # LIMIT
+        if rlow > 16383:
+            rlow = 16383
+        elif rlow < -16384:
+            rlow = -16384
+
+        # Block 2L
+        # INVQAL
+        wd2 = QM4[wd1]
+        dlowt = (self._band[0].det * wd2) >> 15
+
+        # Block 3L
+        # LOGSCL
+        wd2 = RL42[wd1]
+        wd1 = (self._band[0].nb * 127) >> 7
+        wd1 += WL[wd2]
+
+        if wd1 < 0:
+            wd1 = 0
+        elif wd1 > 18432:
+            wd1 = 18432
+
+        self._band[0].nb = wd1
+
+        # SCALEL
+        wd1 = (self._band[0].nb >> 6) & 31
+        wd2 = 8 - (self._band[0].nb >> 11)
+
+        if wd2 < 0:
+            wd3 = ILB[wd1] << -wd2
+        else:
+            wd3 = ILB[wd1] >> wd2
+
+        self._band[0].det = wd3 << 2
+
+        # Block 4L
+        self._band[0].block4(dlowt)
+
+        return rlow
+
+    def higher_sub_band_decoder(self, higher_bits) -> int:
+        """Higher sub-band decoder for first two bits."""
+
+        # Block 2H
+        # INVQAH
+        wd2 = QM2[higher_bits]
+        dhigh = (self._band[1].det * wd2) >> 15
+
+        # Block 5H
+        # RECONS
+        rhigh = dhigh + self._band[1].s
+
+        # Block 6H
+        # LIMIT
+        if rhigh > 16383:
+            rhigh = 16383
+        elif rhigh < -16384:
+            rhigh = -16384
+
+        # Block 3H
+        # LOGSCH
+        wd2 = RH2[higher_bits]
+        wd1 = (self._band[1].nb * 127) >> 7
+        wd1 += WH[wd2]
+
+        if wd1 < 0:
+            wd1 = 0
+        elif wd1 > 22528:
+            wd1 = 22528
+        self._band[1].nb = wd1
+
+        # SCALEH
+        wd1 = (self._band[1].nb >> 6) & 31
+        wd2 = 10 - (self._band[1].nb >> 11)
+
+        if wd2 < 0:
+            wd3 = ILB[wd1] << -wd2
+        else:
+            wd3 = ILB[wd1] >> wd2
+        self._band[1].det = wd3 << 2
+
+        # Block 4H
+        self._band[1].block4(dhigh)
+
+        return rhigh
+
+
+# -----------------------------------------------------------------------------
+class Band(object):
+    """Structure for G722 decode proccessing."""
+
+    s: int = 0
+    nb: int = 0
+    det: int = 0
+
+    def __init__(self):
+        self._sp = 0
+        self._sz = 0
+        self._r = [0] * 3
+        self._a = [0] * 3
+        self._ap = [0] * 3
+        self._p = [0] * 3
+        self._d = [0] * 7
+        self._b = [0] * 7
+        self._bp = [0] * 7
+        self._sg = [0] * 7
+
+    def saturate(self, amp: int) -> int:
+        if amp > 32767:
+            return 32767
+        elif amp < -32768:
+            return -32768
+        else:
+            return amp
+
+    def block4(self, d: int) -> None:
+        """Block4 for both lower and higher sub-band decoder."""
+        wd1 = 0
+        wd2 = 0
+        wd3 = 0
+
+        # RECONS
+        self._d[0] = d
+        self._r[0] = self.saturate(self.s + d)
+
+        # PARREC
+        self._p[0] = self.saturate(self._sz + d)
+
+        # UPPOL2
+        for i in range(3):
+            self._sg[i] = (self._p[i]) >> 15
+        wd1 = self.saturate((self._a[1]) << 2)
+        wd2 = -wd1 if self._sg[0] == self._sg[1] else wd1
+
+        if wd2 > 32767:
+            wd2 = 32767
+
+        wd3 = 128 if self._sg[0] == self._sg[2] else -128
+        wd3 += wd2 >> 7
+        wd3 += (self._a[2] * 32512) >> 15
+
+        if wd3 > 12288:
+            wd3 = 12288
+        elif wd3 < -12288:
+            wd3 = -12288
+        self._ap[2] = wd3
+
+        # UPPOL1
+        self._sg[0] = (self._p[0]) >> 15
+        self._sg[1] = (self._p[1]) >> 15
+        wd1 = 192 if self._sg[0] == self._sg[1] else -192
+        wd2 = (self._a[1] * 32640) >> 15
+
+        self._ap[1] = self.saturate(wd1 + wd2)
+        wd3 = self.saturate(15360 - self._ap[2])
+
+        if self._ap[1] > wd3:
+            self._ap[1] = wd3
+        elif self._ap[1] < -wd3:
+            self._ap[1] = -wd3
+
+        # UPZERO
+        wd1 = 0 if d == 0 else 128
+        self._sg[0] = d >> 15
+        for i in range(1, 7):
+            self._sg[i] = (self._d[i]) >> 15
+            wd2 = wd1 if self._sg[i] == self._sg[0] else -wd1
+            wd3 = (self._b[i] * 32640) >> 15
+            self._bp[i] = self.saturate(wd2 + wd3)
+
+        # DELAYA
+        for i in range(6, 0, -1):
+            self._d[i] = self._d[i - 1]
+            self._b[i] = self._bp[i]
+
+        for i in range(2, 0, -1):
+            self._r[i] = self._r[i - 1]
+            self._p[i] = self._p[i - 1]
+            self._a[i] = self._ap[i]
+
+        # FILTEP
+        self._sp = 0
+        for i in range(1, 3):
+            wd1 = self.saturate(self._r[i] + self._r[i])
+            self._sp += (self._a[i] * wd1) >> 15
+        self._sp = self.saturate(self._sp)
+
+        # FILTEZ
+        self._sz = 0
+        for i in range(6, 0, -1):
+            wd1 = self.saturate(self._d[i] + self._d[i])
+            self._sz += (self._b[i] * wd1) >> 15
+        self._sz = self.saturate(self._sz)
+
+        # PREDIC
+        self.s = self.saturate(self._sp + self._sz)

bumble/drivers/__init__.py

@@ -0,0 +1,90 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Drivers that can be used to customize the interaction between a host and a controller,
+like loading firmware after a cold start.
+"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import abc
+import logging
+import pathlib
+import platform
+import platformdirs
+from . import rtk
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class Driver(abc.ABC):
+    """Base class for drivers."""
+
+    @staticmethod
+    async def for_host(_host):
+        """Return a driver instance for a host.
+
+        Args:
+            host: Host object for which a driver should be created.
+
+        Returns:
+            A Driver instance if a driver should be instantiated for this host, or
+            None if no driver instance of this class is needed.
+        """
+        return None
+
+    @abc.abstractmethod
+    async def init_controller(self):
+        """Initialize the controller."""
+
+
+# -----------------------------------------------------------------------------
+# Functions
+# -----------------------------------------------------------------------------
+async def get_driver_for_host(host):
+    """Probe all known diver classes until one returns a valid instance for a host,
+    or none is found.
+    """
+    if driver := await rtk.Driver.for_host(host):
+        logger.debug("Instantiated RTK driver")
+        return driver
+
+    return None
+
+
+def project_data_dir() -> pathlib.Path:
+    """
+    Returns:
+        A path to an OS-specific directory for bumble data. The directory is created if
+         it doesn't exist.
+    """
+    if platform.system() == 'Darwin':
+        # platformdirs doesn't handle macOS right: it doesn't assemble a bundle id
+        # out of author & project
+        return platformdirs.user_data_path(
+            appname='com.google.bumble', ensure_exists=True
+        )
+    else:
+        # windows and linux don't use the com qualifier
+        return platformdirs.user_data_path(
+            appname='bumble', appauthor='google', ensure_exists=True
+        )

bumble/drivers/rtk.py

@@ -0,0 +1,666 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Support for Realtek USB dongles.
+Based on various online bits of information, including the Linux kernel.
+(see `drivers/bluetooth/btrtl.c`)
+"""
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from dataclasses import dataclass
+import asyncio
+import enum
+import logging
+import math
+import os
+import pathlib
+import platform
+import struct
+from typing import Tuple
+import weakref
+
+
+from bumble.hci import (
+    hci_command_op_code,
+    STATUS_SPEC,
+    HCI_SUCCESS,
+    HCI_COMMAND_NAMES,
+    HCI_Command,
+    HCI_Reset_Command,
+    HCI_Read_Local_Version_Information_Command,
+)
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+RTK_ROM_LMP_8723A = 0x1200
+RTK_ROM_LMP_8723B = 0x8723
+RTK_ROM_LMP_8821A = 0x8821
+RTK_ROM_LMP_8761A = 0x8761
+RTK_ROM_LMP_8822B = 0x8822
+RTK_ROM_LMP_8852A = 0x8852
+RTK_CONFIG_MAGIC = 0x8723AB55
+
+RTK_EPATCH_SIGNATURE = b"Realtech"
+
+RTK_FRAGMENT_LENGTH = 252
+
+RTK_FIRMWARE_DIR_ENV = "BUMBLE_RTK_FIRMWARE_DIR"
+RTK_LINUX_FIRMWARE_DIR = "/lib/firmware/rtl_bt"
+
+
+class RtlProjectId(enum.IntEnum):
+    PROJECT_ID_8723A = 0
+    PROJECT_ID_8723B = 1
+    PROJECT_ID_8821A = 2
+    PROJECT_ID_8761A = 3
+    PROJECT_ID_8822B = 8
+    PROJECT_ID_8723D = 9
+    PROJECT_ID_8821C = 10
+    PROJECT_ID_8822C = 13
+    PROJECT_ID_8761B = 14
+    PROJECT_ID_8852A = 18
+    PROJECT_ID_8852B = 20
+    PROJECT_ID_8852C = 25
+
+
+RTK_PROJECT_ID_TO_ROM = {
+    0: RTK_ROM_LMP_8723A,
+    1: RTK_ROM_LMP_8723B,
+    2: RTK_ROM_LMP_8821A,
+    3: RTK_ROM_LMP_8761A,
+    8: RTK_ROM_LMP_8822B,
+    9: RTK_ROM_LMP_8723B,
+    10: RTK_ROM_LMP_8821A,
+    13: RTK_ROM_LMP_8822B,
+    14: RTK_ROM_LMP_8761A,
+    18: RTK_ROM_LMP_8852A,
+    20: RTK_ROM_LMP_8852A,
+    25: RTK_ROM_LMP_8852A,
+}
+
+# List of USB (VendorID, ProductID) for Realtek-based devices.
+RTK_USB_PRODUCTS = {
+    # Realtek 8723AE
+    (0x0930, 0x021D),
+    (0x13D3, 0x3394),
+    # Realtek 8723BE
+    (0x0489, 0xE085),
+    (0x0489, 0xE08B),
+    (0x04F2, 0xB49F),
+    (0x13D3, 0x3410),
+    (0x13D3, 0x3416),
+    (0x13D3, 0x3459),
+    (0x13D3, 0x3494),
+    # Realtek 8723BU
+    (0x7392, 0xA611),
+    # Realtek 8723DE
+    (0x0BDA, 0xB009),
+    (0x2FF8, 0xB011),
+    # Realtek 8761BUV
+    (0x0B05, 0x190E),
+    (0x0BDA, 0x8771),
+    (0x2230, 0x0016),
+    (0x2357, 0x0604),
+    (0x2550, 0x8761),
+    (0x2B89, 0x8761),
+    (0x7392, 0xC611),
+    (0x0BDA, 0x877B),
+    # Realtek 8821AE
+    (0x0B05, 0x17DC),
+    (0x13D3, 0x3414),
+    (0x13D3, 0x3458),
+    (0x13D3, 0x3461),
+    (0x13D3, 0x3462),
+    # Realtek 8821CE
+    (0x0BDA, 0xB00C),
+    (0x0BDA, 0xC822),
+    (0x13D3, 0x3529),
+    # Realtek 8822BE
+    (0x0B05, 0x185C),
+    (0x13D3, 0x3526),
+    # Realtek 8822CE
+    (0x04C5, 0x161F),
+    (0x04CA, 0x4005),
+    (0x0B05, 0x18EF),
+    (0x0BDA, 0xB00C),
+    (0x0BDA, 0xC123),
+    (0x0BDA, 0xC822),
+    (0x0CB5, 0xC547),
+    (0x1358, 0xC123),
+    (0x13D3, 0x3548),
+    (0x13D3, 0x3549),
+    (0x13D3, 0x3553),
+    (0x13D3, 0x3555),
+    (0x2FF8, 0x3051),
+    # Realtek 8822CU
+    (0x13D3, 0x3549),
+    # Realtek 8852AE
+    (0x04C5, 0x165C),
+    (0x04CA, 0x4006),
+    (0x0BDA, 0x2852),
+    (0x0BDA, 0x385A),
+    (0x0BDA, 0x4852),
+    (0x0BDA, 0xC852),
+    (0x0CB8, 0xC549),
+    # Realtek 8852BE
+    (0x0BDA, 0x887B),
+    (0x0CB8, 0xC559),
+    (0x13D3, 0x3571),
+    # Realtek 8852CE
+    (0x04C5, 0x1675),
+    (0x04CA, 0x4007),
+    (0x0CB8, 0xC558),
+    (0x13D3, 0x3586),
+    (0x13D3, 0x3587),
+    (0x13D3, 0x3592),
+}
+
+# -----------------------------------------------------------------------------
+# HCI Commands
+# -----------------------------------------------------------------------------
+HCI_RTK_READ_ROM_VERSION_COMMAND = hci_command_op_code(0x3F, 0x6D)
+HCI_COMMAND_NAMES[HCI_RTK_READ_ROM_VERSION_COMMAND] = "HCI_RTK_READ_ROM_VERSION_COMMAND"
+
+
+@HCI_Command.command(return_parameters_fields=[("status", STATUS_SPEC), ("version", 1)])
+class HCI_RTK_Read_ROM_Version_Command(HCI_Command):
+    pass
+
+
+HCI_RTK_DOWNLOAD_COMMAND = hci_command_op_code(0x3F, 0x20)
+HCI_COMMAND_NAMES[HCI_RTK_DOWNLOAD_COMMAND] = "HCI_RTK_DOWNLOAD_COMMAND"
+
+
+@HCI_Command.command(
+    fields=[("index", 1), ("payload", RTK_FRAGMENT_LENGTH)],
+    return_parameters_fields=[("status", STATUS_SPEC), ("index", 1)],
+)
+class HCI_RTK_Download_Command(HCI_Command):
+    pass
+
+
+HCI_RTK_DROP_FIRMWARE_COMMAND = hci_command_op_code(0x3F, 0x66)
+HCI_COMMAND_NAMES[HCI_RTK_DROP_FIRMWARE_COMMAND] = "HCI_RTK_DROP_FIRMWARE_COMMAND"
+
+
+@HCI_Command.command()
+class HCI_RTK_Drop_Firmware_Command(HCI_Command):
+    pass
+
+
+# -----------------------------------------------------------------------------
+class Firmware:
+    def __init__(self, firmware):
+        extension_sig = bytes([0x51, 0x04, 0xFD, 0x77])
+
+        if not firmware.startswith(RTK_EPATCH_SIGNATURE):
+            raise ValueError("Firmware does not start with epatch signature")
+
+        if not firmware.endswith(extension_sig):
+            raise ValueError("Firmware does not end with extension sig")
+
+        # The firmware should start with a 14 byte header.
+        epatch_header_size = 14
+        if len(firmware) < epatch_header_size:
+            raise ValueError("Firmware too short")
+
+        # Look for the "project ID", starting from the end.
+        offset = len(firmware) - len(extension_sig)
+        project_id = -1
+        while offset >= epatch_header_size:
+            length, opcode = firmware[offset - 2 : offset]
+            offset -= 2
+
+            if opcode == 0xFF:
+                # End
+                break
+
+            if length == 0:
+                raise ValueError("Invalid 0-length instruction")
+
+            if opcode == 0 and length == 1:
+                project_id = firmware[offset - 1]
+                break
+
+            offset -= length
+
+        if project_id < 0:
+            raise ValueError("Project ID not found")
+
+        self.project_id = project_id
+
+        # Read the patch tables info.
+        self.version, num_patches = struct.unpack("<IH", firmware[8:14])
+        self.patches = []
+
+        # The patches tables are laid out as:
+        # <ChipID_1><ChipID_2>...<ChipID_N>  (16 bits each)
+        # <PatchLength_1><PatchLength_2>...<PatchLength_N> (16 bits each)
+        # <PatchOffset_1><PatchOffset_2>...<PatchOffset_N> (32 bits each)
+        if epatch_header_size + 8 * num_patches > len(firmware):
+            raise ValueError("Firmware too short")
+        chip_id_table_offset = epatch_header_size
+        patch_length_table_offset = chip_id_table_offset + 2 * num_patches
+        patch_offset_table_offset = chip_id_table_offset + 4 * num_patches
+        for patch_index in range(num_patches):
+            chip_id_offset = chip_id_table_offset + 2 * patch_index
+            (chip_id,) = struct.unpack_from("<H", firmware, chip_id_offset)
+            (patch_length,) = struct.unpack_from(
+                "<H", firmware, patch_length_table_offset + 2 * patch_index
+            )
+            (patch_offset,) = struct.unpack_from(
+                "<I", firmware, patch_offset_table_offset + 4 * patch_index
+            )
+            if patch_offset + patch_length > len(firmware):
+                raise ValueError("Firmware too short")
+
+            # Get the SVN version for the patch
+            (svn_version,) = struct.unpack_from(
+                "<I", firmware, patch_offset + patch_length - 8
+            )
+
+            # Create a payload with the patch, replacing the last 4 bytes with
+            # the firmware version.
+            self.patches.append(
+                (
+                    chip_id,
+                    firmware[patch_offset : patch_offset + patch_length - 4]
+                    + struct.pack("<I", self.version),
+                    svn_version,
+                )
+            )
+
+
+class Driver:
+    @dataclass
+    class DriverInfo:
+        rom: int
+        hci: Tuple[int, int]
+        config_needed: bool
+        has_rom_version: bool
+        has_msft_ext: bool = False
+        fw_name: str = ""
+        config_name: str = ""
+
+    DRIVER_INFOS = [
+        # 8723A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8723A,
+            hci=(0x0B, 0x06),
+            config_needed=False,
+            has_rom_version=False,
+            fw_name="rtl8723a_fw.bin",
+            config_name="",
+        ),
+        # 8723B
+        DriverInfo(
+            rom=RTK_ROM_LMP_8723B,
+            hci=(0x0B, 0x06),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8723b_fw.bin",
+            config_name="rtl8723b_config.bin",
+        ),
+        # 8723D
+        DriverInfo(
+            rom=RTK_ROM_LMP_8723B,
+            hci=(0x0D, 0x08),
+            config_needed=True,
+            has_rom_version=True,
+            fw_name="rtl8723d_fw.bin",
+            config_name="rtl8723d_config.bin",
+        ),
+        # 8821A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8821A,
+            hci=(0x0A, 0x06),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8821a_fw.bin",
+            config_name="rtl8821a_config.bin",
+        ),
+        # 8821C
+        DriverInfo(
+            rom=RTK_ROM_LMP_8821A,
+            hci=(0x0C, 0x08),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8821c_fw.bin",
+            config_name="rtl8821c_config.bin",
+        ),
+        # 8761A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8761A,
+            hci=(0x0A, 0x06),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8761a_fw.bin",
+            config_name="rtl8761a_config.bin",
+        ),
+        # 8761BU
+        DriverInfo(
+            rom=RTK_ROM_LMP_8761A,
+            hci=(0x0B, 0x0A),
+            config_needed=False,
+            has_rom_version=True,
+            fw_name="rtl8761bu_fw.bin",
+            config_name="rtl8761bu_config.bin",
+        ),
+        # 8822C
+        DriverInfo(
+            rom=RTK_ROM_LMP_8822B,
+            hci=(0x0C, 0x0A),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8822cu_fw.bin",
+            config_name="rtl8822cu_config.bin",
+        ),
+        # 8822B
+        DriverInfo(
+            rom=RTK_ROM_LMP_8822B,
+            hci=(0x0B, 0x07),
+            config_needed=True,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8822b_fw.bin",
+            config_name="rtl8822b_config.bin",
+        ),
+        # 8852A
+        DriverInfo(
+            rom=RTK_ROM_LMP_8852A,
+            hci=(0x0A, 0x0B),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8852au_fw.bin",
+            config_name="rtl8852au_config.bin",
+        ),
+        # 8852B
+        DriverInfo(
+            rom=RTK_ROM_LMP_8852A,
+            hci=(0xB, 0xB),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8852bu_fw.bin",
+            config_name="rtl8852bu_config.bin",
+        ),
+        # 8852C
+        DriverInfo(
+            rom=RTK_ROM_LMP_8852A,
+            hci=(0x0C, 0x0C),
+            config_needed=False,
+            has_rom_version=True,
+            has_msft_ext=True,
+            fw_name="rtl8852cu_fw.bin",
+            config_name="rtl8852cu_config.bin",
+        ),
+    ]
+
+    POST_DROP_DELAY = 0.2
+
+    @staticmethod
+    def find_driver_info(hci_version, hci_subversion, lmp_subversion):
+        for driver_info in Driver.DRIVER_INFOS:
+            if driver_info.rom == lmp_subversion and driver_info.hci == (
+                hci_subversion,
+                hci_version,
+            ):
+                return driver_info
+
+        return None
+
+    @staticmethod
+    def find_binary_path(file_name):
+        # First check if an environment variable is set
+        if RTK_FIRMWARE_DIR_ENV in os.environ:
+            if (
+                path := pathlib.Path(os.environ[RTK_FIRMWARE_DIR_ENV]) / file_name
+            ).is_file():
+                logger.debug(f"{file_name} found in env dir")
+                return path
+
+            # When the environment variable is set, don't look elsewhere
+            return None
+
+        # Then, look where the firmware download tool writes by default
+        if (path := rtk_firmware_dir() / file_name).is_file():
+            logger.debug(f"{file_name} found in project data dir")
+            return path
+
+        # Then, look in the package's driver directory
+        if (path := pathlib.Path(__file__).parent / "rtk_fw" / file_name).is_file():
+            logger.debug(f"{file_name} found in package dir")
+            return path
+
+        # On Linux, check the system's FW directory
+        if (
+            platform.system() == "Linux"
+            and (path := pathlib.Path(RTK_LINUX_FIRMWARE_DIR) / file_name).is_file()
+        ):
+            logger.debug(f"{file_name} found in Linux system FW dir")
+            return path
+
+        # Finally look in the current directory
+        if (path := pathlib.Path.cwd() / file_name).is_file():
+            logger.debug(f"{file_name} found in CWD")
+            return path
+
+        return None
+
+    @staticmethod
+    def check(host):
+        if not host.hci_metadata:
+            logger.debug("USB metadata not found")
+            return False
+
+        vendor_id = host.hci_metadata.get("vendor_id", None)
+        product_id = host.hci_metadata.get("product_id", None)
+        if vendor_id is None or product_id is None:
+            logger.debug("USB metadata not sufficient")
+            return False
+
+        if (vendor_id, product_id) not in RTK_USB_PRODUCTS:
+            logger.debug(
+                f"USB device ({vendor_id:04X}, {product_id:04X}) " "not in known list"
+            )
+            return False
+
+        return True
+
+    @classmethod
+    async def driver_info_for_host(cls, host):
+        response = await host.send_command(
+            HCI_Read_Local_Version_Information_Command(), check_result=True
+        )
+        local_version = response.return_parameters
+
+        logger.debug(
+            f"looking for a driver: 0x{local_version.lmp_subversion:04X} "
+            f"(0x{local_version.hci_version:02X}, "
+            f"0x{local_version.hci_subversion:04X})"
+        )
+
+        driver_info = cls.find_driver_info(
+            local_version.hci_version,
+            local_version.hci_subversion,
+            local_version.lmp_subversion,
+        )
+        if driver_info is None:
+            # TODO: it seems that the Linux driver will send command (0x3f, 0x66)
+            # in this case and then re-read the local version, then re-match.
+            logger.debug("firmware already loaded or no known driver for this device")
+
+        return driver_info
+
+    @classmethod
+    async def for_host(cls, host, force=False):
+        # Check that a driver is needed for this host
+        if not force and not cls.check(host):
+            return None
+
+        # Get the driver info
+        driver_info = await cls.driver_info_for_host(host)
+        if driver_info is None:
+            return None
+
+        # Load the firmware
+        firmware_path = cls.find_binary_path(driver_info.fw_name)
+        if not firmware_path:
+            logger.warning(f"Firmware file {driver_info.fw_name} not found")
+            logger.warning("See https://google.github.io/bumble/drivers/realtek.html")
+            return None
+        with open(firmware_path, "rb") as firmware_file:
+            firmware = firmware_file.read()
+
+        # Load the config
+        config = None
+        if driver_info.config_name:
+            config_path = cls.find_binary_path(driver_info.config_name)
+            if config_path:
+                with open(config_path, "rb") as config_file:
+                    config = config_file.read()
+        if driver_info.config_needed and not config:
+            logger.warning("Config needed, but no config file available")
+            return None
+
+        return cls(host, driver_info, firmware, config)
+
+    def __init__(self, host, driver_info, firmware, config):
+        self.host = weakref.proxy(host)
+        self.driver_info = driver_info
+        self.firmware = firmware
+        self.config = config
+
+    @staticmethod
+    async def drop_firmware(host):
+        host.send_hci_packet(HCI_RTK_Drop_Firmware_Command())
+
+        # Wait for the command to be effective (no response is sent)
+        await asyncio.sleep(Driver.POST_DROP_DELAY)
+
+    async def download_for_rtl8723a(self):
+        # Check that the firmware image does not include an epatch signature.
+        if RTK_EPATCH_SIGNATURE in self.firmware:
+            logger.warning(
+                "epatch signature found in firmware, it is probably the wrong firmware"
+            )
+            return
+
+        # TODO: load the firmware
+
+    async def download_for_rtl8723b(self):
+        if self.driver_info.has_rom_version:
+            response = await self.host.send_command(
+                HCI_RTK_Read_ROM_Version_Command(), check_result=True
+            )
+            if response.return_parameters.status != HCI_SUCCESS:
+                logger.warning("can't get ROM version")
+                return
+            rom_version = response.return_parameters.version
+            logger.debug(f"ROM version before download: {rom_version:04X}")
+        else:
+            rom_version = 0
+
+        firmware = Firmware(self.firmware)
+        logger.debug(f"firmware: project_id=0x{firmware.project_id:04X}")
+        for patch in firmware.patches:
+            if patch[0] == rom_version + 1:
+                logger.debug(f"using patch {patch[0]}")
+                break
+        else:
+            logger.warning("no valid patch found for rom version {rom_version}")
+            return
+
+        # Append the config if there is one.
+        if self.config:
+            payload = patch[1] + self.config
+        else:
+            payload = patch[1]
+
+        # Download the payload, one fragment at a time.
+        fragment_count = math.ceil(len(payload) / RTK_FRAGMENT_LENGTH)
+        for fragment_index in range(fragment_count):
+            # NOTE: the Linux driver somehow adds 1 to the index after it wraps around.
+            # That's odd, but we"ll do the same here.
+            download_index = fragment_index & 0x7F
+            if download_index >= 0x80:
+                download_index += 1
+            if fragment_index == fragment_count - 1:
+                download_index |= 0x80  # End marker.
+            fragment_offset = fragment_index * RTK_FRAGMENT_LENGTH
+            fragment = payload[fragment_offset : fragment_offset + RTK_FRAGMENT_LENGTH]
+            logger.debug(f"downloading fragment {fragment_index}")
+            await self.host.send_command(
+                HCI_RTK_Download_Command(
+                    index=download_index, payload=fragment, check_result=True
+                )
+            )
+
+        logger.debug("download complete!")
+
+        # Read the version again
+        response = await self.host.send_command(
+            HCI_RTK_Read_ROM_Version_Command(), check_result=True
+        )
+        if response.return_parameters.status != HCI_SUCCESS:
+            logger.warning("can't get ROM version")
+        else:
+            rom_version = response.return_parameters.version
+            logger.debug(f"ROM version after download: {rom_version:04X}")
+
+    async def download_firmware(self):
+        if self.driver_info.rom == RTK_ROM_LMP_8723A:
+            return await self.download_for_rtl8723a()
+
+        if self.driver_info.rom in (
+            RTK_ROM_LMP_8723B,
+            RTK_ROM_LMP_8821A,
+            RTK_ROM_LMP_8761A,
+            RTK_ROM_LMP_8822B,
+            RTK_ROM_LMP_8852A,
+        ):
+            return await self.download_for_rtl8723b()
+
+        raise ValueError("ROM not supported")
+
+    async def init_controller(self):
+        await self.download_firmware()
+        await self.host.send_command(HCI_Reset_Command(), check_result=True)
+        logger.info(f"loaded FW image {self.driver_info.fw_name}")
+
+
+def rtk_firmware_dir() -> pathlib.Path:
+    """
+    Returns:
+        A path to a subdir of the project data dir for Realtek firmware.
+         The directory is created if it doesn't exist.
+    """
+    from bumble.drivers import project_data_dir
+
+    p = project_data_dir() / "firmware" / "realtek"
+    p.mkdir(parents=True, exist_ok=True)
+    return p

bumble/gap.py

@@ -23,7 +23,7 @@ from .gatt import (
     Characteristic,
     GATT_GENERIC_ACCESS_SERVICE,
     GATT_DEVICE_NAME_CHARACTERISTIC,
-    GATT_APPEARANCE_CHARACTERISTIC
+    GATT_APPEARANCE_CHARACTERISTIC,
 )
 
 # -----------------------------------------------------------------------------
@@ -38,22 +38,22 @@ logger = logging.getLogger(__name__)
 
 # -----------------------------------------------------------------------------
 class GenericAccessService(Service):
-    def __init__(self, device_name, appearance = (0, 0)):
+    def __init__(self, device_name, appearance=(0, 0)):
         device_name_characteristic = Characteristic(
             GATT_DEVICE_NAME_CHARACTERISTIC,
-            Characteristic.READ,
+            Characteristic.Properties.READ,
             Characteristic.READABLE,
-            device_name.encode('utf-8')[:248]
+            device_name.encode('utf-8')[:248],
         )
 
         appearance_characteristic = Characteristic(
             GATT_APPEARANCE_CHARACTERISTIC,
-            Characteristic.READ,
+            Characteristic.Properties.READ,
             Characteristic.READABLE,
-            struct.pack('<H', (appearance[0] << 6) | appearance[1])
+            struct.pack('<H', (appearance[0] << 6) | appearance[1]),
         )
 
-        super().__init__(GATT_GENERIC_ACCESS_SERVICE, [
-            device_name_characteristic,
-            appearance_characteristic
-        ])
+        super().__init__(
+            GATT_GENERIC_ACCESS_SERVICE,
+            [device_name_characteristic, appearance_characteristic],
+        )

bumble/gatt.py

@@ -22,16 +22,18 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import enum
-import types
+import functools
 import logging
-from pyee import EventEmitter
-from colors import color
+import struct
+from typing import Optional, Sequence, List
+
+from .colors import color
+from .core import UUID, get_dict_key_by_value
+from .att import Attribute
 
-from .core import *
-from .hci import *
-from .att import *
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -41,6 +43,9 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+# fmt: off
+# pylint: disable=line-too-long
+
 GATT_REQUEST_TIMEOUT = 30  # seconds
 
 GATT_MAX_ATTRIBUTE_VALUE_SIZE = 512
@@ -151,6 +156,14 @@ GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC = UUID.from_16_bits(0x2A39, 'Heart
 # Battery Service
 GATT_BATTERY_LEVEL_CHARACTERISTIC = UUID.from_16_bits(0x2A19, 'Battery Level')
 
+# ASHA Service
+GATT_ASHA_SERVICE                             = UUID.from_16_bits(0xFDF0, 'Audio Streaming for Hearing Aid')
+GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC = UUID('6333651e-c481-4a3e-9169-7c902aad37bb', 'ReadOnlyProperties')
+GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC  = UUID('f0d4de7e-4a88-476c-9d9f-1937b0996cc0', 'AudioControlPoint')
+GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC         = UUID('38663f1a-e711-4cac-b641-326b56404837', 'AudioStatus')
+GATT_ASHA_VOLUME_CHARACTERISTIC               = UUID('00e4ca9e-ab14-41e4-8823-f9e70c7e91df', 'Volume')
+GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC           = UUID('2d410339-82b6-42aa-b34e-e2e01df8cc1a', 'LE_PSM_OUT')
+
 # Misc
 GATT_DEVICE_NAME_CHARACTERISTIC                                = UUID.from_16_bits(0x2A00, 'Device Name')
 GATT_APPEARANCE_CHARACTERISTIC                                 = UUID.from_16_bits(0x2A01, 'Appearance')
@@ -165,11 +178,15 @@ GATT_CURRENT_TIME_CHARACTERISTIC                               = UUID.from_16_bi
 GATT_BOOT_KEYBOARD_OUTPUT_REPORT_CHARACTERISTIC                = UUID.from_16_bits(0x2A32, 'Boot Keyboard Output Report')
 GATT_CENTRAL_ADDRESS_RESOLUTION__CHARACTERISTIC                = UUID.from_16_bits(0x2AA6, 'Central Address Resolution')
 
+# fmt: on
+# pylint: enable=line-too-long
+
 
 # -----------------------------------------------------------------------------
 # Utils
 # -----------------------------------------------------------------------------
 
+
 def show_services(services):
     for service in services:
         print(color(str(service), 'cyan'))
@@ -187,23 +204,48 @@ class Service(Attribute):
     See Vol 3, Part G - 3.1 SERVICE DEFINITION
     '''
 
-    def __init__(self, uuid, characteristics, primary=True):
+    uuid: UUID
+    characteristics: List[Characteristic]
+    included_services: List[Service]
+
+    def __init__(
+        self,
+        uuid,
+        characteristics: List[Characteristic],
+        primary=True,
+        included_services: List[Service] = [],
+    ):
         # Convert the uuid to a UUID object if it isn't already
-        if type(uuid) is str:
+        if isinstance(uuid, str):
             uuid = UUID(uuid)
 
         super().__init__(
-            GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE if primary else GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
+            GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE
+            if primary
+            else GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
             Attribute.READABLE,
-            uuid.to_pdu_bytes()
+            uuid.to_pdu_bytes(),
         )
-        self.uuid              = uuid
-        self.included_services = []
-        self.characteristics   = characteristics[:]
-        self.primary           = primary
+        self.uuid = uuid
+        self.included_services = included_services[:]
+        self.characteristics = characteristics[:]
+        self.primary = primary
+
+    def get_advertising_data(self) -> Optional[bytes]:
+        """
+        Get Service specific advertising data
+        Defined by each Service, default value is empty
+        :return Service data for advertising
+        """
+        return None
 
     def __str__(self):
-        return f'Service(handle=0x{self.handle:04X}, end=0x{self.end_group_handle:04X}, uuid={self.uuid}){"" if self.primary else "*"}'
+        return (
+            f'Service(handle=0x{self.handle:04X}, '
+            f'end=0x{self.end_group_handle:04X}, '
+            f'uuid={self.uuid})'
+            f'{"" if self.primary else "*"}'
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -212,54 +254,109 @@ class TemplateService(Service):
     Convenience abstract class that can be used by profile-specific subclasses that want
     to expose their UUID as a class property
     '''
-    UUID = None
+
+    UUID: Optional[UUID] = None
 
     def __init__(self, characteristics, primary=True):
         super().__init__(self.UUID, characteristics, primary)
 
 
+# -----------------------------------------------------------------------------
+class IncludedServiceDeclaration(Attribute):
+    '''
+    See Vol 3, Part G - 3.2 INCLUDE DEFINITION
+    '''
+
+    service: Service
+
+    def __init__(self, service):
+        declaration_bytes = struct.pack(
+            '<HH2s', service.handle, service.end_group_handle, service.uuid.to_bytes()
+        )
+        super().__init__(
+            GATT_INCLUDE_ATTRIBUTE_TYPE, Attribute.READABLE, declaration_bytes
+        )
+        self.service = service
+
+    def __str__(self):
+        return (
+            f'IncludedServiceDefinition(handle=0x{self.handle:04X}, '
+            f'group_starting_handle=0x{self.service.handle:04X}, '
+            f'group_ending_handle=0x{self.service.end_group_handle:04X}, '
+            f'uuid={self.service.uuid})'
+        )
+
+
 # -----------------------------------------------------------------------------
 class Characteristic(Attribute):
     '''
     See Vol 3, Part G - 3.3 CHARACTERISTIC DEFINITION
     '''
 
-    # Property flags
-    BROADCAST                   = 0x01
-    READ                        = 0x02
-    WRITE_WITHOUT_RESPONSE      = 0x04
-    WRITE                       = 0x08
-    NOTIFY                      = 0x10
-    INDICATE                    = 0X20
-    AUTHENTICATED_SIGNED_WRITES = 0X40
-    EXTENDED_PROPERTIES         = 0X80
+    uuid: UUID
+    properties: Characteristic.Properties
 
-    PROPERTY_NAMES = {
-        BROADCAST:                   'BROADCAST',
-        READ:                        'READ',
-        WRITE_WITHOUT_RESPONSE:      'WRITE_WITHOUT_RESPONSE',
-        WRITE:                       'WRITE',
-        NOTIFY:                      'NOTIFY',
-        INDICATE:                    'INDICATE',
-        AUTHENTICATED_SIGNED_WRITES: 'AUTHENTICATED_SIGNED_WRITES',
-        EXTENDED_PROPERTIES:         'EXTENDED_PROPERTIES'
-    }
+    class Properties(enum.IntFlag):
+        """Property flags"""
 
-    @staticmethod
-    def property_name(property):
-        return Characteristic.PROPERTY_NAMES.get(property, '')
+        BROADCAST = 0x01
+        READ = 0x02
+        WRITE_WITHOUT_RESPONSE = 0x04
+        WRITE = 0x08
+        NOTIFY = 0x10
+        INDICATE = 0x20
+        AUTHENTICATED_SIGNED_WRITES = 0x40
+        EXTENDED_PROPERTIES = 0x80
 
-    @staticmethod
-    def properties_as_string(properties):
-        return ','.join([
-            Characteristic.property_name(p) for p in Characteristic.PROPERTY_NAMES.keys()
-            if properties & p
-        ])
+        @classmethod
+        def from_string(cls, properties_str: str) -> Characteristic.Properties:
+            try:
+                return functools.reduce(
+                    lambda x, y: x | cls[y],
+                    properties_str.replace("|", ",").split(","),
+                    Characteristic.Properties(0),
+                )
+            except (TypeError, KeyError):
+                # The check for `p.name is not None` here is needed because for InFlag
+                # enums, the .name property can be None, when the enum value is 0,
+                # so the type hint for .name is Optional[str].
+                enum_list: List[str] = [p.name for p in cls if p.name is not None]
+                enum_list_str = ",".join(enum_list)
+                raise TypeError(
+                    f"Characteristic.Properties::from_string() error:\nExpected a string containing any of the keys, separated by , or |: {enum_list_str}\nGot: {properties_str}"
+                )
 
-    def __init__(self, uuid, properties, permissions, value = b'', descriptors = []):
+        def __str__(self):
+            # NOTE: we override this method to offer a consistent result between python
+            # versions: the value returned by IntFlag.__str__() changed in version 11.
+            return '|'.join(
+                flag.name
+                for flag in Characteristic.Properties
+                if self.value & flag.value and flag.name is not None
+            )
+
+    # For backwards compatibility these are defined here
+    # For new code, please use Characteristic.Properties.X
+    BROADCAST = Properties.BROADCAST
+    READ = Properties.READ
+    WRITE_WITHOUT_RESPONSE = Properties.WRITE_WITHOUT_RESPONSE
+    WRITE = Properties.WRITE
+    NOTIFY = Properties.NOTIFY
+    INDICATE = Properties.INDICATE
+    AUTHENTICATED_SIGNED_WRITES = Properties.AUTHENTICATED_SIGNED_WRITES
+    EXTENDED_PROPERTIES = Properties.EXTENDED_PROPERTIES
+
+    def __init__(
+        self,
+        uuid,
+        properties: Characteristic.Properties,
+        permissions,
+        value=b'',
+        descriptors: Sequence[Descriptor] = (),
+    ):
         super().__init__(uuid, permissions, value)
-        self.uuid        = self.type
-        self.properties  = properties
+        self.uuid = self.type
+        self.properties = properties
         self.descriptors = descriptors
 
     def get_descriptor(self, descriptor_type):
@@ -267,8 +364,46 @@ class Characteristic(Attribute):
             if descriptor.type == descriptor_type:
                 return descriptor
 
+        return None
+
+    def has_properties(self, properties: Characteristic.Properties) -> bool:
+        return self.properties & properties == properties
+
     def __str__(self):
-        return f'Characteristic(handle=0x{self.handle:04X}, end=0x{self.end_group_handle:04X}, uuid={self.uuid}, properties={Characteristic.properties_as_string(self.properties)})'
+        return (
+            f'Characteristic(handle=0x{self.handle:04X}, '
+            f'end=0x{self.end_group_handle:04X}, '
+            f'uuid={self.uuid}, '
+            f'{self.properties})'
+        )
+
+
+# -----------------------------------------------------------------------------
+class CharacteristicDeclaration(Attribute):
+    '''
+    See Vol 3, Part G - 3.3.1 CHARACTERISTIC DECLARATION
+    '''
+
+    characteristic: Characteristic
+
+    def __init__(self, characteristic, value_handle):
+        declaration_bytes = (
+            struct.pack('<BH', characteristic.properties, value_handle)
+            + characteristic.uuid.to_pdu_bytes()
+        )
+        super().__init__(
+            GATT_CHARACTERISTIC_ATTRIBUTE_TYPE, Attribute.READABLE, declaration_bytes
+        )
+        self.value_handle = value_handle
+        self.characteristic = characteristic
+
+    def __str__(self):
+        return (
+            f'CharacteristicDeclaration(handle=0x{self.handle:04X}, '
+            f'value_handle=0x{self.value_handle:04X}, '
+            f'uuid={self.characteristic.uuid}, '
+            f'{self.characteristic.properties})'
+        )
 
 
 # -----------------------------------------------------------------------------
@@ -277,6 +412,7 @@ class CharacteristicValue:
     Characteristic value where reading and/or writing is delegated to functions
     passed as arguments to the constructor.
     '''
+
     def __init__(self, read=None, write=None):
         self._read = read
         self._write = write
@@ -303,18 +439,18 @@ class CharacteristicAdapter:
     If the characteristic has a `subscribe` method, it is wrapped with one where
     the values are decoded before being passed to the subscriber.
     '''
+
     def __init__(self, characteristic):
         self.wrapped_characteristic = characteristic
         self.subscribers = {}  # Map from subscriber to proxy subscriber
 
-        if (
-            asyncio.iscoroutinefunction(characteristic.read_value) and
-            asyncio.iscoroutinefunction(characteristic.write_value)
-        ):
-            self.read_value  = self.read_decoded_value
+        if asyncio.iscoroutinefunction(
+            characteristic.read_value
+        ) and asyncio.iscoroutinefunction(characteristic.write_value):
+            self.read_value = self.read_decoded_value
             self.write_value = self.write_decoded_value
         else:
-            self.read_value  = self.read_encoded_value
+            self.read_value = self.read_encoded_value
             self.write_value = self.write_encoded_value
 
         if hasattr(self.wrapped_characteristic, 'subscribe'):
@@ -327,14 +463,14 @@ class CharacteristicAdapter:
         return getattr(self.wrapped_characteristic, name)
 
     def __setattr__(self, name, value):
-        if name in {
+        if name in (
             'wrapped_characteristic',
             'subscribers',
             'read_value',
             'write_value',
             'subscribe',
-            'unsubscribe'
-        }:
+            'unsubscribe',
+        ):
             super().__setattr__(name, value)
         else:
             setattr(self.wrapped_characteristic, name, value)
@@ -343,15 +479,16 @@ class CharacteristicAdapter:
         return self.encode_value(self.wrapped_characteristic.read_value(connection))
 
     def write_encoded_value(self, connection, value):
-        return self.wrapped_characteristic.write_value(connection, self.decode_value(value))
+        return self.wrapped_characteristic.write_value(
+            connection, self.decode_value(value)
+        )
 
     async def read_decoded_value(self):
         return self.decode_value(await self.wrapped_characteristic.read_value())
 
     async def write_decoded_value(self, value, with_response=False):
         return await self.wrapped_characteristic.write_value(
-            self.encode_value(value),
-            with_response
+            self.encode_value(value), with_response
         )
 
     def encode_value(self, value):
@@ -371,6 +508,7 @@ class CharacteristicAdapter:
 
                 def on_change(value):
                     original_subscriber(self.decode_value(value))
+
                 self.subscribers[subscriber] = on_change
                 subscriber = on_change
 
@@ -392,6 +530,7 @@ class DelegatedCharacteristicAdapter(CharacteristicAdapter):
     '''
     Adapter that converts bytes values using an encode and a decode function.
     '''
+
     def __init__(self, characteristic, encode=None, decode=None):
         super().__init__(characteristic)
         self.encode = encode
@@ -414,9 +553,10 @@ class PackedCharacteristicAdapter(CharacteristicAdapter):
     they return/accept a tuple with the same number of elements as is required for
     the format.
     '''
-    def __init__(self, characteristic, format):
+
+    def __init__(self, characteristic, pack_format):
         super().__init__(characteristic)
-        self.struct = struct.Struct(format)
+        self.struct = struct.Struct(pack_format)
 
     def pack(self, *values):
         return self.struct.pack(*values)
@@ -425,7 +565,7 @@ class PackedCharacteristicAdapter(CharacteristicAdapter):
         return self.struct.unpack(buffer)
 
     def encode_value(self, value):
-        return self.pack(*value if type(value) is tuple else (value,))
+        return self.pack(*value if isinstance(value, tuple) else (value,))
 
     def decode_value(self, value):
         unpacked = self.unpack(value)
@@ -438,13 +578,15 @@ class MappedCharacteristicAdapter(PackedCharacteristicAdapter):
     Adapter that packs/unpacks characteristic values according to a standard
     Python `struct` format.
     The adapted `read_value` and `write_value` methods return/accept aa dictionary which
-    is packed/unpacked according to format, with the arguments extracted from the dictionary
-    by key, in the same order as they occur in the `keys` parameter.
+    is packed/unpacked according to format, with the arguments extracted from the
+    dictionary by key, in the same order as they occur in the `keys` parameter.
     '''
-    def __init__(self, characteristic, format, keys):
-        super().__init__(characteristic, format)
+
+    def __init__(self, characteristic, pack_format, keys):
+        super().__init__(characteristic, pack_format)
         self.keys = keys
 
+    # pylint: disable=arguments-differ
     def pack(self, values):
         return super().pack(*(values[key] for key in self.keys))
 
@@ -457,6 +599,7 @@ class UTF8CharacteristicAdapter(CharacteristicAdapter):
     '''
     Adapter that converts strings to/from bytes using UTF-8 encoding
     '''
+
     def encode_value(self, value):
         return value.encode('utf-8')
 
@@ -470,17 +613,20 @@ class Descriptor(Attribute):
     See Vol 3, Part G - 3.3.3 Characteristic Descriptor Declarations
     '''
 
-    def __init__(self, descriptor_type, permissions, value = b''):
-        super().__init__(descriptor_type, permissions, value)
-
     def __str__(self):
-        return f'Descriptor(handle=0x{self.handle:04X}, type={self.type}, value={self.read_value(None).hex()})'
+        return (
+            f'Descriptor(handle=0x{self.handle:04X}, '
+            f'type={self.type}, '
+            f'value={self.read_value(None).hex()})'
+        )
 
 
 class ClientCharacteristicConfigurationBits(enum.IntFlag):
     '''
-    See Vol 3, Part G - 3.3.3.3 - Table 3.11 Client Characteristic Configuration bit field definition
+    See Vol 3, Part G - 3.3.3.3 - Table 3.11 Client Characteristic Configuration bit
+    field definition
     '''
+
     DEFAULT = 0x0000
     NOTIFICATION = 0x0001
     INDICATION = 0x0002

bumble/gatt_client.py

@@ -23,22 +23,49 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
 import logging
 import struct
-from colors import color
+from datetime import datetime
+from typing import List, Optional, Dict, Tuple, Callable, Union, Any
 
-from .core import ProtocolError, TimeoutError
-from .hci import *
-from .att import *
+from pyee import EventEmitter
+
+from .colors import color
+from .hci import HCI_Constant
+from .att import (
+    ATT_ATTRIBUTE_NOT_FOUND_ERROR,
+    ATT_ATTRIBUTE_NOT_LONG_ERROR,
+    ATT_CID,
+    ATT_DEFAULT_MTU,
+    ATT_ERROR_RESPONSE,
+    ATT_INVALID_OFFSET_ERROR,
+    ATT_PDU,
+    ATT_RESPONSES,
+    ATT_Exchange_MTU_Request,
+    ATT_Find_By_Type_Value_Request,
+    ATT_Find_Information_Request,
+    ATT_Handle_Value_Confirmation,
+    ATT_Read_Blob_Request,
+    ATT_Read_By_Group_Type_Request,
+    ATT_Read_By_Type_Request,
+    ATT_Read_Request,
+    ATT_Write_Command,
+    ATT_Write_Request,
+    ATT_Error,
+)
+from . import core
+from .core import UUID, InvalidStateError, ProtocolError
 from .gatt import (
-    GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
-    GATT_REQUEST_TIMEOUT,
-    GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
-    GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
     GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
+    GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
+    GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
+    GATT_REQUEST_TIMEOUT,
+    GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
+    GATT_INCLUDE_ATTRIBUTE_TYPE,
     Characteristic,
-    ClientCharacteristicConfigurationBits
+    ClientCharacteristicConfigurationBits,
 )
 
 # -----------------------------------------------------------------------------
@@ -51,18 +78,24 @@ logger = logging.getLogger(__name__)
 # Proxies
 # -----------------------------------------------------------------------------
 class AttributeProxy(EventEmitter):
+    client: Client
+
     def __init__(self, client, handle, end_group_handle, attribute_type):
         EventEmitter.__init__(self)
-        self.client           = client
-        self.handle           = handle
+        self.client = client
+        self.handle = handle
         self.end_group_handle = end_group_handle
-        self.type             = attribute_type
+        self.type = attribute_type
 
     async def read_value(self, no_long_read=False):
-        return self.decode_value(await self.client.read_value(self.handle, no_long_read))
+        return self.decode_value(
+            await self.client.read_value(self.handle, no_long_read)
+        )
 
     async def write_value(self, value, with_response=False):
-        return await self.client.write_value(self.handle, self.encode_value(value), with_response)
+        return await self.client.write_value(
+            self.handle, self.encode_value(value), with_response
+        )
 
     def encode_value(self, value):
         return value
@@ -71,24 +104,33 @@ class AttributeProxy(EventEmitter):
         return value_bytes
 
     def __str__(self):
-        return f'Attribute(handle=0x{self.handle:04X}, type={self.uuid})'
+        return f'Attribute(handle=0x{self.handle:04X}, type={self.type})'
 
 
 class ServiceProxy(AttributeProxy):
+    uuid: UUID
+    characteristics: List[CharacteristicProxy]
+    included_services: List[ServiceProxy]
+
     @staticmethod
-    def from_client(cls, client, service_uuid):
-        # The service and its characteristics are considered to have already been discovered
+    def from_client(service_class, client, service_uuid):
+        # The service and its characteristics are considered to have already been
+        # discovered
         services = client.get_services_by_uuid(service_uuid)
         service = services[0] if services else None
-        return cls(service) if service else None
+        return service_class(service) if service else None
 
     def __init__(self, client, handle, end_group_handle, uuid, primary=True):
-        attribute_type = GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE if primary else GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE
+        attribute_type = (
+            GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE
+            if primary
+            else GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE
+        )
         super().__init__(client, handle, end_group_handle, attribute_type)
-        self.uuid            = uuid
+        self.uuid = uuid
         self.characteristics = []
 
-    async def discover_characteristics(self, uuids=[]):
+    async def discover_characteristics(self, uuids=()):
         return await self.client.discover_characteristics(uuids, self)
 
     def get_characteristics_by_uuid(self, uuid):
@@ -99,23 +141,38 @@ class ServiceProxy(AttributeProxy):
 
 
 class CharacteristicProxy(AttributeProxy):
-    def __init__(self, client, handle, end_group_handle, uuid, properties):
+    properties: Characteristic.Properties
+    descriptors: List[DescriptorProxy]
+    subscribers: Dict[Any, Callable]
+
+    def __init__(
+        self,
+        client,
+        handle,
+        end_group_handle,
+        uuid,
+        properties: int,
+    ):
         super().__init__(client, handle, end_group_handle, uuid)
-        self.uuid                   = uuid
-        self.properties             = properties
-        self.descriptors            = []
+        self.uuid = uuid
+        self.properties = Characteristic.Properties(properties)
+        self.descriptors = []
         self.descriptors_discovered = False
-        self.subscribers            = {}  # Map from subscriber to proxy subscriber
+        self.subscribers = {}  # Map from subscriber to proxy subscriber
 
     def get_descriptor(self, descriptor_type):
         for descriptor in self.descriptors:
             if descriptor.type == descriptor_type:
                 return descriptor
 
+        return None
+
     async def discover_descriptors(self):
         return await self.client.discover_descriptors(self)
 
-    async def subscribe(self, subscriber=None):
+    async def subscribe(
+        self, subscriber: Optional[Callable] = None, prefer_notify=True
+    ):
         if subscriber is not None:
             if subscriber in self.subscribers:
                 # We already have a proxy subscriber
@@ -126,10 +183,11 @@ class CharacteristicProxy(AttributeProxy):
 
                 def on_change(value):
                     original_subscriber(self.decode_value(value))
+
                 self.subscribers[subscriber] = on_change
                 subscriber = on_change
 
-        return await self.client.subscribe(self, subscriber)
+        return await self.client.subscribe(self, subscriber, prefer_notify)
 
     async def unsubscribe(self, subscriber=None):
         if subscriber in self.subscribers:
@@ -138,7 +196,11 @@ class CharacteristicProxy(AttributeProxy):
         return await self.client.unsubscribe(self, subscriber)
 
     def __str__(self):
-        return f'Characteristic(handle=0x{self.handle:04X}, uuid={self.uuid}, properties={Characteristic.properties_as_string(self.properties)})'
+        return (
+            f'Characteristic(handle=0x{self.handle:04X}, '
+            f'uuid={self.uuid}, '
+            f'{self.properties!s})'
+        )
 
 
 class DescriptorProxy(AttributeProxy):
@@ -153,6 +215,7 @@ class ProfileServiceProxy:
     '''
     Base class for profile-specific service proxies
     '''
+
     @classmethod
     def from_client(cls, client):
         return ServiceProxy.from_client(cls, client, cls.SERVICE_CLASS.UUID)
@@ -162,25 +225,35 @@ class ProfileServiceProxy:
 # GATT Client
 # -----------------------------------------------------------------------------
 class Client:
+    services: List[ServiceProxy]
+    cached_values: Dict[int, Tuple[datetime, bytes]]
+
     def __init__(self, connection):
-        self.connection               = connection
-        self.mtu_exchange_done        = False
-        self.request_semaphore        = asyncio.Semaphore(1)
-        self.pending_request          = None
-        self.pending_response         = None
-        self.notification_subscribers = {}  # Notification subscribers, by attribute handle
-        self.indication_subscribers   = {}  # Indication subscribers, by attribute handle
-        self.services                 = []
+        self.connection = connection
+        self.mtu_exchange_done = False
+        self.request_semaphore = asyncio.Semaphore(1)
+        self.pending_request = None
+        self.pending_response = None
+        self.notification_subscribers = (
+            {}
+        )  # Notification subscribers, by attribute handle
+        self.indication_subscribers = {}  # Indication subscribers, by attribute handle
+        self.services = []
+        self.cached_values = {}
 
     def send_gatt_pdu(self, pdu):
         self.connection.send_l2cap_pdu(ATT_CID, pdu)
 
     async def send_command(self, command):
-        logger.debug(f'GATT Command from client: [0x{self.connection.handle:04X}] {command}')
+        logger.debug(
+            f'GATT Command from client: [0x{self.connection.handle:04X}] {command}'
+        )
         self.send_gatt_pdu(command.to_bytes())
 
     async def send_request(self, request):
-        logger.debug(f'GATT Request from client: [0x{self.connection.handle:04X}] {request}')
+        logger.debug(
+            f'GATT Request from client: [0x{self.connection.handle:04X}] {request}'
+        )
 
         # Wait until we can send (only one pending command at a time for the connection)
         response = None
@@ -190,22 +263,27 @@ class Client:
 
             # Create a future value to hold the eventual response
             self.pending_response = asyncio.get_running_loop().create_future()
-            self.pending_request  = request
+            self.pending_request = request
 
             try:
                 self.send_gatt_pdu(request.to_bytes())
-                response = await asyncio.wait_for(self.pending_response, GATT_REQUEST_TIMEOUT)
-            except asyncio.TimeoutError:
+                response = await asyncio.wait_for(
+                    self.pending_response, GATT_REQUEST_TIMEOUT
+                )
+            except asyncio.TimeoutError as error:
                 logger.warning(color('!!! GATT Request timeout', 'red'))
-                raise TimeoutError(f'GATT timeout for {request.name}')
+                raise core.TimeoutError(f'GATT timeout for {request.name}') from error
             finally:
-                self.pending_request  = None
+                self.pending_request = None
                 self.pending_response = None
 
         return response
 
     def send_confirmation(self, confirmation):
-        logger.debug(f'GATT Confirmation from client: [0x{self.connection.handle:04X}] {confirmation}')
+        logger.debug(
+            f'GATT Confirmation from client: [0x{self.connection.handle:04X}] '
+            f'{confirmation}'
+        )
         self.send_gatt_pdu(confirmation.to_bytes())
 
     async def request_mtu(self, mtu):
@@ -221,13 +299,13 @@ class Client:
 
         # Send the request
         self.mtu_exchange_done = True
-        response = await self.send_request(ATT_Exchange_MTU_Request(client_rx_mtu = mtu))
+        response = await self.send_request(ATT_Exchange_MTU_Request(client_rx_mtu=mtu))
         if response.op_code == ATT_ERROR_RESPONSE:
             raise ProtocolError(
                 response.error_code,
                 'att',
                 ATT_PDU.error_name(response.error_code),
-                response
+                response,
             )
 
         # Compute the final MTU
@@ -238,12 +316,45 @@ class Client:
     def get_services_by_uuid(self, uuid):
         return [service for service in self.services if service.uuid == uuid]
 
-    def get_characteristics_by_uuid(self, uuid, service = None):
+    def get_characteristics_by_uuid(self, uuid, service=None):
         services = [service] if service else self.services
-        return [c for c in [c for s in services for c in s.characteristics] if c.uuid == uuid]
+        return [
+            c
+            for c in [c for s in services for c in s.characteristics]
+            if c.uuid == uuid
+        ]
+
+    def get_attribute_grouping(
+        self, attribute_handle: int
+    ) -> Optional[
+        Union[
+            ServiceProxy,
+            Tuple[ServiceProxy, CharacteristicProxy],
+            Tuple[ServiceProxy, CharacteristicProxy, DescriptorProxy],
+        ]
+    ]:
+        """
+        Get the attribute(s) associated with an attribute handle
+        """
+        for service in self.services:
+            if service.handle == attribute_handle:
+                return service
+            if service.handle <= attribute_handle <= service.end_group_handle:
+                for characteristic in service.characteristics:
+                    if characteristic.handle == attribute_handle:
+                        return (service, characteristic)
+                    if (
+                        characteristic.handle
+                        <= attribute_handle
+                        <= characteristic.end_group_handle
+                    ):
+                        for descriptor in characteristic.descriptors:
+                            if descriptor.handle == attribute_handle:
+                                return (service, characteristic, descriptor)
+        return None
 
     def on_service_discovered(self, service):
-        ''' Add a service to the service list if it wasn't already there '''
+        '''Add a service to the service list if it wasn't already there'''
         already_known = False
         for existing_service in self.services:
             if existing_service.handle == service.handle:
@@ -252,7 +363,7 @@ class Client:
         if not already_known:
             self.services.append(service)
 
-    async def discover_services(self, uuids = None):
+    async def discover_services(self, uuids=None) -> List[ServiceProxy]:
         '''
         See Vol 3, Part G - 4.4.1 Discover All Primary Services
         '''
@@ -261,9 +372,9 @@ class Client:
         while starting_handle < 0xFFFF:
             response = await self.send_request(
                 ATT_Read_By_Group_Type_Request(
-                    starting_handle      = starting_handle,
-                    ending_handle        = 0xFFFF,
-                    attribute_group_type = GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE
+                    starting_handle=starting_handle,
+                    ending_handle=0xFFFF,
+                    attribute_group_type=GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
                 )
             )
             if response is None:
@@ -274,16 +385,30 @@ class Client:
             if response.op_code == ATT_ERROR_RESPONSE:
                 if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
                     # Unexpected end
-                    logger.warning(f'!!! unexpected error while discovering services: {HCI_Constant.error_name(response.error_code)}')
-                    # TODO raise appropriate exception
-                    return
+                    logger.warning(
+                        '!!! unexpected error while discovering services: '
+                        f'{HCI_Constant.error_name(response.error_code)}'
+                    )
+                    raise ATT_Error(
+                        error_code=response.error_code,
+                        message='Unexpected error while discovering services',
+                    )
                 break
 
-            for attribute_handle, end_group_handle, attribute_value in response.attributes:
-                if attribute_handle < starting_handle or end_group_handle < attribute_handle:
+            for (
+                attribute_handle,
+                end_group_handle,
+                attribute_value,
+            ) in response.attributes:
+                if (
+                    attribute_handle < starting_handle
+                    or end_group_handle < attribute_handle
+                ):
                     # Something's not right
-                    logger.warning(f'bogus handle values: {attribute_handle} {end_group_handle}')
-                    return
+                    logger.warning(
+                        f'bogus handle values: {attribute_handle} {end_group_handle}'
+                    )
+                    return []
 
                 # Create a service proxy for this service
                 service = ServiceProxy(
@@ -291,7 +416,7 @@ class Client:
                     attribute_handle,
                     end_group_handle,
                     UUID.from_bytes(attribute_value),
-                    True
+                    True,
                 )
 
                 # Filter out returned services based on the given uuids list
@@ -316,7 +441,7 @@ class Client:
         '''
 
         # Force uuid to be a UUID object
-        if type(uuid) is str:
+        if isinstance(uuid, str):
             uuid = UUID(uuid)
 
         starting_handle = 0x0001
@@ -324,10 +449,10 @@ class Client:
         while starting_handle < 0xFFFF:
             response = await self.send_request(
                 ATT_Find_By_Type_Value_Request(
-                    starting_handle = starting_handle,
-                    ending_handle   = 0xFFFF,
-                    attribute_type  = GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
-                    attribute_value = uuid.to_pdu_bytes()
+                    starting_handle=starting_handle,
+                    ending_handle=0xFFFF,
+                    attribute_type=GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
+                    attribute_value=uuid.to_pdu_bytes(),
                 )
             )
             if response is None:
@@ -338,19 +463,29 @@ class Client:
             if response.op_code == ATT_ERROR_RESPONSE:
                 if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
                     # Unexpected end
-                    logger.warning(f'!!! unexpected error while discovering services: {HCI_Constant.error_name(response.error_code)}')
+                    logger.warning(
+                        '!!! unexpected error while discovering services: '
+                        f'{HCI_Constant.error_name(response.error_code)}'
+                    )
                     # TODO raise appropriate exception
                     return
                 break
 
             for attribute_handle, end_group_handle in response.handles_information:
-                if attribute_handle < starting_handle or end_group_handle < attribute_handle:
+                if (
+                    attribute_handle < starting_handle
+                    or end_group_handle < attribute_handle
+                ):
                     # Something's not right
-                    logger.warning(f'bogus handle values: {attribute_handle} {end_group_handle}')
+                    logger.warning(
+                        f'bogus handle values: {attribute_handle} {end_group_handle}'
+                    )
                     return
 
                 # Create a service proxy for this service
-                service = ServiceProxy(self, attribute_handle, end_group_handle, uuid, True)
+                service = ServiceProxy(
+                    self, attribute_handle, end_group_handle, uuid, True
+                )
 
                 # Add the service to the peer's service list
                 services.append(service)
@@ -369,37 +504,97 @@ class Client:
 
         return services
 
-    async def discover_included_services(self, service):
+    async def discover_included_services(
+        self, service: ServiceProxy
+    ) -> List[ServiceProxy]:
         '''
         See Vol 3, Part G - 4.5.1 Find Included Services
         '''
-        # TODO
-        return []
 
-    async def discover_characteristics(self, uuids, service):
+        starting_handle = service.handle
+        ending_handle = service.end_group_handle
+
+        included_services: List[ServiceProxy] = []
+        while starting_handle <= ending_handle:
+            response = await self.send_request(
+                ATT_Read_By_Type_Request(
+                    starting_handle=starting_handle,
+                    ending_handle=ending_handle,
+                    attribute_type=GATT_INCLUDE_ATTRIBUTE_TYPE,
+                )
+            )
+            if response is None:
+                # TODO raise appropriate exception
+                return []
+
+            # Check if we reached the end of the iteration
+            if response.op_code == ATT_ERROR_RESPONSE:
+                if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
+                    # Unexpected end
+                    logger.warning(
+                        '!!! unexpected error while discovering included services: '
+                        f'{HCI_Constant.error_name(response.error_code)}'
+                    )
+                    raise ATT_Error(
+                        error_code=response.error_code,
+                        message='Unexpected error while discovering included services',
+                    )
+                break
+
+            # Stop if for some reason the list was empty
+            if not response.attributes:
+                break
+
+            # Process all included services returned in this iteration
+            for attribute_handle, attribute_value in response.attributes:
+                if attribute_handle < starting_handle:
+                    # Something's not right
+                    logger.warning(f'bogus handle value: {attribute_handle}')
+                    return []
+
+                group_starting_handle, group_ending_handle = struct.unpack_from(
+                    '<HH', attribute_value
+                )
+                service_uuid = UUID.from_bytes(attribute_value[4:])
+                included_service = ServiceProxy(
+                    self, group_starting_handle, group_ending_handle, service_uuid, True
+                )
+
+                included_services.append(included_service)
+
+            # Move on to the next included services
+            starting_handle = response.attributes[-1][0] + 1
+
+        service.included_services = included_services
+        return included_services
+
+    async def discover_characteristics(
+        self, uuids, service: Optional[ServiceProxy]
+    ) -> List[CharacteristicProxy]:
         '''
-        See Vol 3, Part G - 4.6.1 Discover All Characteristics of a Service and 4.6.2 Discover Characteristics by UUID
+        See Vol 3, Part G - 4.6.1 Discover All Characteristics of a Service and 4.6.2
+        Discover Characteristics by UUID
         '''
 
         # Cast the UUIDs type from string to object if needed
-        uuids = [UUID(uuid) if type(uuid) is str else uuid for uuid in uuids]
+        uuids = [UUID(uuid) if isinstance(uuid, str) else uuid for uuid in uuids]
 
         # Decide which services to discover for
         services = [service] if service else self.services
 
         # Perform characteristic discovery for each service
-        discovered_characteristics = []
+        discovered_characteristics: List[CharacteristicProxy] = []
         for service in services:
             starting_handle = service.handle
-            ending_handle   = service.end_group_handle
+            ending_handle = service.end_group_handle
 
-            characteristics = []
+            characteristics: List[CharacteristicProxy] = []
             while starting_handle <= ending_handle:
                 response = await self.send_request(
                     ATT_Read_By_Type_Request(
-                        starting_handle = starting_handle,
-                        ending_handle   = ending_handle,
-                        attribute_type  = GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+                        starting_handle=starting_handle,
+                        ending_handle=ending_handle,
+                        attribute_type=GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
                     )
                 )
                 if response is None:
@@ -410,9 +605,14 @@ class Client:
                 if response.op_code == ATT_ERROR_RESPONSE:
                     if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
                         # Unexpected end
-                        logger.warning(f'!!! unexpected error while discovering characteristics: {HCI_Constant.error_name(response.error_code)}')
-                        # TODO raise appropriate exception
-                        return
+                        logger.warning(
+                            '!!! unexpected error while discovering characteristics: '
+                            f'{HCI_Constant.error_name(response.error_code)}'
+                        )
+                        raise ATT_Error(
+                            error_code=response.error_code,
+                            message='Unexpected error while discovering characteristics',
+                        )
                     break
 
                 # Stop if for some reason the list was empty
@@ -428,7 +628,9 @@ class Client:
 
                     properties, handle = struct.unpack_from('<BH', attribute_value)
                     characteristic_uuid = UUID.from_bytes(attribute_value[3:])
-                    characteristic = CharacteristicProxy(self, handle, 0, characteristic_uuid, properties)
+                    characteristic = CharacteristicProxy(
+                        self, handle, 0, characteristic_uuid, properties
+                    )
 
                     # Set the previous characteristic's end handle
                     if characteristics:
@@ -444,31 +646,37 @@ class Client:
                 characteristics[-1].end_group_handle = service.end_group_handle
 
             # Set the service's characteristics
-            characteristics = [c for c in characteristics if not uuids or c.uuid in uuids]
+            characteristics = [
+                c for c in characteristics if not uuids or c.uuid in uuids
+            ]
             service.characteristics = characteristics
             discovered_characteristics.extend(characteristics)
 
         return discovered_characteristics
 
-    async def discover_descriptors(self, characteristic = None, start_handle = None, end_handle = None):
+    async def discover_descriptors(
+        self,
+        characteristic: Optional[CharacteristicProxy] = None,
+        start_handle=None,
+        end_handle=None,
+    ) -> List[DescriptorProxy]:
         '''
         See Vol 3, Part G - 4.7.1 Discover All Characteristic Descriptors
         '''
         if characteristic:
             starting_handle = characteristic.handle + 1
-            ending_handle   = characteristic.end_group_handle
+            ending_handle = characteristic.end_group_handle
         elif start_handle and end_handle:
             starting_handle = start_handle
-            ending_handle   = end_handle
+            ending_handle = end_handle
         else:
             return []
 
-        descriptors = []
+        descriptors: List[DescriptorProxy] = []
         while starting_handle <= ending_handle:
             response = await self.send_request(
                 ATT_Find_Information_Request(
-                    starting_handle = starting_handle,
-                    ending_handle   = ending_handle
+                    starting_handle=starting_handle, ending_handle=ending_handle
                 )
             )
             if response is None:
@@ -479,7 +687,10 @@ class Client:
             if response.op_code == ATT_ERROR_RESPONSE:
                 if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
                     # Unexpected end
-                    logger.warning(f'!!! unexpected error while discovering descriptors: {HCI_Constant.error_name(response.error_code)}')
+                    logger.warning(
+                        '!!! unexpected error while discovering descriptors: '
+                        f'{HCI_Constant.error_name(response.error_code)}'
+                    )
                     # TODO raise appropriate exception
                     return []
                 break
@@ -495,7 +706,9 @@ class Client:
                     logger.warning(f'bogus handle value: {attribute_handle}')
                     return []
 
-                descriptor = DescriptorProxy(self, attribute_handle, UUID.from_bytes(attribute_uuid))
+                descriptor = DescriptorProxy(
+                    self, attribute_handle, UUID.from_bytes(attribute_uuid)
+                )
                 descriptors.append(descriptor)
                 # TODO: read descriptor value
 
@@ -513,13 +726,12 @@ class Client:
         Discover all attributes, regardless of type
         '''
         starting_handle = 0x0001
-        ending_handle   = 0xFFFF
+        ending_handle = 0xFFFF
         attributes = []
         while True:
             response = await self.send_request(
                 ATT_Find_Information_Request(
-                    starting_handle = starting_handle,
-                    ending_handle   = ending_handle
+                    starting_handle=starting_handle, ending_handle=ending_handle
                 )
             )
             if response is None:
@@ -529,7 +741,10 @@ class Client:
             if response.op_code == ATT_ERROR_RESPONSE:
                 if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
                     # Unexpected end
-                    logger.warning(f'!!! unexpected error while discovering attributes: {HCI_Constant.error_name(response.error_code)}')
+                    logger.warning(
+                        '!!! unexpected error while discovering attributes: '
+                        f'{HCI_Constant.error_name(response.error_code)}'
+                    )
                     return []
                 break
 
@@ -539,7 +754,9 @@ class Client:
                     logger.warning(f'bogus handle value: {attribute_handle}')
                     return []
 
-                attribute = AttributeProxy(self, attribute_handle, 0, UUID.from_bytes(attribute_uuid))
+                attribute = AttributeProxy(
+                    self, attribute_handle, 0, UUID.from_bytes(attribute_uuid)
+                )
                 attributes.append(attribute)
 
             # Move on to the next attributes
@@ -547,58 +764,77 @@ class Client:
 
         return attributes
 
-    async def subscribe(self, characteristic, subscriber=None):
-        # If we haven't already discovered the descriptors for this characteristic, do it now
+    async def subscribe(self, characteristic, subscriber=None, prefer_notify=True):
+        # If we haven't already discovered the descriptors for this characteristic,
+        # do it now
         if not characteristic.descriptors_discovered:
             await self.discover_descriptors(characteristic)
 
         # Look for the CCCD descriptor
-        cccd = characteristic.get_descriptor(GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR)
+        cccd = characteristic.get_descriptor(
+            GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR
+        )
         if not cccd:
             logger.warning('subscribing to characteristic with no CCCD descriptor')
             return
 
-        # Set the subscription bits and select the subscriber set
-        bits = ClientCharacteristicConfigurationBits.DEFAULT
-        subscriber_sets = []
-        if characteristic.properties & Characteristic.NOTIFY:
-            bits |= ClientCharacteristicConfigurationBits.NOTIFICATION
-            subscriber_sets.append(self.notification_subscribers.setdefault(characteristic.handle, set()))
-        if characteristic.properties & Characteristic.INDICATE:
-            bits |= ClientCharacteristicConfigurationBits.INDICATION
-            subscriber_sets.append(self.indication_subscribers.setdefault(characteristic.handle, set()))
+        if (
+            characteristic.properties & Characteristic.Properties.NOTIFY
+            and characteristic.properties & Characteristic.Properties.INDICATE
+        ):
+            if prefer_notify:
+                bits = ClientCharacteristicConfigurationBits.NOTIFICATION
+                subscribers = self.notification_subscribers
+            else:
+                bits = ClientCharacteristicConfigurationBits.INDICATION
+                subscribers = self.indication_subscribers
+        elif characteristic.properties & Characteristic.Properties.NOTIFY:
+            bits = ClientCharacteristicConfigurationBits.NOTIFICATION
+            subscribers = self.notification_subscribers
+        elif characteristic.properties & Characteristic.Properties.INDICATE:
+            bits = ClientCharacteristicConfigurationBits.INDICATION
+            subscribers = self.indication_subscribers
+        else:
+            raise InvalidStateError("characteristic is not notify or indicate")
 
         # Add subscribers to the sets
-        for subscriber_set in subscriber_sets:
-            if subscriber is not None:
-                subscriber_set.add(subscriber)
-            # Add the characteristic as a subscriber, which will result in the characteristic
-            # emitting an 'update' event when a notification or indication is received
-            subscriber_set.add(characteristic)
+        subscriber_set = subscribers.setdefault(characteristic.handle, set())
+        if subscriber is not None:
+            subscriber_set.add(subscriber)
+        # Add the characteristic as a subscriber, which will result in the
+        # characteristic emitting an 'update' event when a notification or indication
+        # is received
+        subscriber_set.add(characteristic)
 
         await self.write_value(cccd, struct.pack('<H', bits), with_response=True)
 
     async def unsubscribe(self, characteristic, subscriber=None):
-        # If we haven't already discovered the descriptors for this characteristic, do it now
+        # If we haven't already discovered the descriptors for this characteristic,
+        # do it now
         if not characteristic.descriptors_discovered:
             await self.discover_descriptors(characteristic)
 
         # Look for the CCCD descriptor
-        cccd = characteristic.get_descriptor(GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR)
+        cccd = characteristic.get_descriptor(
+            GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR
+        )
         if not cccd:
             logger.warning('unsubscribing from characteristic with no CCCD descriptor')
             return
 
         if subscriber is not None:
             # Remove matching subscriber from subscriber sets
-            for subscriber_set in (self.notification_subscribers, self.indication_subscribers):
+            for subscriber_set in (
+                self.notification_subscribers,
+                self.indication_subscribers,
+            ):
                 subscribers = subscriber_set.get(characteristic.handle, [])
                 if subscriber in subscribers:
                     subscribers.remove(subscriber)
 
                     # Cleanup if we removed the last one
                     if not subscribers:
-                        subscriber_set.remove(characteristic.handle)
+                        del subscriber_set[characteristic.handle]
         else:
             # Remove all subscribers for this attribute from the sets!
             self.notification_subscribers.pop(characteristic.handle, None)
@@ -616,8 +852,10 @@ class Client:
         '''
 
         # Send a request to read
-        attribute_handle = attribute if type(attribute) is int else attribute.handle
-        response = await self.send_request(ATT_Read_Request(attribute_handle = attribute_handle))
+        attribute_handle = attribute if isinstance(attribute, int) else attribute.handle
+        response = await self.send_request(
+            ATT_Read_Request(attribute_handle=attribute_handle)
+        )
         if response is None:
             raise TimeoutError('read timeout')
         if response.op_code == ATT_ERROR_RESPONSE:
@@ -625,7 +863,7 @@ class Client:
                 response.error_code,
                 'att',
                 ATT_PDU.error_name(response.error_code),
-                response
+                response,
             )
 
         # If the value is the max size for the MTU, try to read more unless the caller
@@ -636,18 +874,23 @@ class Client:
             offset = len(attribute_value)
             while True:
                 response = await self.send_request(
-                    ATT_Read_Blob_Request(attribute_handle = attribute_handle, value_offset = offset)
+                    ATT_Read_Blob_Request(
+                        attribute_handle=attribute_handle, value_offset=offset
+                    )
                 )
                 if response is None:
                     raise TimeoutError('read timeout')
                 if response.op_code == ATT_ERROR_RESPONSE:
-                    if response.error_code == ATT_ATTRIBUTE_NOT_LONG_ERROR or response.error_code == ATT_INVALID_OFFSET_ERROR:
+                    if response.error_code in (
+                        ATT_ATTRIBUTE_NOT_LONG_ERROR,
+                        ATT_INVALID_OFFSET_ERROR,
+                    ):
                         break
                     raise ProtocolError(
                         response.error_code,
                         'att',
                         ATT_PDU.error_name(response.error_code),
-                        response
+                        response,
                     )
 
                 part = response.part_attribute_value
@@ -658,6 +901,7 @@ class Client:
 
                 offset += len(part)
 
+        self.cache_value(attribute_handle, attribute_value)
         # Return the value as bytes
         return attribute_value
 
@@ -668,18 +912,18 @@ class Client:
 
         if service is None:
             starting_handle = 0x0001
-            ending_handle   = 0xFFFF
+            ending_handle = 0xFFFF
         else:
             starting_handle = service.handle
-            ending_handle   = service.end_group_handle
+            ending_handle = service.end_group_handle
 
         characteristics_values = []
         while starting_handle <= ending_handle:
             response = await self.send_request(
                 ATT_Read_By_Type_Request(
-                    starting_handle = starting_handle,
-                    ending_handle   = ending_handle,
-                    attribute_type  = uuid
+                    starting_handle=starting_handle,
+                    ending_handle=ending_handle,
+                    attribute_type=uuid,
                 )
             )
             if response is None:
@@ -690,7 +934,10 @@ class Client:
             if response.op_code == ATT_ERROR_RESPONSE:
                 if response.error_code != ATT_ATTRIBUTE_NOT_FOUND_ERROR:
                     # Unexpected end
-                    logger.warning(f'!!! unexpected error while reading characteristics: {HCI_Constant.error_name(response.error_code)}')
+                    logger.warning(
+                        '!!! unexpected error while reading characteristics: '
+                        f'{HCI_Constant.error_name(response.error_code)}'
+                    )
                     # TODO raise appropriate exception
                     return []
                 break
@@ -715,47 +962,54 @@ class Client:
 
     async def write_value(self, attribute, value, with_response=False):
         '''
-        See Vol 3, Part G - 4.9.1 Write Without Response & 4.9.3 Write Characteristic Value
+        See Vol 3, Part G - 4.9.1 Write Without Response & 4.9.3 Write Characteristic
+        Value
 
         `attribute` can be an Attribute object, or a handle value
         '''
 
         # Send a request or command to write
-        attribute_handle = attribute if type(attribute) is int else attribute.handle
+        attribute_handle = attribute if isinstance(attribute, int) else attribute.handle
         if with_response:
             response = await self.send_request(
                 ATT_Write_Request(
-                    attribute_handle = attribute_handle,
-                    attribute_value  = value
+                    attribute_handle=attribute_handle, attribute_value=value
                 )
             )
             if response.op_code == ATT_ERROR_RESPONSE:
                 raise ProtocolError(
                     response.error_code,
                     'att',
-                    ATT_PDU.error_name(response.error_code), response
+                    ATT_PDU.error_name(response.error_code),
+                    response,
                 )
         else:
             await self.send_command(
                 ATT_Write_Command(
-                    attribute_handle = attribute_handle,
-                    attribute_value  = value
+                    attribute_handle=attribute_handle, attribute_value=value
                 )
             )
 
     def on_gatt_pdu(self, att_pdu):
-        logger.debug(f'GATT Response to client: [0x{self.connection.handle:04X}] {att_pdu}')
+        logger.debug(
+            f'GATT Response to client: [0x{self.connection.handle:04X}] {att_pdu}'
+        )
         if att_pdu.op_code in ATT_RESPONSES:
             if self.pending_request is None:
                 # Not expected!
                 logger.warning('!!! unexpected response, there is no pending request')
                 return
 
-            # Sanity check: the response should match the pending request unless it is an error response
+            # Sanity check: the response should match the pending request unless it is
+            # an error response
             if att_pdu.op_code != ATT_ERROR_RESPONSE:
-                expected_response_name = self.pending_request.name.replace('_REQUEST', '_RESPONSE')
+                expected_response_name = self.pending_request.name.replace(
+                    '_REQUEST', '_RESPONSE'
+                )
                 if att_pdu.name != expected_response_name:
-                    logger.warning(f'!!! mismatched response: expected {expected_response_name}')
+                    logger.warning(
+                        f'!!! mismatched response: expected {expected_response_name}'
+                    )
                     return
 
             # Return the response to the coroutine that is waiting for it
@@ -766,13 +1020,24 @@ class Client:
             if handler is not None:
                 handler(att_pdu)
             else:
-                logger.warning(f'{color(f"--- Ignoring GATT Response from [0x{self.connection.handle:04X}]:", "red")} {att_pdu}')
+                logger.warning(
+                    color(
+                        '--- Ignoring GATT Response from '
+                        f'[0x{self.connection.handle:04X}]: ',
+                        'red',
+                    )
+                    + str(att_pdu)
+                )
 
     def on_att_handle_value_notification(self, notification):
         # Call all subscribers
-        subscribers = self.notification_subscribers.get(notification.attribute_handle, [])
+        subscribers = self.notification_subscribers.get(
+            notification.attribute_handle, []
+        )
         if not subscribers:
             logger.warning('!!! received notification with no subscriber')
+
+        self.cache_value(notification.attribute_handle, notification.attribute_value)
         for subscriber in subscribers:
             if callable(subscriber):
                 subscriber(notification.attribute_value)
@@ -784,6 +1049,8 @@ class Client:
         subscribers = self.indication_subscribers.get(indication.attribute_handle, [])
         if not subscribers:
             logger.warning('!!! received indication with no subscriber')
+
+        self.cache_value(indication.attribute_handle, indication.attribute_value)
         for subscriber in subscribers:
             if callable(subscriber):
                 subscriber(indication.attribute_value)
@@ -792,3 +1059,9 @@ class Client:
 
         # Confirm that we received the indication
         self.send_confirmation(ATT_Handle_Value_Confirmation())
+
+    def cache_value(self, attribute_handle: int, value: bytes):
+        self.cached_values[attribute_handle] = (
+            datetime.now(),
+            value,
+        )

bumble/gatt_server.py

@@ -26,13 +26,53 @@
 import asyncio
 import logging
 from collections import defaultdict
+import struct
+from typing import List, Tuple, Optional, TypeVar, Type
 from pyee import EventEmitter
-from colors import color
 
-from .core import *
-from .hci import *
-from .att import *
-from .gatt import *
+from .colors import color
+from .core import UUID
+from .att import (
+    ATT_ATTRIBUTE_NOT_FOUND_ERROR,
+    ATT_ATTRIBUTE_NOT_LONG_ERROR,
+    ATT_CID,
+    ATT_DEFAULT_MTU,
+    ATT_INVALID_ATTRIBUTE_LENGTH_ERROR,
+    ATT_INVALID_HANDLE_ERROR,
+    ATT_INVALID_OFFSET_ERROR,
+    ATT_REQUEST_NOT_SUPPORTED_ERROR,
+    ATT_REQUESTS,
+    ATT_UNLIKELY_ERROR_ERROR,
+    ATT_UNSUPPORTED_GROUP_TYPE_ERROR,
+    ATT_Error,
+    ATT_Error_Response,
+    ATT_Exchange_MTU_Response,
+    ATT_Find_By_Type_Value_Response,
+    ATT_Find_Information_Response,
+    ATT_Handle_Value_Indication,
+    ATT_Handle_Value_Notification,
+    ATT_Read_Blob_Response,
+    ATT_Read_By_Group_Type_Response,
+    ATT_Read_By_Type_Response,
+    ATT_Read_Response,
+    ATT_Write_Response,
+    Attribute,
+)
+from .gatt import (
+    GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
+    GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
+    GATT_MAX_ATTRIBUTE_VALUE_SIZE,
+    GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
+    GATT_REQUEST_TIMEOUT,
+    GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
+    Characteristic,
+    CharacteristicDeclaration,
+    CharacteristicValue,
+    IncludedServiceDeclaration,
+    Descriptor,
+    Service,
+)
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -50,22 +90,40 @@ GATT_SERVER_DEFAULT_MAX_MTU = 517
 # GATT Server
 # -----------------------------------------------------------------------------
 class Server(EventEmitter):
+    attributes: List[Attribute]
+
     def __init__(self, device):
         super().__init__()
-        self.device                = device
-        self.attributes            = []  # Attributes, ordered by increasing handle values
-        self.attributes_by_handle  = {}  # Map for fast attribute access by handle
-        self.max_mtu               = GATT_SERVER_DEFAULT_MAX_MTU  # The max MTU we're willing to negotiate
-        self.subscribers           = {}  # Map of subscriber states by connection handle and attribute handle
+        self.device = device
+        self.services = []
+        self.attributes = []  # Attributes, ordered by increasing handle values
+        self.attributes_by_handle = {}  # Map for fast attribute access by handle
+        self.max_mtu = (
+            GATT_SERVER_DEFAULT_MAX_MTU  # The max MTU we're willing to negotiate
+        )
+        self.subscribers = (
+            {}
+        )  # Map of subscriber states by connection handle and attribute handle
         self.indication_semaphores = defaultdict(lambda: asyncio.Semaphore(1))
         self.pending_confirmations = defaultdict(lambda: None)
 
+    def __str__(self):
+        return "\n".join(map(str, self.attributes))
+
     def send_gatt_pdu(self, connection_handle, pdu):
         self.device.send_l2cap_pdu(connection_handle, ATT_CID, pdu)
 
     def next_handle(self):
         return 1 + len(self.attributes)
 
+    def get_advertising_service_data(self):
+        return {
+            attribute: data
+            for attribute in self.attributes
+            if isinstance(attribute, Service)
+            and (data := attribute.get_advertising_data())
+        }
+
     def get_attribute(self, handle):
         attribute = self.attributes_by_handle.get(handle)
         if attribute:
@@ -79,32 +137,107 @@ class Server(EventEmitter):
                 return attribute
         return None
 
+    AttributeGroupType = TypeVar('AttributeGroupType', Service, Characteristic)
+
+    def get_attribute_group(
+        self, handle: int, group_type: Type[AttributeGroupType]
+    ) -> Optional[AttributeGroupType]:
+        return next(
+            (
+                attribute
+                for attribute in self.attributes
+                if isinstance(attribute, group_type)
+                and attribute.handle <= handle <= attribute.end_group_handle
+            ),
+            None,
+        )
+
+    def get_service_attribute(self, service_uuid: UUID) -> Optional[Service]:
+        return next(
+            (
+                attribute
+                for attribute in self.attributes
+                if attribute.type == GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE
+                and isinstance(attribute, Service)
+                and attribute.uuid == service_uuid
+            ),
+            None,
+        )
+
+    def get_characteristic_attributes(
+        self, service_uuid: UUID, characteristic_uuid: UUID
+    ) -> Optional[Tuple[CharacteristicDeclaration, Characteristic]]:
+        service_handle = self.get_service_attribute(service_uuid)
+        if not service_handle:
+            return None
+
+        return next(
+            (
+                (attribute, self.get_attribute(attribute.characteristic.handle))
+                for attribute in map(
+                    self.get_attribute,
+                    range(service_handle.handle, service_handle.end_group_handle + 1),
+                )
+                if attribute.type == GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
+                and attribute.characteristic.uuid == characteristic_uuid
+            ),
+            None,
+        )
+
+    def get_descriptor_attribute(
+        self, service_uuid: UUID, characteristic_uuid: UUID, descriptor_uuid: UUID
+    ) -> Optional[Descriptor]:
+        characteristics = self.get_characteristic_attributes(
+            service_uuid, characteristic_uuid
+        )
+        if not characteristics:
+            return None
+
+        (_, characteristic_value) = characteristics
+
+        return next(
+            (
+                attribute
+                for attribute in map(
+                    self.get_attribute,
+                    range(
+                        characteristic_value.handle + 1,
+                        characteristic_value.end_group_handle + 1,
+                    ),
+                )
+                if attribute.type == descriptor_uuid
+            ),
+            None,
+        )
+
     def add_attribute(self, attribute):
         # Assign a handle to this attribute
         attribute.handle = self.next_handle()
-        attribute.end_group_handle = attribute.handle  # TODO: keep track of descriptors in the group
+        attribute.end_group_handle = (
+            attribute.handle
+        )  # TODO: keep track of descriptors in the group
 
         # Add this attribute to the list
         self.attributes.append(attribute)
 
-    def add_service(self, service):
+    def add_service(self, service: Service):
         # Add the service attribute to the DB
         self.add_attribute(service)
 
-        # TODO: add included services
+        # Add all included service
+        for included_service in service.included_services:
+            # Not registered yet, register the included service first.
+            if included_service not in self.services:
+                self.add_service(included_service)
+                # TODO: Handle circular service reference
+            include_declaration = IncludedServiceDeclaration(included_service)
+            self.add_attribute(include_declaration)
 
         # Add all characteristics
         for characteristic in service.characteristics:
-            # Add a Characteristic Declaration (Vol 3, Part G - 3.3.1 Characteristic Declaration)
-            declaration_bytes = struct.pack(
-                '<BH',
-                characteristic.properties,
-                self.next_handle() + 1,  # The value will be the next attribute after this declaration
-            ) + characteristic.uuid.to_pdu_bytes()
-            characteristic_declaration = Attribute(
-                GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
-                Attribute.READABLE,
-                declaration_bytes
+            # Add a Characteristic Declaration
+            characteristic_declaration = CharacteristicDeclaration(
+                characteristic, self.next_handle() + 1
             )
             self.add_attribute(characteristic_declaration)
 
@@ -118,17 +251,29 @@ class Server(EventEmitter):
             # If the characteristic supports subscriptions, add a CCCD descriptor
             # unless there is one already
             if (
-                characteristic.properties & (Characteristic.NOTIFY | Characteristic.INDICATE) and
-                characteristic.get_descriptor(GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR) is None
+                characteristic.properties
+                & (
+                    Characteristic.Properties.NOTIFY
+                    | Characteristic.Properties.INDICATE
+                )
+                and characteristic.get_descriptor(
+                    GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR
+                )
+                is None
             ):
                 self.add_attribute(
+                    # pylint: disable=line-too-long
                     Descriptor(
                         GATT_CLIENT_CHARACTERISTIC_CONFIGURATION_DESCRIPTOR,
                         Attribute.READABLE | Attribute.WRITEABLE,
                         CharacteristicValue(
-                            read=lambda connection, characteristic=characteristic: self.read_cccd(connection, characteristic),
-                            write=lambda connection, value, characteristic=characteristic: self.write_cccd(connection, characteristic, value)
-                        )
+                            read=lambda connection, characteristic=characteristic: self.read_cccd(
+                                connection, characteristic
+                            ),
+                            write=lambda connection, value, characteristic=characteristic: self.write_cccd(
+                                connection, characteristic, value
+                            ),
+                        ),
                     )
                 )
 
@@ -138,6 +283,7 @@ class Server(EventEmitter):
 
         # Update the service group end
         service.end_group_handle = self.attributes[-1].handle
+        self.services.append(service)
 
     def add_services(self, services):
         for service in services:
@@ -155,23 +301,36 @@ class Server(EventEmitter):
         return cccd or bytes([0, 0])
 
     def write_cccd(self, connection, characteristic, value):
-        logger.debug(f'Subscription update for connection=0x{connection.handle:04X}, handle=0x{characteristic.handle:04X}: {value.hex()}')
+        logger.debug(
+            f'Subscription update for connection=0x{connection.handle:04X}, '
+            f'handle=0x{characteristic.handle:04X}: {value.hex()}'
+        )
 
         # Sanity check
         if len(value) != 2:
-            logger.warn('CCCD value not 2 bytes long')
+            logger.warning('CCCD value not 2 bytes long')
             return
 
         cccds = self.subscribers.setdefault(connection.handle, {})
         cccds[characteristic.handle] = value
         logger.debug(f'CCCDs: {cccds}')
-        notify_enabled = (value[0] & 0x01 != 0)
-        indicate_enabled = (value[0] & 0x02 != 0)
-        characteristic.emit('subscription', connection, notify_enabled, indicate_enabled)
-        self.emit('characteristic_subscription', connection, characteristic, notify_enabled, indicate_enabled)
+        notify_enabled = value[0] & 0x01 != 0
+        indicate_enabled = value[0] & 0x02 != 0
+        characteristic.emit(
+            'subscription', connection, notify_enabled, indicate_enabled
+        )
+        self.emit(
+            'characteristic_subscription',
+            connection,
+            characteristic,
+            notify_enabled,
+            indicate_enabled,
+        )
 
     def send_response(self, connection, response):
-        logger.debug(f'GATT Response from server: [0x{connection.handle:04X}] {response}')
+        logger.debug(
+            f'GATT Response from server: [0x{connection.handle:04X}] {response}'
+        )
         self.send_gatt_pdu(connection.handle, response.to_bytes())
 
     async def notify_subscriber(self, connection, attribute, value=None, force=False):
@@ -183,25 +342,32 @@ class Server(EventEmitter):
                 return
             cccd = subscribers.get(attribute.handle)
             if not cccd:
-                logger.debug(f'not notifying, no subscribers for handle {attribute.handle:04X}')
+                logger.debug(
+                    f'not notifying, no subscribers for handle {attribute.handle:04X}'
+                )
                 return
             if len(cccd) != 2 or (cccd[0] & 0x01 == 0):
                 logger.debug(f'not notifying, cccd={cccd.hex()}')
                 return
 
         # Get or encode the value
-        value = attribute.read_value(connection) if value is None else attribute.encode_value(value)
+        value = (
+            attribute.read_value(connection)
+            if value is None
+            else attribute.encode_value(value)
+        )
 
         # Truncate if needed
         if len(value) > connection.att_mtu - 3:
-            value = value[:connection.att_mtu - 3]
+            value = value[: connection.att_mtu - 3]
 
         # Notify
         notification = ATT_Handle_Value_Notification(
-            attribute_handle = attribute.handle,
-            attribute_value  = value
+            attribute_handle=attribute.handle, attribute_value=value
+        )
+        logger.debug(
+            f'GATT Notify from server: [0x{connection.handle:04X}] {notification}'
         )
-        logger.debug(f'GATT Notify from server: [0x{connection.handle:04X}] {notification}')
         self.send_gatt_pdu(connection.handle, bytes(notification))
 
     async def indicate_subscriber(self, connection, attribute, value=None, force=False):
@@ -213,46 +379,60 @@ class Server(EventEmitter):
                 return
             cccd = subscribers.get(attribute.handle)
             if not cccd:
-                logger.debug(f'not indicating, no subscribers for handle {attribute.handle:04X}')
+                logger.debug(
+                    f'not indicating, no subscribers for handle {attribute.handle:04X}'
+                )
                 return
             if len(cccd) != 2 or (cccd[0] & 0x02 == 0):
                 logger.debug(f'not indicating, cccd={cccd.hex()}')
                 return
 
         # Get or encode the value
-        value = attribute.read_value(connection) if value is None else attribute.encode_value(value)
+        value = (
+            attribute.read_value(connection)
+            if value is None
+            else attribute.encode_value(value)
+        )
 
         # Truncate if needed
         if len(value) > connection.att_mtu - 3:
-            value = value[:connection.att_mtu - 3]
+            value = value[: connection.att_mtu - 3]
 
         # Indicate
         indication = ATT_Handle_Value_Indication(
-            attribute_handle = attribute.handle,
-            attribute_value  = value
+            attribute_handle=attribute.handle, attribute_value=value
+        )
+        logger.debug(
+            f'GATT Indicate from server: [0x{connection.handle:04X}] {indication}'
         )
-        logger.debug(f'GATT Indicate from server: [0x{connection.handle:04X}] {indication}')
 
         # Wait until we can send (only one pending indication at a time per connection)
         async with self.indication_semaphores[connection.handle]:
-            assert(self.pending_confirmations[connection.handle] is None)
+            assert self.pending_confirmations[connection.handle] is None
 
             # Create a future value to hold the eventual response
-            self.pending_confirmations[connection.handle] = asyncio.get_running_loop().create_future()
+            self.pending_confirmations[
+                connection.handle
+            ] = asyncio.get_running_loop().create_future()
 
             try:
                 self.send_gatt_pdu(connection.handle, indication.to_bytes())
-                await asyncio.wait_for(self.pending_confirmations[connection.handle], GATT_REQUEST_TIMEOUT)
-            except asyncio.TimeoutError:
+                await asyncio.wait_for(
+                    self.pending_confirmations[connection.handle], GATT_REQUEST_TIMEOUT
+                )
+            except asyncio.TimeoutError as error:
                 logger.warning(color('!!! GATT Indicate timeout', 'red'))
-                raise TimeoutError(f'GATT timeout for {indication.name}')
+                raise TimeoutError(f'GATT timeout for {indication.name}') from error
             finally:
                 self.pending_confirmations[connection.handle] = None
 
-    async def notify_or_indicate_subscribers(self, indicate, attribute, value=None, force=False):
+    async def notify_or_indicate_subscribers(
+        self, indicate, attribute, value=None, force=False
+    ):
         # Get all the connections for which there's at least one subscription
         connections = [
-            connection for connection in [
+            connection
+            for connection in [
                 self.device.lookup_connection(connection_handle)
                 for (connection_handle, subscribers) in self.subscribers.items()
                 if force or subscribers.get(attribute.handle)
@@ -263,10 +443,12 @@ class Server(EventEmitter):
         # Indicate or notify for each connection
         if connections:
             coroutine = self.indicate_subscriber if indicate else self.notify_subscriber
-            await asyncio.wait([
-                asyncio.create_task(coroutine(connection, attribute, value, force))
-                for connection in connections
-            ])
+            await asyncio.wait(
+                [
+                    asyncio.create_task(coroutine(connection, attribute, value, force))
+                    for connection in connections
+                ]
+            )
 
     async def notify_subscribers(self, attribute, value=None, force=False):
         return await self.notify_or_indicate_subscribers(False, attribute, value, force)
@@ -292,17 +474,17 @@ class Server(EventEmitter):
             except ATT_Error as error:
                 logger.debug(f'normal exception returned by handler: {error}')
                 response = ATT_Error_Response(
-                    request_opcode_in_error   = att_pdu.op_code,
-                    attribute_handle_in_error = error.att_handle,
-                    error_code                = error.error_code
+                    request_opcode_in_error=att_pdu.op_code,
+                    attribute_handle_in_error=error.att_handle,
+                    error_code=error.error_code,
                 )
                 self.send_response(connection, response)
             except Exception as error:
                 logger.warning(f'{color("!!! Exception in handler:", "red")} {error}')
                 response = ATT_Error_Response(
-                    request_opcode_in_error   = att_pdu.op_code,
-                    attribute_handle_in_error = 0x0000,
-                    error_code                = ATT_UNLIKELY_ERROR_ERROR
+                    request_opcode_in_error=att_pdu.op_code,
+                    attribute_handle_in_error=0x0000,
+                    error_code=ATT_UNLIKELY_ERROR_ERROR,
                 )
                 self.send_response(connection, response)
                 raise error
@@ -313,7 +495,13 @@ class Server(EventEmitter):
                 self.on_att_request(connection, att_pdu)
             else:
                 # Just ignore
-                logger.warning(f'{color("--- Ignoring GATT Request from [0x{connection.handle:04X}]:", "red")}  {att_pdu}')
+                logger.warning(
+                    color(
+                        f'--- Ignoring GATT Request from [0x{connection.handle:04X}]: ',
+                        'red',
+                    )
+                    + str(att_pdu)
+                )
 
     #######################################################
     # ATT handlers
@@ -322,11 +510,16 @@ class Server(EventEmitter):
         '''
         Handler for requests without a more specific handler
         '''
-        logger.warning(f'{color(f"--- Unsupported ATT Request from [0x{connection.handle:04X}]:", "red")} {pdu}')
+        logger.warning(
+            color(
+                f'--- Unsupported ATT Request from [0x{connection.handle:04X}]: ', 'red'
+            )
+            + str(pdu)
+        )
         response = ATT_Error_Response(
-            request_opcode_in_error   = pdu.op_code,
-            attribute_handle_in_error = 0x0000,
-            error_code                = ATT_REQUEST_NOT_SUPPORTED_ERROR
+            request_opcode_in_error=pdu.op_code,
+            attribute_handle_in_error=0x0000,
+            error_code=ATT_REQUEST_NOT_SUPPORTED_ERROR,
         )
         self.send_response(connection, response)
 
@@ -334,7 +527,9 @@ class Server(EventEmitter):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.2.1 Exchange MTU Request
         '''
-        self.send_response(connection, ATT_Exchange_MTU_Response(server_rx_mtu = self.max_mtu))
+        self.send_response(
+            connection, ATT_Exchange_MTU_Response(server_rx_mtu=self.max_mtu)
+        )
 
         # Compute the final MTU
         if request.client_rx_mtu >= ATT_DEFAULT_MTU:
@@ -351,12 +546,18 @@ class Server(EventEmitter):
         '''
 
         # Check the request parameters
-        if request.starting_handle == 0 or request.starting_handle > request.ending_handle:
-            self.send_response(connection, ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.starting_handle,
-                error_code                = ATT_INVALID_HANDLE_ERROR
-            ))
+        if (
+            request.starting_handle == 0
+            or request.starting_handle > request.ending_handle
+        ):
+            self.send_response(
+                connection,
+                ATT_Error_Response(
+                    request_opcode_in_error=request.op_code,
+                    attribute_handle_in_error=request.starting_handle,
+                    error_code=ATT_INVALID_HANDLE_ERROR,
+                ),
+            )
             return
 
         # Build list of returned attributes
@@ -364,12 +565,11 @@ class Server(EventEmitter):
         attributes = []
         uuid_size = 0
         for attribute in (
-            attribute for attribute in self.attributes if
-            attribute.handle >= request.starting_handle and
-            attribute.handle <= request.ending_handle
+            attribute
+            for attribute in self.attributes
+            if attribute.handle >= request.starting_handle
+            and attribute.handle <= request.ending_handle
         ):
-            # TODO: check permissions
-
             this_uuid_size = len(attribute.type.to_pdu_bytes())
 
             if attributes:
@@ -393,14 +593,14 @@ class Server(EventEmitter):
                 for attribute in attributes
             ]
             response = ATT_Find_Information_Response(
-                format           = 1 if len(attributes[0].type.to_pdu_bytes()) == 2 else 2,
-                information_data = b''.join(information_data_list)
+                format=1 if len(attributes[0].type.to_pdu_bytes()) == 2 else 2,
+                information_data=b''.join(information_data_list),
             )
         else:
             response = ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.starting_handle,
-                error_code                = ATT_ATTRIBUTE_NOT_FOUND_ERROR
+                request_opcode_in_error=request.op_code,
+                attribute_handle_in_error=request.starting_handle,
+                error_code=ATT_ATTRIBUTE_NOT_FOUND_ERROR,
             )
 
         self.send_response(connection, response)
@@ -414,12 +614,13 @@ class Server(EventEmitter):
         pdu_space_available = connection.att_mtu - 2
         attributes = []
         for attribute in (
-            attribute for attribute in self.attributes if
-            attribute.handle                 >= request.starting_handle and
-            attribute.handle                 <= request.ending_handle   and
-            attribute.type                   == request.attribute_type  and
-            attribute.read_value(connection) == request.attribute_value and
-            pdu_space_available >= 4
+            attribute
+            for attribute in self.attributes
+            if attribute.handle >= request.starting_handle
+            and attribute.handle <= request.ending_handle
+            and attribute.type == request.attribute_type
+            and attribute.read_value(connection) == request.attribute_value
+            and pdu_space_available >= 4
         ):
             # TODO: check permissions
 
@@ -431,25 +632,27 @@ class Server(EventEmitter):
         if attributes:
             handles_information_list = []
             for attribute in attributes:
-                if attribute.type in {
+                if attribute.type in (
                     GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
                     GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
-                    GATT_CHARACTERISTIC_ATTRIBUTE_TYPE
-                }:
+                    GATT_CHARACTERISTIC_ATTRIBUTE_TYPE,
+                ):
                     # Part of a group
                     group_end_handle = attribute.end_group_handle
                 else:
                     # Not part of a group
                     group_end_handle = attribute.handle
-                handles_information_list.append(struct.pack('<HH', attribute.handle, group_end_handle))
+                handles_information_list.append(
+                    struct.pack('<HH', attribute.handle, group_end_handle)
+                )
             response = ATT_Find_By_Type_Value_Response(
-                handles_information_list = b''.join(handles_information_list)
+                handles_information_list=b''.join(handles_information_list)
             )
         else:
             response = ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.starting_handle,
-                error_code                = ATT_ATTRIBUTE_NOT_FOUND_ERROR
+                request_opcode_in_error=request.op_code,
+                attribute_handle_in_error=request.starting_handle,
+                error_code=ATT_ATTRIBUTE_NOT_FOUND_ERROR,
             )
 
         self.send_response(connection, response)
@@ -460,18 +663,37 @@ class Server(EventEmitter):
         '''
 
         pdu_space_available = connection.att_mtu - 2
+
+        response = ATT_Error_Response(
+            request_opcode_in_error=request.op_code,
+            attribute_handle_in_error=request.starting_handle,
+            error_code=ATT_ATTRIBUTE_NOT_FOUND_ERROR,
+        )
+
         attributes = []
         for attribute in (
-            attribute for attribute in self.attributes if
-            attribute.type   == request.attribute_type  and
-            attribute.handle >= request.starting_handle and
-            attribute.handle <= request.ending_handle   and
-            pdu_space_available
+            attribute
+            for attribute in self.attributes
+            if attribute.type == request.attribute_type
+            and attribute.handle >= request.starting_handle
+            and attribute.handle <= request.ending_handle
+            and pdu_space_available
         ):
-            # TODO: check permissions
+
+            try:
+                attribute_value = attribute.read_value(connection)
+            except ATT_Error as error:
+                # If the first attribute is unreadable, return an error
+                # Otherwise return attributes up to this point
+                if not attributes:
+                    response = ATT_Error_Response(
+                        request_opcode_in_error=request.op_code,
+                        attribute_handle_in_error=attribute.handle,
+                        error_code=error.error_code,
+                    )
+                break
 
             # Check the attribute value size
-            attribute_value = attribute.read_value(connection)
             max_attribute_size = min(connection.att_mtu - 4, 253)
             if len(attribute_value) > max_attribute_size:
                 # We need to truncate
@@ -490,17 +712,14 @@ class Server(EventEmitter):
             pdu_space_available -= entry_size
 
         if attributes:
-            attribute_data_list = [struct.pack('<H', handle) + value for handle, value in attributes]
+            attribute_data_list = [
+                struct.pack('<H', handle) + value for handle, value in attributes
+            ]
             response = ATT_Read_By_Type_Response(
-                length              = entry_size,
-                attribute_data_list = b''.join(attribute_data_list)
+                length=entry_size, attribute_data_list=b''.join(attribute_data_list)
             )
         else:
-            response = ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.starting_handle,
-                error_code                = ATT_ATTRIBUTE_NOT_FOUND_ERROR
-            )
+            logging.debug(f"not found {request}")
 
         self.send_response(connection, response)
 
@@ -510,17 +729,22 @@ class Server(EventEmitter):
         '''
 
         if attribute := self.get_attribute(request.attribute_handle):
-            # TODO: check permissions
-            value = attribute.read_value(connection)
-            value_size = min(connection.att_mtu - 1, len(value))
-            response = ATT_Read_Response(
-                attribute_value = value[:value_size]
-            )
+            try:
+                value = attribute.read_value(connection)
+            except ATT_Error as error:
+                response = ATT_Error_Response(
+                    request_opcode_in_error=request.op_code,
+                    attribute_handle_in_error=request.attribute_handle,
+                    error_code=error.error_code,
+                )
+            else:
+                value_size = min(connection.att_mtu - 1, len(value))
+                response = ATT_Read_Response(attribute_value=value[:value_size])
         else:
             response = ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.attribute_handle,
-                error_code                = ATT_INVALID_HANDLE_ERROR
+                request_opcode_in_error=request.op_code,
+                attribute_handle_in_error=request.attribute_handle,
+                error_code=ATT_INVALID_HANDLE_ERROR,
             )
         self.send_response(connection, response)
 
@@ -530,30 +754,41 @@ class Server(EventEmitter):
         '''
 
         if attribute := self.get_attribute(request.attribute_handle):
-            # TODO: check permissions
-            value = attribute.read_value(connection)
-            if request.value_offset > len(value):
+            try:
+                value = attribute.read_value(connection)
+            except ATT_Error as error:
                 response = ATT_Error_Response(
-                    request_opcode_in_error   = request.op_code,
-                    attribute_handle_in_error = request.attribute_handle,
-                    error_code                = ATT_INVALID_OFFSET_ERROR
-                )
-            elif len(value) <= connection.att_mtu - 1:
-                response = ATT_Error_Response(
-                    request_opcode_in_error   = request.op_code,
-                    attribute_handle_in_error = request.attribute_handle,
-                    error_code                = ATT_ATTRIBUTE_NOT_LONG_ERROR
+                    request_opcode_in_error=request.op_code,
+                    attribute_handle_in_error=request.attribute_handle,
+                    error_code=error.error_code,
                 )
             else:
-                part_size = min(connection.att_mtu - 1, len(value) - request.value_offset)
-                response = ATT_Read_Blob_Response(
-                    part_attribute_value = value[request.value_offset:request.value_offset + part_size]
-                )
+                if request.value_offset > len(value):
+                    response = ATT_Error_Response(
+                        request_opcode_in_error=request.op_code,
+                        attribute_handle_in_error=request.attribute_handle,
+                        error_code=ATT_INVALID_OFFSET_ERROR,
+                    )
+                elif len(value) <= connection.att_mtu - 1:
+                    response = ATT_Error_Response(
+                        request_opcode_in_error=request.op_code,
+                        attribute_handle_in_error=request.attribute_handle,
+                        error_code=ATT_ATTRIBUTE_NOT_LONG_ERROR,
+                    )
+                else:
+                    part_size = min(
+                        connection.att_mtu - 1, len(value) - request.value_offset
+                    )
+                    response = ATT_Read_Blob_Response(
+                        part_attribute_value=value[
+                            request.value_offset : request.value_offset + part_size
+                        ]
+                    )
         else:
             response = ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.attribute_handle,
-                error_code                = ATT_INVALID_HANDLE_ERROR
+                request_opcode_in_error=request.op_code,
+                attribute_handle_in_error=request.attribute_handle,
+                error_code=ATT_INVALID_HANDLE_ERROR,
             )
         self.send_response(connection, response)
 
@@ -561,15 +796,14 @@ class Server(EventEmitter):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.4.9 Read by Group Type Request
         '''
-        if request.attribute_group_type not in {
+        if request.attribute_group_type not in (
             GATT_PRIMARY_SERVICE_ATTRIBUTE_TYPE,
             GATT_SECONDARY_SERVICE_ATTRIBUTE_TYPE,
-            GATT_INCLUDE_ATTRIBUTE_TYPE
-        }:
+        ):
             response = ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.starting_handle,
-                error_code                = ATT_UNSUPPORTED_GROUP_TYPE_ERROR
+                request_opcode_in_error=request.op_code,
+                attribute_handle_in_error=request.starting_handle,
+                error_code=ATT_UNSUPPORTED_GROUP_TYPE_ERROR,
             )
             self.send_response(connection, response)
             return
@@ -577,14 +811,17 @@ class Server(EventEmitter):
         pdu_space_available = connection.att_mtu - 2
         attributes = []
         for attribute in (
-            attribute for attribute in self.attributes if
-            attribute.type   == request.attribute_group_type and
-            attribute.handle >= request.starting_handle      and
-            attribute.handle <= request.ending_handle        and
-            pdu_space_available
+            attribute
+            for attribute in self.attributes
+            if attribute.type == request.attribute_group_type
+            and attribute.handle >= request.starting_handle
+            and attribute.handle <= request.ending_handle
+            and pdu_space_available
         ):
-            # Check the attribute value size
+            # No need to catch permission errors here, since these attributes
+            # must all be world-readable
             attribute_value = attribute.read_value(connection)
+            # Check the attribute value size
             max_attribute_size = min(connection.att_mtu - 6, 251)
             if len(attribute_value) > max_attribute_size:
                 # We need to truncate
@@ -599,7 +836,9 @@ class Server(EventEmitter):
                 break
 
             # Add the attribute to the list
-            attributes.append((attribute.handle, attribute.end_group_handle, attribute_value))
+            attributes.append(
+                (attribute.handle, attribute.end_group_handle, attribute_value)
+            )
             pdu_space_available -= entry_size
 
         if attributes:
@@ -608,14 +847,14 @@ class Server(EventEmitter):
                 for handle, end_group_handle, value in attributes
             ]
             response = ATT_Read_By_Group_Type_Response(
-                length              = len(attribute_data_list[0]),
-                attribute_data_list = b''.join(attribute_data_list)
+                length=len(attribute_data_list[0]),
+                attribute_data_list=b''.join(attribute_data_list),
             )
         else:
             response = ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.starting_handle,
-                error_code                = ATT_ATTRIBUTE_NOT_FOUND_ERROR
+                request_opcode_in_error=request.op_code,
+                attribute_handle_in_error=request.starting_handle,
+                error_code=ATT_ATTRIBUTE_NOT_FOUND_ERROR,
             )
 
         self.send_response(connection, response)
@@ -628,22 +867,28 @@ class Server(EventEmitter):
         # Check  that the attribute exists
         attribute = self.get_attribute(request.attribute_handle)
         if attribute is None:
-            self.send_response(connection, ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.attribute_handle,
-                error_code                = ATT_INVALID_HANDLE_ERROR
-            ))
+            self.send_response(
+                connection,
+                ATT_Error_Response(
+                    request_opcode_in_error=request.op_code,
+                    attribute_handle_in_error=request.attribute_handle,
+                    error_code=ATT_INVALID_HANDLE_ERROR,
+                ),
+            )
             return
 
         # TODO: check permissions
 
         # Check the request parameters
         if len(request.attribute_value) > GATT_MAX_ATTRIBUTE_VALUE_SIZE:
-            self.send_response(connection, ATT_Error_Response(
-                request_opcode_in_error   = request.op_code,
-                attribute_handle_in_error = request.attribute_handle,
-                error_code                = ATT_INVALID_ATTRIBUTE_LENGTH_ERROR
-            ))
+            self.send_response(
+                connection,
+                ATT_Error_Response(
+                    request_opcode_in_error=request.op_code,
+                    attribute_handle_in_error=request.attribute_handle,
+                    error_code=ATT_INVALID_ATTRIBUTE_LENGTH_ERROR,
+                ),
+            )
             return
 
         # Accept the value
@@ -674,13 +919,15 @@ class Server(EventEmitter):
         except Exception as error:
             logger.warning(f'!!! ignoring exception: {error}')
 
-    def on_att_handle_value_confirmation(self, connection, confirmation):
+    def on_att_handle_value_confirmation(self, connection, _confirmation):
         '''
         See Bluetooth spec Vol 3, Part F - 3.4.7.3 Handle Value Confirmation
         '''
         if self.pending_confirmations[connection.handle] is None:
             # Not expected!
-            logger.warning('!!! unexpected confirmation, there is no pending indication')
+            logger.warning(
+                '!!! unexpected confirmation, there is no pending indication'
+            )
             return
 
         self.pending_confirmations[connection.handle].set_result(None)

bumble/helpers.py

@@ -16,12 +16,11 @@
 # Imports
 # -----------------------------------------------------------------------------
 import logging
-from colors import color
-
-from bumble.smp import SMP_CID, SMP_Command
 
+from .colors import color
+from .att import ATT_CID, ATT_PDU
+from .smp import SMP_CID, SMP_Command
 from .core import name_or_number
-from .gatt import ATT_PDU, ATT_CID
 from .l2cap import (
     L2CAP_PDU,
     L2CAP_CONNECTION_REQUEST,
@@ -29,20 +28,17 @@ from .l2cap import (
     L2CAP_SIGNALING_CID,
     L2CAP_LE_SIGNALING_CID,
     L2CAP_Control_Frame,
-    L2CAP_Connection_Response
+    L2CAP_Connection_Response,
 )
 from .hci import (
     HCI_EVENT_PACKET,
     HCI_ACL_DATA_PACKET,
     HCI_DISCONNECTION_COMPLETE_EVENT,
-    HCI_AclDataPacketAssembler
+    HCI_AclDataPacketAssembler,
 )
 from .rfcomm import RFCOMM_Frame, RFCOMM_PSM
 from .sdp import SDP_PDU, SDP_PSM
-from .avdtp import (
-    MessageAssembler as AVDTP_MessageAssembler,
-    AVDTP_PSM
-)
+from .avdtp import MessageAssembler as AVDTP_MessageAssembler, AVDTP_PSM
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -53,8 +49,8 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 PSM_NAMES = {
     RFCOMM_PSM: 'RFCOMM',
-    SDP_PSM:    'SDP',
-    AVDTP_PSM:  'AVDTP'
+    SDP_PSM: 'SDP',
+    AVDTP_PSM: 'AVDTP'
     # TODO: add more PSM values
 }
 
@@ -63,12 +59,13 @@ PSM_NAMES = {
 class PacketTracer:
     class AclStream:
         def __init__(self, analyzer):
-            self.analyzer         = analyzer
+            self.analyzer = analyzer
             self.packet_assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
-            self.avdtp_assemblers = {}    # AVDTP assemblers, by source_cid
-            self.psms             = {}    # PSM, by source_cid
-            self.peer             = None  # ACL stream in the other direction
+            self.avdtp_assemblers = {}  # AVDTP assemblers, by source_cid
+            self.psms = {}  # PSM, by source_cid
+            self.peer = None  # ACL stream in the other direction
 
+        # pylint: disable=too-many-nested-blocks
         def on_acl_pdu(self, pdu):
             l2cap_pdu = L2CAP_PDU.from_bytes(pdu)
 
@@ -78,7 +75,7 @@ class PacketTracer:
             elif l2cap_pdu.cid == SMP_CID:
                 smp_command = SMP_Command.from_bytes(l2cap_pdu.payload)
                 self.analyzer.emit(smp_command)
-            elif l2cap_pdu.cid == L2CAP_SIGNALING_CID or l2cap_pdu.cid == L2CAP_LE_SIGNALING_CID:
+            elif l2cap_pdu.cid in (L2CAP_SIGNALING_CID, L2CAP_LE_SIGNALING_CID):
                 control_frame = L2CAP_Control_Frame.from_bytes(l2cap_pdu.payload)
                 self.analyzer.emit(control_frame)
 
@@ -86,16 +83,26 @@ class PacketTracer:
                 if control_frame.code == L2CAP_CONNECTION_REQUEST:
                     self.psms[control_frame.source_cid] = control_frame.psm
                 elif control_frame.code == L2CAP_CONNECTION_RESPONSE:
-                    if control_frame.result == L2CAP_Connection_Response.CONNECTION_SUCCESSFUL:
+                    if (
+                        control_frame.result
+                        == L2CAP_Connection_Response.CONNECTION_SUCCESSFUL
+                    ):
                         if self.peer:
                             if psm := self.peer.psms.get(control_frame.source_cid):
                                 # Found a pending connection
                                 self.psms[control_frame.destination_cid] = psm
 
-                                # For AVDTP connections, create a packet assembler for each direction
+                                # For AVDTP connections, create a packet assembler for
+                                # each direction
                                 if psm == AVDTP_PSM:
-                                    self.avdtp_assemblers[control_frame.source_cid] = AVDTP_MessageAssembler(self.on_avdtp_message)
-                                    self.peer.avdtp_assemblers[control_frame.destination_cid] = AVDTP_MessageAssembler(self.peer.on_avdtp_message)
+                                    self.avdtp_assemblers[
+                                        control_frame.source_cid
+                                    ] = AVDTP_MessageAssembler(self.on_avdtp_message)
+                                    self.peer.avdtp_assemblers[
+                                        control_frame.destination_cid
+                                    ] = AVDTP_MessageAssembler(
+                                        self.peer.on_avdtp_message
+                                    )
 
             else:
                 # Try to find the PSM associated with this PDU
@@ -107,31 +114,42 @@ class PacketTracer:
                         rfcomm_frame = RFCOMM_Frame.from_bytes(l2cap_pdu.payload)
                         self.analyzer.emit(rfcomm_frame)
                     elif psm == AVDTP_PSM:
-                        self.analyzer.emit(f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, PSM=AVDTP]: {l2cap_pdu.payload.hex()}')
+                        self.analyzer.emit(
+                            f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, '
+                            f'PSM=AVDTP]: {l2cap_pdu.payload.hex()}'
+                        )
                         assembler = self.avdtp_assemblers.get(l2cap_pdu.cid)
                         if assembler:
                             assembler.on_pdu(l2cap_pdu.payload)
                     else:
                         psm_string = name_or_number(PSM_NAMES, psm)
-                        self.analyzer.emit(f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, PSM={psm_string}]: {l2cap_pdu.payload.hex()}')
+                        self.analyzer.emit(
+                            f'{color("L2CAP", "green")} [CID={l2cap_pdu.cid}, '
+                            f'PSM={psm_string}]: {l2cap_pdu.payload.hex()}'
+                        )
                 else:
                     self.analyzer.emit(l2cap_pdu)
 
         def on_avdtp_message(self, transaction_label, message):
-            self.analyzer.emit(f'{color("AVDTP", "green")} [{transaction_label}] {message}')
+            self.analyzer.emit(
+                f'{color("AVDTP", "green")} [{transaction_label}] {message}'
+            )
 
         def feed_packet(self, packet):
             self.packet_assembler.feed_packet(packet)
 
     class Analyzer:
         def __init__(self, label, emit_message):
-            self.label        = label
+            self.label = label
             self.emit_message = emit_message
-            self.acl_streams  = {}    # ACL streams, by connection handle
-            self.peer         = None  # Analyzer in the other direction
+            self.acl_streams = {}  # ACL streams, by connection handle
+            self.peer = None  # Analyzer in the other direction
 
         def start_acl_stream(self, connection_handle):
-            logger.info(f'[{self.label}] +++ Creating ACL stream for connection 0x{connection_handle:04X}')
+            logger.info(
+                f'[{self.label}] +++ Creating ACL stream for connection '
+                f'0x{connection_handle:04X}'
+            )
             stream = PacketTracer.AclStream(self)
             self.acl_streams[connection_handle] = stream
 
@@ -144,7 +162,10 @@ class PacketTracer:
 
         def end_acl_stream(self, connection_handle):
             if connection_handle in self.acl_streams:
-                logger.info(f'[{self.label}] --- Removing ACL stream for connection 0x{connection_handle:04X}')
+                logger.info(
+                    f'[{self.label}] --- Removing ACL stream for connection '
+                    f'0x{connection_handle:04X}'
+                )
                 del self.acl_streams[connection_handle]
 
                 # Let the other forwarder know so it can cleanup its stream as well
@@ -176,9 +197,13 @@ class PacketTracer:
         self,
         host_to_controller_label=color('HOST->CONTROLLER', 'blue'),
         controller_to_host_label=color('CONTROLLER->HOST', 'cyan'),
-        emit_message=logger.info
+        emit_message=logger.info,
     ):
-        self.host_to_controller_analyzer = PacketTracer.Analyzer(host_to_controller_label, emit_message)
-        self.controller_to_host_analyzer = PacketTracer.Analyzer(controller_to_host_label, emit_message)
+        self.host_to_controller_analyzer = PacketTracer.Analyzer(
+            host_to_controller_label, emit_message
+        )
+        self.controller_to_host_analyzer = PacketTracer.Analyzer(
+            controller_to_host_label, emit_message
+        )
         self.host_to_controller_analyzer.peer = self.controller_to_host_analyzer
         self.controller_to_host_analyzer.peer = self.host_to_controller_analyzer

bumble/hfp.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2022 Google LLC
+# Copyright 2023 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,8 +17,30 @@
 # -----------------------------------------------------------------------------
 import logging
 import asyncio
-import collections
-from colors import color
+import dataclasses
+import enum
+import traceback
+from typing import Dict, List, Union, Set
+
+from . import at
+from . import rfcomm
+
+from bumble.core import (
+    ProtocolError,
+    BT_GENERIC_AUDIO_SERVICE,
+    BT_HANDSFREE_SERVICE,
+    BT_L2CAP_PROTOCOL_ID,
+    BT_RFCOMM_PROTOCOL_ID,
+)
+from bumble.sdp import (
+    DataElement,
+    ServiceAttribute,
+    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID,
+)
 
 
 # -----------------------------------------------------------------------------
@@ -28,67 +50,700 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-# Protocol Support
+# Normative protocol definitions
 # -----------------------------------------------------------------------------
 
+
+# HF supported features (AT+BRSF=) (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class HfFeature(enum.IntFlag):
+    EC_NR = 0x001  # Echo Cancel & Noise reduction
+    THREE_WAY_CALLING = 0x002
+    CLI_PRESENTATION_CAPABILITY = 0x004
+    VOICE_RECOGNITION_ACTIVATION = 0x008
+    REMOTE_VOLUME_CONTROL = 0x010
+    ENHANCED_CALL_STATUS = 0x020
+    ENHANCED_CALL_CONTROL = 0x040
+    CODEC_NEGOTIATION = 0x080
+    HF_INDICATORS = 0x100
+    ESCO_S4_SETTINGS_SUPPORTED = 0x200
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x400
+    VOICE_RECOGNITION_TEST = 0x800
+
+
+# AG supported features (+BRSF:) (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class AgFeature(enum.IntFlag):
+    THREE_WAY_CALLING = 0x001
+    EC_NR = 0x002  # Echo Cancel & Noise reduction
+    VOICE_RECOGNITION_FUNCTION = 0x004
+    IN_BAND_RING_TONE_CAPABILITY = 0x008
+    VOICE_TAG = 0x010  # Attach a number to voice tag
+    REJECT_CALL = 0x020  # Ability to reject a call
+    ENHANCED_CALL_STATUS = 0x040
+    ENHANCED_CALL_CONTROL = 0x080
+    EXTENDED_ERROR_RESULT_CODES = 0x100
+    CODEC_NEGOTIATION = 0x200
+    HF_INDICATORS = 0x400
+    ESCO_S4_SETTINGS_SUPPORTED = 0x800
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x1000
+    VOICE_RECOGNITION_TEST = 0x2000
+
+
+# Audio Codec IDs (normative).
+# Hands-Free Profile v1.8, 10 Appendix B
+class AudioCodec(enum.IntEnum):
+    CVSD = 0x01  # Support for CVSD audio codec
+    MSBC = 0x02  # Support for mSBC audio codec
+
+
+# HF Indicators (normative).
+# Bluetooth Assigned Numbers, 6.10.1 HF Indicators
+class HfIndicator(enum.IntEnum):
+    ENHANCED_SAFETY = 0x01  # Enhanced safety feature
+    BATTERY_LEVEL = 0x02  # Battery level feature
+
+
+# Call Hold supported operations (normative).
+# AT Commands Reference Guide, 3.5.2.3.12 +CHLD - Call Holding Services
+class CallHoldOperation(enum.IntEnum):
+    RELEASE_ALL_HELD_CALLS = 0  # Release all held calls
+    RELEASE_ALL_ACTIVE_CALLS = 1  # Release all active calls, accept other
+    HOLD_ALL_ACTIVE_CALLS = 2  # Place all active calls on hold, accept other
+    ADD_HELD_CALL = 3  # Adds a held call to conversation
+
+
+# Response Hold status (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class ResponseHoldStatus(enum.IntEnum):
+    INC_CALL_HELD = 0  # Put incoming call on hold
+    HELD_CALL_ACC = 1  # Accept a held incoming call
+    HELD_CALL_REJ = 2  # Reject a held incoming call
+
+
+# Values for the Call Setup AG indicator (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class CallSetupAgIndicator(enum.IntEnum):
+    NOT_IN_CALL_SETUP = 0
+    INCOMING_CALL_PROCESS = 1
+    OUTGOING_CALL_SETUP = 2
+    REMOTE_ALERTED = 3  # Remote party alerted in an outgoing call
+
+
+# Values for the Call Held AG indicator (normative).
+# Hands-Free Profile v1.8, 4.34.2, AT Capabilities Re-Used from GSM 07.07
+# and 3GPP 27.007
+class CallHeldAgIndicator(enum.IntEnum):
+    NO_CALLS_HELD = 0
+    # Call is placed on hold or active/held calls swapped
+    # (The AG has both an active AND a held call)
+    CALL_ON_HOLD_AND_ACTIVE_CALL = 1
+    CALL_ON_HOLD_NO_ACTIVE_CALL = 2  # Call on hold, no active call
+
+
+# Call Info direction (normative).
+# AT Commands Reference Guide, 3.5.2.3.15 +CLCC - List Current Calls
+class CallInfoDirection(enum.IntEnum):
+    MOBILE_ORIGINATED_CALL = 0
+    MOBILE_TERMINATED_CALL = 1
+
+
+# Call Info status (normative).
+# AT Commands Reference Guide, 3.5.2.3.15 +CLCC - List Current Calls
+class CallInfoStatus(enum.IntEnum):
+    ACTIVE = 0
+    HELD = 1
+    DIALING = 2
+    ALERTING = 3
+    INCOMING = 4
+    WAITING = 5
+
+
+# Call Info mode (normative).
+# AT Commands Reference Guide, 3.5.2.3.15 +CLCC - List Current Calls
+class CallInfoMode(enum.IntEnum):
+    VOICE = 0
+    DATA = 1
+    FAX = 2
+    UNKNOWN = 9
+
+
+# -----------------------------------------------------------------------------
+# Hands-Free Control Interoperability Requirements
 # -----------------------------------------------------------------------------
-class HfpProtocol:
-    def __init__(self, dlc):
-        self.dlc             = dlc
-        self.buffer          = ''
-        self.lines           = collections.deque()
-        self.lines_available = asyncio.Event()
 
-        dlc.sink = self.feed
+# Response codes.
+RESPONSE_CODES = [
+    "+APLSIRI",
+    "+BAC",
+    "+BCC",
+    "+BCS",
+    "+BIA",
+    "+BIEV",
+    "+BIND",
+    "+BINP",
+    "+BLDN",
+    "+BRSF",
+    "+BTRH",
+    "+BVRA",
+    "+CCWA",
+    "+CHLD",
+    "+CHUP",
+    "+CIND",
+    "+CLCC",
+    "+CLIP",
+    "+CMEE",
+    "+CMER",
+    "+CNUM",
+    "+COPS",
+    "+IPHONEACCEV",
+    "+NREC",
+    "+VGM",
+    "+VGS",
+    "+VTS",
+    "+XAPL",
+    "A",
+    "D",
+]
 
-    def feed(self, data):
-        # Convert the data to a string if needed
-        if type(data) == bytes:
-            data = data.decode('utf-8')
+# Unsolicited responses and statuses.
+UNSOLICITED_CODES = [
+    "+APLSIRI",
+    "+BCS",
+    "+BIND",
+    "+BSIR",
+    "+BTRH",
+    "+BVRA",
+    "+CCWA",
+    "+CIEV",
+    "+CLIP",
+    "+VGM",
+    "+VGS",
+    "BLACKLISTED",
+    "BUSY",
+    "DELAYED",
+    "NO ANSWER",
+    "NO CARRIER",
+    "RING",
+]
 
-        logger.debug(f'<<< Data received: {data}')
+# Status codes
+STATUS_CODES = [
+    "+CME ERROR",
+    "BLACKLISTED",
+    "BUSY",
+    "DELAYED",
+    "ERROR",
+    "NO ANSWER",
+    "NO CARRIER",
+    "OK",
+]
 
-        # Add to the buffer and look for lines
-        self.buffer += data
-        while (separator := self.buffer.find('\r')) >= 0:
-            line = self.buffer[:separator].strip()
-            self.buffer = self.buffer[separator + 1:]
-            if len(line) > 0:
-                self.on_line(line)
 
-    def on_line(self, line):
-        self.lines.append(line)
-        self.lines_available.set()
+@dataclasses.dataclass
+class Configuration:
+    supported_hf_features: List[HfFeature]
+    supported_hf_indicators: List[HfIndicator]
+    supported_audio_codecs: List[AudioCodec]
 
-    def send_command_line(self, line):
-        logger.debug(color(f'>>> {line}', 'yellow'))
-        self.dlc.write(line + '\r')
 
-    def send_response_line(self, line):
-        logger.debug(color(f'>>> {line}', 'yellow'))
-        self.dlc.write('\r\n' + line + '\r\n')
+class AtResponseType(enum.Enum):
+    """Indicate if a response is expected from an AT command, and if multiple
+    responses are accepted."""
 
-    async def next_line(self):
-        await self.lines_available.wait()
-        line = self.lines.popleft()
-        if not self.lines:
-            self.lines_available.clear()
-        logger.debug(color(f'<<< {line}', 'green'))
-        return line
+    NONE = 0
+    SINGLE = 1
+    MULTIPLE = 2
 
-    async def initialize_service(self):
-        # Perform Service Level Connection Initialization
-        self.send_command_line('AT+BRSF=2072')  # Retrieve Supported Features
-        line = await(self.next_line())
-        line = await(self.next_line())
 
-        self.send_command_line('AT+CIND=?')
-        line = await(self.next_line())
-        line = await(self.next_line())
+class AtResponse:
+    code: str
+    parameters: list
 
-        self.send_command_line('AT+CIND?')
-        line = await(self.next_line())
-        line = await(self.next_line())
+    def __init__(self, response: bytearray):
+        code_and_parameters = response.split(b':')
+        parameters = (
+            code_and_parameters[1] if len(code_and_parameters) > 1 else bytearray()
+        )
+        self.code = code_and_parameters[0].decode()
+        self.parameters = at.parse_parameters(parameters)
 
-        self.send_command_line('AT+CMER=3,0,0,1')
-        line = await(self.next_line())
+
+@dataclasses.dataclass
+class AgIndicatorState:
+    description: str
+    index: int
+    supported_values: Set[int]
+    current_status: int
+
+
+@dataclasses.dataclass
+class HfIndicatorState:
+    supported: bool = False
+    enabled: bool = False
+
+
+class HfProtocol:
+    """Implementation for the Hands-Free side of the Hands-Free profile.
+    Reference specification Hands-Free Profile v1.8"""
+
+    supported_hf_features: int
+    supported_audio_codecs: List[AudioCodec]
+
+    supported_ag_features: int
+    supported_ag_call_hold_operations: List[CallHoldOperation]
+
+    ag_indicators: List[AgIndicatorState]
+    hf_indicators: Dict[HfIndicator, HfIndicatorState]
+
+    dlc: rfcomm.DLC
+    command_lock: asyncio.Lock
+    response_queue: asyncio.Queue
+    unsolicited_queue: asyncio.Queue
+    read_buffer: bytearray
+
+    def __init__(self, dlc: rfcomm.DLC, configuration: Configuration):
+        # Configure internal state.
+        self.dlc = dlc
+        self.command_lock = asyncio.Lock()
+        self.response_queue = asyncio.Queue()
+        self.unsolicited_queue = asyncio.Queue()
+        self.read_buffer = bytearray()
+
+        # Build local features.
+        self.supported_hf_features = sum(configuration.supported_hf_features)
+        self.supported_audio_codecs = configuration.supported_audio_codecs
+
+        self.hf_indicators = {
+            indicator: HfIndicatorState()
+            for indicator in configuration.supported_hf_indicators
+        }
+
+        # Clear remote features.
+        self.supported_ag_features = 0
+        self.supported_ag_call_hold_operations = []
+        self.ag_indicators = []
+
+        # Bind the AT reader to the RFCOMM channel.
+        self.dlc.sink = self._read_at
+
+    def supports_hf_feature(self, feature: HfFeature) -> bool:
+        return (self.supported_hf_features & feature) != 0
+
+    def supports_ag_feature(self, feature: AgFeature) -> bool:
+        return (self.supported_ag_features & feature) != 0
+
+    # Read AT messages from the RFCOMM channel.
+    # Enqueue AT commands, responses, unsolicited responses to their
+    # respective queues, and set the corresponding event.
+    def _read_at(self, data: bytes):
+        # Append to the read buffer.
+        self.read_buffer.extend(data)
+
+        # Locate header and trailer.
+        header = self.read_buffer.find(b'\r\n')
+        trailer = self.read_buffer.find(b'\r\n', header + 2)
+        if header == -1 or trailer == -1:
+            return
+
+        # Isolate the AT response code and parameters.
+        raw_response = self.read_buffer[header + 2 : trailer]
+        response = AtResponse(raw_response)
+        logger.debug(f"<<< {raw_response.decode()}")
+
+        # Consume the response bytes.
+        self.read_buffer = self.read_buffer[trailer + 2 :]
+
+        # Forward the received code to the correct queue.
+        if self.command_lock.locked() and (
+            response.code in STATUS_CODES or response.code in RESPONSE_CODES
+        ):
+            self.response_queue.put_nowait(response)
+        elif response.code in UNSOLICITED_CODES:
+            self.unsolicited_queue.put_nowait(response)
+        else:
+            logger.warning(f"dropping unexpected response with code '{response.code}'")
+
+    # Send an AT command and wait for the peer resposne.
+    # Wait for the AT responses sent by the peer, to the status code.
+    # Raises asyncio.TimeoutError if the status is not received
+    # after a timeout (default 1 second).
+    # Raises ProtocolError if the status is not OK.
+    async def execute_command(
+        self,
+        cmd: str,
+        timeout: float = 1.0,
+        response_type: AtResponseType = AtResponseType.NONE,
+    ) -> Union[None, AtResponse, List[AtResponse]]:
+        async with self.command_lock:
+            logger.debug(f">>> {cmd}")
+            self.dlc.write(cmd + '\r')
+            responses: List[AtResponse] = []
+
+            while True:
+                result = await asyncio.wait_for(
+                    self.response_queue.get(), timeout=timeout
+                )
+                if result.code == 'OK':
+                    if response_type == AtResponseType.SINGLE and len(responses) != 1:
+                        raise ProtocolError("NO ANSWER")
+
+                    if response_type == AtResponseType.MULTIPLE:
+                        return responses
+                    if response_type == AtResponseType.SINGLE:
+                        return responses[0]
+                    return None
+                if result.code in STATUS_CODES:
+                    raise ProtocolError(result.code)
+                responses.append(result)
+
+    # 4.2.1 Service Level Connection Initialization.
+    async def initiate_slc(self):
+        # 4.2.1.1 Supported features exchange
+        # First, in the initialization procedure, the HF shall send the
+        # AT+BRSF=<HF supported features> command to the AG to both notify
+        # the AG of the supported features in the HF, as well as to retrieve the
+        # supported features in the AG using the +BRSF result code.
+        response = await self.execute_command(
+            f"AT+BRSF={self.supported_hf_features}", response_type=AtResponseType.SINGLE
+        )
+
+        self.supported_ag_features = int(response.parameters[0])
+        logger.info(f"supported AG features: {self.supported_ag_features}")
+        for feature in AgFeature:
+            if self.supports_ag_feature(feature):
+                logger.info(f"  - {feature.name}")
+
+        # 4.2.1.2 Codec Negotiation
+        # Secondly, in the initialization procedure, if the HF supports the
+        # Codec Negotiation feature, it shall check if the AT+BRSF command
+        # response from the AG has indicated that it supports the Codec
+        # Negotiation feature.
+        if self.supports_hf_feature(
+            HfFeature.CODEC_NEGOTIATION
+        ) and self.supports_ag_feature(AgFeature.CODEC_NEGOTIATION):
+            # If both the HF and AG do support the Codec Negotiation feature
+            # then the HF shall send the AT+BAC=<HF available codecs> command to
+            # the AG to notify the AG of the available codecs in the HF.
+            codecs = [str(c) for c in self.supported_audio_codecs]
+            await self.execute_command(f"AT+BAC={','.join(codecs)}")
+
+        # 4.2.1.3 AG Indicators
+        # After having retrieved the supported features in the AG, the HF shall
+        # determine which indicators are supported by the AG, as well as the
+        # ordering of the supported indicators. This is because, according to
+        # the 3GPP 27.007 specification [2], the AG may support additional
+        # indicators not provided for by the Hands-Free Profile, and because the
+        # ordering of the indicators is implementation specific. The HF uses
+        # the AT+CIND=? Test command to retrieve information about the supported
+        # indicators and their ordering.
+        response = await self.execute_command(
+            "AT+CIND=?", response_type=AtResponseType.SINGLE
+        )
+
+        self.ag_indicators = []
+        for index, indicator in enumerate(response.parameters):
+            description = indicator[0].decode()
+            supported_values = []
+            for value in indicator[1]:
+                value = value.split(b'-')
+                value = [int(v) for v in value]
+                value_min = value[0]
+                value_max = value[1] if len(value) > 1 else value[0]
+                supported_values.extend([v for v in range(value_min, value_max + 1)])
+
+            self.ag_indicators.append(
+                AgIndicatorState(description, index, set(supported_values), 0)
+            )
+
+        # Once the HF has the necessary supported indicator and ordering
+        # information, it shall retrieve the current status of the indicators
+        # in the AG using the AT+CIND? Read command.
+        response = await self.execute_command(
+            "AT+CIND?", response_type=AtResponseType.SINGLE
+        )
+
+        for index, indicator in enumerate(response.parameters):
+            self.ag_indicators[index].current_status = int(indicator)
+
+        # After having retrieved the status of the indicators in the AG, the HF
+        # shall then enable the "Indicators status update" function in the AG by
+        # issuing the AT+CMER command, to which the AG shall respond with OK.
+        await self.execute_command("AT+CMER=3,,,1")
+
+        if self.supports_hf_feature(
+            HfFeature.THREE_WAY_CALLING
+        ) and self.supports_ag_feature(HfFeature.THREE_WAY_CALLING):
+            # After the HF has enabled the “Indicators status update” function in
+            # the AG, and if the “Call waiting and 3-way calling” bit was set in the
+            # supported features bitmap by both the HF and the AG, the HF shall
+            # issue the AT+CHLD=? test command to retrieve the information about how
+            # the call hold and multiparty services are supported in the AG. The HF
+            # shall not issue the AT+CHLD=? test command in case either the HF or
+            # the AG does not support the "Three-way calling" feature.
+            response = await self.execute_command(
+                "AT+CHLD=?", response_type=AtResponseType.SINGLE
+            )
+
+            self.supported_ag_call_hold_operations = [
+                CallHoldOperation(int(operation))
+                for operation in response.parameters[0]
+                if not b'x' in operation
+            ]
+
+        # 4.2.1.4 HF Indicators
+        # If the HF supports the HF indicator feature, it shall check the +BRSF
+        # response to see if the AG also supports the HF Indicator feature.
+        if self.supports_hf_feature(
+            HfFeature.HF_INDICATORS
+        ) and self.supports_ag_feature(AgFeature.HF_INDICATORS):
+            # If both the HF and AG support the HF Indicator feature, then the HF
+            # shall send the AT+BIND=<HF supported HF indicators> command to the AG
+            # to notify the AG of the supported indicators’ assigned numbers in the
+            # HF. The AG shall respond with OK
+            indicators = [str(i) for i in self.hf_indicators.keys()]
+            await self.execute_command(f"AT+BIND={','.join(indicators)}")
+
+            # After having provided the AG with the HF indicators it supports,
+            # the HF shall send the AT+BIND=? to request HF indicators supported
+            # by the AG. The AG shall reply with the +BIND response listing all
+            # HF indicators that it supports followed by an OK.
+            response = await self.execute_command(
+                "AT+BIND=?", response_type=AtResponseType.SINGLE
+            )
+
+            logger.info("supported HF indicators:")
+            for indicator in response.parameters[0]:
+                indicator = HfIndicator(int(indicator))
+                logger.info(f"  - {indicator.name}")
+                if indicator in self.hf_indicators:
+                    self.hf_indicators[indicator].supported = True
+
+            # Once the HF receives the supported HF indicators list from the AG,
+            # the HF shall send the AT+BIND? command to determine which HF
+            # indicators are enabled. The AG shall respond with one or more
+            # +BIND responses. The AG shall terminate the list with OK.
+            # (See Section 4.36.1.3).
+            responses = await self.execute_command(
+                "AT+BIND?", response_type=AtResponseType.MULTIPLE
+            )
+
+            logger.info("enabled HF indicators:")
+            for response in responses:
+                indicator = HfIndicator(int(response.parameters[0]))
+                enabled = int(response.parameters[1]) != 0
+                logger.info(f"  - {indicator.name}: {enabled}")
+                if indicator in self.hf_indicators:
+                    self.hf_indicators[indicator].enabled = True
+
+        logger.info("SLC setup completed")
+
+    # 4.11.2 Audio Connection Setup by HF
+    async def setup_audio_connection(self):
+        # When the HF triggers the establishment of the Codec Connection it
+        # shall send the AT command AT+BCC to the AG. The AG shall respond with
+        # OK if it will start the Codec Connection procedure, and with ERROR
+        # if it cannot start the Codec Connection procedure.
+        await self.execute_command("AT+BCC")
+
+    # 4.11.3 Codec Connection Setup
+    async def setup_codec_connection(self, codec_id: int):
+        # The AG shall send a +BCS=<Codec ID> unsolicited response to the HF.
+        # The HF shall then respond to the incoming unsolicited response with
+        # the AT command AT+BCS=<Codec ID>. The ID shall be the same as in the
+        # unsolicited response code as long as the ID is supported.
+        # If the received ID is not available, the HF shall respond with
+        # AT+BAC with its available codecs.
+        if codec_id not in self.supported_audio_codecs:
+            codecs = [str(c) for c in self.supported_audio_codecs]
+            await self.execute_command(f"AT+BAC={','.join(codecs)}")
+            return
+
+        await self.execute_command(f"AT+BCS={codec_id}")
+
+        # After sending the OK response, the AG shall open the
+        # Synchronous Connection with the settings that are determined by the
+        # ID. The HF shall be ready to accept the synchronous connection
+        # establishment as soon as it has sent the AT commands AT+BCS=<Codec ID>.
+
+        logger.info("codec connection setup completed")
+
+    # 4.13.1 Answer Incoming Call from the HF – In-Band Ringing
+    async def answer_incoming_call(self):
+        # The user accepts the incoming voice call by using the proper means
+        # provided by the HF. The HF shall then send the ATA command
+        # (see Section 4.34) to the AG. The AG shall then begin the procedure for
+        # accepting the incoming call.
+        await self.execute_command("ATA")
+
+    # 4.14.1 Reject an Incoming Call from the HF
+    async def reject_incoming_call(self):
+        # The user rejects the incoming call by using the User Interface on the
+        # Hands-Free unit. The HF shall then send the AT+CHUP command
+        # (see Section 4.34) to the AG. This may happen at any time during the
+        # procedures described in Sections 4.13.1 and 4.13.2.
+        await self.execute_command("AT+CHUP")
+
+    # 4.15.1 Terminate a Call Process from the HF
+    async def terminate_call(self):
+        # The user may abort the ongoing call process using whatever means
+        # provided by the Hands-Free unit. The HF shall send AT+CHUP command
+        # (see Section 4.34) to the AG, and the AG shall then start the
+        # procedure to terminate or interrupt the current call procedure.
+        # The AG shall then send the OK indication followed by the +CIEV result
+        # code, with the value indicating (call=0).
+        await self.execute_command("AT+CHUP")
+
+    async def update_ag_indicator(self, index: int, value: int):
+        self.ag_indicators[index].current_status = value
+        logger.info(
+            f"AG indicator updated: {self.ag_indicators[index].description}, {value}"
+        )
+
+    async def handle_unsolicited(self):
+        """Handle unsolicited result codes sent by the audio gateway."""
+        result = await self.unsolicited_queue.get()
+        if result.code == "+BCS":
+            await self.setup_codec_connection(int(result.parameters[0]))
+        elif result.code == "+CIEV":
+            await self.update_ag_indicator(
+                int(result.parameters[0]), int(result.parameters[1])
+            )
+        else:
+            logging.info(f"unhandled unsolicited response {result.code}")
+
+    async def run(self):
+        """Main rountine for the Hands-Free side of the HFP protocol.
+        Initiates the service level connection then loops handling
+        unsolicited AG responses."""
+
+        try:
+            await self.initiate_slc()
+            while True:
+                await self.handle_unsolicited()
+        except Exception:
+            logger.error("HFP-HF protocol failed with the following error:")
+            logger.error(traceback.format_exc())
+
+
+# -----------------------------------------------------------------------------
+# Normative SDP definitions
+# -----------------------------------------------------------------------------
+
+
+# Profile version (normative).
+# Hands-Free Profile v1.8, 5.3 SDP Interoperability Requirements
+class ProfileVersion(enum.IntEnum):
+    V1_5 = 0x0105
+    V1_6 = 0x0106
+    V1_7 = 0x0107
+    V1_8 = 0x0108
+    V1_9 = 0x0109
+
+
+# HF supported features (normative).
+# Hands-Free Profile v1.8, 5.3 SDP Interoperability Requirements
+class HfSdpFeature(enum.IntFlag):
+    EC_NR = 0x01  # Echo Cancel & Noise reduction
+    THREE_WAY_CALLING = 0x02
+    CLI_PRESENTATION_CAPABILITY = 0x04
+    VOICE_RECOGNITION_ACTIVATION = 0x08
+    REMOTE_VOLUME_CONTROL = 0x10
+    WIDE_BAND = 0x20  # Wide band speech
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x40
+    VOICE_RECOGNITION_TEST = 0x80
+
+
+# AG supported features (normative).
+# Hands-Free Profile v1.8, 5.3 SDP Interoperability Requirements
+class AgSdpFeature(enum.IntFlag):
+    THREE_WAY_CALLING = 0x01
+    EC_NR = 0x02  # Echo Cancel & Noise reduction
+    VOICE_RECOGNITION_FUNCTION = 0x04
+    IN_BAND_RING_TONE_CAPABILITY = 0x08
+    VOICE_TAG = 0x10  # Attach a number to voice tag
+    WIDE_BAND = 0x20  # Wide band speech
+    ENHANCED_VOICE_RECOGNITION_STATUS = 0x40
+    VOICE_RECOGNITION_TEST = 0x80
+
+
+def sdp_records(
+    service_record_handle: int, rfcomm_channel: int, configuration: Configuration
+) -> List[ServiceAttribute]:
+    """Generate the SDP record for HFP Hands-Free support.
+    The record exposes the features supported in the input configuration,
+    and the allocated RFCOMM channel."""
+
+    hf_supported_features = 0
+
+    if HfFeature.EC_NR in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.EC_NR
+    if HfFeature.THREE_WAY_CALLING in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.THREE_WAY_CALLING
+    if HfFeature.CLI_PRESENTATION_CAPABILITY in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.CLI_PRESENTATION_CAPABILITY
+    if HfFeature.VOICE_RECOGNITION_ACTIVATION in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.VOICE_RECOGNITION_ACTIVATION
+    if HfFeature.REMOTE_VOLUME_CONTROL in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.REMOTE_VOLUME_CONTROL
+    if (
+        HfFeature.ENHANCED_VOICE_RECOGNITION_STATUS
+        in configuration.supported_hf_features
+    ):
+        hf_supported_features |= HfSdpFeature.ENHANCED_VOICE_RECOGNITION_STATUS
+    if HfFeature.VOICE_RECOGNITION_TEST in configuration.supported_hf_features:
+        hf_supported_features |= HfSdpFeature.VOICE_RECOGNITION_TEST
+
+    if AudioCodec.MSBC in configuration.supported_audio_codecs:
+        hf_supported_features |= HfSdpFeature.WIDE_BAND
+
+    return [
+        ServiceAttribute(
+            SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_32(service_record_handle),
+        ),
+        ServiceAttribute(
+            SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.uuid(BT_HANDSFREE_SERVICE),
+                    DataElement.uuid(BT_GENERIC_AUDIO_SERVICE),
+                ]
+            ),
+        ),
+        ServiceAttribute(
+            SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.sequence([DataElement.uuid(BT_L2CAP_PROTOCOL_ID)]),
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_RFCOMM_PROTOCOL_ID),
+                            DataElement.unsigned_integer_8(rfcomm_channel),
+                        ]
+                    ),
+                ]
+            ),
+        ),
+        ServiceAttribute(
+            SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+            DataElement.sequence(
+                [
+                    DataElement.sequence(
+                        [
+                            DataElement.uuid(BT_HANDSFREE_SERVICE),
+                            DataElement.unsigned_integer_16(ProfileVersion.V1_8),
+                        ]
+                    )
+                ]
+            ),
+        ),
+        ServiceAttribute(
+            SDP_SUPPORTED_FEATURES_ATTRIBUTE_ID,
+            DataElement.unsigned_integer_16(hf_supported_features),
+        ),
+    ]

bumble/host.py

@@ -15,17 +15,68 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
 import asyncio
+import collections
 import logging
-from pyee import EventEmitter
-from colors import color
+import struct
+
+from typing import Optional
+
+from bumble.colors import color
+from bumble.l2cap import L2CAP_PDU
+from bumble.snoop import Snooper
+from bumble import drivers
+
+from .hci import (
+    Address,
+    HCI_ACL_DATA_PACKET,
+    HCI_COMMAND_PACKET,
+    HCI_COMMAND_COMPLETE_EVENT,
+    HCI_EVENT_PACKET,
+    HCI_LE_READ_BUFFER_SIZE_COMMAND,
+    HCI_LE_READ_LOCAL_SUPPORTED_FEATURES_COMMAND,
+    HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND,
+    HCI_LE_WRITE_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND,
+    HCI_READ_BUFFER_SIZE_COMMAND,
+    HCI_READ_LOCAL_VERSION_INFORMATION_COMMAND,
+    HCI_RESET_COMMAND,
+    HCI_SUCCESS,
+    HCI_SUPPORTED_COMMANDS_FLAGS,
+    HCI_VERSION_BLUETOOTH_CORE_4_0,
+    HCI_AclDataPacket,
+    HCI_AclDataPacketAssembler,
+    HCI_Command,
+    HCI_Command_Complete_Event,
+    HCI_Constant,
+    HCI_Error,
+    HCI_Event,
+    HCI_LE_Long_Term_Key_Request_Negative_Reply_Command,
+    HCI_LE_Long_Term_Key_Request_Reply_Command,
+    HCI_LE_Read_Buffer_Size_Command,
+    HCI_LE_Read_Local_Supported_Features_Command,
+    HCI_LE_Read_Suggested_Default_Data_Length_Command,
+    HCI_LE_Remote_Connection_Parameter_Request_Reply_Command,
+    HCI_LE_Set_Event_Mask_Command,
+    HCI_LE_Write_Suggested_Default_Data_Length_Command,
+    HCI_Link_Key_Request_Negative_Reply_Command,
+    HCI_Link_Key_Request_Reply_Command,
+    HCI_Packet,
+    HCI_Read_Buffer_Size_Command,
+    HCI_Read_Local_Supported_Commands_Command,
+    HCI_Read_Local_Version_Information_Command,
+    HCI_Reset_Command,
+    HCI_Set_Event_Mask_Command,
+)
+from .core import (
+    BT_BR_EDR_TRANSPORT,
+    BT_LE_TRANSPORT,
+    ConnectionPHY,
+    ConnectionParameters,
+)
+from .utils import AbortableEventEmitter
+from .transport.common import TransportLostError
 
-from .hci import *
-from .l2cap import *
-from .att import *
-from .gatt import *
-from .smp import *
-from .core import ConnectionParameters
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -36,125 +87,214 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 # Constants
 # -----------------------------------------------------------------------------
+# fmt: off
+
 HOST_DEFAULT_HC_LE_ACL_DATA_PACKET_LENGTH = 27
 HOST_HC_TOTAL_NUM_LE_ACL_DATA_PACKETS     = 1
 HOST_DEFAULT_HC_ACL_DATA_PACKET_LENGTH    = 27
 HOST_HC_TOTAL_NUM_ACL_DATA_PACKETS        = 1
 
+# fmt: on
+
 
 # -----------------------------------------------------------------------------
 class Connection:
-    def __init__(self, host, handle, role, peer_address, transport):
-        self.host                  = host
-        self.handle                = handle
-        self.role                  = role
-        self.peer_address          = peer_address
-        self.assembler             = HCI_AclDataPacketAssembler(self.on_acl_pdu)
-        self.transport             = transport
+    def __init__(self, host: Host, handle: int, peer_address: Address, transport: int):
+        self.host = host
+        self.handle = handle
+        self.peer_address = peer_address
+        self.assembler = HCI_AclDataPacketAssembler(self.on_acl_pdu)
+        self.transport = transport
 
-    def on_hci_acl_data_packet(self, packet):
+    def on_hci_acl_data_packet(self, packet: HCI_AclDataPacket) -> None:
         self.assembler.feed_packet(packet)
 
-    def on_acl_pdu(self, pdu):
+    def on_acl_pdu(self, pdu: bytes) -> None:
         l2cap_pdu = L2CAP_PDU.from_bytes(pdu)
         self.host.on_l2cap_pdu(self, l2cap_pdu.cid, l2cap_pdu.payload)
 
 
 # -----------------------------------------------------------------------------
-class Host(EventEmitter):
-    def __init__(self, controller_source = None, controller_sink = None):
+class Host(AbortableEventEmitter):
+    def __init__(self, controller_source=None, controller_sink=None):
         super().__init__()
 
-        self.hci_sink                         = None
-        self.ready                            = False  # True when we can accept incoming packets
-        self.connections                      = {}     # Connections, by connection handle
-        self.pending_command                  = None
-        self.pending_response                 = None
-        self.hc_le_acl_data_packet_length     = HOST_DEFAULT_HC_LE_ACL_DATA_PACKET_LENGTH
+        self.hci_sink = None
+        self.hci_metadata = None
+        self.ready = False  # True when we can accept incoming packets
+        self.reset_done = False
+        self.connections = {}  # Connections, by connection handle
+        self.pending_command = None
+        self.pending_response = None
+        self.hc_le_acl_data_packet_length = HOST_DEFAULT_HC_LE_ACL_DATA_PACKET_LENGTH
         self.hc_total_num_le_acl_data_packets = HOST_HC_TOTAL_NUM_LE_ACL_DATA_PACKETS
-        self.hc_acl_data_packet_length        = HOST_DEFAULT_HC_ACL_DATA_PACKET_LENGTH
-        self.hc_total_num_acl_data_packets    = HOST_HC_TOTAL_NUM_ACL_DATA_PACKETS
-        self.acl_packet_queue                 = collections.deque()
-        self.acl_packets_in_flight            = 0
-        self.local_version                    = None
-        self.local_supported_commands         = bytes(64)
-        self.local_le_features                = 0
-        self.suggested_max_tx_octets          = 251   # Max allowed
-        self.suggested_max_tx_time            = 2120  # Max allowed
-        self.command_semaphore                = asyncio.Semaphore(1)
-        self.long_term_key_provider           = None
-        self.link_key_provider                = None
-        self.pairing_io_capability_provider   = None  # Classic only
+        self.hc_acl_data_packet_length = HOST_DEFAULT_HC_ACL_DATA_PACKET_LENGTH
+        self.hc_total_num_acl_data_packets = HOST_HC_TOTAL_NUM_ACL_DATA_PACKETS
+        self.acl_packet_queue = collections.deque()
+        self.acl_packets_in_flight = 0
+        self.local_version = None
+        self.local_supported_commands = bytes(64)
+        self.local_le_features = 0
+        self.suggested_max_tx_octets = 251  # Max allowed
+        self.suggested_max_tx_time = 2120  # Max allowed
+        self.command_semaphore = asyncio.Semaphore(1)
+        self.long_term_key_provider = None
+        self.link_key_provider = None
+        self.pairing_io_capability_provider = None  # Classic only
+        self.snooper = None
 
         # Connect to the source and sink if specified
         if controller_source:
             controller_source.set_packet_sink(self)
+            self.hci_metadata = getattr(
+                controller_source, 'metadata', self.hci_metadata
+            )
         if controller_sink:
             self.set_packet_sink(controller_sink)
 
-    async def reset(self):
+    def find_connection_by_bd_addr(
+        self,
+        bd_addr: Address,
+        transport: Optional[int] = None,
+        check_address_type: bool = False,
+    ) -> Optional[Connection]:
+        for connection in self.connections.values():
+            if connection.peer_address.to_bytes() == bd_addr.to_bytes():
+                if (
+                    check_address_type
+                    and connection.peer_address.address_type != bd_addr.address_type
+                ):
+                    continue
+                if transport is None or connection.transport == transport:
+                    return connection
+
+        return None
+
+    async def flush(self) -> None:
+        # Make sure no command is pending
+        await self.command_semaphore.acquire()
+
+        # Flush current host state, then release command semaphore
+        self.emit('flush')
+        self.command_semaphore.release()
+
+    async def reset(self, driver_factory=drivers.get_driver_for_host):
+        if self.ready:
+            self.ready = False
+            await self.flush()
+
         await self.send_command(HCI_Reset_Command(), check_result=True)
         self.ready = True
 
-        response = await self.send_command(HCI_Read_Local_Supported_Commands_Command(), check_result=True)
+        # Instantiate and init a driver for the host if needed.
+        # NOTE: we don't keep a reference to the driver here, because we don't
+        # currently have a need for the driver later on. But if the driver interface
+        # evolves, it may be required, then, to store a reference to the driver in
+        # an object property.
+        if driver_factory is not None:
+            if driver := await driver_factory(self):
+                await driver.init_controller()
+
+        response = await self.send_command(
+            HCI_Read_Local_Supported_Commands_Command(), check_result=True
+        )
         self.local_supported_commands = response.return_parameters.supported_commands
 
         if self.supports_command(HCI_LE_READ_LOCAL_SUPPORTED_FEATURES_COMMAND):
-            response = await self.send_command(HCI_LE_Read_Local_Supported_Features_Command(), check_result=True)
-            self.local_le_features = struct.unpack('<Q', response.return_parameters.le_features)[0]
+            response = await self.send_command(
+                HCI_LE_Read_Local_Supported_Features_Command(), check_result=True
+            )
+            self.local_le_features = struct.unpack(
+                '<Q', response.return_parameters.le_features
+            )[0]
 
         if self.supports_command(HCI_READ_LOCAL_VERSION_INFORMATION_COMMAND):
-            response = await self.send_command(HCI_Read_Local_Version_Information_Command(), check_result=True)
+            response = await self.send_command(
+                HCI_Read_Local_Version_Information_Command(), check_result=True
+            )
             self.local_version = response.return_parameters
 
-        await self.send_command(HCI_Set_Event_Mask_Command(event_mask = bytes.fromhex('FFFFFFFFFFFFFF3F')))
-
-        if self.local_version is not None and self.local_version.hci_version <= HCI_VERSION_BLUETOOTH_CORE_4_0:
-            # Some older controllers don't like event masks with bits they don't understand
-            le_event_mask = bytes.fromhex('1F00000000000000')
-        else:
-            le_event_mask = bytes.fromhex('FFFFF00000000000')
-        await self.send_command(HCI_LE_Set_Event_Mask_Command(le_event_mask = le_event_mask))
-
-        if self.supports_command(HCI_READ_BUFFER_SIZE_COMMAND):
-            response = await self.send_command(HCI_Read_Buffer_Size_Command(), check_result=True)
-            self.hc_acl_data_packet_length     = response.return_parameters.hc_acl_data_packet_length
-            self.hc_total_num_acl_data_packets = response.return_parameters.hc_total_num_acl_data_packets
-
-        if self.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
-            response = await self.send_command(HCI_LE_Read_Buffer_Size_Command(), check_result=True)
-            self.hc_le_acl_data_packet_length     = response.return_parameters.hc_le_acl_data_packet_length
-            self.hc_total_num_le_acl_data_packets = response.return_parameters.hc_total_num_le_acl_data_packets
-
-        if response.return_parameters.hc_le_acl_data_packet_length == 0 or response.return_parameters.hc_total_num_le_acl_data_packets == 0:
-            # LE and Classic share the same values
-            self.hc_le_acl_data_packet_length     = self.hc_acl_data_packet_length
-            self.hc_total_num_le_acl_data_packets = self.hc_total_num_acl_data_packets
-
-        logger.debug(
-            f'HCI ACL flow control: hc_acl_data_packet_length={self.hc_acl_data_packet_length},'
-            f'hc_total_num_acl_data_packets={self.hc_total_num_acl_data_packets}'
-        )
-        logger.debug(
-            f'HCI LE ACL flow control: hc_le_acl_data_packet_length={self.hc_le_acl_data_packet_length},'
-            f'hc_total_num_le_acl_data_packets={self.hc_total_num_le_acl_data_packets}'
+        await self.send_command(
+            HCI_Set_Event_Mask_Command(event_mask=bytes.fromhex('FFFFFFFFFFFFFF3F'))
         )
 
         if (
-            self.supports_command(HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND) and
-            self.supports_command(HCI_LE_WRITE_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND)
+            self.local_version is not None
+            and self.local_version.hci_version <= HCI_VERSION_BLUETOOTH_CORE_4_0
         ):
-            response = await self.send_command(HCI_LE_Read_Suggested_Default_Data_Length_Command())
-            suggested_max_tx_octets = response.return_parameters.suggested_max_tx_octets
-            suggested_max_tx_time   = response.return_parameters.suggested_max_tx_time
+            # Some older controllers don't like event masks with bits they don't
+            # understand
+            le_event_mask = bytes.fromhex('1F00000000000000')
+        else:
+            le_event_mask = bytes.fromhex('FFFFF00000000000')
+
+        await self.send_command(
+            HCI_LE_Set_Event_Mask_Command(le_event_mask=le_event_mask)
+        )
+
+        if self.supports_command(HCI_READ_BUFFER_SIZE_COMMAND):
+            response = await self.send_command(
+                HCI_Read_Buffer_Size_Command(), check_result=True
+            )
+            self.hc_acl_data_packet_length = (
+                response.return_parameters.hc_acl_data_packet_length
+            )
+            self.hc_total_num_acl_data_packets = (
+                response.return_parameters.hc_total_num_acl_data_packets
+            )
+
+            logger.debug(
+                'HCI ACL flow control: '
+                f'hc_acl_data_packet_length={self.hc_acl_data_packet_length},'
+                f'hc_total_num_acl_data_packets={self.hc_total_num_acl_data_packets}'
+            )
+
+        if self.supports_command(HCI_LE_READ_BUFFER_SIZE_COMMAND):
+            response = await self.send_command(
+                HCI_LE_Read_Buffer_Size_Command(), check_result=True
+            )
+            self.hc_le_acl_data_packet_length = (
+                response.return_parameters.hc_le_acl_data_packet_length
+            )
+            self.hc_total_num_le_acl_data_packets = (
+                response.return_parameters.hc_total_num_le_acl_data_packets
+            )
+
+            logger.debug(
+                'HCI LE ACL flow control: '
+                f'hc_le_acl_data_packet_length={self.hc_le_acl_data_packet_length},'
+                'hc_total_num_le_acl_data_packets='
+                f'{self.hc_total_num_le_acl_data_packets}'
+            )
+
             if (
-                suggested_max_tx_octets != self.suggested_max_tx_octets or
-                suggested_max_tx_time != self.suggested_max_tx_time
+                response.return_parameters.hc_le_acl_data_packet_length == 0
+                or response.return_parameters.hc_total_num_le_acl_data_packets == 0
             ):
-                await self.send_command(HCI_LE_Write_Suggested_Default_Data_Length_Command(
-                    suggested_max_tx_octets = self.suggested_max_tx_octets,
-                    suggested_max_tx_time   = self.suggested_max_tx_time
-                ))
+                # LE and Classic share the same values
+                self.hc_le_acl_data_packet_length = self.hc_acl_data_packet_length
+                self.hc_total_num_le_acl_data_packets = (
+                    self.hc_total_num_acl_data_packets
+                )
+
+        if self.supports_command(
+            HCI_LE_READ_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND
+        ) and self.supports_command(HCI_LE_WRITE_SUGGESTED_DEFAULT_DATA_LENGTH_COMMAND):
+            response = await self.send_command(
+                HCI_LE_Read_Suggested_Default_Data_Length_Command()
+            )
+            suggested_max_tx_octets = response.return_parameters.suggested_max_tx_octets
+            suggested_max_tx_time = response.return_parameters.suggested_max_tx_time
+            if (
+                suggested_max_tx_octets != self.suggested_max_tx_octets
+                or suggested_max_tx_time != self.suggested_max_tx_time
+            ):
+                await self.send_command(
+                    HCI_LE_Write_Suggested_Default_Data_Length_Command(
+                        suggested_max_tx_octets=self.suggested_max_tx_octets,
+                        suggested_max_tx_time=self.suggested_max_tx_time,
+                    )
+                )
 
         self.reset_done = True
 
@@ -171,8 +311,11 @@ class Host(EventEmitter):
     def set_packet_sink(self, sink):
         self.hci_sink = sink
 
-    def send_hci_packet(self, packet):
-        self.hci_sink.on_packet(packet.to_bytes())
+    def send_hci_packet(self, packet: HCI_Packet) -> None:
+        if self.snooper:
+            self.snooper.snoop(bytes(packet), Snooper.Direction.HOST_TO_CONTROLLER)
+
+        self.hci_sink.on_packet(bytes(packet))
 
     async def send_command(self, command, check_result=False):
         logger.debug(f'{color("### HOST -> CONTROLLER", "blue")}: {command}')
@@ -192,35 +335,39 @@ class Host(EventEmitter):
 
                 # Check the return parameters if required
                 if check_result:
-                    if type(response.return_parameters) is int:
+                    if isinstance(response.return_parameters, int):
                         status = response.return_parameters
-                    elif type(response.return_parameters) is bytes:
+                    elif isinstance(response.return_parameters, bytes):
                         # return parameters first field is a one byte status code
                         status = response.return_parameters[0]
                     else:
                         status = response.return_parameters.status
 
                     if status != HCI_SUCCESS:
-                        logger.warning(f'{command.name} failed ({HCI_Constant.error_name(status)})')
+                        logger.warning(
+                            f'{command.name} failed ({HCI_Constant.error_name(status)})'
+                        )
                         raise HCI_Error(status)
 
                 return response
             except Exception as error:
-                logger.warning(f'{color("!!! Exception while sending HCI packet:", "red")} {error}')
+                logger.warning(
+                    f'{color("!!! Exception while sending command:", "red")} {error}'
+                )
                 raise error
             finally:
                 self.pending_command = None
                 self.pending_response = None
 
     # Use this method to send a command from a task
-    def send_command_sync(self, command):
-        async def send_command(command):
+    def send_command_sync(self, command: HCI_Command) -> None:
+        async def send_command(command: HCI_Command) -> None:
             await self.send_command(command)
 
         asyncio.create_task(send_command(command))
 
-    def send_l2cap_pdu(self, connection_handle, cid, pdu):
-        l2cap_pdu = L2CAP_PDU(cid, pdu).to_bytes()
+    def send_l2cap_pdu(self, connection_handle: int, cid: int, pdu: bytes) -> None:
+        l2cap_pdu = bytes(L2CAP_PDU(cid, pdu))
 
         # Send the data to the controller via ACL packets
         bytes_remaining = len(l2cap_pdu)
@@ -230,47 +377,57 @@ class Host(EventEmitter):
             # TODO: support different LE/Classic lengths
             data_total_length = min(bytes_remaining, self.hc_le_acl_data_packet_length)
             acl_packet = HCI_AclDataPacket(
-                connection_handle  = connection_handle,
-                pb_flag            = pb_flag,
-                bc_flag            = 0,
-                data_total_length  = data_total_length,
-                data               = l2cap_pdu[offset:offset + data_total_length]
+                connection_handle=connection_handle,
+                pb_flag=pb_flag,
+                bc_flag=0,
+                data_total_length=data_total_length,
+                data=l2cap_pdu[offset : offset + data_total_length],
+            )
+            logger.debug(
+                f'{color("### HOST -> CONTROLLER", "blue")}: (CID={cid}) {acl_packet}'
             )
-            logger.debug(f'{color("### HOST -> CONTROLLER", "blue")}: (CID={cid}) {acl_packet}')
             self.queue_acl_packet(acl_packet)
             pb_flag = 1
             offset += data_total_length
             bytes_remaining -= data_total_length
 
-    def queue_acl_packet(self, acl_packet):
+    def queue_acl_packet(self, acl_packet: HCI_AclDataPacket) -> None:
         self.acl_packet_queue.appendleft(acl_packet)
         self.check_acl_packet_queue()
 
         if len(self.acl_packet_queue):
-            logger.debug(f'{self.acl_packets_in_flight} ACL packets in flight, {len(self.acl_packet_queue)} in queue')
+            logger.debug(
+                f'{self.acl_packets_in_flight} ACL packets in flight, '
+                f'{len(self.acl_packet_queue)} in queue'
+            )
 
-    def check_acl_packet_queue(self):
+    def check_acl_packet_queue(self) -> None:
         # Send all we can (TODO: support different LE/Classic limits)
-        while len(self.acl_packet_queue) > 0 and self.acl_packets_in_flight < self.hc_total_num_le_acl_data_packets:
+        while (
+            len(self.acl_packet_queue) > 0
+            and self.acl_packets_in_flight < self.hc_total_num_le_acl_data_packets
+        ):
             packet = self.acl_packet_queue.pop()
             self.send_hci_packet(packet)
             self.acl_packets_in_flight += 1
 
     def supports_command(self, command):
         # Find the support flag position for this command
-        for (octet, flags) in enumerate(HCI_SUPPORTED_COMMANDS_FLAGS):
-            for (flag_position, value) in enumerate(flags):
+        for octet, flags in enumerate(HCI_SUPPORTED_COMMANDS_FLAGS):
+            for flag_position, value in enumerate(flags):
                 if value == command:
                     # Check if the flag is set
                     if octet < len(self.local_supported_commands) and flag_position < 8:
-                        return (self.local_supported_commands[octet] & (1 << flag_position)) != 0
+                        return (
+                            self.local_supported_commands[octet] & (1 << flag_position)
+                        ) != 0
 
         return False
 
     @property
     def supported_commands(self):
         commands = []
-        for (octet, flags) in enumerate(self.local_supported_commands):
+        for octet, flags in enumerate(self.local_supported_commands):
             if octet < len(HCI_SUPPORTED_COMMANDS_FLAGS):
                 for flag in range(8):
                     if flags & (1 << flag) != 0:
@@ -285,54 +442,69 @@ class Host(EventEmitter):
 
     @property
     def supported_le_features(self):
-        return [feature for feature in range(64) if self.local_le_features & (1 << feature)]
+        return [
+            feature for feature in range(64) if self.local_le_features & (1 << feature)
+        ]
 
     # Packet Sink protocol (packets coming from the controller via HCI)
-    def on_packet(self, packet):
+    def on_packet(self, packet: bytes) -> None:
         hci_packet = HCI_Packet.from_bytes(packet)
         if self.ready or (
-            hci_packet.hci_packet_type == HCI_EVENT_PACKET and
-            hci_packet.event_code == HCI_COMMAND_COMPLETE_EVENT and
-            hci_packet.command_opcode == HCI_RESET_COMMAND
+            isinstance(hci_packet, HCI_Command_Complete_Event)
+            and hci_packet.command_opcode == HCI_RESET_COMMAND
         ):
             self.on_hci_packet(hci_packet)
         else:
             logger.debug('reset not done, ignoring packet from controller')
 
-    def on_hci_packet(self, packet):
+    def on_transport_lost(self):
+        # Called by the source when the transport has been lost.
+        if self.pending_response:
+            self.pending_response.set_exception(TransportLostError('transport lost'))
+
+        self.emit('flush')
+
+    def on_hci_packet(self, packet: HCI_Packet) -> None:
         logger.debug(f'{color("### CONTROLLER -> HOST", "green")}: {packet}')
 
+        if self.snooper:
+            self.snooper.snoop(bytes(packet), Snooper.Direction.CONTROLLER_TO_HOST)
+
         # If the packet is a command, invoke the handler for this packet
-        if packet.hci_packet_type == HCI_COMMAND_PACKET:
+        if isinstance(packet, HCI_Command):
             self.on_hci_command_packet(packet)
-        elif packet.hci_packet_type == HCI_EVENT_PACKET:
+        elif isinstance(packet, HCI_Event):
             self.on_hci_event_packet(packet)
-        elif packet.hci_packet_type == HCI_ACL_DATA_PACKET:
+        elif isinstance(packet, HCI_AclDataPacket):
             self.on_hci_acl_data_packet(packet)
         else:
             logger.warning(f'!!! unknown packet type {packet.hci_packet_type}')
 
-    def on_hci_command_packet(self, command):
+    def on_hci_command_packet(self, command: HCI_Command) -> None:
         logger.warning(f'!!! unexpected command packet: {command}')
 
-    def on_hci_event_packet(self, event):
+    def on_hci_event_packet(self, event: HCI_Event) -> None:
         handler_name = f'on_{event.name.lower()}'
         handler = getattr(self, handler_name, self.on_hci_event)
         handler(event)
 
-    def on_hci_acl_data_packet(self, packet):
+    def on_hci_acl_data_packet(self, packet: HCI_AclDataPacket) -> None:
         # Look for the connection to which this data belongs
         if connection := self.connections.get(packet.connection_handle):
             connection.on_hci_acl_data_packet(packet)
 
-    def on_l2cap_pdu(self, connection, cid, pdu):
+    def on_l2cap_pdu(self, connection: Connection, cid: int, pdu: bytes) -> None:
         self.emit('l2cap_pdu', connection.handle, cid, pdu)
 
     def on_command_processed(self, event):
         if self.pending_response:
             # Check that it is what we were expecting
             if self.pending_command.op_code != event.command_opcode:
-                logger.warning(f'!!! command result mismatch, expected 0x{self.pending_command.op_code:X} but got 0x{event.command_opcode:X}')
+                logger.warning(
+                    '!!! command result mismatch, expected '
+                    f'0x{self.pending_command.op_code:X} but got '
+                    f'0x{event.command_opcode:X}'
+                )
 
             self.pending_response.set_result(event)
         else:
@@ -346,10 +518,12 @@ class Host(EventEmitter):
 
     def on_hci_command_complete_event(self, event):
         if event.command_opcode == 0:
-            # This is used just for the Num_HCI_Command_Packets field, not related to an actual command
+            # This is used just for the Num_HCI_Command_Packets field, not related to
+            # an actual command
             logger.debug('no-command event')
-        else:
-            return self.on_command_processed(event)
+            return None
+
+        return self.on_command_processed(event)
 
     def on_hci_command_status_event(self, event):
         return self.on_command_processed(event)
@@ -360,7 +534,12 @@ class Host(EventEmitter):
             self.acl_packets_in_flight -= total_packets
             self.check_acl_packet_queue()
         else:
-            logger.warning(color(f'!!! {total_packets} completed but only {self.acl_packets_in_flight} in flight'))
+            logger.warning(
+                color(
+                    '!!! {total_packets} completed but only '
+                    f'{self.acl_packets_in_flight} in flight'
+                )
+            )
             self.acl_packets_in_flight = 0
 
     # Classic only
@@ -377,33 +556,42 @@ class Host(EventEmitter):
         # Check if this is a cancellation
         if event.status == HCI_SUCCESS:
             # Create/update the connection
-            logger.debug(f'### CONNECTION: [0x{event.connection_handle:04X}] {event.peer_address} as {HCI_Constant.role_name(event.role)}')
+            logger.debug(
+                f'### LE CONNECTION: [0x{event.connection_handle:04X}] '
+                f'{event.peer_address} as {HCI_Constant.role_name(event.role)}'
+            )
 
             connection = self.connections.get(event.connection_handle)
             if connection is None:
-                connection = Connection(self, event.connection_handle, event.role, event.peer_address, BT_LE_TRANSPORT)
+                connection = Connection(
+                    self,
+                    event.connection_handle,
+                    event.peer_address,
+                    BT_LE_TRANSPORT,
+                )
                 self.connections[event.connection_handle] = connection
 
             # Notify the client
             connection_parameters = ConnectionParameters(
                 event.connection_interval,
                 event.peripheral_latency,
-                event.supervision_timeout
+                event.supervision_timeout,
             )
             self.emit(
                 'connection',
                 event.connection_handle,
                 BT_LE_TRANSPORT,
                 event.peer_address,
-                None,
                 event.role,
-                connection_parameters
+                connection_parameters,
             )
         else:
             logger.debug(f'### CONNECTION FAILED: {event.status}')
 
             # Notify the listeners
-            self.emit('connection_failure', BT_LE_TRANSPORT, event.peer_address, event.status)
+            self.emit(
+                'connection_failure', BT_LE_TRANSPORT, event.peer_address, event.status
+            )
 
     def on_hci_le_enhanced_connection_complete_event(self, event):
         # Just use the same implementation as for the non-enhanced event for now
@@ -412,11 +600,19 @@ class Host(EventEmitter):
     def on_hci_connection_complete_event(self, event):
         if event.status == HCI_SUCCESS:
             # Create/update the connection
-            logger.debug(f'### BR/EDR CONNECTION: [0x{event.connection_handle:04X}] {event.bd_addr}')
+            logger.debug(
+                f'### BR/EDR CONNECTION: [0x{event.connection_handle:04X}] '
+                f'{event.bd_addr}'
+            )
 
             connection = self.connections.get(event.connection_handle)
             if connection is None:
-                connection = Connection(self, event.connection_handle, BT_CENTRAL_ROLE, event.bd_addr, BT_BR_EDR_TRANSPORT)
+                connection = Connection(
+                    self,
+                    event.connection_handle,
+                    event.bd_addr,
+                    BT_BR_EDR_TRANSPORT,
+                )
                 self.connections[event.connection_handle] = connection
 
             # Notify the client
@@ -426,14 +622,15 @@ class Host(EventEmitter):
                 BT_BR_EDR_TRANSPORT,
                 event.bd_addr,
                 None,
-                BT_CENTRAL_ROLE,
-                None
+                None,
             )
         else:
             logger.debug(f'### BR/EDR CONNECTION FAILED: {event.status}')
 
             # Notify the client
-            self.emit('connection_failure', BT_BR_EDR_TRANSPORT, event.bd_addr, event.status)
+            self.emit(
+                'connection_failure', BT_BR_EDR_TRANSPORT, event.bd_addr, event.status
+            )
 
     def on_hci_disconnection_complete_event(self, event):
         # Find the connection
@@ -442,7 +639,11 @@ class Host(EventEmitter):
             return
 
         if event.status == HCI_SUCCESS:
-            logger.debug(f'### DISCONNECTION: [0x{event.connection_handle:04X}] {connection.peer_address} as {HCI_Constant.role_name(connection.role)}, reason={event.reason}')
+            logger.debug(
+                f'### DISCONNECTION: [0x{event.connection_handle:04X}] '
+                f'{connection.peer_address} '
+                f'reason={event.reason}'
+            )
             del self.connections[event.connection_handle]
 
             # Notify the listeners
@@ -463,11 +664,15 @@ class Host(EventEmitter):
             connection_parameters = ConnectionParameters(
                 event.connection_interval,
                 event.peripheral_latency,
-                event.supervision_timeout
+                event.supervision_timeout,
+            )
+            self.emit(
+                'connection_parameters_update', connection.handle, connection_parameters
             )
-            self.emit('connection_parameters_update', connection.handle, connection_parameters)
         else:
-            self.emit('connection_parameters_update_failure', connection.handle, event.status)
+            self.emit(
+                'connection_parameters_update_failure', connection.handle, event.status
+            )
 
     def on_hci_le_phy_update_complete_event(self, event):
         if (connection := self.connections.get(event.connection_handle)) is None:
@@ -497,13 +702,13 @@ class Host(EventEmitter):
         # TODO: delegate the decision
         self.send_command_sync(
             HCI_LE_Remote_Connection_Parameter_Request_Reply_Command(
-                connection_handle = event.connection_handle,
-                interval_min      = event.interval_min,
-                interval_max      = event.interval_max,
-                latency           = event.latency,
-                timeout           = event.timeout,
-                min_ce_length     = 0,
-                max_ce_length     = 0
+                connection_handle=event.connection_handle,
+                interval_min=event.interval_min,
+                interval_max=event.interval_max,
+                max_latency=event.max_latency,
+                timeout=event.timeout,
+                min_ce_length=0,
+                max_ce_length=0,
             )
         )
 
@@ -517,19 +722,23 @@ class Host(EventEmitter):
                 logger.debug('no long term key provider')
                 long_term_key = None
             else:
-                long_term_key = await self.long_term_key_provider(
-                    connection.handle,
-                    event.random_number,
-                    event.encryption_diversifier
+                long_term_key = await self.abort_on(
+                    'flush',
+                    # pylint: disable-next=not-callable
+                    self.long_term_key_provider(
+                        connection.handle,
+                        event.random_number,
+                        event.encryption_diversifier,
+                    ),
                 )
             if long_term_key:
                 response = HCI_LE_Long_Term_Key_Request_Reply_Command(
-                    connection_handle = event.connection_handle,
-                    long_term_key     = long_term_key
+                    connection_handle=event.connection_handle,
+                    long_term_key=long_term_key,
                 )
             else:
                 response = HCI_LE_Long_Term_Key_Request_Negative_Reply_Command(
-                    connection_handle = event.connection_handle
+                    connection_handle=event.connection_handle
                 )
 
             await self.send_command(response)
@@ -544,10 +753,17 @@ class Host(EventEmitter):
 
     def on_hci_role_change_event(self, event):
         if event.status == HCI_SUCCESS:
-            logger.debug(f'role change for {event.bd_addr}: {HCI_Constant.role_name(event.new_role)}')
-            # TODO: lookup the connection and update the role
+            logger.debug(
+                f'role change for {event.bd_addr}: '
+                f'{HCI_Constant.role_name(event.new_role)}'
+            )
+            self.emit('role_change', event.bd_addr, event.new_role)
         else:
-            logger.debug(f'role change for {event.bd_addr} failed: {HCI_Constant.error_name(event.status)}')
+            logger.debug(
+                f'role change for {event.bd_addr} failed: '
+                f'{HCI_Constant.error_name(event.status)}'
+            )
+            self.emit('role_change_failure', event.bd_addr, event.status)
 
     def on_hci_le_data_length_change_event(self, event):
         self.emit(
@@ -556,7 +772,7 @@ class Host(EventEmitter):
             event.max_tx_octets,
             event.max_tx_time,
             event.max_rx_octets,
-            event.max_rx_time
+            event.max_rx_time,
         )
 
     def on_hci_authentication_complete_event(self, event):
@@ -564,21 +780,35 @@ class Host(EventEmitter):
         if event.status == HCI_SUCCESS:
             self.emit('connection_authentication', event.connection_handle)
         else:
-            self.emit('connection_authentication_failure', event.connection_handle, event.status)
+            self.emit(
+                'connection_authentication_failure',
+                event.connection_handle,
+                event.status,
+            )
 
     def on_hci_encryption_change_event(self, event):
         # Notify the client
         if event.status == HCI_SUCCESS:
-            self.emit('connection_encryption_change', event.connection_handle, event.encryption_enabled)
+            self.emit(
+                'connection_encryption_change',
+                event.connection_handle,
+                event.encryption_enabled,
+            )
         else:
-            self.emit('connection_encryption_failure', event.connection_handle, event.status)
+            self.emit(
+                'connection_encryption_failure', event.connection_handle, event.status
+            )
 
     def on_hci_encryption_key_refresh_complete_event(self, event):
         # Notify the client
         if event.status == HCI_SUCCESS:
             self.emit('connection_encryption_key_refresh', event.connection_handle)
         else:
-            self.emit('connection_encryption_key_refresh_failure', event.connection_handle, event.status)
+            self.emit(
+                'connection_encryption_key_refresh_failure',
+                event.connection_handle,
+                event.status,
+            )
 
     def on_hci_link_supervision_timeout_changed_event(self, event):
         pass
@@ -590,20 +820,24 @@ class Host(EventEmitter):
         pass
 
     def on_hci_link_key_notification_event(self, event):
-        logger.debug(f'link key for {event.bd_addr}: {event.link_key.hex()}, type={HCI_Constant.link_key_type_name(event.key_type)}')
+        logger.debug(
+            f'link key for {event.bd_addr}: {event.link_key.hex()}, '
+            f'type={HCI_Constant.link_key_type_name(event.key_type)}'
+        )
         self.emit('link_key', event.bd_addr, event.link_key, event.key_type)
 
     def on_hci_simple_pairing_complete_event(self, event):
-        logger.debug(f'simple pairing complete for {event.bd_addr}: status={HCI_Constant.status_name(event.status)}')
+        logger.debug(
+            f'simple pairing complete for {event.bd_addr}: '
+            f'status={HCI_Constant.status_name(event.status)}'
+        )
+        if event.status == HCI_SUCCESS:
+            self.emit('classic_pairing', event.bd_addr)
+        else:
+            self.emit('classic_pairing_failure', event.bd_addr, event.status)
 
     def on_hci_pin_code_request_event(self, event):
-        # For now, just refuse all requests
-        # TODO: delegate the decision
-        self.send_command_sync(
-            HCI_PIN_Code_Request_Negative_Reply_Command(
-                bd_addr = event.bd_addr
-            )
-        )
+        self.emit('pin_code_request', event.bd_addr)
 
     def on_hci_link_key_request_event(self, event):
         async def send_link_key():
@@ -611,15 +845,18 @@ class Host(EventEmitter):
                 logger.debug('no link key provider')
                 link_key = None
             else:
-                link_key = await self.link_key_provider(event.bd_addr)
+                link_key = await self.abort_on(
+                    'flush',
+                    # pylint: disable-next=not-callable
+                    self.link_key_provider(event.bd_addr),
+                )
             if link_key:
                 response = HCI_Link_Key_Request_Reply_Command(
-                    bd_addr  = event.bd_addr,
-                    link_key = link_key
+                    bd_addr=event.bd_addr, link_key=link_key
                 )
             else:
                 response = HCI_Link_Key_Request_Negative_Reply_Command(
-                    bd_addr = event.bd_addr
+                    bd_addr=event.bd_addr
                 )
 
             await self.send_command(response)
@@ -630,15 +867,29 @@ class Host(EventEmitter):
         self.emit('authentication_io_capability_request', event.bd_addr)
 
     def on_hci_io_capability_response_event(self, event):
-        pass
+        self.emit(
+            'authentication_io_capability_response',
+            event.bd_addr,
+            event.io_capability,
+            event.authentication_requirements,
+        )
 
     def on_hci_user_confirmation_request_event(self, event):
-        self.emit('authentication_user_confirmation_request', event.bd_addr, event.numeric_value)
+        self.emit(
+            'authentication_user_confirmation_request',
+            event.bd_addr,
+            event.numeric_value,
+        )
 
     def on_hci_user_passkey_request_event(self, event):
         self.emit('authentication_user_passkey_request', event.bd_addr)
 
-    def on_hci_inquiry_complete_event(self, event):
+    def on_hci_user_passkey_notification_event(self, event):
+        self.emit(
+            'authentication_user_passkey_notification', event.bd_addr, event.passkey
+        )
+
+    def on_hci_inquiry_complete_event(self, _event):
         self.emit('inquiry_complete')
 
     def on_hci_inquiry_result_with_rssi_event(self, event):
@@ -648,7 +899,7 @@ class Host(EventEmitter):
                 response.bd_addr,
                 response.class_of_device,
                 b'',
-                response.rssi
+                response.rssi,
             )
 
     def on_hci_extended_inquiry_result_event(self, event):
@@ -657,14 +908,23 @@ class Host(EventEmitter):
             event.bd_addr,
             event.class_of_device,
             event.extended_inquiry_response,
-            event.rssi
+            event.rssi,
         )
 
     def on_hci_remote_name_request_complete_event(self, event):
         if event.status != HCI_SUCCESS:
             self.emit('remote_name_failure', event.bd_addr, event.status)
         else:
-            self.emit('remote_name', event.bd_addr, event.remote_name)
+            utf8_name = event.remote_name
+            terminator = utf8_name.find(0)
+            if terminator >= 0:
+                utf8_name = utf8_name[0:terminator]
+
+            self.emit('remote_name', event.bd_addr, utf8_name)
 
     def on_hci_remote_host_supported_features_notification_event(self, event):
-        self.emit('remote_host_supported_features', event.bd_addr, event.host_supported_features)
+        self.emit(
+            'remote_host_supported_features',
+            event.bd_addr,
+            event.host_supported_features,
+        )

bumble/keys.py

@@ -20,13 +20,19 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+import asyncio
 import logging
 import os
 import json
-from colors import color
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
 
+from .colors import color
 from .hci import Address
 
+if TYPE_CHECKING:
+    from .device import Device
+
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -38,10 +44,10 @@ logger = logging.getLogger(__name__)
 class PairingKeys:
     class Key:
         def __init__(self, value, authenticated=False, ediv=None, rand=None):
-            self.value         = value
+            self.value = value
             self.authenticated = authenticated
-            self.ediv          = ediv
-            self.rand          = rand
+            self.ediv = ediv
+            self.rand = rand
 
         @classmethod
         def from_dict(cls, key_dict):
@@ -64,31 +70,33 @@ class PairingKeys:
             return key_dict
 
     def __init__(self):
-        self.address_type   = None
-        self.ltk            = None
-        self.ltk_central    = None
+        self.address_type = None
+        self.ltk = None
+        self.ltk_central = None
         self.ltk_peripheral = None
-        self.irk            = None
-        self.csrk           = None
-        self.link_key       = None  # Classic
+        self.irk = None
+        self.csrk = None
+        self.link_key = None  # Classic
 
     @staticmethod
     def key_from_dict(keys_dict, key_name):
         key_dict = keys_dict.get(key_name)
-        if key_dict is not None:
-            return PairingKeys.Key.from_dict(key_dict)
+        if key_dict is None:
+            return None
+
+        return PairingKeys.Key.from_dict(key_dict)
 
     @staticmethod
     def from_dict(keys_dict):
         keys = PairingKeys()
 
-        keys.address_type   = keys_dict.get('address_type')
-        keys.ltk            = PairingKeys.key_from_dict(keys_dict, 'ltk')
-        keys.ltk_central    = PairingKeys.key_from_dict(keys_dict, 'ltk_central')
+        keys.address_type = keys_dict.get('address_type')
+        keys.ltk = PairingKeys.key_from_dict(keys_dict, 'ltk')
+        keys.ltk_central = PairingKeys.key_from_dict(keys_dict, 'ltk_central')
         keys.ltk_peripheral = PairingKeys.key_from_dict(keys_dict, 'ltk_peripheral')
-        keys.irk            = PairingKeys.key_from_dict(keys_dict, 'irk')
-        keys.csrk           = PairingKeys.key_from_dict(keys_dict, 'csrk')
-        keys.link_key       = PairingKeys.key_from_dict(keys_dict, 'link_key')
+        keys.irk = PairingKeys.key_from_dict(keys_dict, 'irk')
+        keys.csrk = PairingKeys.key_from_dict(keys_dict, 'csrk')
+        keys.link_key = PairingKeys.key_from_dict(keys_dict, 'link_key')
 
         return keys
 
@@ -120,29 +128,33 @@ class PairingKeys:
 
     def print(self, prefix=''):
         keys_dict = self.to_dict()
-        for (property, value) in keys_dict.items():
-            if type(value) is dict:
-                print(f'{prefix}{color(property, "cyan")}:')
+        for (container_property, value) in keys_dict.items():
+            if isinstance(value, dict):
+                print(f'{prefix}{color(container_property, "cyan")}:')
                 for (key_property, key_value) in value.items():
                     print(f'{prefix}  {color(key_property, "green")}: {key_value}')
             else:
-                print(f'{prefix}{color(property, "cyan")}: {value}')
+                print(f'{prefix}{color(container_property, "cyan")}: {value}')
 
 
 # -----------------------------------------------------------------------------
 class KeyStore:
-    async def delete(self, name):
+    async def delete(self, name: str):
         pass
 
-    async def update(self, name, keys):
+    async def update(self, name: str, keys: PairingKeys) -> None:
         pass
 
-    async def get(self, name):
-        return PairingKeys()
+    async def get(self, _name: str) -> Optional[PairingKeys]:
+        return None
 
-    async def get_all(self):
+    async def get_all(self) -> List[Tuple[str, PairingKeys]]:
         return []
 
+    async def delete_all(self) -> None:
+        all_keys = await self.get_all()
+        await asyncio.gather(*(self.delete(name) for (name, _) in all_keys))
+
     async def get_resolving_keys(self):
         all_keys = await self.get_all()
         resolving_keys = []
@@ -161,39 +173,79 @@ class KeyStore:
         separator = ''
         for (name, keys) in entries:
             print(separator + prefix + color(name, 'yellow'))
-            keys.print(prefix = prefix + '  ')
+            keys.print(prefix=prefix + '  ')
             separator = '\n'
 
     @staticmethod
-    def create_for_device(device_config):
-        if device_config.keystore is None:
-            return None
+    def create_for_device(device: Device) -> KeyStore:
+        if device.config.keystore is None:
+            return MemoryKeyStore()
 
-        keystore_type = device_config.keystore.split(':', 1)[0]
+        keystore_type = device.config.keystore.split(':', 1)[0]
         if keystore_type == 'JsonKeyStore':
-            return JsonKeyStore.from_device_config(device_config)
+            return JsonKeyStore.from_device(device)
 
-        return None
+        return MemoryKeyStore()
 
 
 # -----------------------------------------------------------------------------
 class JsonKeyStore(KeyStore):
-    APP_NAME          = 'Bumble'
-    APP_AUTHOR        = 'Google'
-    KEYS_DIR          = 'Pairing'
+    """
+    KeyStore implementation that is backed by a JSON file.
+
+    This implementation supports storing a hierarchy of key sets in a single file.
+    A key set is a representation of a PairingKeys object. Each key set is stored
+    in a map, with the address of paired peer as the key. Maps are themselves grouped
+    into namespaces, grouping pairing keys by controller addresses.
+    The JSON object model looks like:
+    {
+        "<namespace>": {
+            "peer-address": {
+                "address_type": <n>,
+                "irk" : {
+                    "authenticated": <true/false>,
+                    "value": "hex-encoded-key"
+                },
+                ... other keys ...
+            },
+            ... other peers ...
+        }
+        ... other namespaces ...
+    }
+
+    A namespace is typically the BD_ADDR of a controller, since that is a convenient
+    unique identifier, but it may be something else.
+    A special namespace, called the "default" namespace, is used when instantiating this
+    class without a namespace. With the default namespace, reading from a file will
+    load an existing namespace if there is only one, which may be convenient for reading
+    from a file with a single key set and for which the namespace isn't known. If the
+    file does not include any existing key set, or if there are more than one and none
+    has the default name, a new one will be created with the name "__DEFAULT__".
+    """
+
+    APP_NAME = 'Bumble'
+    APP_AUTHOR = 'Google'
+    KEYS_DIR = 'Pairing'
     DEFAULT_NAMESPACE = '__DEFAULT__'
+    DEFAULT_BASE_NAME = "keys"
 
     def __init__(self, namespace, filename=None):
         self.namespace = namespace if namespace is not None else self.DEFAULT_NAMESPACE
 
         if filename is None:
             # Use a default for the current user
+
+            # Import here because this may not exist on all platforms
+            # pylint: disable=import-outside-toplevel
             import appdirs
+
             self.directory_name = os.path.join(
-                appdirs.user_data_dir(self.APP_NAME, self.APP_AUTHOR),
-                self.KEYS_DIR
+                appdirs.user_data_dir(self.APP_NAME, self.APP_AUTHOR), self.KEYS_DIR
+            )
+            base_name = self.DEFAULT_BASE_NAME if namespace is None else self.namespace
+            json_filename = (
+                f'{base_name}.json'.lower().replace(':', '-').replace('/p', '-p')
             )
-            json_filename = f'{self.namespace}.json'.lower().replace(':', '-')
             self.filename = os.path.join(self.directory_name, json_filename)
         else:
             self.filename = filename
@@ -202,22 +254,46 @@ class JsonKeyStore(KeyStore):
         logger.debug(f'JSON keystore: {self.filename}')
 
     @staticmethod
-    def from_device_config(device_config):
-        params = device_config.keystore.split(':', 1)[1:]
-        namespace = str(device_config.address)
-        if params:
-            filename = params[1]
+    def from_device(device: Device, filename=None) -> Optional[JsonKeyStore]:
+        if not filename:
+            # Extract the filename from the config if there is one
+            if device.config.keystore is not None:
+                params = device.config.keystore.split(':', 1)[1:]
+                if params:
+                    filename = params[0]
+
+        # Use a namespace based on the device address
+        if device.public_address not in (Address.ANY, Address.ANY_RANDOM):
+            namespace = str(device.public_address)
+        elif device.random_address != Address.ANY_RANDOM:
+            namespace = str(device.random_address)
         else:
-            filename = None
+            namespace = JsonKeyStore.DEFAULT_NAMESPACE
 
         return JsonKeyStore(namespace, filename)
 
     async def load(self):
+        # Try to open the file, without failing. If the file does not exist, it
+        # will be created upon saving.
         try:
-            with open(self.filename, 'r') as json_file:
-                return json.load(json_file)
+            with open(self.filename, 'r', encoding='utf-8') as json_file:
+                db = json.load(json_file)
         except FileNotFoundError:
-            return {}
+            db = {}
+
+        # First, look for a namespace match
+        if self.namespace in db:
+            return (db, db[self.namespace])
+
+        # Then, if the namespace is the default namespace, and there's
+        # only one entry in the db, use that
+        if self.namespace == self.DEFAULT_NAMESPACE and len(db) == 1:
+            return next(iter(db.items()))
+
+        # Finally, just create an empty key map for the namespace
+        key_map = {}
+        db[self.namespace] = key_map
+        return (db, key_map)
 
     async def save(self, db):
         # Create the directory if it doesn't exist
@@ -226,48 +302,55 @@ class JsonKeyStore(KeyStore):
 
         # Save to a temporary file
         temp_filename = self.filename + '.tmp'
-        with open(temp_filename, 'w') as output:
+        with open(temp_filename, 'w', encoding='utf-8') as output:
             json.dump(db, output, sort_keys=True, indent=4)
 
         # Atomically replace the previous file
-        os.rename(temp_filename, self.filename)
+        os.replace(temp_filename, self.filename)
 
-    async def delete(self, name):
-        db = await self.load()
-
-        namespace = db.get(self.namespace)
-        if namespace is None:
-            raise KeyError(name)
-
-        del namespace[name]
+    async def delete(self, name: str) -> None:
+        db, key_map = await self.load()
+        del key_map[name]
         await self.save(db)
 
     async def update(self, name, keys):
-        db = await self.load()
-
-        namespace = db.setdefault(self.namespace, {})
-        namespace[name] = keys.to_dict()
-
+        db, key_map = await self.load()
+        key_map.setdefault(name, {}).update(keys.to_dict())
         await self.save(db)
 
     async def get_all(self):
-        db = await self.load()
+        _, key_map = await self.load()
+        return [(name, PairingKeys.from_dict(keys)) for (name, keys) in key_map.items()]
 
-        namespace = db.get(self.namespace)
-        if namespace is None:
-            return []
+    async def delete_all(self):
+        db, key_map = await self.load()
+        key_map.clear()
+        await self.save(db)
 
-        return [(name, PairingKeys.from_dict(keys)) for (name, keys) in namespace.items()]
-
-    async def get(self, name):
-        db = await self.load()
-
-        namespace = db.get(self.namespace)
-        if namespace is None:
+    async def get(self, name: str) -> Optional[PairingKeys]:
+        _, key_map = await self.load()
+        if name not in key_map:
             return None
 
-        keys = namespace.get(name)
-        if keys is None:
-            return None
+        return PairingKeys.from_dict(key_map[name])
 
-        return PairingKeys.from_dict(keys)
+
+# -----------------------------------------------------------------------------
+class MemoryKeyStore(KeyStore):
+    all_keys: Dict[str, PairingKeys]
+
+    def __init__(self) -> None:
+        self.all_keys = {}
+
+    async def delete(self, name: str) -> None:
+        if name in self.all_keys:
+            del self.all_keys[name]
+
+    async def update(self, name: str, keys: PairingKeys) -> None:
+        self.all_keys[name] = keys
+
+    async def get(self, name: str) -> Optional[PairingKeys]:
+        return self.all_keys.get(name)
+
+    async def get_all(self) -> List[Tuple[str, PairingKeys]]:
+        return list(self.all_keys.items())

bumble/link.py

@@ -17,15 +17,17 @@
 # -----------------------------------------------------------------------------
 import logging
 import asyncio
-import websockets
 from functools import partial
-from colors import color
 
+from bumble.core import BT_PERIPHERAL_ROLE, BT_BR_EDR_TRANSPORT, BT_LE_TRANSPORT
+from bumble.colors import color
 from bumble.hci import (
     Address,
     HCI_SUCCESS,
     HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR,
-    HCI_CONNECTION_TIMEOUT_ERROR
+    HCI_CONNECTION_TIMEOUT_ERROR,
+    HCI_PAGE_TIMEOUT_ERROR,
+    HCI_Connection_Complete_Event,
 )
 
 # -----------------------------------------------------------------------------
@@ -47,7 +49,8 @@ def parse_parameters(params_str):
 
 
 # -----------------------------------------------------------------------------
-# TODO: add more support for various LL exchanges (see Vol 6, Part B - 2.4 DATA CHANNEL PDU)
+# TODO: add more support for various LL exchanges
+# (see Vol 6, Part B - 2.4 DATA CHANNEL PDU)
 # -----------------------------------------------------------------------------
 class LocalLink:
     '''
@@ -55,8 +58,13 @@ class LocalLink:
     '''
 
     def __init__(self):
-        self.controllers        = set()
+        self.controllers = set()
         self.pending_connection = None
+        self.pending_classic_connection = None
+
+    ############################################################
+    # Common utils
+    ############################################################
 
     def add_controller(self, controller):
         logger.debug(f'new controller: {controller}')
@@ -71,22 +79,39 @@ class LocalLink:
                 return controller
         return None
 
-    def on_address_changed(self, controller):
-        pass
+    def find_classic_controller(self, address):
+        for controller in self.controllers:
+            if controller.public_address == address:
+                return controller
+        return None
 
     def get_pending_connection(self):
         return self.pending_connection
 
+    ############################################################
+    # LE handlers
+    ############################################################
+
+    def on_address_changed(self, controller):
+        pass
+
     def send_advertising_data(self, sender_address, data):
         # Send the advertising data to all controllers, except the sender
         for controller in self.controllers:
             if controller.random_address != sender_address:
                 controller.on_link_advertising_data(sender_address, data)
 
-    def send_acl_data(self, sender_address, destination_address, data):
+    def send_acl_data(self, sender_controller, destination_address, transport, data):
         # Send the data to the first controller with a matching address
-        if controller := self.find_controller(destination_address):
-            controller.on_link_acl_data(sender_address, data)
+        if transport == BT_LE_TRANSPORT:
+            destination_controller = self.find_controller(destination_address)
+            source_address = sender_controller.random_address
+        elif transport == BT_BR_EDR_TRANSPORT:
+            destination_controller = self.find_classic_controller(destination_address)
+            source_address = sender_controller.public_address
+
+        if destination_controller is not None:
+            destination_controller.on_link_acl_data(source_address, transport, data)
 
     def on_connection_complete(self):
         # Check that we expect this call
@@ -103,23 +128,31 @@ class LocalLink:
             return
 
         # Connect to the first controller with a matching address
-        if peripheral_controller := self.find_controller(le_create_connection_command.peer_address):
-            central_controller.on_link_peripheral_connection_complete(le_create_connection_command, HCI_SUCCESS)
+        if peripheral_controller := self.find_controller(
+            le_create_connection_command.peer_address
+        ):
+            central_controller.on_link_peripheral_connection_complete(
+                le_create_connection_command, HCI_SUCCESS
+            )
             peripheral_controller.on_link_central_connected(central_address)
             return
 
         # No peripheral found
         central_controller.on_link_peripheral_connection_complete(
-            le_create_connection_command,
-            HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR
+            le_create_connection_command, HCI_CONNECTION_ACCEPT_TIMEOUT_ERROR
         )
 
     def connect(self, central_address, le_create_connection_command):
-        logger.debug(f'$$$ CONNECTION {central_address} -> {le_create_connection_command.peer_address}')
+        logger.debug(
+            f'$$$ CONNECTION {central_address} -> '
+            f'{le_create_connection_command.peer_address}'
+        )
         self.pending_connection = (central_address, le_create_connection_command)
         asyncio.get_running_loop().call_soon(self.on_connection_complete)
 
-    def on_disconnection_complete(self, central_address, peripheral_address, disconnect_command):
+    def on_disconnection_complete(
+        self, central_address, peripheral_address, disconnect_command
+    ):
         # Find the controller that initiated the disconnection
         if not (central_controller := self.find_controller(central_address)):
             logger.warning('!!! Initiating controller not found')
@@ -127,16 +160,26 @@ class LocalLink:
 
         # Disconnect from the first controller with a matching address
         if peripheral_controller := self.find_controller(peripheral_address):
-            peripheral_controller.on_link_central_disconnected(central_address, disconnect_command.reason)
+            peripheral_controller.on_link_central_disconnected(
+                central_address, disconnect_command.reason
+            )
 
-        central_controller.on_link_peripheral_disconnection_complete(disconnect_command, HCI_SUCCESS)
+        central_controller.on_link_peripheral_disconnection_complete(
+            disconnect_command, HCI_SUCCESS
+        )
 
     def disconnect(self, central_address, peripheral_address, disconnect_command):
-        logger.debug(f'$$$ DISCONNECTION {central_address} -> {peripheral_address}: reason = {disconnect_command.reason}')
+        logger.debug(
+            f'$$$ DISCONNECTION {central_address} -> '
+            f'{peripheral_address}: reason = {disconnect_command.reason}'
+        )
         args = [central_address, peripheral_address, disconnect_command]
         asyncio.get_running_loop().call_soon(self.on_disconnection_complete, *args)
 
-    def on_connection_encrypted(self, central_address, peripheral_address, rand, ediv, ltk):
+    # pylint: disable=too-many-arguments
+    def on_connection_encrypted(
+        self, central_address, peripheral_address, rand, ediv, ltk
+    ):
         logger.debug(f'*** ENCRYPTION {central_address} -> {peripheral_address}')
 
         if central_controller := self.find_controller(central_address):
@@ -145,6 +188,89 @@ class LocalLink:
         if peripheral_controller := self.find_controller(peripheral_address):
             peripheral_controller.on_link_encrypted(central_address, rand, ediv, ltk)
 
+    ############################################################
+    # Classic handlers
+    ############################################################
+
+    def classic_connect(self, initiator_controller, responder_address):
+        logger.debug(
+            f'[Classic] {initiator_controller.public_address} connects to {responder_address}'
+        )
+        responder_controller = self.find_classic_controller(responder_address)
+        if responder_controller is None:
+            initiator_controller.on_classic_connection_complete(
+                responder_address, HCI_PAGE_TIMEOUT_ERROR
+            )
+            return
+        self.pending_classic_connection = (initiator_controller, responder_controller)
+
+        responder_controller.on_classic_connection_request(
+            initiator_controller.public_address,
+            HCI_Connection_Complete_Event.ACL_LINK_TYPE,
+        )
+
+    def classic_accept_connection(
+        self, responder_controller, initiator_address, responder_role
+    ):
+        logger.debug(
+            f'[Classic] {responder_controller.public_address} accepts to connect {initiator_address}'
+        )
+        initiator_controller = self.find_classic_controller(initiator_address)
+        if initiator_controller is None:
+            responder_controller.on_classic_connection_complete(
+                responder_controller.public_address, HCI_PAGE_TIMEOUT_ERROR
+            )
+            return
+
+        async def task():
+            if responder_role != BT_PERIPHERAL_ROLE:
+                initiator_controller.on_classic_role_change(
+                    responder_controller.public_address, int(not (responder_role))
+                )
+            initiator_controller.on_classic_connection_complete(
+                responder_controller.public_address, HCI_SUCCESS
+            )
+
+        asyncio.create_task(task())
+        responder_controller.on_classic_role_change(
+            initiator_controller.public_address, responder_role
+        )
+        responder_controller.on_classic_connection_complete(
+            initiator_controller.public_address, HCI_SUCCESS
+        )
+        self.pending_classic_connection = None
+
+    def classic_disconnect(self, initiator_controller, responder_address, reason):
+        logger.debug(
+            f'[Classic] {initiator_controller.public_address} disconnects {responder_address}'
+        )
+        responder_controller = self.find_classic_controller(responder_address)
+
+        async def task():
+            initiator_controller.on_classic_disconnected(responder_address, reason)
+
+        asyncio.create_task(task())
+        responder_controller.on_classic_disconnected(
+            initiator_controller.public_address, reason
+        )
+
+    def classic_switch_role(
+        self, initiator_controller, responder_address, initiator_new_role
+    ):
+        responder_controller = self.find_classic_controller(responder_address)
+        if responder_controller is None:
+            return
+
+        async def task():
+            initiator_controller.on_classic_role_change(
+                responder_address, initiator_new_role
+            )
+
+        asyncio.create_task(task())
+        responder_controller.on_classic_role_change(
+            initiator_controller.public_address, int(not (initiator_new_role))
+        )
+
 
 # -----------------------------------------------------------------------------
 class RemoteLink:
@@ -152,15 +278,18 @@ class RemoteLink:
     A Link implementation that communicates with other virtual controllers via a
     WebSocket relay
     '''
+
     def __init__(self, uri):
-        self.controller             = None
-        self.uri                    = uri
-        self.execution_queue        = asyncio.Queue()
-        self.websocket              = asyncio.get_running_loop().create_future()
-        self.rpc_result             = None
-        self.pending_connection     = None
-        self.central_connections    = set()  # List of addresses that we have connected to
-        self.peripheral_connections = set()  # List of addresses that have connected to us
+        self.controller = None
+        self.uri = uri
+        self.execution_queue = asyncio.Queue()
+        self.websocket = asyncio.get_running_loop().create_future()
+        self.rpc_result = None
+        self.pending_connection = None
+        self.central_connections = set()  # List of addresses that we have connected to
+        self.peripheral_connections = (
+            set()
+        )  # List of addresses that have connected to us
 
         # Connect and run asynchronously
         asyncio.create_task(self.run_connection())
@@ -179,6 +308,9 @@ class RemoteLink:
     def get_pending_connection(self):
         return self.pending_connection
 
+    def get_pending_classic_connection(self):
+        return self.pending_classic_connection
+
     async def wait_until_connected(self):
         await self.websocket
 
@@ -192,11 +324,16 @@ class RemoteLink:
             try:
                 await item
             except Exception as error:
-                logger.warning(f'{color("!!! Exception in async handler:", "red")} {error}')
+                logger.warning(
+                    f'{color("!!! Exception in async handler:", "red")} {error}'
+                )
 
     async def run_connection(self):
+        import websockets  # lazy import
+
         # Connect to the relay
         logger.debug(f'connecting to {self.uri}')
+        # pylint: disable-next=no-member
         websocket = await websockets.connect(self.uri)
         self.websocket.set_result(websocket)
         logger.debug(f'connected to {self.uri}')
@@ -227,7 +364,9 @@ class RemoteLink:
             self.central_connections.remove(address)
 
         if address in self.peripheral_connections:
-            self.controller.on_link_central_disconnected(address, HCI_CONNECTION_TIMEOUT_ERROR)
+            self.controller.on_link_central_disconnected(
+                address, HCI_CONNECTION_TIMEOUT_ERROR
+            )
             self.peripheral_connections.remove(address)
 
     async def on_unreachable_received(self, target):
@@ -244,7 +383,9 @@ class RemoteLink:
 
     async def on_advertisement_message_received(self, sender, advertisement):
         try:
-            self.controller.on_link_advertising_data(Address(sender), bytes.fromhex(advertisement))
+            self.controller.on_link_advertising_data(
+                Address(sender), bytes.fromhex(advertisement)
+            )
         except Exception:
             logger.exception('exception')
 
@@ -263,11 +404,11 @@ class RemoteLink:
         self.controller.on_link_central_connected(Address(sender))
 
         # Accept the connection by responding to it
-        await self.send_targetted_message(sender, 'connected')
+        await self.send_targeted_message(sender, 'connected')
 
     async def on_connected_message_received(self, sender, _):
         if not self.pending_connection:
-            logger.warn('received a connection ack, but no connection is pending')
+            logger.warning('received a connection ack, but no connection is pending')
             return
 
         # Remember the connection
@@ -275,7 +416,9 @@ class RemoteLink:
 
         # Notify the controller
         logger.debug(f'connected to peripheral {self.pending_connection.peer_address}')
-        self.controller.on_link_peripheral_connection_complete(self.pending_connection, HCI_SUCCESS)
+        self.controller.on_link_peripheral_connection_complete(
+            self.pending_connection, HCI_SUCCESS
+        )
 
     async def on_disconnect_message_received(self, sender, message):
         # Notify the controller
@@ -287,7 +430,7 @@ class RemoteLink:
         if sender in self.peripheral_connections:
             self.peripheral_connections.remove(sender)
 
-    async def on_encrypted_message_received(self, sender, message):
+    async def on_encrypted_message_received(self, sender, _):
         # TODO parse params to get real args
         self.controller.on_link_encrypted(Address(sender), bytes(8), 0, bytes(16))
 
@@ -296,7 +439,7 @@ class RemoteLink:
         websocket = await self.websocket
 
         # Create a future value to hold the eventual result
-        assert(self.rpc_result is None)
+        assert self.rpc_result is None
         self.rpc_result = asyncio.get_running_loop().create_future()
 
         # Send the command
@@ -309,7 +452,7 @@ class RemoteLink:
 
         # TODO: parse the result
 
-    async def send_targetted_message(self, target, message):
+    async def send_targeted_message(self, target, message):
         # Ensure we have a connection
         websocket = await self.websocket
 
@@ -326,35 +469,62 @@ class RemoteLink:
         self.execute(self.notify_address_changed)
 
     async def send_advertising_data_to_relay(self, data):
-        await self.send_targetted_message('*', f'advertisement:{data.hex()}')
+        await self.send_targeted_message('*', f'advertisement:{data.hex()}')
 
-    def send_advertising_data(self, sender_address, data):
+    def send_advertising_data(self, _, data):
         self.execute(partial(self.send_advertising_data_to_relay, data))
 
     async def send_acl_data_to_relay(self, peer_address, data):
-        await self.send_targetted_message(peer_address, f'acl:{data.hex()}')
+        await self.send_targeted_message(peer_address, f'acl:{data.hex()}')
 
-    def send_acl_data(self, sender_address, peer_address, data):
+    def send_acl_data(self, _, peer_address, _transport, data):
+        # TODO: handle different transport
         self.execute(partial(self.send_acl_data_to_relay, peer_address, data))
 
     async def send_connection_request_to_relay(self, peer_address):
-        await self.send_targetted_message(peer_address, 'connect')
+        await self.send_targeted_message(peer_address, 'connect')
 
-    def connect(self, central_address, le_create_connection_command):
+    def connect(self, _, le_create_connection_command):
         if self.pending_connection:
-            logger.warn('connection already pending')
+            logger.warning('connection already pending')
             return
         self.pending_connection = le_create_connection_command
-        self.execute(partial(self.send_connection_request_to_relay, str(le_create_connection_command.peer_address)))
+        self.execute(
+            partial(
+                self.send_connection_request_to_relay,
+                str(le_create_connection_command.peer_address),
+            )
+        )
 
     def on_disconnection_complete(self, disconnect_command):
-        self.controller.on_link_peripheral_disconnection_complete(disconnect_command, HCI_SUCCESS)
+        self.controller.on_link_peripheral_disconnection_complete(
+            disconnect_command, HCI_SUCCESS
+        )
 
     def disconnect(self, central_address, peripheral_address, disconnect_command):
-        logger.debug(f'disconnect {central_address} -> {peripheral_address}: reason = {disconnect_command.reason}')
-        self.execute(partial(self.send_targetted_message, peripheral_address, f'disconnect:reason={disconnect_command.reason}'))
-        asyncio.get_running_loop().call_soon(self.on_disconnection_complete, disconnect_command)
+        logger.debug(
+            f'disconnect {central_address} -> '
+            f'{peripheral_address}: reason = {disconnect_command.reason}'
+        )
+        self.execute(
+            partial(
+                self.send_targeted_message,
+                peripheral_address,
+                f'disconnect:reason={disconnect_command.reason}',
+            )
+        )
+        asyncio.get_running_loop().call_soon(
+            self.on_disconnection_complete, disconnect_command
+        )
 
-    def on_connection_encrypted(self, central_address, peripheral_address, rand, ediv, ltk):
-        asyncio.get_running_loop().call_soon(self.controller.on_link_encrypted, peripheral_address, rand, ediv, ltk)
-        self.execute(partial(self.send_targetted_message, peripheral_address, f'encrypted:ltk={ltk.hex()}'))
+    def on_connection_encrypted(self, _, peripheral_address, rand, ediv, ltk):
+        asyncio.get_running_loop().call_soon(
+            self.controller.on_link_encrypted, peripheral_address, rand, ediv, ltk
+        )
+        self.execute(
+            partial(
+                self.send_targeted_message,
+                peripheral_address,
+                f'encrypted:ltk={ltk.hex()}',
+            )
+        )

bumble/pairing.py

@@ -0,0 +1,196 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import enum
+from typing import Optional, Tuple
+
+from .hci import (
+    Address,
+    HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
+    HCI_DISPLAY_ONLY_IO_CAPABILITY,
+    HCI_DISPLAY_YES_NO_IO_CAPABILITY,
+    HCI_KEYBOARD_ONLY_IO_CAPABILITY,
+)
+from .smp import (
+    SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
+    SMP_KEYBOARD_ONLY_IO_CAPABILITY,
+    SMP_DISPLAY_ONLY_IO_CAPABILITY,
+    SMP_DISPLAY_YES_NO_IO_CAPABILITY,
+    SMP_KEYBOARD_DISPLAY_IO_CAPABILITY,
+    SMP_ENC_KEY_DISTRIBUTION_FLAG,
+    SMP_ID_KEY_DISTRIBUTION_FLAG,
+    SMP_SIGN_KEY_DISTRIBUTION_FLAG,
+    SMP_LINK_KEY_DISTRIBUTION_FLAG,
+)
+
+
+# -----------------------------------------------------------------------------
+class PairingDelegate:
+    """Abstract base class for Pairing Delegates."""
+
+    # I/O Capabilities.
+    # These are defined abstractly, and can be mapped to specific Classic pairing
+    # and/or SMP constants.
+    class IoCapability(enum.IntEnum):
+        NO_OUTPUT_NO_INPUT = SMP_NO_INPUT_NO_OUTPUT_IO_CAPABILITY
+        KEYBOARD_INPUT_ONLY = SMP_KEYBOARD_ONLY_IO_CAPABILITY
+        DISPLAY_OUTPUT_ONLY = SMP_DISPLAY_ONLY_IO_CAPABILITY
+        DISPLAY_OUTPUT_AND_YES_NO_INPUT = SMP_DISPLAY_YES_NO_IO_CAPABILITY
+        DISPLAY_OUTPUT_AND_KEYBOARD_INPUT = SMP_KEYBOARD_DISPLAY_IO_CAPABILITY
+
+    # Direct names for backward compatibility.
+    NO_OUTPUT_NO_INPUT = IoCapability.NO_OUTPUT_NO_INPUT
+    KEYBOARD_INPUT_ONLY = IoCapability.KEYBOARD_INPUT_ONLY
+    DISPLAY_OUTPUT_ONLY = IoCapability.DISPLAY_OUTPUT_ONLY
+    DISPLAY_OUTPUT_AND_YES_NO_INPUT = IoCapability.DISPLAY_OUTPUT_AND_YES_NO_INPUT
+    DISPLAY_OUTPUT_AND_KEYBOARD_INPUT = IoCapability.DISPLAY_OUTPUT_AND_KEYBOARD_INPUT
+
+    # Key Distribution [LE only]
+    class KeyDistribution(enum.IntFlag):
+        DISTRIBUTE_ENCRYPTION_KEY = SMP_ENC_KEY_DISTRIBUTION_FLAG
+        DISTRIBUTE_IDENTITY_KEY = SMP_ID_KEY_DISTRIBUTION_FLAG
+        DISTRIBUTE_SIGNING_KEY = SMP_SIGN_KEY_DISTRIBUTION_FLAG
+        DISTRIBUTE_LINK_KEY = SMP_LINK_KEY_DISTRIBUTION_FLAG
+
+    DEFAULT_KEY_DISTRIBUTION: KeyDistribution = (
+        KeyDistribution.DISTRIBUTE_ENCRYPTION_KEY
+        | KeyDistribution.DISTRIBUTE_IDENTITY_KEY
+    )
+
+    # Default mapping from abstract to Classic I/O capabilities.
+    # Subclasses may override this if they prefer a different mapping.
+    CLASSIC_IO_CAPABILITIES_MAP = {
+        NO_OUTPUT_NO_INPUT: HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY,
+        KEYBOARD_INPUT_ONLY: HCI_KEYBOARD_ONLY_IO_CAPABILITY,
+        DISPLAY_OUTPUT_ONLY: HCI_DISPLAY_ONLY_IO_CAPABILITY,
+        DISPLAY_OUTPUT_AND_YES_NO_INPUT: HCI_DISPLAY_YES_NO_IO_CAPABILITY,
+        DISPLAY_OUTPUT_AND_KEYBOARD_INPUT: HCI_DISPLAY_YES_NO_IO_CAPABILITY,
+    }
+
+    io_capability: IoCapability
+    local_initiator_key_distribution: KeyDistribution
+    local_responder_key_distribution: KeyDistribution
+
+    def __init__(
+        self,
+        io_capability: IoCapability = NO_OUTPUT_NO_INPUT,
+        local_initiator_key_distribution: KeyDistribution = DEFAULT_KEY_DISTRIBUTION,
+        local_responder_key_distribution: KeyDistribution = DEFAULT_KEY_DISTRIBUTION,
+    ) -> None:
+        self.io_capability = io_capability
+        self.local_initiator_key_distribution = local_initiator_key_distribution
+        self.local_responder_key_distribution = local_responder_key_distribution
+
+    @property
+    def classic_io_capability(self) -> int:
+        """Map the abstract I/O capability to a Classic constant."""
+
+        # pylint: disable=line-too-long
+        return self.CLASSIC_IO_CAPABILITIES_MAP.get(
+            self.io_capability, HCI_NO_INPUT_NO_OUTPUT_IO_CAPABILITY
+        )
+
+    @property
+    def smp_io_capability(self) -> int:
+        """Map the abstract I/O capability to an SMP constant."""
+
+        # This is just a 1-1 direct mapping
+        return self.io_capability
+
+    async def accept(self) -> bool:
+        """Accept or reject a Pairing request."""
+        return True
+
+    async def confirm(self, auto: bool = False) -> bool:
+        """
+        Respond yes or no to a Pairing confirmation question.
+        The `auto` parameter stands for automatic confirmation.
+        """
+        return True
+
+    # pylint: disable-next=unused-argument
+    async def compare_numbers(self, number: int, digits: int) -> bool:
+        """Compare two numbers."""
+        return True
+
+    async def get_number(self) -> Optional[int]:
+        """
+        Return an optional number as an answer to a passkey request.
+        Returning `None` will result in a negative reply.
+        """
+        return 0
+
+    async def get_string(self, max_length: int) -> Optional[str]:
+        """
+        Return a string whose utf-8 encoding is up to max_length bytes.
+        """
+        return None
+
+    # pylint: disable-next=unused-argument
+    async def display_number(self, number: int, digits: int) -> None:
+        """Display a number."""
+
+    # [LE only]
+    async def key_distribution_response(
+        self, peer_initiator_key_distribution: int, peer_responder_key_distribution: int
+    ) -> Tuple[int, int]:
+        """
+        Return the key distribution response in an SMP protocol context.
+
+        NOTE: since it is only used by the SMP protocol, this method's input and output
+        are directly as integers, using the SMP constants, rather than the abstract
+        KeyDistribution enums.
+        """
+        return (
+            int(
+                peer_initiator_key_distribution & self.local_initiator_key_distribution
+            ),
+            int(
+                peer_responder_key_distribution & self.local_responder_key_distribution
+            ),
+        )
+
+
+# -----------------------------------------------------------------------------
+class PairingConfig:
+    """Configuration for the Pairing protocol."""
+
+    class AddressType(enum.IntEnum):
+        PUBLIC = Address.PUBLIC_DEVICE_ADDRESS
+        RANDOM = Address.RANDOM_DEVICE_ADDRESS
+
+    def __init__(
+        self,
+        sc: bool = True,
+        mitm: bool = True,
+        bonding: bool = True,
+        delegate: Optional[PairingDelegate] = None,
+        identity_address_type: Optional[AddressType] = None,
+    ) -> None:
+        self.sc = sc
+        self.mitm = mitm
+        self.bonding = bonding
+        self.delegate = delegate or PairingDelegate()
+        self.identity_address_type = identity_address_type
+
+    def __str__(self) -> str:
+        return (
+            f'PairingConfig(sc={self.sc}, '
+            f'mitm={self.mitm}, bonding={self.bonding}, '
+            f'identity_address_type={self.identity_address_type}, '
+            f'delegate[{self.delegate.io_capability}])'
+        )

bumble/pandora/__init__.py

@@ -0,0 +1,105 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Bumble Pandora server.
+This module implement the Pandora Bluetooth test APIs for the Bumble stack.
+"""
+
+__version__ = "0.0.1"
+
+import grpc
+import grpc.aio
+
+from .config import Config
+from .device import PandoraDevice
+from .host import HostService
+from .security import SecurityService, SecurityStorageService
+from pandora.host_grpc_aio import add_HostServicer_to_server
+from pandora.security_grpc_aio import (
+    add_SecurityServicer_to_server,
+    add_SecurityStorageServicer_to_server,
+)
+from typing import Callable, List, Optional
+
+# public symbols
+__all__ = [
+    'register_servicer_hook',
+    'serve',
+    'Config',
+    'PandoraDevice',
+]
+
+
+# Add servicers hooks.
+_SERVICERS_HOOKS: List[Callable[[PandoraDevice, Config, grpc.aio.Server], None]] = []
+
+
+def register_servicer_hook(
+    hook: Callable[[PandoraDevice, Config, grpc.aio.Server], None]
+) -> None:
+    _SERVICERS_HOOKS.append(hook)
+
+
+async def serve(
+    bumble: PandoraDevice,
+    config: Config = Config(),
+    grpc_server: Optional[grpc.aio.Server] = None,
+    port: int = 0,
+) -> None:
+    # initialize a gRPC server if not provided.
+    server = grpc_server if grpc_server is not None else grpc.aio.server()
+    port = server.add_insecure_port(f'localhost:{port}')
+
+    try:
+        while True:
+            # load server config from dict.
+            config.load_from_dict(bumble.config.get('server', {}))
+
+            # add Pandora services to the gRPC server.
+            add_HostServicer_to_server(
+                HostService(server, bumble.device, config), server
+            )
+            add_SecurityServicer_to_server(
+                SecurityService(bumble.device, config), server
+            )
+            add_SecurityStorageServicer_to_server(
+                SecurityStorageService(bumble.device, config), server
+            )
+
+            # call hooks if any.
+            for hook in _SERVICERS_HOOKS:
+                hook(bumble, config, server)
+
+            # open device.
+            await bumble.open()
+            try:
+                # Pandora require classic devices to be discoverable & connectable.
+                if bumble.device.classic_enabled:
+                    await bumble.device.set_discoverable(True)
+                    await bumble.device.set_connectable(True)
+
+                # start & serve gRPC server.
+                await server.start()
+                await server.wait_for_termination()
+            finally:
+                # close device.
+                await bumble.close()
+
+            # re-initialize the gRPC server.
+            server = grpc.aio.server()
+            server.add_insecure_port(f'localhost:{port}')
+    finally:
+        # stop server.
+        await server.stop(None)

bumble/pandora/config.py

@@ -0,0 +1,55 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from bumble.pairing import PairingConfig, PairingDelegate
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass
+class Config:
+    io_capability: PairingDelegate.IoCapability = PairingDelegate.NO_OUTPUT_NO_INPUT
+    identity_address_type: PairingConfig.AddressType = PairingConfig.AddressType.RANDOM
+    pairing_sc_enable: bool = True
+    pairing_mitm_enable: bool = True
+    pairing_bonding_enable: bool = True
+    smp_local_initiator_key_distribution: PairingDelegate.KeyDistribution = (
+        PairingDelegate.DEFAULT_KEY_DISTRIBUTION
+    )
+    smp_local_responder_key_distribution: PairingDelegate.KeyDistribution = (
+        PairingDelegate.DEFAULT_KEY_DISTRIBUTION
+    )
+
+    def load_from_dict(self, config: Dict[str, Any]) -> None:
+        io_capability_name: str = config.get(
+            'io_capability', 'no_output_no_input'
+        ).upper()
+        self.io_capability = getattr(PairingDelegate, io_capability_name)
+        identity_address_type_name: str = config.get(
+            'identity_address_type', 'random'
+        ).upper()
+        self.identity_address_type = getattr(
+            PairingConfig.AddressType, identity_address_type_name
+        )
+        self.pairing_sc_enable = config.get('pairing_sc_enable', True)
+        self.pairing_mitm_enable = config.get('pairing_mitm_enable', True)
+        self.pairing_bonding_enable = config.get('pairing_bonding_enable', True)
+        self.smp_local_initiator_key_distribution = config.get(
+            'smp_local_initiator_key_distribution',
+            PairingDelegate.DEFAULT_KEY_DISTRIBUTION,
+        )
+        self.smp_local_responder_key_distribution = config.get(
+            'smp_local_responder_key_distribution',
+            PairingDelegate.DEFAULT_KEY_DISTRIBUTION,
+        )

bumble/pandora/device.py

@@ -0,0 +1,163 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Generic & dependency free Bumble (reference) device."""
+
+from bumble import transport
+from bumble.core import (
+    BT_GENERIC_AUDIO_SERVICE,
+    BT_HANDSFREE_SERVICE,
+    BT_L2CAP_PROTOCOL_ID,
+    BT_RFCOMM_PROTOCOL_ID,
+)
+from bumble.device import Device, DeviceConfiguration
+from bumble.host import Host
+from bumble.sdp import (
+    SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+    SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+    DataElement,
+    ServiceAttribute,
+)
+from typing import Any, Dict, List, Optional
+
+
+# Default rootcanal HCI TCP address
+ROOTCANAL_HCI_ADDRESS = "localhost:6402"
+
+
+class PandoraDevice:
+    """
+    Small wrapper around a Bumble device and it's HCI transport.
+    Notes:
+      - The Bumble device is idle by default.
+      - Repetitive calls to `open`/`close` will result on new Bumble device instances.
+    """
+
+    # Bumble device instance & configuration.
+    device: Device
+    config: Dict[str, Any]
+
+    # HCI transport name & instance.
+    _hci_name: str
+    _hci: Optional[transport.Transport]  # type: ignore[name-defined]
+
+    def __init__(self, config: Dict[str, Any]) -> None:
+        self.config = config
+        self.device = _make_device(config)
+        self._hci_name = config.get(
+            'transport', f"tcp-client:{config.get('tcp', ROOTCANAL_HCI_ADDRESS)}"
+        )
+        self._hci = None
+
+    @property
+    def idle(self) -> bool:
+        return self._hci is None
+
+    async def open(self) -> None:
+        if self._hci is not None:
+            return
+
+        # open HCI transport & set device host.
+        self._hci = await transport.open_transport(self._hci_name)
+        self.device.host = Host(controller_source=self._hci.source, controller_sink=self._hci.sink)  # type: ignore[no-untyped-call]
+
+        # power-on.
+        await self.device.power_on()
+
+    async def close(self) -> None:
+        if self._hci is None:
+            return
+
+        # flush & re-initialize device.
+        await self.device.host.flush()
+        self.device.host = None  # type: ignore[assignment]
+        self.device = _make_device(self.config)
+
+        # close HCI transport.
+        await self._hci.close()
+        self._hci = None
+
+    async def reset(self) -> None:
+        await self.close()
+        await self.open()
+
+    def info(self) -> Optional[Dict[str, str]]:
+        return {
+            'public_bd_address': str(self.device.public_address),
+            'random_address': str(self.device.random_address),
+        }
+
+
+def _make_device(config: Dict[str, Any]) -> Device:
+    """Initialize an idle Bumble device instance."""
+
+    # initialize bumble device.
+    device_config = DeviceConfiguration()
+    device_config.load_from_dict(config)
+    device = Device(config=device_config, host=None)
+
+    # Add fake a2dp service to avoid Android disconnect
+    device.sdp_service_records = _make_sdp_records(1)
+
+    return device
+
+
+# TODO(b/267540823): remove when Pandora A2dp is supported
+def _make_sdp_records(rfcomm_channel: int) -> Dict[int, List[ServiceAttribute]]:
+    return {
+        0x00010001: [
+            ServiceAttribute(
+                SDP_SERVICE_RECORD_HANDLE_ATTRIBUTE_ID,
+                DataElement.unsigned_integer_32(0x00010001),
+            ),
+            ServiceAttribute(
+                SDP_SERVICE_CLASS_ID_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.uuid(BT_HANDSFREE_SERVICE),
+                        DataElement.uuid(BT_GENERIC_AUDIO_SERVICE),
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                SDP_PROTOCOL_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence([DataElement.uuid(BT_L2CAP_PROTOCOL_ID)]),
+                        DataElement.sequence(
+                            [
+                                DataElement.uuid(BT_RFCOMM_PROTOCOL_ID),
+                                DataElement.unsigned_integer_8(rfcomm_channel),
+                            ]
+                        ),
+                    ]
+                ),
+            ),
+            ServiceAttribute(
+                SDP_BLUETOOTH_PROFILE_DESCRIPTOR_LIST_ATTRIBUTE_ID,
+                DataElement.sequence(
+                    [
+                        DataElement.sequence(
+                            [
+                                DataElement.uuid(BT_HANDSFREE_SERVICE),
+                                DataElement.unsigned_integer_16(0x0105),
+                            ]
+                        )
+                    ]
+                ),
+            ),
+        ]
+    }

bumble/pandora/host.py

@@ -0,0 +1,857 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import bumble.device
+import grpc
+import grpc.aio
+import logging
+import struct
+
+from . import utils
+from .config import Config
+from bumble.core import (
+    BT_BR_EDR_TRANSPORT,
+    BT_LE_TRANSPORT,
+    BT_PERIPHERAL_ROLE,
+    UUID,
+    AdvertisingData,
+    ConnectionError,
+)
+from bumble.device import (
+    DEVICE_DEFAULT_SCAN_INTERVAL,
+    DEVICE_DEFAULT_SCAN_WINDOW,
+    Advertisement,
+    AdvertisingType,
+    Device,
+)
+from bumble.gatt import Service
+from bumble.hci import (
+    HCI_CONNECTION_ALREADY_EXISTS_ERROR,
+    HCI_PAGE_TIMEOUT_ERROR,
+    HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR,
+    Address,
+)
+from google.protobuf import any_pb2  # pytype: disable=pyi-error
+from google.protobuf import empty_pb2  # pytype: disable=pyi-error
+from pandora.host_grpc_aio import HostServicer
+from pandora.host_pb2 import (
+    NOT_CONNECTABLE,
+    NOT_DISCOVERABLE,
+    PRIMARY_1M,
+    PRIMARY_CODED,
+    SECONDARY_1M,
+    SECONDARY_2M,
+    SECONDARY_CODED,
+    SECONDARY_NONE,
+    AdvertiseRequest,
+    AdvertiseResponse,
+    Connection,
+    ConnectLERequest,
+    ConnectLEResponse,
+    ConnectRequest,
+    ConnectResponse,
+    DataTypes,
+    DisconnectRequest,
+    InquiryResponse,
+    PrimaryPhy,
+    ReadLocalAddressResponse,
+    ScanningResponse,
+    ScanRequest,
+    SecondaryPhy,
+    SetConnectabilityModeRequest,
+    SetDiscoverabilityModeRequest,
+    WaitConnectionRequest,
+    WaitConnectionResponse,
+    WaitDisconnectionRequest,
+)
+from typing import AsyncGenerator, Dict, List, Optional, Set, Tuple, cast
+
+PRIMARY_PHY_MAP: Dict[int, PrimaryPhy] = {
+    # Default value reported by Bumble for legacy Advertising reports.
+    # FIXME(uael): `None` might be a better value, but Bumble need to change accordingly.
+    0: PRIMARY_1M,
+    1: PRIMARY_1M,
+    3: PRIMARY_CODED,
+}
+
+SECONDARY_PHY_MAP: Dict[int, SecondaryPhy] = {
+    0: SECONDARY_NONE,
+    1: SECONDARY_1M,
+    2: SECONDARY_2M,
+    3: SECONDARY_CODED,
+}
+
+
+class HostService(HostServicer):
+    waited_connections: Set[int]
+
+    def __init__(
+        self, grpc_server: grpc.aio.Server, device: Device, config: Config
+    ) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(), {'service_name': 'Host', 'device': device}
+        )
+        self.grpc_server = grpc_server
+        self.device = device
+        self.config = config
+        self.waited_connections = set()
+
+    @utils.rpc
+    async def FactoryReset(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug('FactoryReset')
+
+        # delete all bonds
+        if self.device.keystore is not None:
+            await self.device.keystore.delete_all()
+
+        # trigger gRCP server stop then return
+        asyncio.create_task(self.grpc_server.stop(None))
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def Reset(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug('Reset')
+
+        # clear service.
+        self.waited_connections.clear()
+
+        # (re) power device on
+        await self.device.power_on()
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def ReadLocalAddress(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> ReadLocalAddressResponse:
+        self.log.debug('ReadLocalAddress')
+        return ReadLocalAddressResponse(
+            address=bytes(reversed(bytes(self.device.public_address)))
+        )
+
+    @utils.rpc
+    async def Connect(
+        self, request: ConnectRequest, context: grpc.ServicerContext
+    ) -> ConnectResponse:
+        # Need to reverse bytes order since Bumble Address is using MSB.
+        address = Address(
+            bytes(reversed(request.address)), address_type=Address.PUBLIC_DEVICE_ADDRESS
+        )
+        self.log.debug(f"Connect to {address}")
+
+        try:
+            connection = await self.device.connect(
+                address, transport=BT_BR_EDR_TRANSPORT
+            )
+        except ConnectionError as e:
+            if e.error_code == HCI_PAGE_TIMEOUT_ERROR:
+                self.log.warning(f"Peer not found: {e}")
+                return ConnectResponse(peer_not_found=empty_pb2.Empty())
+            if e.error_code == HCI_CONNECTION_ALREADY_EXISTS_ERROR:
+                self.log.warning(f"Connection already exists: {e}")
+                return ConnectResponse(connection_already_exists=empty_pb2.Empty())
+            raise e
+
+        self.log.debug(f"Connect to {address} done (handle={connection.handle})")
+
+        cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+        return ConnectResponse(connection=Connection(cookie=cookie))
+
+    @utils.rpc
+    async def WaitConnection(
+        self, request: WaitConnectionRequest, context: grpc.ServicerContext
+    ) -> WaitConnectionResponse:
+        if not request.address:
+            raise ValueError('Request address field must be set')
+
+        # Need to reverse bytes order since Bumble Address is using MSB.
+        address = Address(
+            bytes(reversed(request.address)), address_type=Address.PUBLIC_DEVICE_ADDRESS
+        )
+        if address in (Address.NIL, Address.ANY):
+            raise ValueError('Invalid address')
+
+        self.log.debug(f"WaitConnection from {address}...")
+
+        connection = self.device.find_connection_by_bd_addr(
+            address, transport=BT_BR_EDR_TRANSPORT
+        )
+        if connection and id(connection) in self.waited_connections:
+            # this connection was already returned: wait for a new one.
+            connection = None
+
+        if not connection:
+            connection = await self.device.accept(address)
+
+        # save connection has waited and respond.
+        self.waited_connections.add(id(connection))
+
+        self.log.debug(
+            f"WaitConnection from {address} done (handle={connection.handle})"
+        )
+
+        cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+        return WaitConnectionResponse(connection=Connection(cookie=cookie))
+
+    @utils.rpc
+    async def ConnectLE(
+        self, request: ConnectLERequest, context: grpc.ServicerContext
+    ) -> ConnectLEResponse:
+        address = utils.address_from_request(request, request.WhichOneof("address"))
+        if address in (Address.NIL, Address.ANY):
+            raise ValueError('Invalid address')
+
+        self.log.debug(f"ConnectLE to {address}...")
+
+        try:
+            connection = await self.device.connect(
+                address,
+                transport=BT_LE_TRANSPORT,
+                own_address_type=request.own_address_type,
+            )
+        except ConnectionError as e:
+            if e.error_code == HCI_PAGE_TIMEOUT_ERROR:
+                self.log.warning(f"Peer not found: {e}")
+                return ConnectLEResponse(peer_not_found=empty_pb2.Empty())
+            if e.error_code == HCI_CONNECTION_ALREADY_EXISTS_ERROR:
+                self.log.warning(f"Connection already exists: {e}")
+                return ConnectLEResponse(connection_already_exists=empty_pb2.Empty())
+            raise e
+
+        self.log.debug(f"ConnectLE to {address} done (handle={connection.handle})")
+
+        cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+        return ConnectLEResponse(connection=Connection(cookie=cookie))
+
+    @utils.rpc
+    async def Disconnect(
+        self, request: DisconnectRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        self.log.debug(f"Disconnect: {connection_handle}")
+
+        self.log.debug("Disconnecting...")
+        if connection := self.device.lookup_connection(connection_handle):
+            await connection.disconnect(HCI_REMOTE_USER_TERMINATED_CONNECTION_ERROR)
+        self.log.debug("Disconnected")
+
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def WaitDisconnection(
+        self, request: WaitDisconnectionRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        self.log.debug(f"WaitDisconnection: {connection_handle}")
+
+        if connection := self.device.lookup_connection(connection_handle):
+            disconnection_future: asyncio.Future[
+                None
+            ] = asyncio.get_running_loop().create_future()
+
+            def on_disconnection(_: None) -> None:
+                disconnection_future.set_result(None)
+
+            connection.on('disconnection', on_disconnection)
+            try:
+                await disconnection_future
+                self.log.debug("Disconnected")
+            finally:
+                connection.remove_listener('disconnection', on_disconnection)  # type: ignore
+
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def Advertise(
+        self, request: AdvertiseRequest, context: grpc.ServicerContext
+    ) -> AsyncGenerator[AdvertiseResponse, None]:
+        if not request.legacy:
+            raise NotImplementedError(
+                "TODO: add support for extended advertising in Bumble"
+            )
+        if request.interval:
+            raise NotImplementedError("TODO: add support for `request.interval`")
+        if request.interval_range:
+            raise NotImplementedError("TODO: add support for `request.interval_range`")
+        if request.primary_phy:
+            raise NotImplementedError("TODO: add support for `request.primary_phy`")
+        if request.secondary_phy:
+            raise NotImplementedError("TODO: add support for `request.secondary_phy`")
+
+        if self.device.is_advertising:
+            raise NotImplementedError('TODO: add support for advertising sets')
+
+        if data := request.data:
+            self.device.advertising_data = bytes(self.unpack_data_types(data))
+
+            if scan_response_data := request.scan_response_data:
+                self.device.scan_response_data = bytes(
+                    self.unpack_data_types(scan_response_data)
+                )
+                scannable = True
+            else:
+                scannable = False
+
+            # Retrieve services data
+            for service in self.device.gatt_server.attributes:
+                if isinstance(service, Service) and (
+                    service_data := service.get_advertising_data()
+                ):
+                    service_uuid = service.uuid.to_hex_str('-')
+                    if (
+                        service_uuid in request.data.incomplete_service_class_uuids16
+                        or service_uuid in request.data.complete_service_class_uuids16
+                        or service_uuid in request.data.incomplete_service_class_uuids32
+                        or service_uuid in request.data.complete_service_class_uuids32
+                        or service_uuid
+                        in request.data.incomplete_service_class_uuids128
+                        or service_uuid in request.data.complete_service_class_uuids128
+                    ):
+                        self.device.advertising_data += service_data
+                    if (
+                        service_uuid
+                        in scan_response_data.incomplete_service_class_uuids16
+                        or service_uuid
+                        in scan_response_data.complete_service_class_uuids16
+                        or service_uuid
+                        in scan_response_data.incomplete_service_class_uuids32
+                        or service_uuid
+                        in scan_response_data.complete_service_class_uuids32
+                        or service_uuid
+                        in scan_response_data.incomplete_service_class_uuids128
+                        or service_uuid
+                        in scan_response_data.complete_service_class_uuids128
+                    ):
+                        self.device.scan_response_data += service_data
+
+            target = None
+            if request.connectable and scannable:
+                advertising_type = AdvertisingType.UNDIRECTED_CONNECTABLE_SCANNABLE
+            elif scannable:
+                advertising_type = AdvertisingType.UNDIRECTED_SCANNABLE
+            else:
+                advertising_type = AdvertisingType.UNDIRECTED
+        else:
+            target = None
+            advertising_type = AdvertisingType.UNDIRECTED
+
+        if request.target:
+            # Need to reverse bytes order since Bumble Address is using MSB.
+            target_bytes = bytes(reversed(request.target))
+            if request.target_variant() == "public":
+                target = Address(target_bytes, Address.PUBLIC_DEVICE_ADDRESS)
+                advertising_type = (
+                    AdvertisingType.DIRECTED_CONNECTABLE_HIGH_DUTY
+                )  # FIXME: HIGH_DUTY ?
+            else:
+                target = Address(target_bytes, Address.RANDOM_DEVICE_ADDRESS)
+                advertising_type = (
+                    AdvertisingType.DIRECTED_CONNECTABLE_HIGH_DUTY
+                )  # FIXME: HIGH_DUTY ?
+
+        if request.connectable:
+
+            def on_connection(connection: bumble.device.Connection) -> None:
+                if (
+                    connection.transport == BT_LE_TRANSPORT
+                    and connection.role == BT_PERIPHERAL_ROLE
+                ):
+                    pending_connection.set_result(connection)
+
+            self.device.on('connection', on_connection)
+
+        try:
+            while True:
+                if not self.device.is_advertising:
+                    self.log.debug('Advertise')
+                    await self.device.start_advertising(
+                        target=target,
+                        advertising_type=advertising_type,
+                        own_address_type=request.own_address_type,
+                    )
+
+                if not request.connectable:
+                    await asyncio.sleep(1)
+                    continue
+
+                pending_connection: asyncio.Future[
+                    bumble.device.Connection
+                ] = asyncio.get_running_loop().create_future()
+
+                self.log.debug('Wait for LE connection...')
+                connection = await pending_connection
+
+                self.log.debug(
+                    f"Advertise: Connected to {connection.peer_address} (handle={connection.handle})"
+                )
+
+                cookie = any_pb2.Any(value=connection.handle.to_bytes(4, 'big'))
+                yield AdvertiseResponse(connection=Connection(cookie=cookie))
+
+                # wait a small delay before restarting the advertisement.
+                await asyncio.sleep(1)
+        finally:
+            if request.connectable:
+                self.device.remove_listener('connection', on_connection)  # type: ignore
+
+            try:
+                self.log.debug('Stop advertising')
+                await self.device.abort_on('flush', self.device.stop_advertising())
+            except:
+                pass
+
+    @utils.rpc
+    async def Scan(
+        self, request: ScanRequest, context: grpc.ServicerContext
+    ) -> AsyncGenerator[ScanningResponse, None]:
+        # TODO: modify `start_scanning` to accept floats instead of int for ms values
+        if request.phys:
+            raise NotImplementedError("TODO: add support for `request.phys`")
+
+        self.log.debug('Scan')
+
+        scan_queue: asyncio.Queue[Advertisement] = asyncio.Queue()
+        handler = self.device.on('advertisement', scan_queue.put_nowait)
+        await self.device.start_scanning(
+            legacy=request.legacy,
+            active=not request.passive,
+            own_address_type=request.own_address_type,
+            scan_interval=int(request.interval)
+            if request.interval
+            else DEVICE_DEFAULT_SCAN_INTERVAL,
+            scan_window=int(request.window)
+            if request.window
+            else DEVICE_DEFAULT_SCAN_WINDOW,
+        )
+
+        try:
+            # TODO: add support for `direct_address` in Bumble
+            # TODO: add support for `periodic_advertising_interval` in Bumble
+            while adv := await scan_queue.get():
+                sr = ScanningResponse(
+                    legacy=adv.is_legacy,
+                    connectable=adv.is_connectable,
+                    scannable=adv.is_scannable,
+                    truncated=adv.is_truncated,
+                    sid=adv.sid,
+                    primary_phy=PRIMARY_PHY_MAP[adv.primary_phy],
+                    secondary_phy=SECONDARY_PHY_MAP[adv.secondary_phy],
+                    tx_power=adv.tx_power,
+                    rssi=adv.rssi,
+                    data=self.pack_data_types(adv.data),
+                )
+
+                if adv.address.address_type == Address.PUBLIC_DEVICE_ADDRESS:
+                    sr.public = bytes(reversed(bytes(adv.address)))
+                elif adv.address.address_type == Address.RANDOM_DEVICE_ADDRESS:
+                    sr.random = bytes(reversed(bytes(adv.address)))
+                elif adv.address.address_type == Address.PUBLIC_IDENTITY_ADDRESS:
+                    sr.public_identity = bytes(reversed(bytes(adv.address)))
+                else:
+                    sr.random_static_identity = bytes(reversed(bytes(adv.address)))
+
+                yield sr
+
+        finally:
+            self.device.remove_listener('advertisement', handler)  # type: ignore
+            try:
+                self.log.debug('Stop scanning')
+                await self.device.abort_on('flush', self.device.stop_scanning())
+            except:
+                pass
+
+    @utils.rpc
+    async def Inquiry(
+        self, request: empty_pb2.Empty, context: grpc.ServicerContext
+    ) -> AsyncGenerator[InquiryResponse, None]:
+        self.log.debug('Inquiry')
+
+        inquiry_queue: asyncio.Queue[
+            Optional[Tuple[Address, int, AdvertisingData, int]]
+        ] = asyncio.Queue()
+        complete_handler = self.device.on(
+            'inquiry_complete', lambda: inquiry_queue.put_nowait(None)
+        )
+        result_handler = self.device.on(  # type: ignore
+            'inquiry_result',
+            lambda address, class_of_device, eir_data, rssi: inquiry_queue.put_nowait(  # type: ignore
+                (address, class_of_device, eir_data, rssi)  # type: ignore
+            ),
+        )
+
+        await self.device.start_discovery(auto_restart=False)
+        try:
+            while inquiry_result := await inquiry_queue.get():
+                (address, class_of_device, eir_data, rssi) = inquiry_result
+                # FIXME: if needed, add support for `page_scan_repetition_mode` and `clock_offset` in Bumble
+                yield InquiryResponse(
+                    address=bytes(reversed(bytes(address))),
+                    class_of_device=class_of_device,
+                    rssi=rssi,
+                    data=self.pack_data_types(eir_data),
+                )
+
+        finally:
+            self.device.remove_listener('inquiry_complete', complete_handler)  # type: ignore
+            self.device.remove_listener('inquiry_result', result_handler)  # type: ignore
+            try:
+                self.log.debug('Stop inquiry')
+                await self.device.abort_on('flush', self.device.stop_discovery())
+            except:
+                pass
+
+    @utils.rpc
+    async def SetDiscoverabilityMode(
+        self, request: SetDiscoverabilityModeRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug("SetDiscoverabilityMode")
+        await self.device.set_discoverable(request.mode != NOT_DISCOVERABLE)
+        return empty_pb2.Empty()
+
+    @utils.rpc
+    async def SetConnectabilityMode(
+        self, request: SetConnectabilityModeRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        self.log.debug("SetConnectabilityMode")
+        await self.device.set_connectable(request.mode != NOT_CONNECTABLE)
+        return empty_pb2.Empty()
+
+    def unpack_data_types(self, dt: DataTypes) -> AdvertisingData:
+        ad_structures: List[Tuple[int, bytes]] = []
+
+        uuids: List[str]
+        datas: Dict[str, bytes]
+
+        def uuid128_from_str(uuid: str) -> bytes:
+            """Decode a 128-bit uuid encoded as XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
+            to byte format."""
+            return bytes(reversed(bytes.fromhex(uuid.replace('-', ''))))
+
+        def uuid32_from_str(uuid: str) -> bytes:
+            """Decode a 32-bit uuid encoded as XXXXXXXX to byte format."""
+            return bytes(reversed(bytes.fromhex(uuid)))
+
+        def uuid16_from_str(uuid: str) -> bytes:
+            """Decode a 16-bit uuid encoded as XXXX to byte format."""
+            return bytes(reversed(bytes.fromhex(uuid)))
+
+        if uuids := dt.incomplete_service_class_uuids16:
+            ad_structures.append(
+                (
+                    AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid16_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.complete_service_class_uuids16:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid16_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.incomplete_service_class_uuids32:
+            ad_structures.append(
+                (
+                    AdvertisingData.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid32_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.complete_service_class_uuids32:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid32_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.incomplete_service_class_uuids128:
+            ad_structures.append(
+                (
+                    AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid128_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.complete_service_class_uuids128:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS,
+                    b''.join([uuid128_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if dt.HasField('include_shortened_local_name'):
+            ad_structures.append(
+                (
+                    AdvertisingData.SHORTENED_LOCAL_NAME,
+                    bytes(self.device.name[:8], 'utf-8'),
+                )
+            )
+        elif dt.shortened_local_name:
+            ad_structures.append(
+                (
+                    AdvertisingData.SHORTENED_LOCAL_NAME,
+                    bytes(dt.shortened_local_name, 'utf-8'),
+                )
+            )
+        if dt.HasField('include_complete_local_name'):
+            ad_structures.append(
+                (AdvertisingData.COMPLETE_LOCAL_NAME, bytes(self.device.name, 'utf-8'))
+            )
+        elif dt.complete_local_name:
+            ad_structures.append(
+                (
+                    AdvertisingData.COMPLETE_LOCAL_NAME,
+                    bytes(dt.complete_local_name, 'utf-8'),
+                )
+            )
+        if dt.HasField('include_tx_power_level'):
+            raise ValueError('unsupported data type')
+        elif dt.tx_power_level:
+            ad_structures.append(
+                (
+                    AdvertisingData.TX_POWER_LEVEL,
+                    bytes(struct.pack('<I', dt.tx_power_level)[:1]),
+                )
+            )
+        if dt.HasField('include_class_of_device'):
+            ad_structures.append(
+                (
+                    AdvertisingData.CLASS_OF_DEVICE,
+                    bytes(struct.pack('<I', self.device.class_of_device)[:-1]),
+                )
+            )
+        elif dt.class_of_device:
+            ad_structures.append(
+                (
+                    AdvertisingData.CLASS_OF_DEVICE,
+                    bytes(struct.pack('<I', dt.class_of_device)[:-1]),
+                )
+            )
+        if dt.peripheral_connection_interval_min:
+            ad_structures.append(
+                (
+                    AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE,
+                    bytes(
+                        [
+                            *struct.pack('<H', dt.peripheral_connection_interval_min),
+                            *struct.pack(
+                                '<H',
+                                dt.peripheral_connection_interval_max
+                                if dt.peripheral_connection_interval_max
+                                else dt.peripheral_connection_interval_min,
+                            ),
+                        ]
+                    ),
+                )
+            )
+        if uuids := dt.service_solicitation_uuids16:
+            ad_structures.append(
+                (
+                    AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS,
+                    b''.join([uuid16_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.service_solicitation_uuids32:
+            ad_structures.append(
+                (
+                    AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS,
+                    b''.join([uuid32_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if uuids := dt.service_solicitation_uuids128:
+            ad_structures.append(
+                (
+                    AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS,
+                    b''.join([uuid128_from_str(uuid) for uuid in uuids]),
+                )
+            )
+        if datas := dt.service_data_uuid16:
+            ad_structures.extend(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_16_BIT_UUID,
+                        uuid16_from_str(uuid) + data,
+                    )
+                    for uuid, data in datas.items()
+                ]
+            )
+        if datas := dt.service_data_uuid32:
+            ad_structures.extend(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_32_BIT_UUID,
+                        uuid32_from_str(uuid) + data,
+                    )
+                    for uuid, data in datas.items()
+                ]
+            )
+        if datas := dt.service_data_uuid128:
+            ad_structures.extend(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_128_BIT_UUID,
+                        uuid128_from_str(uuid) + data,
+                    )
+                    for uuid, data in datas.items()
+                ]
+            )
+        if dt.appearance:
+            ad_structures.append(
+                (AdvertisingData.APPEARANCE, struct.pack('<H', dt.appearance))
+            )
+        if dt.advertising_interval:
+            ad_structures.append(
+                (
+                    AdvertisingData.ADVERTISING_INTERVAL,
+                    struct.pack('<H', dt.advertising_interval),
+                )
+            )
+        if dt.uri:
+            ad_structures.append((AdvertisingData.URI, bytes(dt.uri, 'utf-8')))
+        if dt.le_supported_features:
+            ad_structures.append(
+                (AdvertisingData.LE_SUPPORTED_FEATURES, dt.le_supported_features)
+            )
+        if dt.manufacturer_specific_data:
+            ad_structures.append(
+                (
+                    AdvertisingData.MANUFACTURER_SPECIFIC_DATA,
+                    dt.manufacturer_specific_data,
+                )
+            )
+
+        return AdvertisingData(ad_structures)
+
+    def pack_data_types(self, ad: AdvertisingData) -> DataTypes:
+        dt = DataTypes()
+        uuids: List[UUID]
+        s: str
+        i: int
+        ij: Tuple[int, int]
+        uuid_data: Tuple[UUID, bytes]
+        data: bytes
+
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.incomplete_service_class_uuids16.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.COMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.complete_service_class_uuids16.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.INCOMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.incomplete_service_class_uuids32.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.COMPLETE_LIST_OF_32_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.complete_service_class_uuids32.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.INCOMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.incomplete_service_class_uuids128.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.COMPLETE_LIST_OF_128_BIT_SERVICE_CLASS_UUIDS),
+        ):
+            dt.complete_service_class_uuids128.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if s := cast(str, ad.get(AdvertisingData.SHORTENED_LOCAL_NAME)):
+            dt.shortened_local_name = s
+        if s := cast(str, ad.get(AdvertisingData.COMPLETE_LOCAL_NAME)):
+            dt.complete_local_name = s
+        if i := cast(int, ad.get(AdvertisingData.TX_POWER_LEVEL)):
+            dt.tx_power_level = i
+        if i := cast(int, ad.get(AdvertisingData.CLASS_OF_DEVICE)):
+            dt.class_of_device = i
+        if ij := cast(
+            Tuple[int, int],
+            ad.get(AdvertisingData.PERIPHERAL_CONNECTION_INTERVAL_RANGE),
+        ):
+            dt.peripheral_connection_interval_min = ij[0]
+            dt.peripheral_connection_interval_max = ij[1]
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.LIST_OF_16_BIT_SERVICE_SOLICITATION_UUIDS),
+        ):
+            dt.service_solicitation_uuids16.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.LIST_OF_32_BIT_SERVICE_SOLICITATION_UUIDS),
+        ):
+            dt.service_solicitation_uuids32.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuids := cast(
+            List[UUID],
+            ad.get(AdvertisingData.LIST_OF_128_BIT_SERVICE_SOLICITATION_UUIDS),
+        ):
+            dt.service_solicitation_uuids128.extend(
+                list(map(lambda x: x.to_hex_str('-'), uuids))
+            )
+        if uuid_data := cast(
+            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_16_BIT_UUID)
+        ):
+            dt.service_data_uuid16[uuid_data[0].to_hex_str('-')] = uuid_data[1]
+        if uuid_data := cast(
+            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_32_BIT_UUID)
+        ):
+            dt.service_data_uuid32[uuid_data[0].to_hex_str('-')] = uuid_data[1]
+        if uuid_data := cast(
+            Tuple[UUID, bytes], ad.get(AdvertisingData.SERVICE_DATA_128_BIT_UUID)
+        ):
+            dt.service_data_uuid128[uuid_data[0].to_hex_str('-')] = uuid_data[1]
+        if data := cast(bytes, ad.get(AdvertisingData.PUBLIC_TARGET_ADDRESS, raw=True)):
+            dt.public_target_addresses.extend(
+                [data[i * 6 :: i * 6 + 6] for i in range(int(len(data) / 6))]
+            )
+        if data := cast(bytes, ad.get(AdvertisingData.RANDOM_TARGET_ADDRESS, raw=True)):
+            dt.random_target_addresses.extend(
+                [data[i * 6 :: i * 6 + 6] for i in range(int(len(data) / 6))]
+            )
+        if i := cast(int, ad.get(AdvertisingData.APPEARANCE)):
+            dt.appearance = i
+        if i := cast(int, ad.get(AdvertisingData.ADVERTISING_INTERVAL)):
+            dt.advertising_interval = i
+        if s := cast(str, ad.get(AdvertisingData.URI)):
+            dt.uri = s
+        if data := cast(bytes, ad.get(AdvertisingData.LE_SUPPORTED_FEATURES, raw=True)):
+            dt.le_supported_features = data
+        if data := cast(
+            bytes, ad.get(AdvertisingData.MANUFACTURER_SPECIFIC_DATA, raw=True)
+        ):
+            dt.manufacturer_specific_data = data
+
+        return dt

bumble/pandora/security.py

@@ -0,0 +1,529 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import grpc
+import logging
+
+from . import utils
+from .config import Config
+from bumble import hci
+from bumble.core import (
+    BT_BR_EDR_TRANSPORT,
+    BT_LE_TRANSPORT,
+    BT_PERIPHERAL_ROLE,
+    ProtocolError,
+)
+from bumble.device import Connection as BumbleConnection, Device
+from bumble.hci import HCI_Error
+from bumble.pairing import PairingConfig, PairingDelegate as BasePairingDelegate
+from contextlib import suppress
+from google.protobuf import any_pb2  # pytype: disable=pyi-error
+from google.protobuf import empty_pb2  # pytype: disable=pyi-error
+from google.protobuf import wrappers_pb2  # pytype: disable=pyi-error
+from pandora.host_pb2 import Connection
+from pandora.security_grpc_aio import SecurityServicer, SecurityStorageServicer
+from pandora.security_pb2 import (
+    LE_LEVEL1,
+    LE_LEVEL2,
+    LE_LEVEL3,
+    LE_LEVEL4,
+    LEVEL0,
+    LEVEL1,
+    LEVEL2,
+    LEVEL3,
+    LEVEL4,
+    DeleteBondRequest,
+    IsBondedRequest,
+    LESecurityLevel,
+    PairingEvent,
+    PairingEventAnswer,
+    SecureRequest,
+    SecureResponse,
+    SecurityLevel,
+    WaitSecurityRequest,
+    WaitSecurityResponse,
+)
+from typing import Any, AsyncGenerator, AsyncIterator, Callable, Dict, Optional, Union
+
+
+class PairingDelegate(BasePairingDelegate):
+    def __init__(
+        self,
+        connection: BumbleConnection,
+        service: "SecurityService",
+        io_capability: BasePairingDelegate.IoCapability = BasePairingDelegate.NO_OUTPUT_NO_INPUT,
+        local_initiator_key_distribution: BasePairingDelegate.KeyDistribution = BasePairingDelegate.DEFAULT_KEY_DISTRIBUTION,
+        local_responder_key_distribution: BasePairingDelegate.KeyDistribution = BasePairingDelegate.DEFAULT_KEY_DISTRIBUTION,
+    ) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(),
+            {'service_name': 'Security', 'device': connection.device},
+        )
+        self.connection = connection
+        self.service = service
+        super().__init__(
+            io_capability,
+            local_initiator_key_distribution,
+            local_responder_key_distribution,
+        )
+
+    async def accept(self) -> bool:
+        return True
+
+    def add_origin(self, ev: PairingEvent) -> PairingEvent:
+        if not self.connection.is_incomplete:
+            assert ev.connection
+            ev.connection.CopyFrom(
+                Connection(
+                    cookie=any_pb2.Any(value=self.connection.handle.to_bytes(4, 'big'))
+                )
+            )
+        else:
+            # In BR/EDR, connection may not be complete,
+            # use address instead
+            assert self.connection.transport == BT_BR_EDR_TRANSPORT
+            ev.address = bytes(reversed(bytes(self.connection.peer_address)))
+
+        return ev
+
+    async def confirm(self, auto: bool = False) -> bool:
+        self.log.debug(
+            f"Pairing event: `just_works` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            return True
+
+        event = self.add_origin(PairingEvent(just_works=empty_pb2.Empty()))
+        self.service.event_queue.put_nowait(event)
+        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        assert answer.event == event
+        assert answer.answer_variant() == 'confirm' and answer.confirm is not None
+        return answer.confirm
+
+    async def compare_numbers(self, number: int, digits: int = 6) -> bool:
+        self.log.debug(
+            f"Pairing event: `numeric_comparison` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            raise RuntimeError('security: unhandled number comparison request')
+
+        event = self.add_origin(PairingEvent(numeric_comparison=number))
+        self.service.event_queue.put_nowait(event)
+        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        assert answer.event == event
+        assert answer.answer_variant() == 'confirm' and answer.confirm is not None
+        return answer.confirm
+
+    async def get_number(self) -> Optional[int]:
+        self.log.debug(
+            f"Pairing event: `passkey_entry_request` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            raise RuntimeError('security: unhandled number request')
+
+        event = self.add_origin(PairingEvent(passkey_entry_request=empty_pb2.Empty()))
+        self.service.event_queue.put_nowait(event)
+        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        assert answer.event == event
+        if answer.answer_variant() is None:
+            return None
+        assert answer.answer_variant() == 'passkey'
+        return answer.passkey
+
+    async def get_string(self, max_length: int) -> Optional[str]:
+        self.log.debug(
+            f"Pairing event: `pin_code_request` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None or self.service.event_answer is None:
+            raise RuntimeError('security: unhandled pin_code request')
+
+        event = self.add_origin(PairingEvent(pin_code_request=empty_pb2.Empty()))
+        self.service.event_queue.put_nowait(event)
+        answer = await anext(self.service.event_answer)  # pytype: disable=name-error
+        assert answer.event == event
+        if answer.answer_variant() is None:
+            return None
+        assert answer.answer_variant() == 'pin'
+
+        if answer.pin is None:
+            return None
+
+        pin = answer.pin.decode('utf-8')
+        if not pin or len(pin) > max_length:
+            raise ValueError(f'Pin must be utf-8 encoded up to {max_length} bytes')
+
+        return pin
+
+    async def display_number(self, number: int, digits: int = 6) -> None:
+        if (
+            self.connection.transport == BT_BR_EDR_TRANSPORT
+            and self.io_capability == BasePairingDelegate.DISPLAY_OUTPUT_ONLY
+        ):
+            return
+
+        self.log.debug(
+            f"Pairing event: `passkey_entry_notification` (io_capability: {self.io_capability})"
+        )
+
+        if self.service.event_queue is None:
+            raise RuntimeError('security: unhandled number display request')
+
+        event = self.add_origin(PairingEvent(passkey_entry_notification=number))
+        self.service.event_queue.put_nowait(event)
+
+
+BR_LEVEL_REACHED: Dict[SecurityLevel, Callable[[BumbleConnection], bool]] = {
+    LEVEL0: lambda connection: True,
+    LEVEL1: lambda connection: connection.encryption == 0 or connection.authenticated,
+    LEVEL2: lambda connection: connection.encryption != 0 and connection.authenticated,
+    LEVEL3: lambda connection: connection.encryption != 0
+    and connection.authenticated
+    and connection.link_key_type
+    in (
+        hci.HCI_AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_192_TYPE,
+        hci.HCI_AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_256_TYPE,
+    ),
+    LEVEL4: lambda connection: connection.encryption
+    == hci.HCI_Encryption_Change_Event.AES_CCM
+    and connection.authenticated
+    and connection.link_key_type
+    == hci.HCI_AUTHENTICATED_COMBINATION_KEY_GENERATED_FROM_P_256_TYPE,
+}
+
+LE_LEVEL_REACHED: Dict[LESecurityLevel, Callable[[BumbleConnection], bool]] = {
+    LE_LEVEL1: lambda connection: True,
+    LE_LEVEL2: lambda connection: connection.encryption != 0,
+    LE_LEVEL3: lambda connection: connection.encryption != 0
+    and connection.authenticated,
+    LE_LEVEL4: lambda connection: connection.encryption != 0
+    and connection.authenticated
+    and connection.sc,
+}
+
+
+class SecurityService(SecurityServicer):
+    def __init__(self, device: Device, config: Config) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(), {'service_name': 'Security', 'device': device}
+        )
+        self.event_queue: Optional[asyncio.Queue[PairingEvent]] = None
+        self.event_answer: Optional[AsyncIterator[PairingEventAnswer]] = None
+        self.device = device
+        self.config = config
+
+        def pairing_config_factory(connection: BumbleConnection) -> PairingConfig:
+            return PairingConfig(
+                sc=config.pairing_sc_enable,
+                mitm=config.pairing_mitm_enable,
+                bonding=config.pairing_bonding_enable,
+                identity_address_type=config.identity_address_type,
+                delegate=PairingDelegate(
+                    connection,
+                    self,
+                    io_capability=config.io_capability,
+                    local_initiator_key_distribution=config.smp_local_initiator_key_distribution,
+                    local_responder_key_distribution=config.smp_local_responder_key_distribution,
+                ),
+            )
+
+        self.device.pairing_config_factory = pairing_config_factory
+
+    @utils.rpc
+    async def OnPairing(
+        self, request: AsyncIterator[PairingEventAnswer], context: grpc.ServicerContext
+    ) -> AsyncGenerator[PairingEvent, None]:
+        self.log.debug('OnPairing')
+
+        if self.event_queue is not None:
+            raise RuntimeError('already streaming pairing events')
+
+        if len(self.device.connections):
+            raise RuntimeError(
+                'the `OnPairing` method shall be initiated before establishing any connections.'
+            )
+
+        self.event_queue = asyncio.Queue()
+        self.event_answer = request
+
+        try:
+            while event := await self.event_queue.get():
+                yield event
+
+        finally:
+            self.event_queue = None
+            self.event_answer = None
+
+    @utils.rpc
+    async def Secure(
+        self, request: SecureRequest, context: grpc.ServicerContext
+    ) -> SecureResponse:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        self.log.debug(f"Secure: {connection_handle}")
+
+        connection = self.device.lookup_connection(connection_handle)
+        assert connection
+
+        oneof = request.WhichOneof('level')
+        level = getattr(request, oneof)
+        assert {BT_BR_EDR_TRANSPORT: 'classic', BT_LE_TRANSPORT: 'le'}[
+            connection.transport
+        ] == oneof
+
+        # security level already reached
+        if self.reached_security_level(connection, level):
+            return SecureResponse(success=empty_pb2.Empty())
+
+        # trigger pairing if needed
+        if self.need_pairing(connection, level):
+            try:
+                self.log.debug('Pair...')
+
+                if (
+                    connection.transport == BT_LE_TRANSPORT
+                    and connection.role == BT_PERIPHERAL_ROLE
+                ):
+                    wait_for_security: asyncio.Future[
+                        bool
+                    ] = asyncio.get_running_loop().create_future()
+                    connection.on("pairing", lambda *_: wait_for_security.set_result(True))  # type: ignore
+                    connection.on("pairing_failure", wait_for_security.set_exception)
+
+                    connection.request_pairing()
+
+                    await wait_for_security
+                else:
+                    await connection.pair()
+
+                self.log.debug('Paired')
+            except asyncio.CancelledError:
+                self.log.warning("Connection died during encryption")
+                return SecureResponse(connection_died=empty_pb2.Empty())
+            except (HCI_Error, ProtocolError) as e:
+                self.log.warning(f"Pairing failure: {e}")
+                return SecureResponse(pairing_failure=empty_pb2.Empty())
+
+        # trigger authentication if needed
+        if self.need_authentication(connection, level):
+            try:
+                self.log.debug('Authenticate...')
+                await connection.authenticate()
+                self.log.debug('Authenticated')
+            except asyncio.CancelledError:
+                self.log.warning("Connection died during authentication")
+                return SecureResponse(connection_died=empty_pb2.Empty())
+            except (HCI_Error, ProtocolError) as e:
+                self.log.warning(f"Authentication failure: {e}")
+                return SecureResponse(authentication_failure=empty_pb2.Empty())
+
+        # trigger encryption if needed
+        if self.need_encryption(connection, level):
+            try:
+                self.log.debug('Encrypt...')
+                await connection.encrypt()
+                self.log.debug('Encrypted')
+            except asyncio.CancelledError:
+                self.log.warning("Connection died during encryption")
+                return SecureResponse(connection_died=empty_pb2.Empty())
+            except (HCI_Error, ProtocolError) as e:
+                self.log.warning(f"Encryption failure: {e}")
+                return SecureResponse(encryption_failure=empty_pb2.Empty())
+
+        # security level has been reached ?
+        if self.reached_security_level(connection, level):
+            return SecureResponse(success=empty_pb2.Empty())
+        return SecureResponse(not_reached=empty_pb2.Empty())
+
+    @utils.rpc
+    async def WaitSecurity(
+        self, request: WaitSecurityRequest, context: grpc.ServicerContext
+    ) -> WaitSecurityResponse:
+        connection_handle = int.from_bytes(request.connection.cookie.value, 'big')
+        self.log.debug(f"WaitSecurity: {connection_handle}")
+
+        connection = self.device.lookup_connection(connection_handle)
+        assert connection
+
+        assert request.level
+        level = request.level
+        assert {BT_BR_EDR_TRANSPORT: 'classic', BT_LE_TRANSPORT: 'le'}[
+            connection.transport
+        ] == request.level_variant()
+
+        wait_for_security: asyncio.Future[
+            str
+        ] = asyncio.get_running_loop().create_future()
+        authenticate_task: Optional[asyncio.Future[None]] = None
+
+        async def authenticate() -> None:
+            assert connection
+            if (encryption := connection.encryption) != 0:
+                self.log.debug('Disable encryption...')
+                try:
+                    await connection.encrypt(enable=False)
+                except:
+                    pass
+                self.log.debug('Disable encryption: done')
+
+            self.log.debug('Authenticate...')
+            await connection.authenticate()
+            self.log.debug('Authenticate: done')
+
+            if encryption != 0 and connection.encryption != encryption:
+                self.log.debug('Re-enable encryption...')
+                await connection.encrypt()
+                self.log.debug('Re-enable encryption: done')
+
+        def set_failure(name: str) -> Callable[..., None]:
+            def wrapper(*args: Any) -> None:
+                self.log.debug(f'Wait for security: error `{name}`: {args}')
+                wait_for_security.set_result(name)
+
+            return wrapper
+
+        def try_set_success(*_: Any) -> None:
+            assert connection
+            if self.reached_security_level(connection, level):
+                self.log.debug('Wait for security: done')
+                wait_for_security.set_result('success')
+
+        def on_encryption_change(*_: Any) -> None:
+            assert connection
+            if self.reached_security_level(connection, level):
+                self.log.debug('Wait for security: done')
+                wait_for_security.set_result('success')
+            elif (
+                connection.transport == BT_BR_EDR_TRANSPORT
+                and self.need_authentication(connection, level)
+            ):
+                nonlocal authenticate_task
+                if authenticate_task is None:
+                    authenticate_task = asyncio.create_task(authenticate())
+
+        listeners: Dict[str, Callable[..., None]] = {
+            'disconnection': set_failure('connection_died'),
+            'pairing_failure': set_failure('pairing_failure'),
+            'connection_authentication_failure': set_failure('authentication_failure'),
+            'connection_encryption_failure': set_failure('encryption_failure'),
+            'pairing': try_set_success,
+            'connection_authentication': try_set_success,
+            'connection_encryption_change': on_encryption_change,
+            'classic_pairing': try_set_success,
+            'classic_pairing_failure': set_failure('pairing_failure'),
+        }
+
+        # register event handlers
+        for event, listener in listeners.items():
+            connection.on(event, listener)
+
+        # security level already reached
+        if self.reached_security_level(connection, level):
+            return WaitSecurityResponse(success=empty_pb2.Empty())
+
+        self.log.debug('Wait for security...')
+        kwargs = {}
+        kwargs[await wait_for_security] = empty_pb2.Empty()
+
+        # remove event handlers
+        for event, listener in listeners.items():
+            connection.remove_listener(event, listener)  # type: ignore
+
+        # wait for `authenticate` to finish if any
+        if authenticate_task is not None:
+            self.log.debug('Wait for authentication...')
+            try:
+                await authenticate_task  # type: ignore
+            except:
+                pass
+            self.log.debug('Authenticated')
+
+        return WaitSecurityResponse(**kwargs)
+
+    def reached_security_level(
+        self, connection: BumbleConnection, level: Union[SecurityLevel, LESecurityLevel]
+    ) -> bool:
+        self.log.debug(
+            str(
+                {
+                    'level': level,
+                    'encryption': connection.encryption,
+                    'authenticated': connection.authenticated,
+                    'sc': connection.sc,
+                    'link_key_type': connection.link_key_type,
+                }
+            )
+        )
+
+        if isinstance(level, LESecurityLevel):
+            return LE_LEVEL_REACHED[level](connection)
+
+        return BR_LEVEL_REACHED[level](connection)
+
+    def need_pairing(self, connection: BumbleConnection, level: int) -> bool:
+        if connection.transport == BT_LE_TRANSPORT:
+            return level >= LE_LEVEL3 and not connection.authenticated
+        return False
+
+    def need_authentication(self, connection: BumbleConnection, level: int) -> bool:
+        if connection.transport == BT_LE_TRANSPORT:
+            return False
+        if level == LEVEL2 and connection.encryption != 0:
+            return not connection.authenticated
+        return level >= LEVEL2 and not connection.authenticated
+
+    def need_encryption(self, connection: BumbleConnection, level: int) -> bool:
+        # TODO(abel): need to support MITM
+        if connection.transport == BT_LE_TRANSPORT:
+            return level == LE_LEVEL2 and not connection.encryption
+        return level >= LEVEL2 and not connection.encryption
+
+
+class SecurityStorageService(SecurityStorageServicer):
+    def __init__(self, device: Device, config: Config) -> None:
+        self.log = utils.BumbleServerLoggerAdapter(
+            logging.getLogger(), {'service_name': 'SecurityStorage', 'device': device}
+        )
+        self.device = device
+        self.config = config
+
+    @utils.rpc
+    async def IsBonded(
+        self, request: IsBondedRequest, context: grpc.ServicerContext
+    ) -> wrappers_pb2.BoolValue:
+        address = utils.address_from_request(request, request.WhichOneof("address"))
+        self.log.debug(f"IsBonded: {address}")
+
+        if self.device.keystore is not None:
+            is_bonded = await self.device.keystore.get(str(address)) is not None
+        else:
+            is_bonded = False
+
+        return wrappers_pb2.BoolValue(value=is_bonded)
+
+    @utils.rpc
+    async def DeleteBond(
+        self, request: DeleteBondRequest, context: grpc.ServicerContext
+    ) -> empty_pb2.Empty:
+        address = utils.address_from_request(request, request.WhichOneof("address"))
+        self.log.debug(f"DeleteBond: {address}")
+
+        if self.device.keystore is not None:
+            with suppress(KeyError):
+                await self.device.keystore.delete(str(address))
+
+        return empty_pb2.Empty()

bumble/pandora/utils.py

@@ -0,0 +1,112 @@
+# Copyright 2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import contextlib
+import functools
+import grpc
+import inspect
+import logging
+
+from bumble.device import Device
+from bumble.hci import Address
+from google.protobuf.message import Message  # pytype: disable=pyi-error
+from typing import Any, Dict, Generator, MutableMapping, Optional, Tuple
+
+ADDRESS_TYPES: Dict[str, int] = {
+    "public": Address.PUBLIC_DEVICE_ADDRESS,
+    "random": Address.RANDOM_DEVICE_ADDRESS,
+    "public_identity": Address.PUBLIC_IDENTITY_ADDRESS,
+    "random_static_identity": Address.RANDOM_IDENTITY_ADDRESS,
+}
+
+
+def address_from_request(request: Message, field: Optional[str]) -> Address:
+    if field is None:
+        return Address.ANY
+    return Address(bytes(reversed(getattr(request, field))), ADDRESS_TYPES[field])
+
+
+class BumbleServerLoggerAdapter(logging.LoggerAdapter):  # type: ignore
+    """Formats logs from the PandoraClient."""
+
+    def process(
+        self, msg: str, kwargs: MutableMapping[str, Any]
+    ) -> Tuple[str, MutableMapping[str, Any]]:
+        assert self.extra
+        service_name = self.extra['service_name']
+        assert isinstance(service_name, str)
+        device = self.extra['device']
+        assert isinstance(device, Device)
+        addr_bytes = bytes(
+            reversed(bytes(device.public_address))
+        )  # pytype: disable=attribute-error
+        addr = ':'.join([f'{x:02X}' for x in addr_bytes[4:]])
+        return (f'[bumble.{service_name}:{addr}] {msg}', kwargs)
+
+
+@contextlib.contextmanager
+def exception_to_rpc_error(
+    context: grpc.ServicerContext,
+) -> Generator[None, None, None]:
+    try:
+        yield None
+    except NotImplementedError as e:
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)  # type: ignore
+        context.set_details(str(e))  # type: ignore
+    except ValueError as e:
+        context.set_code(grpc.StatusCode.INVALID_ARGUMENT)  # type: ignore
+        context.set_details(str(e))  # type: ignore
+    except RuntimeError as e:
+        context.set_code(grpc.StatusCode.ABORTED)  # type: ignore
+        context.set_details(str(e))  # type: ignore
+
+
+# Decorate an RPC servicer method with a wrapper that transform exceptions to gRPC errors.
+def rpc(func: Any) -> Any:
+    @functools.wraps(func)
+    async def asyncgen_wrapper(
+        self: Any, request: Any, context: grpc.ServicerContext
+    ) -> Any:
+        with exception_to_rpc_error(context):
+            async for v in func(self, request, context):
+                yield v
+
+    @functools.wraps(func)
+    async def async_wrapper(
+        self: Any, request: Any, context: grpc.ServicerContext
+    ) -> Any:
+        with exception_to_rpc_error(context):
+            return await func(self, request, context)
+
+    @functools.wraps(func)
+    def gen_wrapper(self: Any, request: Any, context: grpc.ServicerContext) -> Any:
+        with exception_to_rpc_error(context):
+            for v in func(self, request, context):
+                yield v
+
+    @functools.wraps(func)
+    def wrapper(self: Any, request: Any, context: grpc.ServicerContext) -> Any:
+        with exception_to_rpc_error(context):
+            return func(self, request, context)
+
+    if inspect.isasyncgenfunction(func):
+        return asyncgen_wrapper
+
+    if inspect.iscoroutinefunction(func):
+        return async_wrapper
+
+    if inspect.isgenerator(func):
+        return gen_wrapper
+
+    return wrapper

bumble/profiles/asha_service.py

@@ -0,0 +1,188 @@
+# Copyright 2021-2022 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import struct
+import logging
+from typing import List
+from ..core import AdvertisingData
+from ..device import Device, Connection
+from ..gatt import (
+    GATT_ASHA_SERVICE,
+    GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
+    GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
+    GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
+    GATT_ASHA_VOLUME_CHARACTERISTIC,
+    GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
+    TemplateService,
+    Characteristic,
+    CharacteristicValue,
+)
+from ..utils import AsyncRunner
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+class AshaService(TemplateService):
+    UUID = GATT_ASHA_SERVICE
+    OPCODE_START = 1
+    OPCODE_STOP = 2
+    OPCODE_STATUS = 3
+    PROTOCOL_VERSION = 0x01
+    RESERVED_FOR_FUTURE_USE = [00, 00]
+    FEATURE_MAP = [0x01]  # [LE CoC audio output streaming supported]
+    SUPPORTED_CODEC_ID = [0x02, 0x01]  # Codec IDs [G.722 at 16 kHz]
+    RENDER_DELAY = [00, 00]
+
+    def __init__(self, capability: int, hisyncid: List[int], device: Device, psm=0):
+        self.hisyncid = hisyncid
+        self.capability = capability  # Device Capabilities [Left, Monaural]
+        self.device = device
+        self.audio_out_data = b''
+        self.psm = psm  # a non-zero psm is mainly for testing purpose
+
+        # Handler for volume control
+        def on_volume_write(connection, value):
+            logger.info(f'--- VOLUME Write:{value[0]}')
+            self.emit('volume', connection, value[0])
+
+        # Handler for audio control commands
+        def on_audio_control_point_write(connection: Connection, value):
+            logger.info(f'--- AUDIO CONTROL POINT Write:{value.hex()}')
+            opcode = value[0]
+            if opcode == AshaService.OPCODE_START:
+                # Start
+                audio_type = ('Unknown', 'Ringtone', 'Phone Call', 'Media')[value[2]]
+                logger.info(
+                    f'### START: codec={value[1]}, '
+                    f'audio_type={audio_type}, '
+                    f'volume={value[3]}, '
+                    f'otherstate={value[4]}'
+                )
+                self.emit(
+                    'start',
+                    connection,
+                    {
+                        'codec': value[1],
+                        'audiotype': value[2],
+                        'volume': value[3],
+                        'otherstate': value[4],
+                    },
+                )
+            elif opcode == AshaService.OPCODE_STOP:
+                logger.info('### STOP')
+                self.emit('stop', connection)
+            elif opcode == AshaService.OPCODE_STATUS:
+                logger.info(f'### STATUS: connected={value[1]}')
+
+            # OPCODE_STATUS does not need audio status point update
+            if opcode != AshaService.OPCODE_STATUS:
+                AsyncRunner.spawn(
+                    device.notify_subscribers(
+                        self.audio_status_characteristic, force=True
+                    )
+                )
+
+        self.read_only_properties_characteristic = Characteristic(
+            GATT_ASHA_READ_ONLY_PROPERTIES_CHARACTERISTIC,
+            Characteristic.Properties.READ,
+            Characteristic.READABLE,
+            bytes(
+                [
+                    AshaService.PROTOCOL_VERSION,  # Version
+                    self.capability,
+                ]
+            )
+            + bytes(self.hisyncid)
+            + bytes(AshaService.FEATURE_MAP)
+            + bytes(AshaService.RENDER_DELAY)
+            + bytes(AshaService.RESERVED_FOR_FUTURE_USE)
+            + bytes(AshaService.SUPPORTED_CODEC_ID),
+        )
+
+        self.audio_control_point_characteristic = Characteristic(
+            GATT_ASHA_AUDIO_CONTROL_POINT_CHARACTERISTIC,
+            Characteristic.Properties.WRITE
+            | Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+            Characteristic.WRITEABLE,
+            CharacteristicValue(write=on_audio_control_point_write),
+        )
+        self.audio_status_characteristic = Characteristic(
+            GATT_ASHA_AUDIO_STATUS_CHARACTERISTIC,
+            Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
+            Characteristic.READABLE,
+            bytes([0]),
+        )
+        self.volume_characteristic = Characteristic(
+            GATT_ASHA_VOLUME_CHARACTERISTIC,
+            Characteristic.Properties.WRITE_WITHOUT_RESPONSE,
+            Characteristic.WRITEABLE,
+            CharacteristicValue(write=on_volume_write),
+        )
+
+        # Register an L2CAP CoC server
+        def on_coc(channel):
+            def on_data(data):
+                logging.debug(f'<<< data received:{data}')
+
+                self.emit('data', channel.connection, data)
+                self.audio_out_data += data
+
+            channel.sink = on_data
+
+        # let the server find a free PSM
+        self.psm = self.device.register_l2cap_channel_server(self.psm, on_coc, 8)
+        self.le_psm_out_characteristic = Characteristic(
+            GATT_ASHA_LE_PSM_OUT_CHARACTERISTIC,
+            Characteristic.Properties.READ,
+            Characteristic.READABLE,
+            struct.pack('<H', self.psm),
+        )
+
+        characteristics = [
+            self.read_only_properties_characteristic,
+            self.audio_control_point_characteristic,
+            self.audio_status_characteristic,
+            self.volume_characteristic,
+            self.le_psm_out_characteristic,
+        ]
+
+        super().__init__(characteristics)
+
+    def get_advertising_data(self):
+        # Advertisement only uses 4 least significant bytes of the HiSyncId.
+        return bytes(
+            AdvertisingData(
+                [
+                    (
+                        AdvertisingData.SERVICE_DATA_16_BIT_UUID,
+                        bytes(GATT_ASHA_SERVICE)
+                        + bytes(
+                            [
+                                AshaService.PROTOCOL_VERSION,
+                                self.capability,
+                            ]
+                        )
+                        + bytes(self.hisyncid[:4]),
+                    ),
+                ]
+            )
+        )

bumble/profiles/battery_service.py

@@ -23,7 +23,7 @@ from ..gatt import (
     TemplateService,
     Characteristic,
     CharacteristicValue,
-    PackedCharacteristicAdapter
+    PackedCharacteristicAdapter,
 )
 
 
@@ -36,11 +36,11 @@ class BatteryService(TemplateService):
         self.battery_level_characteristic = PackedCharacteristicAdapter(
             Characteristic(
                 GATT_BATTERY_LEVEL_CHARACTERISTIC,
-                Characteristic.READ | Characteristic.NOTIFY,
+                Characteristic.Properties.READ | Characteristic.Properties.NOTIFY,
                 Characteristic.READABLE,
-                CharacteristicValue(read=read_battery_level)
+                CharacteristicValue(read=read_battery_level),
             ),
-            format=BatteryService.BATTERY_LEVEL_FORMAT
+            pack_format=BatteryService.BATTERY_LEVEL_FORMAT,
         )
         super().__init__([self.battery_level_characteristic])
 
@@ -52,10 +52,11 @@ class BatteryServiceProxy(ProfileServiceProxy):
     def __init__(self, service_proxy):
         self.service_proxy = service_proxy
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_BATTERY_LEVEL_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_BATTERY_LEVEL_CHARACTERISTIC
+        ):
             self.battery_level = PackedCharacteristicAdapter(
-                characteristics[0],
-                format=BatteryService.BATTERY_LEVEL_FORMAT
+                characteristics[0], pack_format=BatteryService.BATTERY_LEVEL_FORMAT
             )
         else:
             self.battery_level = None

bumble/profiles/device_information_service.py

@@ -17,7 +17,7 @@
 # Imports
 # -----------------------------------------------------------------------------
 import struct
-from typing import Tuple
+from typing import Optional, Tuple
 
 from ..gatt_client import ProfileServiceProxy
 from ..gatt import (
@@ -33,7 +33,7 @@ from ..gatt import (
     TemplateService,
     Characteristic,
     DelegatedCharacteristicAdapter,
-    UTF8CharacteristicAdapter
+    UTF8CharacteristicAdapter,
 )
 
 
@@ -52,49 +52,50 @@ class DeviceInformationService(TemplateService):
 
     def __init__(
         self,
-        manufacturer_name: str = None,
-        model_number: str = None,
-        serial_number: str = None,
-        hardware_revision: str = None,
-        firmware_revision: str = None,
-        software_revision: str = None,
-        system_id: Tuple[int, int] = None,  # (OUI, Manufacturer ID)
-        ieee_regulatory_certification_data_list: bytes = None
+        manufacturer_name: Optional[str] = None,
+        model_number: Optional[str] = None,
+        serial_number: Optional[str] = None,
+        hardware_revision: Optional[str] = None,
+        firmware_revision: Optional[str] = None,
+        software_revision: Optional[str] = None,
+        system_id: Optional[Tuple[int, int]] = None,  # (OUI, Manufacturer ID)
+        ieee_regulatory_certification_data_list: Optional[bytes] = None
         # TODO: pnp_id
     ):
         characteristics = [
             Characteristic(
-                uuid,
-                Characteristic.READ,
-                Characteristic.READABLE,
-                field
+                uuid, Characteristic.Properties.READ, Characteristic.READABLE, field
             )
             for (field, uuid) in (
                 (manufacturer_name, GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC),
-                (model_number,      GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
-                (serial_number,     GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
+                (model_number, GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
+                (serial_number, GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
                 (hardware_revision, GATT_HARDWARE_REVISION_STRING_CHARACTERISTIC),
                 (firmware_revision, GATT_FIRMWARE_REVISION_STRING_CHARACTERISTIC),
-                (software_revision, GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC)
+                (software_revision, GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC),
             )
             if field is not None
         ]
 
         if system_id is not None:
-            characteristics.append(Characteristic(
-                GATT_SYSTEM_ID_CHARACTERISTIC,
-                Characteristic.READ,
-                Characteristic.READABLE,
-                self.pack_system_id(*system_id)
-            ))
+            characteristics.append(
+                Characteristic(
+                    GATT_SYSTEM_ID_CHARACTERISTIC,
+                    Characteristic.Properties.READ,
+                    Characteristic.READABLE,
+                    self.pack_system_id(*system_id),
+                )
+            )
 
         if ieee_regulatory_certification_data_list is not None:
-            characteristics.append(Characteristic(
-                GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC,
-                Characteristic.READ,
-                Characteristic.READABLE,
-                ieee_regulatory_certification_data_list
-            ))
+            characteristics.append(
+                Characteristic(
+                    GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC,
+                    Characteristic.Properties.READ,
+                    Characteristic.READABLE,
+                    ieee_regulatory_certification_data_list,
+                )
+            )
 
         super().__init__(characteristics)
 
@@ -108,11 +109,11 @@ class DeviceInformationServiceProxy(ProfileServiceProxy):
 
         for (field, uuid) in (
             ('manufacturer_name', GATT_MANUFACTURER_NAME_STRING_CHARACTERISTIC),
-            ('model_number',      GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
-            ('serial_number',     GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
+            ('model_number', GATT_MODEL_NUMBER_STRING_CHARACTERISTIC),
+            ('serial_number', GATT_SERIAL_NUMBER_STRING_CHARACTERISTIC),
             ('hardware_revision', GATT_HARDWARE_REVISION_STRING_CHARACTERISTIC),
             ('firmware_revision', GATT_FIRMWARE_REVISION_STRING_CHARACTERISTIC),
-            ('software_revision', GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC)
+            ('software_revision', GATT_SOFTWARE_REVISION_STRING_CHARACTERISTIC),
         ):
             if characteristics := service_proxy.get_characteristics_by_uuid(uuid):
                 characteristic = UTF8CharacteristicAdapter(characteristics[0])
@@ -120,16 +121,20 @@ class DeviceInformationServiceProxy(ProfileServiceProxy):
                 characteristic = None
             self.__setattr__(field, characteristic)
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_SYSTEM_ID_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_SYSTEM_ID_CHARACTERISTIC
+        ):
             self.system_id = DelegatedCharacteristicAdapter(
                 characteristics[0],
                 encode=lambda v: DeviceInformationService.pack_system_id(*v),
-                decode=DeviceInformationService.unpack_system_id
+                decode=DeviceInformationService.unpack_system_id,
             )
         else:
             self.system_id = None
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_REGULATORY_CERTIFICATION_DATA_LIST_CHARACTERISTIC
+        ):
             self.ieee_regulatory_certification_data_list = characteristics[0]
         else:
             self.ieee_regulatory_certification_data_list = None

bumble/profiles/heart_rate_service.py

@@ -30,25 +30,25 @@ from ..gatt import (
     Characteristic,
     CharacteristicValue,
     DelegatedCharacteristicAdapter,
-    PackedCharacteristicAdapter
+    PackedCharacteristicAdapter,
 )
 
 
 # -----------------------------------------------------------------------------
 class HeartRateService(TemplateService):
-    UUID                            = GATT_HEART_RATE_SERVICE
+    UUID = GATT_HEART_RATE_SERVICE
     HEART_RATE_CONTROL_POINT_FORMAT = 'B'
-    CONTROL_POINT_NOT_SUPPORTED     = 0x80
-    RESET_ENERGY_EXPENDED           = 0x01
+    CONTROL_POINT_NOT_SUPPORTED = 0x80
+    RESET_ENERGY_EXPENDED = 0x01
 
     class BodySensorLocation(IntEnum):
-        OTHER    = 0,
-        CHEST    = 1,
-        WRIST    = 2,
-        FINGER   = 3,
-        HAND     = 4,
-        EAR_LOBE = 5,
-        FOOT     = 6
+        OTHER = (0,)
+        CHEST = (1,)
+        WRIST = (2,)
+        FINGER = (3,)
+        HAND = (4,)
+        EAR_LOBE = (5,)
+        FOOT = 6
 
     class HeartRateMeasurement:
         def __init__(
@@ -56,12 +56,14 @@ class HeartRateService(TemplateService):
             heart_rate,
             sensor_contact_detected=None,
             energy_expended=None,
-            rr_intervals=None
+            rr_intervals=None,
         ):
             if heart_rate < 0 or heart_rate > 0xFFFF:
                 raise ValueError('heart_rate out of range')
 
-            if energy_expended is not None and (energy_expended < 0 or energy_expended > 0xFFFF):
+            if energy_expended is not None and (
+                energy_expended < 0 or energy_expended > 0xFFFF
+            ):
                 raise ValueError('energy_expended out of range')
 
             if rr_intervals:
@@ -69,10 +71,10 @@ class HeartRateService(TemplateService):
                     if rr_interval < 0 or rr_interval * 1024 > 0xFFFF:
                         raise ValueError('rr_intervals out of range')
 
-            self.heart_rate              = heart_rate
+            self.heart_rate = heart_rate
             self.sensor_contact_detected = sensor_contact_detected
-            self.energy_expended         = energy_expended
-            self.rr_intervals            = rr_intervals
+            self.energy_expended = energy_expended
+            self.rr_intervals = rr_intervals
 
         @classmethod
         def from_bytes(cls, data):
@@ -87,7 +89,7 @@ class HeartRateService(TemplateService):
                 offset += 1
 
             if flags & (1 << 2):
-                sensor_contact_detected = (flags & (1 << 1) != 0)
+                sensor_contact_detected = flags & (1 << 1) != 0
             else:
                 sensor_contact_detected = None
 
@@ -119,51 +121,57 @@ class HeartRateService(TemplateService):
                 flags |= ((1 if self.sensor_contact_detected else 0) << 1) | (1 << 2)
 
             if self.energy_expended is not None:
-                flags |= (1 << 3)
+                flags |= 1 << 3
                 data += struct.pack('<H', self.energy_expended)
 
             if self.rr_intervals:
-                flags |= (1 << 4)
-                data += b''.join([
-                    struct.pack('<H', int(rr_interval * 1024))
-                    for rr_interval in self.rr_intervals
-                ])
+                flags |= 1 << 4
+                data += b''.join(
+                    [
+                        struct.pack('<H', int(rr_interval * 1024))
+                        for rr_interval in self.rr_intervals
+                    ]
+                )
 
             return bytes([flags]) + data
 
         def __str__(self):
-            return f'HeartRateMeasurement(heart_rate={self.heart_rate},'\
-                f' sensor_contact_detected={self.sensor_contact_detected},'\
-                f' energy_expended={self.energy_expended},'\
+            return (
+                f'HeartRateMeasurement(heart_rate={self.heart_rate},'
+                f' sensor_contact_detected={self.sensor_contact_detected},'
+                f' energy_expended={self.energy_expended},'
                 f' rr_intervals={self.rr_intervals})'
+            )
 
     def __init__(
         self,
         read_heart_rate_measurement,
         body_sensor_location=None,
-        reset_energy_expended=None
+        reset_energy_expended=None,
     ):
         self.heart_rate_measurement_characteristic = DelegatedCharacteristicAdapter(
             Characteristic(
                 GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC,
-                Characteristic.NOTIFY,
+                Characteristic.Properties.NOTIFY,
                 0,
-                CharacteristicValue(read=read_heart_rate_measurement)
+                CharacteristicValue(read=read_heart_rate_measurement),
             ),
-            encode=lambda value: bytes(value)
+            # pylint: disable=unnecessary-lambda
+            encode=lambda value: bytes(value),
         )
         characteristics = [self.heart_rate_measurement_characteristic]
 
         if body_sensor_location is not None:
             self.body_sensor_location_characteristic = Characteristic(
                 GATT_BODY_SENSOR_LOCATION_CHARACTERISTIC,
-                Characteristic.READ,
+                Characteristic.Properties.READ,
                 Characteristic.READABLE,
-                bytes([int(body_sensor_location)])
+                bytes([int(body_sensor_location)]),
             )
             characteristics.append(self.body_sensor_location_characteristic)
 
         if reset_energy_expended:
+
             def write_heart_rate_control_point_value(connection, value):
                 if value == self.RESET_ENERGY_EXPENDED:
                     if reset_energy_expended is not None:
@@ -174,11 +182,11 @@ class HeartRateService(TemplateService):
             self.heart_rate_control_point_characteristic = PackedCharacteristicAdapter(
                 Characteristic(
                     GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC,
-                    Characteristic.WRITE,
+                    Characteristic.Properties.WRITE,
                     Characteristic.WRITEABLE,
-                    CharacteristicValue(write=write_heart_rate_control_point_value)
+                    CharacteristicValue(write=write_heart_rate_control_point_value),
                 ),
-                format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT
+                pack_format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT,
             )
             characteristics.append(self.heart_rate_control_point_characteristic)
 
@@ -192,30 +200,38 @@ class HeartRateServiceProxy(ProfileServiceProxy):
     def __init__(self, service_proxy):
         self.service_proxy = service_proxy
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_HEART_RATE_MEASUREMENT_CHARACTERISTIC
+        ):
             self.heart_rate_measurement = DelegatedCharacteristicAdapter(
                 characteristics[0],
-                decode=HeartRateService.HeartRateMeasurement.from_bytes
+                decode=HeartRateService.HeartRateMeasurement.from_bytes,
             )
         else:
             self.heart_rate_measurement = None
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_BODY_SENSOR_LOCATION_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_BODY_SENSOR_LOCATION_CHARACTERISTIC
+        ):
             self.body_sensor_location = DelegatedCharacteristicAdapter(
                 characteristics[0],
-                decode=lambda value: HeartRateService.BodySensorLocation(value[0])
+                decode=lambda value: HeartRateService.BodySensorLocation(value[0]),
             )
         else:
             self.body_sensor_location = None
 
-        if characteristics := service_proxy.get_characteristics_by_uuid(GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC):
+        if characteristics := service_proxy.get_characteristics_by_uuid(
+            GATT_HEART_RATE_CONTROL_POINT_CHARACTERISTIC
+        ):
             self.heart_rate_control_point = PackedCharacteristicAdapter(
                 characteristics[0],
-                format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT
+                pack_format=HeartRateService.HEART_RATE_CONTROL_POINT_FORMAT,
             )
         else:
             self.heart_rate_control_point = None
 
     async def reset_energy_expended(self):
         if self.heart_rate_control_point is not None:
-            return await self.heart_rate_control_point.write_value(HeartRateService.RESET_ENERGY_EXPENDED)
+            return await self.heart_rate_control_point.write_value(
+                HeartRateService.RESET_ENERGY_EXPENDED
+            )

bumble/snoop.py

@@ -0,0 +1,170 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+from contextlib import contextmanager
+from enum import IntEnum
+import logging
+import struct
+import datetime
+from typing import BinaryIO, Generator
+import os
+
+from bumble.hci import HCI_COMMAND_PACKET, HCI_EVENT_PACKET
+
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+class Snooper:
+    """
+    Base class for snooper implementations.
+
+    A snooper is an object that will be provided with HCI packets as they are
+    exchanged between a host and a controller.
+    """
+
+    class Direction(IntEnum):
+        HOST_TO_CONTROLLER = 0
+        CONTROLLER_TO_HOST = 1
+
+    class DataLinkType(IntEnum):
+        H1 = 1001
+        H4 = 1002
+        HCI_BSCP = 1003
+        H5 = 1004
+
+    def snoop(self, hci_packet: bytes, direction: Direction) -> None:
+        """Snoop on an HCI packet."""
+
+
+# -----------------------------------------------------------------------------
+class BtSnooper(Snooper):
+    """
+    Snooper that saves HCI packets using the BTSnoop format, based on RFC 1761.
+    """
+
+    IDENTIFICATION_PATTERN = b'btsnoop\0'
+    TIMESTAMP_ANCHOR = datetime.datetime(2000, 1, 1)
+    TIMESTAMP_DELTA = 0x00E03AB44A676000
+    ONE_MS = datetime.timedelta(microseconds=1)
+
+    def __init__(self, output: BinaryIO):
+        self.output = output
+
+        # Write the header
+        self.output.write(
+            self.IDENTIFICATION_PATTERN + struct.pack('>LL', 1, self.DataLinkType.H4)
+        )
+
+    def snoop(self, hci_packet: bytes, direction: Snooper.Direction) -> None:
+        flags = int(direction)
+        packet_type = hci_packet[0]
+        if packet_type in (HCI_EVENT_PACKET, HCI_COMMAND_PACKET):
+            flags |= 0x10
+
+        # Compute the current timestamp
+        timestamp = (
+            int((datetime.datetime.utcnow() - self.TIMESTAMP_ANCHOR) / self.ONE_MS)
+            + self.TIMESTAMP_DELTA
+        )
+
+        # Emit the record
+        self.output.write(
+            struct.pack(
+                '>IIIIQ',
+                len(hci_packet),  # Original Length
+                len(hci_packet),  # Included Length
+                flags,  # Packet Flags
+                0,  # Cumulative Drops
+                timestamp,  # Timestamp
+            )
+            + hci_packet
+        )
+
+
+# -----------------------------------------------------------------------------
+_SNOOPER_INSTANCE_COUNT = 0
+
+
+@contextmanager
+def create_snooper(spec: str) -> Generator[Snooper, None, None]:
+    """
+    Create a snooper given a specification string.
+
+    The general syntax for the specification string is:
+      <snooper-type>:<type-specific-arguments>
+
+    Supported snooper types are:
+
+      btsnoop
+        The syntax for the type-specific arguments for this type is:
+        <io-type>:<io-type-specific-arguments>
+
+        Supported I/O types are:
+
+        file
+          The type-specific arguments for this I/O type is a string that is converted
+          to a file path using the python `str.format()` string formatting. The log
+          records will be written to that file if it can be opened/created.
+          The keyword args that may be referenced by the string pattern are:
+            now: the value of `datetime.now()`
+            utcnow: the value of `datetime.utcnow()`
+            pid: the current process ID.
+            instance: the instance ID in the current process.
+
+    Examples:
+      btsnoop:file:my_btsnoop.log
+      btsnoop:file:/tmp/bumble_{now:%Y-%m-%d-%H:%M:%S}_{pid}.log
+
+    """
+    if ':' not in spec:
+        raise ValueError('snooper type prefix missing')
+
+    snooper_type, snooper_args = spec.split(':', maxsplit=1)
+
+    if snooper_type == 'btsnoop':
+        if ':' not in snooper_args:
+            raise ValueError('I/O type for btsnoop snooper type missing')
+
+        io_type, io_name = snooper_args.split(':', maxsplit=1)
+        if io_type == 'file':
+            # Process the file name string pattern.
+            global _SNOOPER_INSTANCE_COUNT
+            file_path = io_name.format(
+                now=datetime.datetime.now(),
+                utcnow=datetime.datetime.utcnow(),
+                pid=os.getpid(),
+                instance=_SNOOPER_INSTANCE_COUNT,
+            )
+
+            # Open the file
+            logger.debug(f'Snoop file: {file_path}')
+            with open(file_path, 'wb') as snoop_file:
+                _SNOOPER_INSTANCE_COUNT += 1
+                yield BtSnooper(snoop_file)
+                _SNOOPER_INSTANCE_COUNT -= 1
+                return
+
+        raise ValueError(f'I/O type {io_type} not supported')
+
+    raise ValueError(f'snooper type {snooper_type} not found')

bumble/transport/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2022 Google LLC
+# Copyright 2021-2023 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,11 +15,13 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from contextlib import asynccontextmanager
 import logging
+import os
 
-from .common import Transport, AsyncPipeSink
-from ..link import RemoteLink
+from .common import Transport, AsyncPipeSink, SnoopingTransport
 from ..controller import Controller
+from ..snoop import create_snooper
 
 # -----------------------------------------------------------------------------
 # Logging
@@ -28,68 +30,154 @@ logger = logging.getLogger(__name__)
 
 
 # -----------------------------------------------------------------------------
-async def open_transport(name):
-    '''
-    Open a transport by name.
-    The name must be <type>:<parameters>
-    Where <parameters> depend on the type (and may be empty for some types).
-    The supported types are: serial,udp,tcp,pty,usb
-    '''
-    scheme, *spec = name.split(':', 1)
-    if scheme == 'serial' and spec:
-        from .serial import open_serial_transport
-        return await open_serial_transport(spec[0])
-    elif scheme == 'udp' and spec:
-        from .udp import open_udp_transport
-        return await open_udp_transport(spec[0])
-    elif scheme == 'tcp-client' and spec:
-        from .tcp_client import open_tcp_client_transport
-        return await open_tcp_client_transport(spec[0])
-    elif scheme == 'tcp-server' and spec:
-        from .tcp_server import open_tcp_server_transport
-        return await open_tcp_server_transport(spec[0])
-    elif scheme == 'ws-client' and spec:
-        from .ws_client import open_ws_client_transport
-        return await open_ws_client_transport(spec[0])
-    elif scheme == 'ws-server' and spec:
-        from .ws_server import open_ws_server_transport
-        return await open_ws_server_transport(spec[0])
-    elif scheme == 'pty':
-        from .pty import open_pty_transport
-        return await open_pty_transport(spec[0] if spec else None)
-    elif scheme == 'file':
-        from .file import open_file_transport
-        return await open_file_transport(spec[0] if spec else None)
-    elif scheme == 'vhci':
-        from .vhci import open_vhci_transport
-        return await open_vhci_transport(spec[0] if spec else None)
-    elif scheme == 'hci-socket':
-        from .hci_socket import open_hci_socket_transport
-        return await open_hci_socket_transport(spec[0] if spec else None)
-    elif scheme == 'usb':
-        from .usb import open_usb_transport
-        return await open_usb_transport(spec[0] if spec else None)
-    elif scheme == 'pyusb':
-        from .pyusb import open_pyusb_transport
-        return await open_pyusb_transport(spec[0] if spec else None)
-    elif scheme == 'android-emulator':
-        from .android_emulator import open_android_emulator_transport
-        return await open_android_emulator_transport(spec[0] if spec else None)
-    else:
-        raise ValueError('unknown transport scheme')
+def _wrap_transport(transport: Transport) -> Transport:
+    """
+    Automatically wrap a Transport instance when a wrapping class can be inferred
+    from the environment.
+    If no wrapping class is applicable, the transport argument is returned as-is.
+    """
+
+    # If BUMBLE_SNOOPER is set, try to automatically create a snooper.
+    if snooper_spec := os.getenv('BUMBLE_SNOOPER'):
+        try:
+            return SnoopingTransport.create_with(
+                transport, create_snooper(snooper_spec)
+            )
+        except Exception as exc:
+            logger.warning(f'Exception while creating snooper: {exc}')
+
+    return transport
 
 
 # -----------------------------------------------------------------------------
-async def open_transport_or_link(name):
+async def open_transport(name: str) -> Transport:
+    """
+    Open a transport by name.
+    The name must be <type>:<parameters>
+    Where <parameters> depend on the type (and may be empty for some types).
+    The supported types are:
+      * serial
+      * udp
+      * tcp-client
+      * tcp-server
+      * ws-client
+      * ws-server
+      * pty
+      * file
+      * vhci
+      * hci-socket
+      * usb
+      * pyusb
+      * android-emulator
+      * android-netsim
+    """
+
+    return _wrap_transport(await _open_transport(name))
+
+
+# -----------------------------------------------------------------------------
+async def _open_transport(name: str) -> Transport:
+    # pylint: disable=import-outside-toplevel
+    # pylint: disable=too-many-return-statements
+
+    scheme, *spec = name.split(':', 1)
+    if scheme == 'serial' and spec:
+        from .serial import open_serial_transport
+
+        return await open_serial_transport(spec[0])
+
+    if scheme == 'udp' and spec:
+        from .udp import open_udp_transport
+
+        return await open_udp_transport(spec[0])
+
+    if scheme == 'tcp-client' and spec:
+        from .tcp_client import open_tcp_client_transport
+
+        return await open_tcp_client_transport(spec[0])
+
+    if scheme == 'tcp-server' and spec:
+        from .tcp_server import open_tcp_server_transport
+
+        return await open_tcp_server_transport(spec[0])
+
+    if scheme == 'ws-client' and spec:
+        from .ws_client import open_ws_client_transport
+
+        return await open_ws_client_transport(spec[0])
+
+    if scheme == 'ws-server' and spec:
+        from .ws_server import open_ws_server_transport
+
+        return await open_ws_server_transport(spec[0])
+
+    if scheme == 'pty':
+        from .pty import open_pty_transport
+
+        return await open_pty_transport(spec[0] if spec else None)
+
+    if scheme == 'file':
+        from .file import open_file_transport
+
+        return await open_file_transport(spec[0] if spec else None)
+
+    if scheme == 'vhci':
+        from .vhci import open_vhci_transport
+
+        return await open_vhci_transport(spec[0] if spec else None)
+
+    if scheme == 'hci-socket':
+        from .hci_socket import open_hci_socket_transport
+
+        return await open_hci_socket_transport(spec[0] if spec else None)
+
+    if scheme == 'usb':
+        from .usb import open_usb_transport
+
+        return await open_usb_transport(spec[0] if spec else None)
+
+    if scheme == 'pyusb':
+        from .pyusb import open_pyusb_transport
+
+        return await open_pyusb_transport(spec[0] if spec else None)
+
+    if scheme == 'android-emulator':
+        from .android_emulator import open_android_emulator_transport
+
+        return await open_android_emulator_transport(spec[0] if spec else None)
+
+    if scheme == 'android-netsim':
+        from .android_netsim import open_android_netsim_transport
+
+        return await open_android_netsim_transport(spec[0] if spec else None)
+
+    raise ValueError('unknown transport scheme')
+
+
+# -----------------------------------------------------------------------------
+async def open_transport_or_link(name: str) -> Transport:
+    """
+    Open a transport or a link relay.
+
+    Args:
+      name:
+        Name of the transport or link relay to open.
+        When the name starts with "link-relay:", open a link relay (see RemoteLink
+        for details on what the arguments are).
+        For other namespaces, see `open_transport`.
+
+    """
     if name.startswith('link-relay:'):
+        from ..link import RemoteLink  # lazy import
+
         link = RemoteLink(name[11:])
         await link.wait_until_connected()
-        controller = Controller('remote', link = link)
+        controller = Controller('remote', link=link)
 
         class LinkTransport(Transport):
             async def close(self):
                 link.close()
 
-        return LinkTransport(controller, AsyncPipeSink(controller))
-    else:
-        return await open_transport(name)
+        return _wrap_transport(LinkTransport(controller, AsyncPipeSink(controller)))
+
+    return await open_transport(name)

bumble/transport/android_emulator.py

@@ -1,4 +1,4 @@
-# Copyright 2021-2022 Google LLC
+# Copyright 2021-2023 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,12 +16,14 @@
 # Imports
 # -----------------------------------------------------------------------------
 import logging
-import grpc
+import grpc.aio
 
 from .common import PumpedTransport, PumpedPacketSource, PumpedPacketSink
-from .emulated_bluetooth_pb2_grpc import EmulatedBluetoothServiceStub
-from .emulated_bluetooth_packets_pb2 import HCIPacket
-from .emulated_bluetooth_vhci_pb2_grpc import VhciForwardingServiceStub
+
+# pylint: disable=no-name-in-module
+from .grpc_protobuf.emulated_bluetooth_pb2_grpc import EmulatedBluetoothServiceStub
+from .grpc_protobuf.emulated_bluetooth_packets_pb2 import HCIPacket
+from .grpc_protobuf.emulated_bluetooth_vhci_pb2_grpc import VhciForwardingServiceStub
 
 
 # -----------------------------------------------------------------------------
@@ -59,15 +61,10 @@ async def open_android_emulator_transport(spec):
             return bytes([packet.type]) + packet.packet
 
         async def write(self, packet):
-            await self.hci_device.write(
-                HCIPacket(
-                    type   = packet[0],
-                    packet = packet[1:]
-                )
-            )
+            await self.hci_device.write(HCIPacket(type=packet[0], packet=packet[1:]))
 
     # Parse the parameters
-    mode        = 'host'
+    mode = 'host'
     server_host = 'localhost'
     server_port = 8554
     if spec is not None:
@@ -100,7 +97,7 @@ async def open_android_emulator_transport(spec):
     transport = PumpedTransport(
         PumpedPacketSource(hci_device.read),
         PumpedPacketSink(hci_device.write),
-        channel.close
+        channel.close,
     )
     transport.start()
 

bumble/transport/android_netsim.py

@@ -0,0 +1,410 @@
+# Copyright 2021-2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# -----------------------------------------------------------------------------
+# Imports
+# -----------------------------------------------------------------------------
+import asyncio
+import atexit
+import logging
+import grpc.aio
+import os
+import pathlib
+import sys
+from typing import Optional
+
+from .common import (
+    ParserSource,
+    PumpedTransport,
+    PumpedPacketSource,
+    PumpedPacketSink,
+    Transport,
+)
+
+# pylint: disable=no-name-in-module
+from .grpc_protobuf.packet_streamer_pb2_grpc import PacketStreamerStub
+from .grpc_protobuf.packet_streamer_pb2_grpc import (
+    PacketStreamerServicer,
+    add_PacketStreamerServicer_to_server,
+)
+from .grpc_protobuf.packet_streamer_pb2 import PacketRequest, PacketResponse
+from .grpc_protobuf.hci_packet_pb2 import HCIPacket
+from .grpc_protobuf.startup_pb2 import Chip, ChipInfo
+from .grpc_protobuf.common_pb2 import ChipKind
+
+# -----------------------------------------------------------------------------
+# Logging
+# -----------------------------------------------------------------------------
+logger = logging.getLogger(__name__)
+
+
+# -----------------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------------
+DEFAULT_NAME = 'bumble0'
+DEFAULT_MANUFACTURER = 'Bumble'
+
+
+# -----------------------------------------------------------------------------
+def get_ini_dir() -> Optional[pathlib.Path]:
+    if sys.platform == 'darwin':
+        if tmpdir := os.getenv('TMPDIR', None):
+            return pathlib.Path(tmpdir)
+        if home := os.getenv('HOME', None):
+            return pathlib.Path(home) / 'Library/Caches/TemporaryItems'
+    elif sys.platform == 'linux':
+        if xdg_runtime_dir := os.environ.get('XDG_RUNTIME_DIR', None):
+            return pathlib.Path(xdg_runtime_dir)
+    elif sys.platform == 'win32':
+        if local_app_data_dir := os.environ.get('LOCALAPPDATA', None):
+            return pathlib.Path(local_app_data_dir) / 'Temp'
+
+    return None
+
+
+# -----------------------------------------------------------------------------
+def find_grpc_port() -> int:
+    if not (ini_dir := get_ini_dir()):
+        logger.debug('no known directory for .ini file')
+        return 0
+
+    ini_file = ini_dir / 'netsim.ini'
+    if ini_file.is_file():
+        logger.debug(f'Found .ini file at {ini_file}')
+        with open(ini_file, 'r') as ini_file_data:
+            for line in ini_file_data.readlines():
+                if '=' in line:
+                    key, value = line.split('=')
+                    if key == 'grpc.port':
+                        logger.debug(f'gRPC port = {value}')
+                        return int(value)
+
+    # Not found
+    return 0
+
+
+# -----------------------------------------------------------------------------
+def publish_grpc_port(grpc_port) -> bool:
+    if not (ini_dir := get_ini_dir()):
+        logger.debug('no known directory for .ini file')
+        return False
+
+    if not ini_dir.is_dir():
+        logger.debug('ini directory does not exist')
+        return False
+
+    ini_file = ini_dir / 'netsim.ini'
+    try:
+        ini_file.write_text(f'grpc.port={grpc_port}\n')
+        logger.debug(f"published gRPC port at {ini_file}")
+
+        def cleanup():
+            logger.debug("removing .ini file")
+            ini_file.unlink()
+
+        atexit.register(cleanup)
+        return True
+    except OSError:
+        logger.debug('failed to write to .ini file')
+        return False
+
+
+# -----------------------------------------------------------------------------
+async def open_android_netsim_controller_transport(server_host, server_port):
+    if not server_port:
+        raise ValueError('invalid port')
+    if server_host == '_' or not server_host:
+        server_host = 'localhost'
+
+    if not publish_grpc_port(server_port):
+        logger.warning("unable to publish gRPC port")
+
+    class HciDevice:
+        def __init__(self, context, on_data_received):
+            self.context = context
+            self.on_data_received = on_data_received
+            self.name = None
+            self.loop = asyncio.get_running_loop()
+            self.done = self.loop.create_future()
+            self.task = self.loop.create_task(self.pump())
+
+        async def pump(self):
+            try:
+                await self.pump_loop()
+            except asyncio.CancelledError:
+                logger.debug('Pump task canceled')
+                self.done.set_result(None)
+
+        async def pump_loop(self):
+            while True:
+                request = await self.context.read()
+                if request == grpc.aio.EOF:
+                    logger.debug('End of request stream')
+                    self.done.set_result(None)
+                    return
+
+                # If we're not initialized yet, wait for a init packet.
+                if self.name is None:
+                    if request.WhichOneof('request_type') == 'initial_info':
+                        logger.debug(f'Received initial info: {request}')
+
+                        # We only accept BLUETOOTH
+                        if request.initial_info.chip.kind != ChipKind.BLUETOOTH:
+                            logger.warning('Unsupported chip type')
+                            error = PacketResponse(error='Unsupported chip type')
+                            await self.context.write(error)
+                            return
+
+                    self.name = request.initial_info.name
+                    continue
+
+                # Expect a data packet
+                request_type = request.WhichOneof('request_type')
+                if request_type != 'hci_packet':
+                    logger.warning(f'Unexpected request type: {request_type}')
+                    error = PacketResponse(error='Unexpected request type')
+                    await self.context.write(error)
+                    continue
+
+                # Process the packet
+                data = (
+                    bytes([request.hci_packet.packet_type]) + request.hci_packet.packet
+                )
+                logger.debug(f'<<< PACKET: {data.hex()}')
+                self.on_data_received(data)
+
+        def send_packet(self, data):
+            async def send():
+                await self.context.write(
+                    PacketResponse(
+                        hci_packet=HCIPacket(packet_type=data[0], packet=data[1:])
+                    )
+                )
+
+            self.loop.create_task(send())
+
+        def terminate(self):
+            self.task.cancel()
+
+        async def wait_for_termination(self):
+            await self.done
+
+    class Server(PacketStreamerServicer, ParserSource):
+        def __init__(self):
+            PacketStreamerServicer.__init__(self)
+            ParserSource.__init__(self)
+            self.device = None
+
+            # Create a gRPC server with `so_reuseport=0` so that if there's already
+            # a server listening on that port, we get an exception.
+            self.grpc_server = grpc.aio.server(options=(('grpc.so_reuseport', 0),))
+            add_PacketStreamerServicer_to_server(self, self.grpc_server)
+            self.grpc_server.add_insecure_port(f'{server_host}:{server_port}')
+            logger.debug(f'gRPC server listening on {server_host}:{server_port}')
+
+        async def start(self):
+            logger.debug('Starting gRPC server')
+            await self.grpc_server.start()
+
+        async def serve(self):
+            # Keep serving until terminated.
+            try:
+                await self.grpc_server.wait_for_termination()
+                logger.debug('gRPC server terminated')
+            except asyncio.CancelledError:
+                logger.debug('gRPC server cancelled')
+                await self.grpc_server.stop(None)
+
+        def on_packet(self, packet):
+            if not self.device:
+                logger.debug('no device, dropping packet')
+                return
+
+            self.device.send_packet(packet)
+
+        async def StreamPackets(self, _request_iterator, context):
+            logger.debug('StreamPackets request')
+
+            # Check that we won't already have a device
+            if self.device:
+                logger.debug('busy, already serving a device')
+                return PacketResponse(error='Busy')
+
+            # Instantiate a new device
+            self.device = HciDevice(context, self.parser.feed_data)
+
+            # Wait for the device to terminate
+            logger.debug('Waiting for device to terminate')
+            try:
+                await self.device.wait_for_termination()
+            except asyncio.CancelledError:
+                logger.debug('Request canceled')
+                self.device.terminate()
+
+            logger.debug('Device terminated')
+            self.device = None
+
+    server = Server()
+    await server.start()
+    asyncio.get_running_loop().create_task(server.serve())
+
+    class GrpcServerTransport(Transport):
+        async def close(self):
+            await super().close()
+
+    return GrpcServerTransport(server, server)
+
+
+# -----------------------------------------------------------------------------
+async def open_android_netsim_host_transport(server_host, server_port, options):
+    # Wrapper for I/O operations
+    class HciDevice:
+        def __init__(self, name, manufacturer, hci_device):
+            self.name = name
+            self.manufacturer = manufacturer
+            self.hci_device = hci_device
+
+        async def start(self):  # Send the startup info
+            chip_info = ChipInfo(
+                name=self.name,
+                chip=Chip(kind=ChipKind.BLUETOOTH, manufacturer=self.manufacturer),
+            )
+            logger.debug(f'Sending chip info to netsim: {chip_info}')
+            await self.hci_device.write(PacketRequest(initial_info=chip_info))
+
+        async def read(self):
+            response = await self.hci_device.read()
+            response_type = response.WhichOneof('response_type')
+            if response_type == 'error':
+                logger.warning(f'received error: {response.error}')
+                raise RuntimeError(response.error)
+            elif response_type == 'hci_packet':
+                return (
+                    bytes([response.hci_packet.packet_type])
+                    + response.hci_packet.packet
+                )
+
+            raise ValueError('unsupported response type')
+
+        async def write(self, packet):
+            await self.hci_device.write(
+                PacketRequest(
+                    hci_packet=HCIPacket(packet_type=packet[0], packet=packet[1:])
+                )
+            )
+
+    name = options.get('name', DEFAULT_NAME)
+    manufacturer = DEFAULT_MANUFACTURER
+
+    if server_host == '_' or not server_host:
+        server_host = 'localhost'
+
+    if not server_port:
+        # Look for the gRPC config in a .ini file
+        server_host = 'localhost'
+        server_port = find_grpc_port()
+        if not server_port:
+            raise RuntimeError('gRPC server port not found')
+
+    # Connect to the gRPC server
+    server_address = f'{server_host}:{server_port}'
+    logger.debug(f'Connecting to gRPC server at {server_address}')
+    channel = grpc.aio.insecure_channel(server_address)
+
+    # Connect as a host
+    service = PacketStreamerStub(channel)
+    hci_device = HciDevice(
+        name=name,
+        manufacturer=manufacturer,
+        hci_device=service.StreamPackets(),
+    )
+    await hci_device.start()
+
+    # Create the transport object
+    transport = PumpedTransport(
+        PumpedPacketSource(hci_device.read),
+        PumpedPacketSink(hci_device.write),
+        channel.close,
+    )
+    transport.start()
+
+    return transport
+
+
+# -----------------------------------------------------------------------------
+async def open_android_netsim_transport(spec):
+    '''
+    Open a transport connection as a client or server, implementing Android's `netsim`
+    simulator protocol over gRPC.
+    The parameter string has this syntax:
+    [<host>:<port>][<options>]
+    Where <options> is a ','-separated list of <name>=<value> pairs.
+
+    General options:
+      mode=host|controller (default: host)
+        Specifies whether the transport is used
+        to connect *to* a netsim server (netsim is the controller), or accept
+        connections *as* a netsim-compatible server.
+
+    In `host` mode:
+      The <host>:<port> part is optional. When not specified, the transport
+      looks for a netsim .ini file, from which it will read the `grpc.backend.port`
+      property.
+      Options for this mode are:
+        name=<name>
+          The "chip" name, used to identify the "chip" instance. This
+          may be useful when several clients are connected, since each needs to use a
+          different name.
+
+    In `controller` mode:
+      The <host>:<port> part is required. <host> may be the address of a local network
+      interface, or '_' to accept connections on all local network interfaces.
+
+    Examples:
+    (empty string) --> connect to netsim on the port specified in the .ini file
+    localhost:8555 --> connect to netsim on localhost:8555
+    name=bumble1 --> connect to netsim, using `bumble1` as the "chip" name.
+    localhost:8555,name=bumble1 --> connect to netsim on localhost:8555, using
+    `bumble1` as the "chip" name.
+    _:8877,mode=controller --> accept connections as a controller on any interface
+    on port 8877.
+    '''
+
+    # Parse the parameters
+    params = spec.split(',') if spec else []
+    if params and ':' in params[0]:
+        # Explicit <host>:<port>
+        host, port = params[0].split(':')
+        params_offset = 1
+    else:
+        host = None
+        port = 0
+        params_offset = 0
+
+    options = {}
+    for param in params[params_offset:]:
+        if '=' not in param:
+            raise ValueError('invalid parameter, expected <name>=<value>')
+        option_name, option_value = param.split('=')
+        options[option_name] = option_value
+
+    mode = options.get('mode', 'host')
+    if mode == 'host':
+        return await open_android_netsim_host_transport(host, port, options)
+    if mode == 'controller':
+        if host is None:
+            raise ValueError('<host>:<port> missing')
+        return await open_android_netsim_controller_transport(host, port)
+
+    raise ValueError('invalid mode option')

bumble/transport/common.py

@@ -15,12 +15,16 @@
 # -----------------------------------------------------------------------------
 # Imports
 # -----------------------------------------------------------------------------
+from __future__ import annotations
+import contextlib
 import struct
 import asyncio
 import logging
-from colors import color
+from typing import ContextManager
 
 from .. import hci
+from ..colors import color
+from ..snoop import Snooper
 
 
 # -----------------------------------------------------------------------------
@@ -33,22 +37,29 @@ logger = logging.getLogger(__name__)
 # For each packet type, the info represents:
 # (length-size, length-offset, unpack-type)
 HCI_PACKET_INFO = {
-    hci.HCI_COMMAND_PACKET:          (1, 2, 'B'),
-    hci.HCI_ACL_DATA_PACKET:         (2, 2, 'H'),
+    hci.HCI_COMMAND_PACKET: (1, 2, 'B'),
+    hci.HCI_ACL_DATA_PACKET: (2, 2, 'H'),
     hci.HCI_SYNCHRONOUS_DATA_PACKET: (1, 2, 'B'),
-    hci.HCI_EVENT_PACKET:            (1, 1, 'B')
+    hci.HCI_EVENT_PACKET: (1, 1, 'B'),
 }
 
 
+# -----------------------------------------------------------------------------
+class TransportLostError(Exception):
+    """
+    The Transport has been lost/disconnected.
+    """
+
+
 # -----------------------------------------------------------------------------
 class PacketPump:
-    '''
-    Pump HCI packets from a reader to a sink
-    '''
+    """
+    Pump HCI packets from a reader to a sink.
+    """
 
     def __init__(self, reader, sink):
         self.reader = reader
-        self.sink   = sink
+        self.sink = sink
 
     async def run(self):
         while True:
@@ -64,44 +75,52 @@ class PacketPump:
 
 # -----------------------------------------------------------------------------
 class PacketParser:
-    '''
-    In-line parser that accepts data and emits 'on_packet' when a full packet has been parsed
-    '''
-    NEED_TYPE   = 0
-    NEED_LENGTH = 1
-    NEED_BODY   = 2
+    """
+    In-line parser that accepts data and emits 'on_packet' when a full packet has been
+    parsed.
+    """
 
-    def __init__(self, sink = None):
+    # pylint: disable=attribute-defined-outside-init
+
+    NEED_TYPE = 0
+    NEED_LENGTH = 1
+    NEED_BODY = 2
+
+    def __init__(self, sink=None):
         self.sink = sink
         self.extended_packet_info = {}
         self.reset()
 
     def reset(self):
-        self.state        = PacketParser.NEED_TYPE
+        self.state = PacketParser.NEED_TYPE
         self.bytes_needed = 1
-        self.packet       = bytearray()
-        self.packet_info  = None
+        self.packet = bytearray()
+        self.packet_info = None
 
     def feed_data(self, data):
         data_offset = 0
         data_left = len(data)
         while data_left and self.bytes_needed:
             consumed = min(self.bytes_needed, data_left)
-            self.packet.extend(data[data_offset:data_offset + consumed])
-            data_offset       += consumed
-            data_left         -= consumed
+            self.packet.extend(data[data_offset : data_offset + consumed])
+            data_offset += consumed
+            data_left -= consumed
             self.bytes_needed -= consumed
 
             if self.bytes_needed == 0:
                 if self.state == PacketParser.NEED_TYPE:
                     packet_type = self.packet[0]
-                    self.packet_info  = HCI_PACKET_INFO.get(packet_type) or self.extended_packet_info.get(packet_type)
+                    self.packet_info = HCI_PACKET_INFO.get(
+                        packet_type
+                    ) or self.extended_packet_info.get(packet_type)
                     if self.packet_info is None:
                         raise ValueError(f'invalid packet type {packet_type}')
                     self.state = PacketParser.NEED_LENGTH
                     self.bytes_needed = self.packet_info[0] + self.packet_info[1]
                 elif self.state == PacketParser.NEED_LENGTH:
-                    body_length = struct.unpack_from(self.packet_info[2], self.packet, 1 + self.packet_info[1])[0]
+                    body_length = struct.unpack_from(
+                        self.packet_info[2], self.packet, 1 + self.packet_info[1]
+                    )[0]
                     self.bytes_needed = body_length
                     self.state = PacketParser.NEED_BODY
 
@@ -111,7 +130,9 @@ class PacketParser:
                         try:
                             self.sink.on_packet(bytes(self.packet))
                         except Exception as error:
-                            logger.warning(color(f'!!! Exception in on_packet: {error}', 'red'))
+                            logger.warning(
+                                color(f'!!! Exception in on_packet: {error}', 'red')
+                            )
                     self.reset()
 
     def set_packet_sink(self, sink):
@@ -120,9 +141,9 @@ class PacketParser:
 
 # -----------------------------------------------------------------------------
 class PacketReader:
-    '''
-    Reader that reads HCI packets from a sync source
-    '''
+    """
+    Reader that reads HCI packets from a sync source.
+    """
 
     def __init__(self, source):
         self.source = source
@@ -155,9 +176,9 @@ class PacketReader:
 
 # -----------------------------------------------------------------------------
 class AsyncPacketReader:
-    '''
-    Reader that reads HCI packets from an async source
-    '''
+    """
+    Reader that reads HCI packets from an async source.
+    """
 
     def __init__(self, source):
         self.source = source
@@ -184,9 +205,10 @@ class AsyncPacketReader:
 
 # -----------------------------------------------------------------------------
 class AsyncPipeSink:
-    '''
-    Sink that forwards packets asynchronously to another sink
-    '''
+    """
+    Sink that forwards packets asynchronously to another sink.
+    """
+
     def __init__(self, sink):
         self.sink = sink
         self.loop = asyncio.get_running_loop()
@@ -201,14 +223,29 @@ class ParserSource:
     Base class designed to be subclassed by transport-specific source classes
     """
 
+    terminated: asyncio.Future
+    parser: PacketParser
+
     def __init__(self):
-        self.parser     = PacketParser()
+        self.parser = PacketParser()
         self.terminated = asyncio.get_running_loop().create_future()
 
     def set_packet_sink(self, sink):
         self.parser.set_packet_sink(sink)
 
+    def on_transport_lost(self):
+        self.terminated.set_result(None)
+        if self.parser.sink:
+            try:
+                self.parser.sink.on_transport_lost()
+            except AttributeError:
+                pass
+
     async def wait_for_termination(self):
+        """
+        Convenience method for backward compatibility. Prefer using the `terminated`
+        attribute instead.
+        """
         return await self.terminated
 
     def close(self):
@@ -235,9 +272,23 @@ class StreamPacketSink:
 
 # -----------------------------------------------------------------------------
 class Transport:
+    """
+    Base class for all transports.
+
+    A Transport represents a source and a sink together.
+    An instance must be closed by calling close() when no longer used. Instances
+    implement the ContextManager protocol so that they may be used in a `async with`
+    statement.
+    An instance is iterable. The iterator yields, in order, its source and sink, so
+    that it may be used with a convenient call syntax like:
+
+    async with create_transport() as (source, sink):
+        ...
+    """
+
     def __init__(self, source, sink):
         self.source = source
-        self.sink   = sink
+        self.sink = sink
 
     async def __aenter__(self):
         return self
@@ -248,7 +299,7 @@ class Transport:
     def __iter__(self):
         return iter((self.source, self.sink))
 
-    async def close(self):
+    async def close(self) -> None:
         self.source.close()
         self.sink.close()
 
@@ -258,7 +309,7 @@ class PumpedPacketSource(ParserSource):
     def __init__(self, receive):
         super().__init__()
         self.receive_function = receive
-        self.pump_task        = None
+        self.pump_task = None
 
     def start(self):
         async def pump_packets():
@@ -270,7 +321,7 @@ class PumpedPacketSource(ParserSource):
                     logger.debug('source pump task done')
                     break
                 except Exception as error:
-                    logger.warn(f'exception while waiting for packet: {error}')
+                    logger.warning(f'exception while waiting for packet: {error}')
                     self.terminated.set_result(error)
                     break
 
@@ -285,8 +336,8 @@ class PumpedPacketSource(ParserSource):
 class PumpedPacketSink:
     def __init__(self, send):
         self.send_function = send
-        self.packet_queue  = asyncio.Queue()
-        self.pump_task     = None
+        self.packet_queue = asyncio.Queue()
+        self.pump_task = None
 
     def on_packet(self, packet):
         self.packet_queue.put_nowait(packet)
@@ -301,7 +352,7 @@ class PumpedPacketSink:
                     logger.debug('sink pump task done')
                     break
                 except Exception as error:
-                    logger.warn(f'exception while sending packet: {error}')
+                    logger.warning(f'exception while sending packet: {error}')
                     break
 
         self.pump_task = asyncio.create_task(pump_packets())
@@ -324,3 +375,60 @@ class PumpedTransport(Transport):
     async def close(self):
         await super().close()
         await self.close_function()
+
+
+# -----------------------------------------------------------------------------
+class SnoopingTransport(Transport):
+    """Transport wrapper that snoops on packets to/from a wrapped transport."""
+
+    @staticmethod
+    def create_with(
+        transport: Transport, snooper: ContextManager[Snooper]
+    ) -> SnoopingTransport:
+        """
+        Create an instance given a snooper that works as as context manager.
+
+        The returned instance will exit the snooper context when it is closed.
+        """
+        with contextlib.ExitStack() as exit_stack:
+            return SnoopingTransport(
+                transport, exit_stack.enter_context(snooper), exit_stack.pop_all().close
+            )
+        raise RuntimeError('unexpected code path')  # Satisfy the type checker
+
+    class Source:
+        def __init__(self, source, snooper):
+            self.source = source
+            self.snooper = snooper
+            self.sink = None
+
+        def set_packet_sink(self, sink):
+            self.sink = sink
+            self.source.set_packet_sink(self)
+
+        def on_packet(self, packet):
+            self.snooper.snoop(packet, Snooper.Direction.CONTROLLER_TO_HOST)
+            if self.sink:
+                self.sink.on_packet(packet)
+
+    class Sink:
+        def __init__(self, sink, snooper):
+            self.sink = sink
+            self.snooper = snooper
+
+        def on_packet(self, packet):
+            self.snooper.snoop(packet, Snooper.Direction.HOST_TO_CONTROLLER)
+            if self.sink:
+                self.sink.on_packet(packet)
+
+    def __init__(self, transport, snooper, close_snooper=None):
+        super().__init__(
+            self.Source(transport.source, snooper), self.Sink(transport.sink, snooper)
+        )
+        self.transport = transport
+        self.close_snooper = close_snooper
+
+    async def close(self):
+        await self.transport.close()
+        if self.close_snooper:
+            self.close_snooper()

bumble/transport/emulated_bluetooth_pb2.py

@@ -1,53 +0,0 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# -*- coding: utf-8 -*-
-# Generated by the protocol buffer compiler.  DO NOT EDIT!
-# source: emulated_bluetooth.proto
-"""Generated protocol buffer code."""
-from google.protobuf import descriptor as _descriptor
-from google.protobuf import descriptor_pool as _descriptor_pool
-from google.protobuf import message as _message
-from google.protobuf import reflection as _reflection
-from google.protobuf import symbol_database as _symbol_database
-# @@protoc_insertion_point(imports)
-
-_sym_db = _symbol_database.Default()
-
-
-from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
-
-
-DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x18\x65mulated_bluetooth.proto\x12\x1b\x61ndroid.emulation.bluetooth\x1a emulated_bluetooth_packets.proto\"\x19\n\x07RawData\x12\x0e\n\x06packet\x18\x01 \x01(\x0c\x32\xcb\x02\n\x18\x45mulatedBluetoothService\x12\x64\n\x12registerClassicPhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12`\n\x0eregisterBlePhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12g\n\x11registerHCIDevice\x12&.android.emulation.bluetooth.HCIPacket\x1a&.android.emulation.bluetooth.HCIPacket(\x01\x30\x01\x42\"\n\x1e\x63om.android.emulator.bluetoothP\x01\x62\x06proto3')
-
-
-
-_RAWDATA = DESCRIPTOR.message_types_by_name['RawData']
-RawData = _reflection.GeneratedProtocolMessageType('RawData', (_message.Message,), {
-  'DESCRIPTOR' : _RAWDATA,
-  '__module__' : 'emulated_bluetooth_pb2'
-  # @@protoc_insertion_point(class_scope:android.emulation.bluetooth.RawData)
-  })
-_sym_db.RegisterMessage(RawData)
-
-_EMULATEDBLUETOOTHSERVICE = DESCRIPTOR.services_by_name['EmulatedBluetoothService']
-if _descriptor._USE_C_DESCRIPTORS == False:
-
-  DESCRIPTOR._options = None
-  DESCRIPTOR._serialized_options = b'\n\036com.android.emulator.bluetoothP\001'
-  _RAWDATA._serialized_start=91
-  _RAWDATA._serialized_end=116
-  _EMULATEDBLUETOOTHSERVICE._serialized_start=119
-  _EMULATEDBLUETOOTHSERVICE._serialized_end=450
-# @@protoc_insertion_point(module_scope)

bumble/transport/file.py

@@ -30,8 +30,9 @@ logger = logging.getLogger(__name__)
 # -----------------------------------------------------------------------------
 async def open_file_transport(spec):
     '''
-    Open a File transport (typically not for a real file, but for a PTY or other unix virtual files).
-    The parameter string is the path of the file to open
+    Open a File transport (typically not for a real file, but for a PTY or other unix
+    virtual files).
+    The parameter string is the path of the file to open.
     '''
 
     # Open the file
@@ -39,14 +40,12 @@ async def open_file_transport(spec):
 
     # Setup reading
     read_transport, packet_source = await asyncio.get_running_loop().connect_read_pipe(
-        lambda: StreamPacketSource(),
-        file
+        StreamPacketSource, file
     )
 
     # Setup writing
     write_transport, _ = await asyncio.get_running_loop().connect_write_pipe(
-        lambda: asyncio.BaseProtocol(),
-        file
+        asyncio.BaseProtocol, file
     )
     packet_sink = StreamPacketSink(write_transport)
 
@@ -57,4 +56,3 @@ async def open_file_transport(spec):
             file.close()
 
     return FileTransport(packet_source, packet_sink)
-

bumble/transport/grpc_protobuf/common_pb2.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: common.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0c\x63ommon.proto\x12\rnetsim.common*=\n\x08\x43hipKind\x12\x0f\n\x0bUNSPECIFIED\x10\x00\x12\r\n\tBLUETOOTH\x10\x01\x12\x08\n\x04WIFI\x10\x02\x12\x07\n\x03UWB\x10\x03\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'common_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  _CHIPKIND._serialized_start=31
+  _CHIPKIND._serialized_end=92
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/common_pb2.pyi

@@ -0,0 +1,12 @@
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from typing import ClassVar as _ClassVar
+
+BLUETOOTH: ChipKind
+DESCRIPTOR: _descriptor.FileDescriptor
+UNSPECIFIED: ChipKind
+UWB: ChipKind
+WIFI: ChipKind
+
+class ChipKind(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = []

bumble/transport/grpc_protobuf/common_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/grpc_protobuf/emulated_bluetooth_device_pb2.pyi

@@ -0,0 +1,158 @@
+from . import grpc_endpoint_description_pb2 as _grpc_endpoint_description_pb2
+from google.protobuf import empty_pb2 as _empty_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Advertisement(_message.Message):
+    __slots__ = ["connection_mode", "device_name", "discovery_mode"]
+    class ConnectionMode(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    class DiscoveryMode(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CONNECTION_MODE_DIRECTED: Advertisement.ConnectionMode
+    CONNECTION_MODE_FIELD_NUMBER: _ClassVar[int]
+    CONNECTION_MODE_NON_CONNECTABLE: Advertisement.ConnectionMode
+    CONNECTION_MODE_UNDIRECTED: Advertisement.ConnectionMode
+    CONNECTION_MODE_UNSPECIFIED: Advertisement.ConnectionMode
+    DEVICE_NAME_FIELD_NUMBER: _ClassVar[int]
+    DISCOVERY_MODE_FIELD_NUMBER: _ClassVar[int]
+    DISCOVERY_MODE_GENERAL: Advertisement.DiscoveryMode
+    DISCOVERY_MODE_LIMITED: Advertisement.DiscoveryMode
+    DISCOVERY_MODE_NON_DISCOVERABLE: Advertisement.DiscoveryMode
+    DISCOVERY_MODE_UNSPECIFIED: Advertisement.DiscoveryMode
+    connection_mode: Advertisement.ConnectionMode
+    device_name: str
+    discovery_mode: Advertisement.DiscoveryMode
+    def __init__(self, device_name: _Optional[str] = ..., connection_mode: _Optional[_Union[Advertisement.ConnectionMode, str]] = ..., discovery_mode: _Optional[_Union[Advertisement.DiscoveryMode, str]] = ...) -> None: ...
+
+class CallbackIdentifier(_message.Message):
+    __slots__ = ["identity"]
+    IDENTITY_FIELD_NUMBER: _ClassVar[int]
+    identity: str
+    def __init__(self, identity: _Optional[str] = ...) -> None: ...
+
+class CharacteristicValueRequest(_message.Message):
+    __slots__ = ["callback_device_id", "callback_id", "data", "from_device"]
+    CALLBACK_DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
+    CALLBACK_ID_FIELD_NUMBER: _ClassVar[int]
+    DATA_FIELD_NUMBER: _ClassVar[int]
+    FROM_DEVICE_FIELD_NUMBER: _ClassVar[int]
+    callback_device_id: CallbackIdentifier
+    callback_id: Uuid
+    data: bytes
+    from_device: DeviceIdentifier
+    def __init__(self, callback_device_id: _Optional[_Union[CallbackIdentifier, _Mapping]] = ..., from_device: _Optional[_Union[DeviceIdentifier, _Mapping]] = ..., callback_id: _Optional[_Union[Uuid, _Mapping]] = ..., data: _Optional[bytes] = ...) -> None: ...
+
+class CharacteristicValueResponse(_message.Message):
+    __slots__ = ["data", "status"]
+    class GattStatus(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    DATA_FIELD_NUMBER: _ClassVar[int]
+    GATT_STATUS_FAILURE: CharacteristicValueResponse.GattStatus
+    GATT_STATUS_SUCCESS: CharacteristicValueResponse.GattStatus
+    GATT_STATUS_UNSPECIFIED: CharacteristicValueResponse.GattStatus
+    STATUS_FIELD_NUMBER: _ClassVar[int]
+    data: bytes
+    status: CharacteristicValueResponse.GattStatus
+    def __init__(self, status: _Optional[_Union[CharacteristicValueResponse.GattStatus, str]] = ..., data: _Optional[bytes] = ...) -> None: ...
+
+class ConnectionStateChange(_message.Message):
+    __slots__ = ["callback_device_id", "from_device", "new_state"]
+    class ConnectionState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CALLBACK_DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
+    CONNECTION_STATE_CONNECTED: ConnectionStateChange.ConnectionState
+    CONNECTION_STATE_DISCONNECTED: ConnectionStateChange.ConnectionState
+    CONNECTION_STATE_UNDEFINED: ConnectionStateChange.ConnectionState
+    FROM_DEVICE_FIELD_NUMBER: _ClassVar[int]
+    NEW_STATE_FIELD_NUMBER: _ClassVar[int]
+    callback_device_id: CallbackIdentifier
+    from_device: DeviceIdentifier
+    new_state: ConnectionStateChange.ConnectionState
+    def __init__(self, callback_device_id: _Optional[_Union[CallbackIdentifier, _Mapping]] = ..., from_device: _Optional[_Union[DeviceIdentifier, _Mapping]] = ..., new_state: _Optional[_Union[ConnectionStateChange.ConnectionState, str]] = ...) -> None: ...
+
+class DeviceIdentifier(_message.Message):
+    __slots__ = ["address"]
+    ADDRESS_FIELD_NUMBER: _ClassVar[int]
+    address: str
+    def __init__(self, address: _Optional[str] = ...) -> None: ...
+
+class GattCharacteristic(_message.Message):
+    __slots__ = ["callback_id", "permissions", "properties", "uuid"]
+    class Permissions(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    class Properties(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CALLBACK_ID_FIELD_NUMBER: _ClassVar[int]
+    PERMISSIONS_FIELD_NUMBER: _ClassVar[int]
+    PERMISSION_READ: GattCharacteristic.Permissions
+    PERMISSION_READ_ENCRYPTED: GattCharacteristic.Permissions
+    PERMISSION_READ_ENCRYPTED_MITM: GattCharacteristic.Permissions
+    PERMISSION_UNSPECIFIED: GattCharacteristic.Permissions
+    PERMISSION_WRITE: GattCharacteristic.Permissions
+    PERMISSION_WRITE_ENCRYPTED: GattCharacteristic.Permissions
+    PERMISSION_WRITE_ENCRYPTED_MITM: GattCharacteristic.Permissions
+    PERMISSION_WRITE_SIGNED: GattCharacteristic.Permissions
+    PERMISSION_WRITE_SIGNED_MITM: GattCharacteristic.Permissions
+    PROPERTIES_FIELD_NUMBER: _ClassVar[int]
+    PROPERTY_BROADCAST: GattCharacteristic.Properties
+    PROPERTY_EXTENDED_PROPS: GattCharacteristic.Properties
+    PROPERTY_INDICATE: GattCharacteristic.Properties
+    PROPERTY_NOTIFY: GattCharacteristic.Properties
+    PROPERTY_READ: GattCharacteristic.Properties
+    PROPERTY_SIGNED_WRITE: GattCharacteristic.Properties
+    PROPERTY_UNSPECIFIED: GattCharacteristic.Properties
+    PROPERTY_WRITE: GattCharacteristic.Properties
+    PROPERTY_WRITE_NO_RESPONSE: GattCharacteristic.Properties
+    UUID_FIELD_NUMBER: _ClassVar[int]
+    callback_id: Uuid
+    permissions: int
+    properties: int
+    uuid: Uuid
+    def __init__(self, uuid: _Optional[_Union[Uuid, _Mapping]] = ..., properties: _Optional[int] = ..., permissions: _Optional[int] = ..., callback_id: _Optional[_Union[Uuid, _Mapping]] = ...) -> None: ...
+
+class GattDevice(_message.Message):
+    __slots__ = ["advertisement", "endpoint", "profile"]
+    ADVERTISEMENT_FIELD_NUMBER: _ClassVar[int]
+    ENDPOINT_FIELD_NUMBER: _ClassVar[int]
+    PROFILE_FIELD_NUMBER: _ClassVar[int]
+    advertisement: Advertisement
+    endpoint: _grpc_endpoint_description_pb2.Endpoint
+    profile: GattProfile
+    def __init__(self, endpoint: _Optional[_Union[_grpc_endpoint_description_pb2.Endpoint, _Mapping]] = ..., advertisement: _Optional[_Union[Advertisement, _Mapping]] = ..., profile: _Optional[_Union[GattProfile, _Mapping]] = ...) -> None: ...
+
+class GattProfile(_message.Message):
+    __slots__ = ["services"]
+    SERVICES_FIELD_NUMBER: _ClassVar[int]
+    services: _containers.RepeatedCompositeFieldContainer[GattService]
+    def __init__(self, services: _Optional[_Iterable[_Union[GattService, _Mapping]]] = ...) -> None: ...
+
+class GattService(_message.Message):
+    __slots__ = ["characteristics", "service_type", "uuid"]
+    class ServiceType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    CHARACTERISTICS_FIELD_NUMBER: _ClassVar[int]
+    SERVICE_TYPE_FIELD_NUMBER: _ClassVar[int]
+    SERVICE_TYPE_PRIMARY: GattService.ServiceType
+    SERVICE_TYPE_SECONDARY: GattService.ServiceType
+    SERVICE_TYPE_UNSPECIFIED: GattService.ServiceType
+    UUID_FIELD_NUMBER: _ClassVar[int]
+    characteristics: _containers.RepeatedCompositeFieldContainer[GattCharacteristic]
+    service_type: GattService.ServiceType
+    uuid: Uuid
+    def __init__(self, uuid: _Optional[_Union[Uuid, _Mapping]] = ..., service_type: _Optional[_Union[GattService.ServiceType, str]] = ..., characteristics: _Optional[_Iterable[_Union[GattCharacteristic, _Mapping]]] = ...) -> None: ...
+
+class Uuid(_message.Message):
+    __slots__ = ["id", "lsb", "msb"]
+    ID_FIELD_NUMBER: _ClassVar[int]
+    LSB_FIELD_NUMBER: _ClassVar[int]
+    MSB_FIELD_NUMBER: _ClassVar[int]
+    id: int
+    lsb: int
+    msb: int
+    def __init__(self, id: _Optional[int] = ..., lsb: _Optional[int] = ..., msb: _Optional[int] = ...) -> None: ...

bumble/transport/grpc_protobuf/emulated_bluetooth_device_pb2_grpc.py

@@ -0,0 +1,193 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+
+from . import emulated_bluetooth_device_pb2 as emulated__bluetooth__device__pb2
+from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2
+
+
+class GattDeviceServiceStub(object):
+    """You can provide your own GattDevice by implementing this service
+    and registering it with the android emulator.
+
+    The device will appear as a real bluetooth device, and you will
+    receive callbacks when the bluetooth system wants to
+    read, write or observe a characteristic.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.OnCharacteristicReadRequest = channel.unary_unary(
+                '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicReadRequest',
+                request_serializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+                response_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+                )
+        self.OnCharacteristicWriteRequest = channel.unary_unary(
+                '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicWriteRequest',
+                request_serializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+                response_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+                )
+        self.OnCharacteristicObserveRequest = channel.unary_stream(
+                '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicObserveRequest',
+                request_serializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+                response_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+                )
+        self.OnConnectionStateChange = channel.unary_unary(
+                '/android.emulation.bluetooth.GattDeviceService/OnConnectionStateChange',
+                request_serializer=emulated__bluetooth__device__pb2.ConnectionStateChange.SerializeToString,
+                response_deserializer=google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+                )
+
+
+class GattDeviceServiceServicer(object):
+    """You can provide your own GattDevice by implementing this service
+    and registering it with the android emulator.
+
+    The device will appear as a real bluetooth device, and you will
+    receive callbacks when the bluetooth system wants to
+    read, write or observe a characteristic.
+    """
+
+    def OnCharacteristicReadRequest(self, request, context):
+        """A remote client has requested to read a local characteristic.
+
+        Return the current observed value.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def OnCharacteristicWriteRequest(self, request, context):
+        """A remote client has requested to write to a local characteristic.
+
+        Return the current observed value.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def OnCharacteristicObserveRequest(self, request, context):
+        """Listens for notifications from the emulated device, the device should
+        write to the stream with a response when a change has occurred.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def OnConnectionStateChange(self, request, context):
+        """A remote device has been connected or disconnected.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_GattDeviceServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'OnCharacteristicReadRequest': grpc.unary_unary_rpc_method_handler(
+                    servicer.OnCharacteristicReadRequest,
+                    request_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.FromString,
+                    response_serializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.SerializeToString,
+            ),
+            'OnCharacteristicWriteRequest': grpc.unary_unary_rpc_method_handler(
+                    servicer.OnCharacteristicWriteRequest,
+                    request_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.FromString,
+                    response_serializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.SerializeToString,
+            ),
+            'OnCharacteristicObserveRequest': grpc.unary_stream_rpc_method_handler(
+                    servicer.OnCharacteristicObserveRequest,
+                    request_deserializer=emulated__bluetooth__device__pb2.CharacteristicValueRequest.FromString,
+                    response_serializer=emulated__bluetooth__device__pb2.CharacteristicValueResponse.SerializeToString,
+            ),
+            'OnConnectionStateChange': grpc.unary_unary_rpc_method_handler(
+                    servicer.OnConnectionStateChange,
+                    request_deserializer=emulated__bluetooth__device__pb2.ConnectionStateChange.FromString,
+                    response_serializer=google_dot_protobuf_dot_empty__pb2.Empty.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'android.emulation.bluetooth.GattDeviceService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+
+
+ # This class is part of an EXPERIMENTAL API.
+class GattDeviceService(object):
+    """You can provide your own GattDevice by implementing this service
+    and registering it with the android emulator.
+
+    The device will appear as a real bluetooth device, and you will
+    receive callbacks when the bluetooth system wants to
+    read, write or observe a characteristic.
+    """
+
+    @staticmethod
+    def OnCharacteristicReadRequest(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicReadRequest',
+            emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+            emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def OnCharacteristicWriteRequest(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicWriteRequest',
+            emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+            emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def OnCharacteristicObserveRequest(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(request, target, '/android.emulation.bluetooth.GattDeviceService/OnCharacteristicObserveRequest',
+            emulated__bluetooth__device__pb2.CharacteristicValueRequest.SerializeToString,
+            emulated__bluetooth__device__pb2.CharacteristicValueResponse.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def OnConnectionStateChange(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.GattDeviceService/OnConnectionStateChange',
+            emulated__bluetooth__device__pb2.ConnectionStateChange.SerializeToString,
+            google_dot_protobuf_dot_empty__pb2.Empty.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

bumble/transport/grpc_protobuf/emulated_bluetooth_packets_pb2.py

@@ -1,25 +1,10 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
 # -*- coding: utf-8 -*-
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: emulated_bluetooth_packets.proto
 """Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
-from google.protobuf import message as _message
-from google.protobuf import reflection as _reflection
 from google.protobuf import symbol_database as _symbol_database
 # @@protoc_insertion_point(imports)
 
@@ -30,17 +15,8 @@ _sym_db = _symbol_database.Default()
 
 DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n emulated_bluetooth_packets.proto\x12\x1b\x61ndroid.emulation.bluetooth\"\xfb\x01\n\tHCIPacket\x12?\n\x04type\x18\x01 \x01(\x0e\x32\x31.android.emulation.bluetooth.HCIPacket.PacketType\x12\x0e\n\x06packet\x18\x02 \x01(\x0c\"\x9c\x01\n\nPacketType\x12\x1b\n\x17PACKET_TYPE_UNSPECIFIED\x10\x00\x12\x1b\n\x17PACKET_TYPE_HCI_COMMAND\x10\x01\x12\x13\n\x0fPACKET_TYPE_ACL\x10\x02\x12\x13\n\x0fPACKET_TYPE_SCO\x10\x03\x12\x15\n\x11PACKET_TYPE_EVENT\x10\x04\x12\x13\n\x0fPACKET_TYPE_ISO\x10\x05\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3')
 
-
-
-_HCIPACKET = DESCRIPTOR.message_types_by_name['HCIPacket']
-_HCIPACKET_PACKETTYPE = _HCIPACKET.enum_types_by_name['PacketType']
-HCIPacket = _reflection.GeneratedProtocolMessageType('HCIPacket', (_message.Message,), {
-  'DESCRIPTOR' : _HCIPACKET,
-  '__module__' : 'emulated_bluetooth_packets_pb2'
-  # @@protoc_insertion_point(class_scope:android.emulation.bluetooth.HCIPacket)
-  })
-_sym_db.RegisterMessage(HCIPacket)
-
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'emulated_bluetooth_packets_pb2', globals())
 if _descriptor._USE_C_DESCRIPTORS == False:
 
   DESCRIPTOR._options = None

bumble/transport/grpc_protobuf/emulated_bluetooth_packets_pb2.pyi

@@ -0,0 +1,22 @@
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class HCIPacket(_message.Message):
+    __slots__ = ["packet", "type"]
+    class PacketType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+        __slots__ = []
+    PACKET_FIELD_NUMBER: _ClassVar[int]
+    PACKET_TYPE_ACL: HCIPacket.PacketType
+    PACKET_TYPE_EVENT: HCIPacket.PacketType
+    PACKET_TYPE_HCI_COMMAND: HCIPacket.PacketType
+    PACKET_TYPE_ISO: HCIPacket.PacketType
+    PACKET_TYPE_SCO: HCIPacket.PacketType
+    PACKET_TYPE_UNSPECIFIED: HCIPacket.PacketType
+    TYPE_FIELD_NUMBER: _ClassVar[int]
+    packet: bytes
+    type: HCIPacket.PacketType
+    def __init__(self, type: _Optional[_Union[HCIPacket.PacketType, str]] = ..., packet: _Optional[bytes] = ...) -> None: ...

bumble/transport/grpc_protobuf/emulated_bluetooth_packets_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/grpc_protobuf/emulated_bluetooth_pb2.py

@@ -0,0 +1,32 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: emulated_bluetooth.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
+from . import emulated_bluetooth_device_pb2 as emulated__bluetooth__device__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x18\x65mulated_bluetooth.proto\x12\x1b\x61ndroid.emulation.bluetooth\x1a emulated_bluetooth_packets.proto\x1a\x1f\x65mulated_bluetooth_device.proto\"\x19\n\x07RawData\x12\x0e\n\x06packet\x18\x01 \x01(\x0c\"a\n\x12RegistrationStatus\x12K\n\x12\x63\x61llback_device_id\x18\x01 \x01(\x0b\x32/.android.emulation.bluetooth.CallbackIdentifier2\xbb\x03\n\x18\x45mulatedBluetoothService\x12\x64\n\x12registerClassicPhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12`\n\x0eregisterBlePhy\x12$.android.emulation.bluetooth.RawData\x1a$.android.emulation.bluetooth.RawData(\x01\x30\x01\x12g\n\x11registerHCIDevice\x12&.android.emulation.bluetooth.HCIPacket\x1a&.android.emulation.bluetooth.HCIPacket(\x01\x30\x01\x12n\n\x12registerGattDevice\x12\'.android.emulation.bluetooth.GattDevice\x1a/.android.emulation.bluetooth.RegistrationStatusB\"\n\x1e\x63om.android.emulator.bluetoothP\x01\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'emulated_bluetooth_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\036com.android.emulator.bluetoothP\001'
+  _RAWDATA._serialized_start=124
+  _RAWDATA._serialized_end=149
+  _REGISTRATIONSTATUS._serialized_start=151
+  _REGISTRATIONSTATUS._serialized_end=248
+  _EMULATEDBLUETOOTHSERVICE._serialized_start=251
+  _EMULATEDBLUETOOTHSERVICE._serialized_end=694
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/emulated_bluetooth_pb2.pyi

@@ -0,0 +1,19 @@
+from . import emulated_bluetooth_packets_pb2 as _emulated_bluetooth_packets_pb2
+from . import emulated_bluetooth_device_pb2 as _emulated_bluetooth_device_pb2
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class RawData(_message.Message):
+    __slots__ = ["packet"]
+    PACKET_FIELD_NUMBER: _ClassVar[int]
+    packet: bytes
+    def __init__(self, packet: _Optional[bytes] = ...) -> None: ...
+
+class RegistrationStatus(_message.Message):
+    __slots__ = ["callback_device_id"]
+    CALLBACK_DEVICE_ID_FIELD_NUMBER: _ClassVar[int]
+    callback_device_id: _emulated_bluetooth_device_pb2.CallbackIdentifier
+    def __init__(self, callback_device_id: _Optional[_Union[_emulated_bluetooth_device_pb2.CallbackIdentifier, _Mapping]] = ...) -> None: ...

bumble/transport/grpc_protobuf/emulated_bluetooth_pb2_grpc.py

@@ -1,21 +1,8 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
 # Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
 """Client and server classes corresponding to protobuf-defined services."""
 import grpc
 
+from . import emulated_bluetooth_device_pb2 as emulated__bluetooth__device__pb2
 from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
 from . import emulated_bluetooth_pb2 as emulated__bluetooth__pb2
 
@@ -53,6 +40,11 @@ class EmulatedBluetoothServiceStub(object):
                 request_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
                 response_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
                 )
+        self.registerGattDevice = channel.unary_unary(
+                '/android.emulation.bluetooth.EmulatedBluetoothService/registerGattDevice',
+                request_serializer=emulated__bluetooth__device__pb2.GattDevice.SerializeToString,
+                response_deserializer=emulated__bluetooth__pb2.RegistrationStatus.FromString,
+                )
 
 
 class EmulatedBluetoothServiceServicer(object):
@@ -118,6 +110,22 @@ class EmulatedBluetoothServiceServicer(object):
         context.set_details('Method not implemented!')
         raise NotImplementedError('Method not implemented!')
 
+    def registerGattDevice(self, request, context):
+        """Registers an emulated bluetooth device. The emulator will reach out to
+        the emulated device to read/write and subscribe to properties.
+
+        The following gRPC error codes can be returned:
+        -  FAILED_PRECONDITION (code 9):
+        - root canal is not available on this device
+        - unable to reach the endpoint for the GattDevice
+        -  INTERNAL (code 13) if there was an internal emulator failure.
+
+        The device will not be discoverable in case of an error.
+        """
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
 
 def add_EmulatedBluetoothServiceServicer_to_server(servicer, server):
     rpc_method_handlers = {
@@ -136,6 +144,11 @@ def add_EmulatedBluetoothServiceServicer_to_server(servicer, server):
                     request_deserializer=emulated__bluetooth__packets__pb2.HCIPacket.FromString,
                     response_serializer=emulated__bluetooth__packets__pb2.HCIPacket.SerializeToString,
             ),
+            'registerGattDevice': grpc.unary_unary_rpc_method_handler(
+                    servicer.registerGattDevice,
+                    request_deserializer=emulated__bluetooth__device__pb2.GattDevice.FromString,
+                    response_serializer=emulated__bluetooth__pb2.RegistrationStatus.SerializeToString,
+            ),
     }
     generic_handler = grpc.method_handlers_generic_handler(
             'android.emulation.bluetooth.EmulatedBluetoothService', rpc_method_handlers)
@@ -205,3 +218,20 @@ class EmulatedBluetoothService(object):
             emulated__bluetooth__packets__pb2.HCIPacket.FromString,
             options, channel_credentials,
             insecure, call_credentials, compression, wait_for_ready, timeout, metadata)
+
+    @staticmethod
+    def registerGattDevice(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(request, target, '/android.emulation.bluetooth.EmulatedBluetoothService/registerGattDevice',
+            emulated__bluetooth__device__pb2.GattDevice.SerializeToString,
+            emulated__bluetooth__pb2.RegistrationStatus.FromString,
+            options, channel_credentials,
+            insecure, call_credentials, compression, wait_for_ready, timeout, metadata)

bumble/transport/grpc_protobuf/emulated_bluetooth_vhci_pb2.py

@@ -1,39 +1,23 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
 # -*- coding: utf-8 -*-
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: emulated_bluetooth_vhci.proto
 """Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
-from google.protobuf import message as _message
-from google.protobuf import reflection as _reflection
 from google.protobuf import symbol_database as _symbol_database
 # @@protoc_insertion_point(imports)
 
 _sym_db = _symbol_database.Default()
 
 
-import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
+from . import emulated_bluetooth_packets_pb2 as emulated__bluetooth__packets__pb2
 
 
 DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1d\x65mulated_bluetooth_vhci.proto\x12\x1b\x61ndroid.emulation.bluetooth\x1a emulated_bluetooth_packets.proto2y\n\x15VhciForwardingService\x12`\n\nattachVhci\x12&.android.emulation.bluetooth.HCIPacket\x1a&.android.emulation.bluetooth.HCIPacket(\x01\x30\x01\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3')
 
-
-
-_VHCIFORWARDINGSERVICE = DESCRIPTOR.services_by_name['VhciForwardingService']
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'emulated_bluetooth_vhci_pb2', globals())
 if _descriptor._USE_C_DESCRIPTORS == False:
 
   DESCRIPTOR._options = None

bumble/transport/grpc_protobuf/emulated_bluetooth_vhci_pb2.pyi

@@ -0,0 +1,5 @@
+import emulated_bluetooth_packets_pb2 as _emulated_bluetooth_packets_pb2
+from google.protobuf import descriptor as _descriptor
+from typing import ClassVar as _ClassVar
+
+DESCRIPTOR: _descriptor.FileDescriptor

bumble/transport/grpc_protobuf/emulated_bluetooth_vhci_pb2_grpc.py

@@ -1,17 +1,3 @@
-# Copyright 2021-2022 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
 # Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
 """Client and server classes corresponding to protobuf-defined services."""
 import grpc

bumble/transport/grpc_protobuf/grpc_endpoint_description_pb2.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: grpc_endpoint_description.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1fgrpc_endpoint_description.proto\x12\x18\x61ndroid.emulation.remote\"V\n\x0b\x43redentials\x12\x16\n\x0epem_root_certs\x18\x01 \x01(\t\x12\x17\n\x0fpem_private_key\x18\x02 \x01(\t\x12\x16\n\x0epem_cert_chain\x18\x03 \x01(\t\"$\n\x06Header\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t\"\x96\x01\n\x08\x45ndpoint\x12\x0e\n\x06target\x18\x01 \x01(\t\x12>\n\x0ftls_credentials\x18\x02 \x01(\x0b\x32%.android.emulation.remote.Credentials\x12:\n\x10required_headers\x18\x03 \x03(\x0b\x32 .android.emulation.remote.HeaderB \n\x1c\x63om.android.emulation.remoteP\x01\x62\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'grpc_endpoint_description_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\034com.android.emulation.remoteP\001'
+  _CREDENTIALS._serialized_start=61
+  _CREDENTIALS._serialized_end=147
+  _HEADER._serialized_start=149
+  _HEADER._serialized_end=185
+  _ENDPOINT._serialized_start=188
+  _ENDPOINT._serialized_end=338
+# @@protoc_insertion_point(module_scope)

bumble/transport/grpc_protobuf/grpc_endpoint_description_pb2.pyi

@@ -0,0 +1,34 @@
+from google.protobuf.internal import containers as _containers
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Credentials(_message.Message):
+    __slots__ = ["pem_cert_chain", "pem_private_key", "pem_root_certs"]
+    PEM_CERT_CHAIN_FIELD_NUMBER: _ClassVar[int]
+    PEM_PRIVATE_KEY_FIELD_NUMBER: _ClassVar[int]
+    PEM_ROOT_CERTS_FIELD_NUMBER: _ClassVar[int]
+    pem_cert_chain: str
+    pem_private_key: str
+    pem_root_certs: str
+    def __init__(self, pem_root_certs: _Optional[str] = ..., pem_private_key: _Optional[str] = ..., pem_cert_chain: _Optional[str] = ...) -> None: ...
+
+class Endpoint(_message.Message):
+    __slots__ = ["required_headers", "target", "tls_credentials"]
+    REQUIRED_HEADERS_FIELD_NUMBER: _ClassVar[int]
+    TARGET_FIELD_NUMBER: _ClassVar[int]
+    TLS_CREDENTIALS_FIELD_NUMBER: _ClassVar[int]
+    required_headers: _containers.RepeatedCompositeFieldContainer[Header]
+    target: str
+    tls_credentials: Credentials
+    def __init__(self, target: _Optional[str] = ..., tls_credentials: _Optional[_Union[Credentials, _Mapping]] = ..., required_headers: _Optional[_Iterable[_Union[Header, _Mapping]]] = ...) -> None: ...
+
+class Header(_message.Message):
+    __slots__ = ["key", "value"]
+    KEY_FIELD_NUMBER: _ClassVar[int]
+    VALUE_FIELD_NUMBER: _ClassVar[int]
+    key: str
+    value: str
+    def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...

bumble/transport/grpc_protobuf/grpc_endpoint_description_pb2_grpc.py

@@ -0,0 +1,4 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+

bumble/transport/grpc_protobuf/hci_packet_pb2.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: hci_packet.proto
+"""Generated protocol buffer code."""
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x10hci_packet.proto\x12\rnetsim.packet\"\xb2\x01\n\tHCIPacket\x12\x38\n\x0bpacket_type\x18\x01 \x01(\x0e\x32#.netsim.packet.HCIPacket.PacketType\x12\x0e\n\x06packet\x18\x02 \x01(\x0c\"[\n\nPacketType\x12\x1a\n\x16HCI_PACKET_UNSPECIFIED\x10\x00\x12\x0b\n\x07\x43OMMAND\x10\x01\x12\x07\n\x03\x41\x43L\x10\x02\x12\x07\n\x03SCO\x10\x03\x12\t\n\x05\x45VENT\x10\x04\x12\x07\n\x03ISO\x10\x05\x42J\n\x1f\x63om.android.emulation.bluetoothP\x01\xf8\x01\x01\xa2\x02\x03\x41\x45\x42\xaa\x02\x1b\x41ndroid.Emulation.Bluetoothb\x06proto3')
+
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, globals())
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'hci_packet_pb2', globals())
+if _descriptor._USE_C_DESCRIPTORS == False:
+
+  DESCRIPTOR._options = None
+  DESCRIPTOR._serialized_options = b'\n\037com.android.emulation.bluetoothP\001\370\001\001\242\002\003AEB\252\002\033Android.Emulation.Bluetooth'
+  _HCIPACKET._serialized_start=36
+  _HCIPACKET._serialized_end=214
+  _HCIPACKET_PACKETTYPE._serialized_start=123
+  _HCIPACKET_PACKETTYPE._serialized_end=214
+# @@protoc_insertion_point(module_scope)