initial import

docs/mkdocs/src/api/examples.md

@@ -0,0 +1,2 @@
+API EXAMPLES
+============

docs/mkdocs/src/api/guide.md

@@ -0,0 +1,2 @@
+API DEVELOPER GUIDE
+===================

docs/mkdocs/src/api/reference.md

@@ -0,0 +1,19 @@
+Bumble Python API
+=================
+
+# Classes
+
+## Address
+::: bumble.hci.Address
+
+## HCI_Packet
+::: bumble.hci.HCI_Packet
+
+## HCI Commands
+
+### HCI_Command
+::: bumble.hci.HCI_Command
+
+### HCI_Disconnect_Command
+::: bumble.hci.HCI_Disconnect_Command
+

docs/mkdocs/src/apps_and_tools/console.md

@@ -0,0 +1,31 @@
+CONSOLE APP
+===========
+
+![logo](../images/console_screenshot.png){ width=300 height=300 }
+
+The Console app is an interactive text user interface that offers a number of functions, including:
+
+  * scanning
+  * advertising
+  * connecting to devices
+  * changing connection parameters
+  * discovering GATT services and characteristics
+  * read & write GATT characteristics
+
+The console user interface has 3 main panes:
+
+  * a display pane, that displays information, depending on a user-selected mode. The `show` command can be used to switch what is displayed in this pane
+  * a command history pane that shows a short history of the last commands and their results
+  * a command pane, with tab completion, where you can enter commands
+
+In addition to the display panes, the console has a status bar, showing the scanning state and the connection state.
+
+!!! info "Running the console app"
+    ```
+    python console.py <transport-spec>
+    ```
+
+    Example:
+    ```
+    python console.py usb:0
+    ```

docs/mkdocs/src/apps_and_tools/gg_bridge.md

@@ -0,0 +1,2 @@
+GOLDEN GATE BRIDGE
+==================

docs/mkdocs/src/apps_and_tools/hci_bridge.md

@@ -0,0 +1,32 @@
+HCI BRIDGE
+==========
+
+This tool acts as a simple bridge between two HCI transports, with a host on one side and
+a controller on the other. All the HCI packets bridged between the two are printed on the console
+for logging. This bridge also has the ability to short-circuit some HCI packets (respond to them
+with a fixed response instead of bridging them to the other side), which may be useful when used with
+a host that send custom HCI commands that the controller may not understand.
+
+
+!!! info "Running the HCI bridge tool"
+    ```
+    python hci_bridge.py <host-transport-spec> <controller-transport-spec> [command-short-circuit-list]
+    ```
+
+!!! example "UDP to Serial"
+    ```
+    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
+    ```
+
+!!! example "PTY to Link Relay"
+    ```
+    python hci_bridge.py serial:emulated_uart_pty,1000000 link-relay:ws://127.0.0.1:10723/test
+    ```
+
+    In this example, an emulator that exposes a PTY as an interface to its HCI UART is running as
+    a Bluetooth host, and we are connecting it to a virtual controller attached to a link relay
+    (through which the communication with other virtual controllers will be mediated).
+
+    NOTE: this assumes you're running a Link Relay on port `10723`.
+
+

docs/mkdocs/src/apps_and_tools/index.md

@@ -0,0 +1,12 @@
+APPS & TOOLS
+============
+
+Included in the project are a few apps and tools, built on top of the core libraries.
+These include:
+
+  * [Console](console.md) - an interactive text-based console
+  * [HCI Bridge](hci_bridge.md) - a HCI transport bridge to connect two HCI transports and filter/snoop the HCI packets
+  * [Golden Gate Bridge](gg_bridge.md) - a bridge between GATT and UDP to use with the Golden Gate "stack tool"
+  * [`Show`](show.md) - Parse a file with HCI packets and print the details of each packet in a human readable form
+  * [`Link Relay`](link_relay.md) - WebSocket relay for virtual RemoteLink instances to communicate with each other.
+

docs/mkdocs/src/apps_and_tools/link_relay.md

@@ -0,0 +1,34 @@
+LINK RELAY TOOL
+===============
+
+The Link Relay is a WebSocket relay, which acts like an online chat system, where each "chat room" can be joined by multiple virtual controllers, which can then communicate with each other, as if connected with radio communication.
+
+```
+usage: python link_relay.py [-h] [--log-level LOG_LEVEL] [--log-config LOG_CONFIG] [--port PORT]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --log-level LOG_LEVEL
+                        logger level
+  --log-config LOG_CONFIG
+                        logger config file (YAML)
+  --port PORT           Port to listen on
+```
+
+(the default port is `10723`)
+
+When running, the link relay waits for connections on its listening port.
+The WebSocket path used by a connecting client indicates which virtual "chat room" to join.
+
+
+!!! tip "Connecting to the relay as a controller"
+    Most of the examples and tools that take a transport moniker as an argument also accept a link relay moniker, which is equivalent to a transport to a virtual controller that is connected to a relay.
+    The moniker syntax is: `link-relay:ws://<hostname>/<room>` where `<hostname>` is the hostname to connect to and `<room>` is the virtual "chat room" in a relay.
+
+    Example: `link-relay:ws://localhost:10723/test` will join the `test` "chat room"
+
+!!! tip "Connecting to the relay as an observer"
+    It is possible to connect to a "chat room" in a relay as an observer, rather than a virtual controller. In this case, a text-based console can be used to observe what is going on in the "chat room". Tools like [`wscat`](https://github.com/websockets/wscat#readme) or [`websocat`](https://github.com/vi/websocat) can be used for that.
+
+    Example: `wscat --connect ws://localhost:10723/test`
+

docs/mkdocs/src/components/controller.md

@@ -0,0 +1,2 @@
+CONTROLLER
+==========

docs/mkdocs/src/components/gatt.md

@@ -0,0 +1,2 @@
+GATT
+====

docs/mkdocs/src/components/host.md

@@ -0,0 +1,2 @@
+HOST
+====

docs/mkdocs/src/components/security_manager.md

@@ -0,0 +1,2 @@
+SECURITY MANAGER
+================

docs/mkdocs/src/examples/index.md

@@ -0,0 +1,72 @@
+EXAMPLES
+========
+
+The project includes a few simple example applications the illustrate some of the ways the library APIs can be used.
+These examples include:
+
+## `battery_service.py`
+Run a simple device example with a GATT server that exposes a standard Battery Service.
+
+## `get_peer_device_info.py`
+An app that connects to a device, discovers its GATT services, and, if the Device Information Service is found, looks for a Manufacturer Name characteristics, reads and prints it.
+
+## `keyboard.py`
+An app that implements a virtual keyboard or mouse, or can connect to a real keyboard and receive key presses.
+
+## `run_a2dp_info.py`
+An app that connects to a device, phone or computer and inspects its A2DP (Advanced Audio Profile) capabilities
+
+## `run_a2dp_source.py`
+An app that can connect to a Bluetooth speaker and play audio.
+
+## `run_a2dp_sink.py`
+An app that implements a virtual Bluetooth speaker that can receive audio.
+
+## `run_advertiser.py`
+An app that runs a simple device that just advertises (BLE).
+
+## `run_classic_connect.py`
+An app that connects to a Bluetooth Classic device and prints its services.
+
+## `run_classic_discoverable.py`
+An app that implements a discoverable and connectable Bluetooth Classic device.
+
+## `run_classic_discovery.py`
+An app that discovers Bluetooth Classic devices and prints their information.
+
+## `run_connect_and_encrypt.py`
+An app that connected to a device (BLE) and encrypts the connection.
+
+## `run_controller_with_scanner.py`
+
+## `run_controller.py`
+Creates two linked controllers, attaches one to a transport, and the other to a local host with a GATT server application. This can be used, for example, to attach a virtual controller to a native stack, like BlueZ on Linux, and use the native tools, like `bluetoothctl`, to scan and connect to the GATT server included in the example.
+
+## `run_gatt_client_and_server.py`
+Runs a local GATT server and GATT client, connected to each other. The GATT client discovers and logs all the services and characteristics exposed by the GATT server
+
+## `run_gatt_client.py`
+A simple GATT client that either connects to another BLE device or waits for a connection, then dumps its GATT database.
+
+## `run_gatt_server.py`
+A simple GATT server that either connects to another BLE device or waits for connections.
+
+## `run_hfp_gateway.py`
+A app that implements a Hands Free gateway. It can connect to a Hands Free headset.
+
+## `run_hfp_handsfree.py`
+A app that implements a Hands Free headset. It can simulate some of the events that a real headset would
+emit, like picking up or hanging up a call, pressing a button, etc.
+
+## `run_notifier.py`
+An app that implements a GATT server with characteristics that can be subscribed to, and emits notifications
+for those characteristics at regular intervals.
+
+## `run_rfcomm_client.py`
+An app that connects to an RFComm server and bridges the RFComm channel to a local TCP socket
+
+## `run_rfcomm_server.py`
+An app that implements an RFComm server and, when a connection is received, bridges the channel to a local TCP socket
+
+## `run_scanner.py`
+An app that scan for BLE devices and print the advertisements received.

docs/mkdocs/src/getting_started.md

@@ -0,0 +1,108 @@
+GETTING STARTED WITH BUMBLE
+===========================
+
+# Prerequisites
+
+You need Python 3.8 or above. Python >= 3.9 is recommended, but 3.8 should be sufficient if
+necessary (there may be some optional functionality that will not work on some platforms with
+python 3.8).  
+Visit the [Python site](https://www.python.org/) for instructions on how to install Python
+for your platform.  
+Throughout the documentation, when shell commands are shown, it is assumed that you can
+invoke Python as
+```
+$ python
+```
+If invoking python is different on your platform (it may be `python3` for example, or just `py` or `py.exe`), 
+adjust accordingly.
+
+You may be simply using Bumble as a module for your own application or as a dependency to your own 
+module, or you may be working on modifying or contributing to the Bumble module or example code
+itself.
+
+# Working With Bumble As A Module
+
+## Installing
+
+You may choose to install the Bumble module from an online package repository, with a package
+manager, or from source.
+
+!!! tip "Python Virtual Environments"
+    When you install Bumble, you have the option to install it as part of your default
+    python environment, or in a virtual environment, such as a `venv`, `pyenv` or `conda` environment
+
+### venv
+
+`venv` is a standard module that is included with python.
+Visit the [`venv` documentation](https://docs.python.org/3/library/venv.html) page for details.
+
+### Pyenv
+
+`pyenv` lets you easily switch between multiple versions of Python. It's simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well.  
+Visit the [`pyenv` site](https://github.com/pyenv/pyenv) for instructions on how to install
+and use `pyenv`
+
+### Conda
+
+Conda is a convenient package manager and virtual environment.
+The file `environment.yml` is a Conda environment file that you can use to create
+a new Conda environment. Once created, you can simply activate this environment when
+working with Bumble.  
+Visit the [Conda side](https://docs.conda.io/en/latest/) for instructions on how to install
+and use Conda.
+A few useful commands:  
+
+#### Create a new `bumble` Conda environment
+```
+$ conda env create -f environment.yml
+```
+This will create a new environment, named `bumble`, which you can then activate with:
+```
+$ conda activate bumble
+```
+
+#### Update an existing `bumble` environment
+```
+$ conda env update -f environment.yml
+```
+
+### Install From Source
+
+The instructions for working with virtual Python environments above also apply in this case.
+
+Install with `pip`
+```
+$ python -m pip install -e .
+```
+
+# Working On The Bumble Code
+When you work on the Bumble code itself, and run some of the tests or example apps, or import the
+module in your own code, you typically either install the package from source in "development mode" as described above, or you may choose to skip the install phase. 
+
+## Without Installing
+If you prefer not to install the package (even in development mode), you can load the module directly from its location in the project. 
+A simple way to do that is to set your `PYTHONPATH` to
+point to the root project directory, where the `bumble` subdirectory is located. You may set
+`PYTHONPATH` globally, or locally with each command line execution (on Unix-like systems).
+
+Example with a global `PYTHONPATH`, from a unix shell, when the working directory is the root 
+directory of the project.
+
+```bash
+$ export PYTHONPATH=.
+$ python apps/console.py serial:/dev/tty.usbmodem0006839912171
+```
+
+or running an example, with the working directory set to the `examples` subdirectory
+```bash
+$ cd examples
+$ export PYTHONPATH=..
+$ python run_scanner.py usb:0
+```
+
+Or course, `export PYTHONPATH` only needs to be invoked once, not before each app/script execution.
+
+Setting `PYTHONPATH` locally with each command would look something like:
+```
+$ PYTHONPATH=. python examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171
+```

docs/mkdocs/src/hardware/index.md

@@ -0,0 +1,19 @@
+HARDWARE
+========
+
+The Bumble Host connects to a controller over an [HCI Transport](../transports/index.md). 
+To use a hardware controller attached to the host on which the host application is running, the transport is typically either [HCI over UART](../transports/serial.md) or [HCI over USB](../transports/usb.md). 
+On Linux, the [VHCI Transport](../transports/vhci.md) can be used to communicate with any controller hardware managed by the operating system. Alternatively, a remote controller (a phyiscal controller attached to a remote host) can be used by connecting one of the networked transports (such as the [TCP Client transport](../transports/tcp_client.md), the [TCP Server transport](../transports/tcp_server.md) or the [UDP Transport](../transports/udp.md)) to an [HCI Bridge](../apps_and_tools/hci_bridge) bridging the network transport to a physical controller on a remote host. 
+
+In theory, any controller that is compliant with the HCI over UART or HCI over USB protocols can be used. 
+
+HCI over USB is very common, implemented by a number of commercial Bluetooth dongles. 
+
+It is also possible to use an embedded development board, running a specialized application, such as the [`HCI UART`](https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html) and [`HCI USB`](https://docs.zephyrproject.org/latest/samples/bluetooth/hci_usb/README.html) demo applications from the [Zephyr project](https://www.zephyrproject.org/), or the [`blehci`](https://mynewt.apache.org/latest/tutorials/ble/blehci_project.html) application from [mynewt/nimble](https://mynewt.apache.org/)
+
+Some specific USB dongles and embedded boards that are known to work include:
+  
+  * [Nordic nRF52840 DK board](https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dk) with the Zephyr `HCI UART` application
+  * [Nordic nRF52840 DK board](https://www.nordicsemi.com/Products/Development-hardware/nrf52840-dk) with the mynewt `blehci` application
+  * [Nordic nrf52840 dongle](https://www.nordicsemi.com/Products/Development-hardware/nRF52840-Dongle) with the Zephyr `HCI USB` application
+  * [BT820 USB Dongle](https://www.lairdconnect.com/wireless-modules/bluetooth-modules/bluetooth-42-and-40-modules/bt800-series-bluetooth-module)

docs/mkdocs/src/index.md

@@ -0,0 +1,166 @@
+Bumble, a Python Bluetooth Stack
+================================
+
+![logo](images/logo_framed.png){ width=100 height=100 }
+
+A Bluetooth stack, written in Python, useful for emulation, test, experimentation, and implementation of any sort of virtual device, with virtual or physical Bluetooth controllers.
+The project initially only supported BLE (Bluetooth Low Energy), but support for Bluetooth Classic was
+eventually added. Support for BLE is therefore currently somewhat more advanced than for Classic.
+
+!!! warning
+    This project is still very much experimental and in an alpha state where a lot of things are still missing or broken, and what's there changes frequently.
+    Also, there are still a few hardcoded values/parameters in some of the examples and apps which need to be changed (those will eventually be command line arguments, as appropriate)
+
+Overview
+--------
+
+The goal of this project is to offer a suite of components that can be put together to implement a number of tasks related to Bluetooth. That's fairly open-ended, but at the very least, it should be possible to:
+
+* Implement a virtual controller that can be attached to any compliant Bluetooth host that supports HCI.
+* Implement a Bluetooth host that communicates through a controller over HCI, including of course a virtual controller
+* Connect two or more virtual controllers together inside a single app, or across multiple apps over a network connection or local IPC
+* Scan, advertise, connect, pair
+* Implement a GATT client and server
+* Implement an SDP client and server
+* Create an L2CAP channel between two peers
+
+Some of the configurations that may be useful:
+
+* A virtual controller used with an emulated or simulated device
+* A GATT client and/or GATT server test application that can be connected to a real or virtual Bluetooth device
+* Simulate certain conditions, including errors, with precise control that normal Bluetooth stacks don't offer through their standard APIs
+
+See the [use cases page](use_cases/index.md) for more use cases.
+
+The project is implemented in Python (Python >= 3.8 is required). A number of APIs for functionality that is inherently I/O bound is implemented in terms of python coroutines with async IO. This means that all of the concurrent tasks run in the same thread, which makes everything much simpler and more predictable.
+
+![layers](images/bumble_layers.svg)
+
+What's Included
+---------------
+
+Components of a Bluetooth stack:
+
+## Controller
+The (virtual) Controller component exposes an HCI interface to a host, and connects to a virtual link-layer bus. Several instances of this class can be connected to the same bus, in which case they can communicate with each other (both broadcast for advertising data and unicast for ACL data). The bus may be
+process-local, in which case all the controllers attached to the bus run in the same process, or
+it may be remote (see Remote Link), in which case several controllers in separate processes can
+communicate with each other.
+
+### Link
+The Controller component communicates with other virtual controllers through a Link interface.
+The link interface defines basic functionality like connection, disconnection, sending and
+receiving ACL data, sending and receiving advertising data, and more.
+Included in the project are two types of Link interface implementations:
+
+#### Local Link
+The LocalLink implementation is a simple object used by an application that instantiates
+more than one Controller objects and connects them in-memory and in-process.
+
+#### Remote Link
+The RemoteLink implementation communicates with other virtual controllers over a WebSocket.
+Multiple instances of RemoteLink objects communicate with each other through a simple
+WebSocket relay that can host any number of virtual 'rooms', where each 'room' is
+a set of controllers that can communicate between themselves.
+The `link_relay` app is where this relay is implemented.
+
+## Host
+The Host component connects to a controller over an HCI interface. It is responsible to sending commands and ACL data to the controller and receiving back events and ACL data.
+
+## Channel Manager
+The ChannelManager is responsible for managing L2CAP channels.
+
+## Security Manager
+The SecurityManager is responsible for pairing/bonding.
+
+## GATT Client
+The GATT Client offers an API to discover peer services and characteristics, reading and writing characteristics, subscribing to characteristics, and all other GATT client functions.
+
+## GATT Server
+The GATT Server offers an API to expose services and characteristics, responding to reads and writes on characteristics, handling subscriptions to characteristics, and all other GATT server functions.
+
+## SDP
+SDP implements the service discovery protocol for Bluetooth Classic.
+
+## RFComm
+RFComm is a bi-directional serial-port-like protocol. It is used in several profiles.
+
+## Device
+The Device component it a compound object that ties together a Host, GATT Client, GATT Server, L2CAP channel access, advertising and scanning, and more.
+
+## Profiles
+Profiles are ways of using the underlying protocols for certain well-defined used cases, like playing music, implementing a headset, and so on.
+
+### A2DP
+A2DP is the Advanced Audio Profile, which enables asynchronous streaming of audio to speakers, or from microphones. Both the "source" (typically music playback source) and "sink" (typically a speaker) functions of A2DP.
+
+### HFP
+Hands Free Profile. Used for headsets.
+
+### HID
+Human Interface Device. For keyboards, mice, etc.
+
+## Transports
+The Hosts and Controllers communicate over a transport, which is responsible for sending/receiving
+HCI packets.
+Several types of transports are supported:
+
+  * **In Process**: HCI packets are passed via a function call
+  * Serial: interface with a controller over a serial port (HCI UART, like a development board or serial Bluetooth dongle)
+  * **USB**: interface with a controller over USB (HCI USB, like a Bluetooth USB dongle)
+  * **UDP**: packets are sent to a specified host/port and received on a specified port over a UDP socket
+  * **TCP Client**: a connection to a TCP server is made, after which HCI packets are sent/received over a TCP socket
+  * **TCP Server**: listens for a TCP client on a specified port. When a client connection is made, HCI packets are sent/received over a TCP socket
+  * **WebSocket Client**: a connection to a WebSocket server is made, after which HCI packets are sent/received over the socket.
+  * **WebSocket Server**: listens for a WebSocket client on a specified port. When a client connection is made, HCI packets are sent/received over the socket.
+  * **PTY**: a PTY (pseudo terminal) is used to send/receive HCI packets. This is convenient to expose a virtual controller as if it were an HCI UART
+  * **VHCI**: used to attach a virtual controller to a Bluetooth stack on platforms that support it.
+  * **HCI** Socket: an HCI socket, on platforms that support it, to send/receive HCI packets to/from an HCI controller managed by the OS.
+  * **Android Emulator**: a gRPC connection to an Android emulator is used to setup either an HCI interface to the emulator's "Root Canal" virtual controller, or attach a virtual controller to the Android Bluetooth host stack.
+  * **File**: HCI packets are read/written to a file-like node in the filesystem.
+
+A Bumble Host object communicates with a Bumble Controller object, or external Controller, via a Transport connection. A Bumble Controller object communicates with a Bumble Host, or external Host, via a Transport connection. When both the Host and Controller are Bumble objects, they typically communicate In Process, or via a Link Relay.
+
+See the [Transports page](transports/index.md) for details.
+
+Hardware
+--------
+The Host part of the stack can interact with Bumble's Controller implementation, but also with external hardware controllers.
+
+See the [Hardware page](hardware/index.md) for details.
+
+
+Examples
+--------
+
+See the [Examples page](examples/index.md)
+
+Apps & Tools
+------------
+
+See the [Apps & Tools page](apps_and_tools/index.md)
+
+Platforms
+---------
+
+The core library should work on any platform on which you can run Python3.
+Some platforms support features that not all platforms support
+
+  * :material-apple: macOS - see the [macOS platform page](platforms/macos.md)
+  * :material-linux: Linux - see the [Linux platform page](platforms/linux.md)
+  * :material-microsoft-windows: Windows - see the [Windows platform page](platforms/windows.md)
+  * :material-android: Android - see the [Android platform page](platforms/android.md)
+
+See the [Platforms page](platforms/index.md) for details.
+
+Roadmap
+-------
+
+Future features to be considered include:
+
+  * More device examples
+  * Add a new type of virtual link (beyond the two existing ones) to allow for link-level simulation (timing, loss, etc)
+  * Bindings for languages other than Python
+  * RPC interface to expose most of the API for remote use
+  * (...suggest anything you want...)
+

docs/mkdocs/src/platforms/android.md

@@ -0,0 +1,79 @@
+:material-android: ANDROID PLATFORM
+===================================
+
+Using Bumble with Android is not about running the Bumble stack on the Android
+OS itself, but rather using Bumble with the Bluetooth support of the Android 
+emulator.
+
+The two main use cases are:
+
+  * Connecting the Bumble host stack to the Android emulator's virtual controller.
+  * Using Bumble as an HCI bridge to connect the Android emulator to a physical 
+    Bluetooth controller, such as a USB dongle
+
+!!! warning
+    Bluetooth support in the Android emulator is a recent feature that may still
+    be evolving. The information contained here be somewhat out of sync with the
+    version of the emulator you are using.
+    You will need version 31.3.8.0 or later.
+
+The Android emulator supports Bluetooth in two ways: either by exposing virtual 
+Bluetooth controllers to which you can connect a virtual Bluetooth host stack, or
+by exposing an way to connect your own virtual controller to the Android Bluetooth
+stack via a virtual HCI interface.
+Both ways are controlled via gRPC requests to the Android emulator.
+
+## Launching the Emulator
+
+If the version of the emulator you are running does not yet support enabling 
+Bluetooth support by default or automatically, you must launch the emulator from
+the command line.
+
+!!! tip
+    For details on how to launch the Android emulator from the command line,
+    visit [this Android Studio user guide page](https://developer.android.com/studio/run/emulator-commandline)
+
+The `-grpc <port>` command line option may be used to select a gRPC port other than the default.
+
+## Connecting to Root Canal
+
+The Android emulator's virtual Bluetooth controller is called **Root Canal**.
+Multiple instances of Root Canal virtual controllers can be instantiated, they
+communicate link layer packets between them, thus creating a virtual radio network.
+Configuring a Bumble Device instance to use Root Canal as a virtual controller
+allows that virtual device to communicate with the Android Bluetooth stack, and
+through it with Android applications as well as system-managed profiles.
+To connect a Bumble host stack to a Root Canal virtual controller instance, use 
+the bumble `android-emulator` transport in `host` mode (the default).
+
+!!! example "Running the example GATT server connected to the emulator"
+    ``` shell
+    $ python run_gatt_server.py device1.json android-emulator
+    ```
+
+## Connecting a Custom Virtual Controller
+
+This is an advanced use case, which may not be officially supported, but should work in recent
+versions of the emulator.
+You will likely need to start the emulator from the command line, in order to specify the `-forward-vhci` option (unless the emulator offers a way to control that feature from a user/ui menu).
+
+!!! example "Launching the emulator with VHCI forwarding"
+    In this example, we launch an emulator AVD named "Tiramisu"
+    ```shell
+    $ emulator -forward-vhci -avd Tiramisu
+    ```
+
+!!! tip
+    Attaching a virtual controller use the VHCI forwarder while the Android Bluetooth stack
+    is running isn't supported. So you need to disable Bluetooth in your running Android guest
+    before attaching the virtual controller, then re-enable it once attached.
+
+To connect a virtual controller to the Android Bluetooth stack, use the bumble `android-emulator` transport in `controller` mode. For example, using the default gRPC port, the transport name would be: `android-emulator:mode=controller`.
+
+!!! example "connecting the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application"
+    ```shell
+    $ bumble-hci-bridge android-emulator:mode=controller usb:0
+    ```
+
+
+

docs/mkdocs/src/platforms/index.md

@@ -0,0 +1,11 @@
+PLATFORMS
+=========
+
+Most of the code included in the project should run on any platform that supports Python >= 3.8. Not all features are supported on all platforms (for example, USB dongle support is only available on platforms where the python USB library is functional).
+
+For platform-specific information, see the following pages:
+
+  * :material-apple: macOS - see the [macOS platform page](macos.md)
+  * :material-linux: Linux - see the [Linux platform page](linux.md)
+  * :material-microsoft-windows: Windows - see the [Windows platform page](windows.md)
+  * :material-android: Android - see the [Android platform page](android.md)

docs/mkdocs/src/platforms/linux.md

@@ -0,0 +1,138 @@
+:material-linux: LINUX PLATFORM
+===============================
+
+In addition to all the standard functionality available from the project by running the python tools and/or writing your own apps by leveraging the API, it is also possible on Linux hosts to interface the Bumble stack with the native BlueZ stack, and with Bluetooth controllers.
+
+Using Bumble With BlueZ
+-----------------------
+
+A Bumble virtual controller can be attached to the BlueZ stack.
+Attaching a controller to BlueZ can be done by either simulating a UART HCI interface, or by using the VHCI driver interface if available.
+In both cases, the controller can run locally on the Linux host, or remotely on a different host, with a bridge between the remote controller and the local BlueZ host, which may be useful when the BlueZ stack is running on an embedded system, or a host on which running the Bumble controller is not convenient.
+
+### Using VHCI
+
+With the [VHCI transport](../transports/vhci.md) you can attach a Bumble virtual controller to the BlueZ stack. Once attached, the controller will appear just like any other controller, and thus can be used with the standard BlueZ tools.
+
+!!! example "Attaching a virtual controller"
+    With the example app `run_controller.py`:
+    ```
+    PYTHONPATH=. python3 examples/run_controller.py F6:F7:F8:F9:FA:FB examples/device1.json vhci
+    ```
+    
+    You should see a 'Virtual Bus' controller. For example:
+    ```
+    $ hciconfig
+    hci0:	Type: Primary  Bus: Virtual
+        BD Address: F6:F7:F8:F9:FA:FB  ACL MTU: 27:64  SCO MTU: 0:0
+        UP RUNNING 
+        RX bytes:0 acl:0 sco:0 events:43 errors:0
+        TX bytes:274 acl:0 sco:0 commands:43 errors:0
+    ```
+
+    And scanning for devices should show the virtual 'Bumble' device that's running as part of the `run_controller.py` example app:
+    ```
+    pi@raspberrypi:~ $ sudo hcitool -i hci2 lescan
+    LE Scan ...
+    F0:F1:F2:F3:F4:F5 Bumble
+    ```
+
+### Using HCI Sockets
+
+HCI sockets provide a way to send/receive HCI packets to/from a Bluetooth controller managed by the kernel.
+The HCI device referenced by an `hci-socket` transport (`hciX`, where `X` is an integer, with `hci0` being the first controller device, and so on) must be in the `DOWN` state before it can be opened as a transport.
+You can bring a HCI controller `UP` or `DOWN` with `hciconfig`.
+
+!!! tip "List all available controllers"
+    The command
+    ```
+    $ hciconfig
+    ```
+    lists all available HCI controllers and their state.
+
+    Example:
+
+    ```
+    pi@raspberrypi:~ $ hciconfig
+    hci1:	Type: Primary  Bus: USB
+        BD Address: 00:16:A4:5A:40:F2  ACL MTU: 1021:8  SCO MTU: 64:1
+        DOWN 
+        RX bytes:84056 acl:0 sco:0 events:51 errors:0
+        TX bytes:1980 acl:0 sco:0 commands:90 errors:0
+
+    hci0:	Type: Primary  Bus: UART
+        BD Address: DC:A6:32:75:2C:97  ACL MTU: 1021:8  SCO MTU: 64:1
+        DOWN 
+        RX bytes:68038 acl:0 sco:0 events:692 errors:0
+        TX bytes:20105 acl:0 sco:0 commands:843 errors:0
+    ```
+
+!!! tip "Disabling `bluetoothd`"
+    When the Bluetooth daemon, `bluetoothd`, is running, it will try to use any HCI controller attached to the BlueZ stack, automatically. This means that whenever an HCI socket transport is released, it is likely that `bluetoothd` will take it over, so you will get a "device busy" condition (ex: `OSError: [Errno 16] Device or resource busy`). If that happens, you can always use 
+    ```
+    $ hciconfig hci0 down
+    ``` 
+    (or `hciX` with `X` being the index of the controller device you want to use), but a simpler solution is to just stop the `bluetoothd` daemon, with a command like:
+    ```
+    $ sudo systemctl stop bluetooth.service
+    ```
+    You can always re-start the daemon with
+    ```
+    $ sudo systemctl start bluetooth.service
+    ```
+
+### Using a Simulated UART HCI
+
+### Bridge to a Remote Controller
+
+
+Using Bumble With Bluetooth Controllers
+---------------------------------------
+
+A Bumble application can interface with a local Bluetooth controller.
+If your Bluetooth controller is a standard HCI USB controller, see the [USB Transport page](../transports/usb.md) for details on how to use HCI USB controllers.
+If your Bluetooth controller is a standard HCI UART controller, see the [Serial Transport page](../transports/serial.md).
+Alternatively, a Bumble Host object can communicate with one of the platform's controllers via an HCI Socket.
+
+`<details to be filled in>`
+
+### Raspberry Pi 4 :fontawesome-brands-raspberry-pi:
+
+You can use the Bluetooth controller either via the kernel, or directly to the device.
+
+#### Via The Kernel
+
+Use an HCI Socket transport
+
+#### Directly
+In order to use the Bluetooth controller directly on a Raspberry Pi 4 board, you need to ensure that it isn't being used by the BlueZ stack (which it probably is by default).
+
+```
+$ sudo systemctl stop hciuart
+```
+should detach the controller from the stack, after which you can use the HCI UART with Bumble.
+
+!!! tip "Check the device name for the UART and at what speed it should be opened"
+    ```
+    $ sudo systemctl status hciuart
+    ```
+    should show the speed at which the UART should be opened.
+    For example:
+    ```
+    $ sudo systemctl status hciuart
+     hciuart.service - Configure Bluetooth Modems connected by UART
+      Loaded: loaded (/lib/systemd/system/hciuart.service; enabled; vendor preset: enabled)
+      Active: active (running) since Fri 2021-06-18 02:17:28 BST; 1min 10s ago
+     Process: 357 ExecStart=/usr/bin/btuart (code=exited, status=0/SUCCESS)
+    Main PID: 586 (hciattach)
+       Tasks: 1 (limit: 4915)
+      CGroup: /system.slice/hciuart.service
+              └─586 /usr/bin/hciattach /dev/serial1 bcm43xx 3000000 flow -
+    ```
+    When run before stopping the `hciuart` service, shows that on this board, the UART device is `/dev/serial` and the speed is `3000000`
+
+!!! example "Example: scanning"
+    ```
+    python3 run_scanner.py serial:/dev/serial1,3000000
+    ```
+

docs/mkdocs/src/platforms/macos.md

@@ -0,0 +1,14 @@
+:material-apple: MACOS PLATFORM
+===============================
+
+USB HCI
+-------
+
+To use the experimental USB HCI support on macOS, you need to tell macOS not to use the USB Bluetooth
+controller with its internal Bluetooth stack.
+To do that, use the following command:
+```
+sudo nvram bluetoothHostControllerSwitchBehavior="never"
+```
+A reboot shouldn't be necessary after that. See [Tech Note 2295](https://developer.apple.com/library/archive/technotes/tn2295/_index.html)
+

docs/mkdocs/src/platforms/windows.md

@@ -0,0 +1,13 @@
+:material-microsoft-windows: WINDOWS PLATFORM
+=============================================
+
+USB HCI
+-------
+
+To use a Bluetooth USB dongle on Windows, you need a USB dongle that does not require a vendor Windows driver (the dongle will be used directly through the [`WinUSB`](https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb) driver rather than through a vendor-supplied Windows driver).
+
+In order to use the dongle, the `WinUSB` driver must be assigned to the USB device. It is likely that, by default, when you first plug in the dongle, it will be recognized by Windows as a Bluetooth USB device, and Windows will try to use it with its native Bluetooth stack. You will need to switch the driver, which can be done easily with the [Zadig tool](https://zadig.akeo.ie/).
+In the Zadig tool, select your USB dongle device, and associate it with WinUSB.  
+Once the WinUSB driver is correctly assigned to your device, you can confirm that by checking the settings with the Windows Device Manager control panel. Your device should appear under "Universal Serial Bus Device" (not under "Bluetooth"), and inspecting the driver details, you should see `winusb.sys` in the list of driver files.
+
+![USB Driver Details](winusb_driver.png)

docs/mkdocs/src/transports/android_emulator.md

@@ -0,0 +1,21 @@
+ANDROID EMULATOR TRANSPORT
+==========================
+
+The Android emulator transport either connects, as a host, to a "Root Canal" virtual controller
+("host" mode), or attaches a virtual controller to the Android Bluetooth host stack ("controller" mode).
+
+## Moniker
+The moniker syntax for an Android Emulator transport is: `android-emulator:[mode=<host|controller>][mode=<host|controller>]`.
+Both the `mode=<host|controller>` and `mode=<host|controller>` parameters are optional (so the moniker `android-emulator` by itself is a valid moniker, which will create a transport in `host` mode, connected to `localhost` on the default gRPC port for the emulator)
+
+!!! example Example
+    `android-emulator`  
+    connect as a host to the emulator on localhost:8554
+
+!!! example Example
+    `android-emulator:mode=controller`  
+    connect as a controller to the emulator on localhost:8554
+
+!!! example Example
+    `android-emulator:localhost:8555`  
+    connect as a host to the emulator on localhost:8555

docs/mkdocs/src/transports/file.md

@@ -0,0 +1,12 @@
+FILE TRANSPORT
+==============
+
+The File transport allows opening any named entry on a filesystem and use it for HCI transport I/O.
+This is typically used to open a PTY, or unix driver, not for real files.
+
+## Moniker
+The moniker for a File transport is `file:<path>`
+
+!!! example
+    `file:/dev/ttys001`  
+    Opens the pseudo terminal `/dev/ttys001` as a transport

docs/mkdocs/src/transports/hci_socket.md

@@ -0,0 +1,17 @@
+HCI SOCKET TRANSPORT
+====================
+
+An HCI Socket can send/receive HCI packets to/from a Bluetooth HCI controller managed by the host OS. This is only supported on some platforms (currently only tested on Linux).
+
+!!! note
+    This type of transport can only be used for virtual hosts, not virtual controllers
+
+## Moniker
+The moniker for an HCI Socket transport is either just `hci-socket` (to use the default/first Bluetooth controller), or `hci-socket:<index>` where `<index>` is the 0-based index of a Bluetooth controller device.
+
+!!! example
+    `hci-socket`  
+    Use an HCI socket to the first Bluetooth controller (`hci0 on Linux`)
+
+!!! tip "On Linux"
+    See the [Linux Platform](../platforms/linux.md) page for details on how to use HCI sockets on Linux

docs/mkdocs/src/transports/index.md

@@ -0,0 +1,20 @@
+TRANSPORTS
+==========
+
+The Hosts and Controllers communicate over a transport, which is responsible for sending/receiving
+HCI packets.
+Several types of transports are supported:
+
+  * In Process: HCI packets are passed via a function call
+  * [Serial](serial.md): interface with a controller over a serial port (HCI UART, like a development board or serial Bluetooth dongle)
+  * [USB](usb.md): interface with a controller over USB (HCI USB, like a Bluetooth USB dongle)
+  * [UDP](udp.md): packets are sent to a specified host/port and received on a specified port over a UDP socket
+  * [TCP Client](tcp_client.md): a connection to a TCP server is made, after which HCI packets are sent/received over a TCP socket
+  * [TCP Server](tcp_server.md): listens for a TCP client on a specified port. When a client connection is made, HCI packets are sent/received over a TCP socket
+  * [WebSocket Client](ws_client.md): a connection to a WebSocket server is made, after which HCI packets are sent/received over the socket.
+  * [WebSocket Server](ws_server.md): listens for a WebSocket client on a specified port. When a client connection is made, HCI packets are sent/received over the socket.
+  * [PTY](pty.md): a PTY (pseudo terminal) is used to send/receive HCI packets. This is convenient to expose a virtual controller as if it were an HCI UART
+  * [VHCI](vhci.md): used to attach a virtual controller to a Bluetooth stack on platforms that support it.
+  * [HCI Socket](hci_socket.md): an HCI socket, on platforms that support it, to send/receive HCI packets to/from an HCI controller managed by the OS.
+  * [Android Emulator](android_emulator.md): a gRPC connection to an Android emulator is used to setup either an HCI interface to the emulator's "Root Canal" virtual controller, or attach a virtual controller to the Android Bluetooth host stack.
+  * [File](file.md): HCI packets are read/written to a file-like node in the filesystem.

docs/mkdocs/src/transports/pty.md

@@ -0,0 +1,12 @@
+PTY TRANSPORT
+=============
+
+The PTY transport uses a Unix pseudo-terminal device to communicate with another process on the host, as if it were over a serial port.
+
+## Moniker
+The moniker syntax for a PTY transport is: `pty[:path]`.
+Where `path`, is used, is the path name where a symbolic link to the PTY will be created for convenience (the link will be removed when the transport is closed or when the process exits).
+
+!!! example
+    `pty:virtual_hci`  
+    Creates a PTY entry and a symbolic link, named `virtual_hci`, linking to the PTY

docs/mkdocs/src/transports/serial.md

@@ -0,0 +1,12 @@
+SERIAL TRANSPORT
+================
+
+The serial transport implements sending/receiving HCI packets over a UART (a.k.a serial port).
+
+## Moniker
+The moniker syntax for a serial transport is: `serial:<device-path>[,<speed>]`
+When `<speed>` is omitted, the default value of 1000000 is used
+
+!!! example
+    `serial:/dev/tty.usbmodem0006839912172,1000000`  
+    Opens the serial port `/dev/tty.usbmodem0006839912172` at `1000000`bps

docs/mkdocs/src/transports/tcp_client.md

@@ -0,0 +1,11 @@
+TCP CLIENT TRANSPORT
+====================
+
+The TCP Client transport uses an outgoing TCP connection to a host:port address.
+
+## Moniker
+The moniker syntax for a TCP client transport is: `tcp-client:<remote-host>:<remote-port>`
+
+!!! example
+    `tcp-client:127.0.0.1:9001`  
+    Connects to port 9001 on the local host

docs/mkdocs/src/transports/tcp_server.md

@@ -0,0 +1,13 @@
+TCP SERVER TRANSPORT
+====================
+
+The TCP Client transport uses an incoming TCP connection to a host:port address.
+
+## Moniker
+The moniker syntax for a TCP server transport is: `tcp-server:<local-host>:<local-port>`
+where `<local-host>` may be the address of a local network interface, or `_` to accept 
+connections on all local network interfaces.
+
+!!! example
+    `tcp-server:_:9001`  
+    Waits for and accepts connections on port `9001`

docs/mkdocs/src/transports/udp.md

@@ -0,0 +1,11 @@
+UDP TRANSPORT
+=============
+
+The UDP transport is a UDP socket, receiving packets on a specified port number, and sending packets to a specified host and port number.
+
+## Moniker
+The moniker syntax for a UDP transport is: `udp:<local-host>:<local-port>,<remote-host>:<remote-port>`.
+
+!!! example
+    `udp:0.0.0.0:9000,127.0.0.1:9001`  
+    UDP transport where packets are received on port `9000` and sent to `127.0.0.1` on port `9001`

docs/mkdocs/src/transports/usb.md

@@ -0,0 +1,19 @@
+USB TRANSPORT
+=============
+
+The USB transport interfaces with a local Bluetooth USB dongle.
+
+## Moniker
+The moniker for a USB transport is either `usb:<index>` or `usb:<vendor>:<product>`
+with `<index>` as the 0-based index to select amongst all the devices that appear to be supporting Bluetooth HCI (0 being the first one), or where `<vendor>` and `<product>` are a vendor ID and product ID in hexadecimal.
+
+!!! example
+    `usb:04b4:f901`  
+    Use the USB dongle with `vendor` equal to `04b4` and `product` equal to `f901`
+
+    `usb:0`  
+    Use the first Bluetooth dongle
+
+## Alternative
+The library includes two different implementations of the USB transport, implemented using different python bindings for `libusb`.
+Using the transport prefix `pyusb:` instead of `usb:` selects the implementation based on  [PyUSB](https://pypi.org/project/pyusb/), using the synchronous API of `libusb`, whereas the default implementation is based on [libusb1](https://pypi.org/project/libusb1/), using the asynchronous API of `libusb`. In order to use the alternative PyUSB-based implementation, you need to ensure that you have installed that python module, as it isn't installed by default as a dependency of Bumble.

docs/mkdocs/src/transports/vhci.md

@@ -0,0 +1,14 @@
+VHCI TRANSPORT
+==============
+
+The VHCI transport allows attaching a virtual controller to the Bluetooth stack on operating systems that offer a VHCI driver (Linux, if enabled, maybe others).
+
+!!! note
+    This type of transport can only be used for virtual controllers, not virtual hosts
+
+## Moniker
+The moniker for a VHCI transport is either just `vhci` (to use the default VHCI device path at `/dev/vhci`), or `vhci:<path>` where `<path>` is the path of a VHCI device.
+
+!!! example
+    `vhci`  
+    Attaches a virtual controller transport to `/dev/vhci`

docs/mkdocs/src/transports/ws_client.md

@@ -0,0 +1,11 @@
+UDP TRANSPORT
+=============
+
+The UDP transport is a UDP socket, receiving packets on a specified port number, and sending packets to a specified host and port number.
+
+## Moniker
+The moniker syntax for a UDP transport is: `udp:<local-host>:<local-port>,<remote-host>:<remote-port>`.
+
+!!! example
+    `udp:0.0.0.0:9000,127.0.0.1:9001`  
+    UDP transport where packets are received on port `9000` and sent to `127.0.0.1` on port `9001`

docs/mkdocs/src/transports/ws_server.md

@@ -0,0 +1,11 @@
+UDP TRANSPORT
+=============
+
+The UDP transport is a UDP socket, receiving packets on a specified port number, and sending packets to a specified host and port number.
+
+## Moniker
+The moniker syntax for a UDP transport is: `udp:<local-host>:<local-port>,<remote-host>:<remote-port>`.
+
+!!! example
+    `udp:0.0.0.0:9000,127.0.0.1:9001`  
+    UDP transport where packets are received on port `9000` and sent to `127.0.0.1` on port `9001`

docs/mkdocs/src/use_cases/index.md

@@ -0,0 +1,11 @@
+USE CASES
+=========
+
+While the Bumble project aims to be a general purpose set of libraries and tools for any purpose, there are some typical use case patterns that are typical and representative of what can be done.
+
+  * [Use case 1](use_case_1.md) - Bumble python application connected to a "real" Bluetooth device with a physical controller
+  * [Use case 2](use_case_2.md) - Native Bluetooth application connected to a Bumble python application with virtual controller
+  * [Use case 3](use_case_3.md) - Emulated Bluetooth device connected to a Bumble python application with virtual controller
+  * [Use case 4](use_case_4.md) - Connecting two emulated Bluetooth devices
+  * [Use case 5](use_case_5.md) - Connecting multiple Bumble python applications
+  * [Use case 6](use_case_6.md) - Connecting an emulated Bluetooth device to a physical controller

docs/mkdocs/src/use_cases/use_case_1.md

@@ -0,0 +1,14 @@
+USE CASE 1
+==========
+
+# Bumble python application connected to a device with a "real" Bluetooth controller
+
+Write a python application (ex: a GATT client that will connect to a hear rate sensor, or a GATT server exposing a battery level) that can connect to or receive connections from a "real" Bluetooth device (like a sensor, or a mobile phone) using a Bluetooth controller (a USB dongle, or HCI-UART controller)
+
+```
++--------++--------+             +------------+             +-----------+
+| Bumble || Bumble |             | Physical   |             | Bluetooth |
+| Python || Host   |<--  HCI  -->| Controller |{...radio...}| Device    |
+| App    ||        |  Transport  |            |             |           |
++--------++--------+             +------------+             +-----------+
+```

docs/mkdocs/src/use_cases/use_case_2.md

@@ -0,0 +1,14 @@
+USE CASE 2
+==========
+
+# Native Bluetooth application connected to a Bumble python application with virtual controller
+
+Connect a native Bluetooth application, running on a host with Bluetooth stack to which we can attach a virtual controller (Linux for example), to a Bumble python application (ex: a GATT server or client).
+
+```
++-----------+             +------------+                +------------++--------++--------+
+| Native    |             | Bumble     |    Bumble      | Bumble     || Bumble || Bumble |
+| Bluetooth |<--  HCI  -->| Virtual    |<== Local or ==>| Virtual    || Host   || Python |
+| App       |  Transport  | Controller |    Remote      | Controller ||        || App    |
++-----------+             +------------+    Link        +------------++--------++--------+
+```

docs/mkdocs/src/use_cases/use_case_3.md

@@ -0,0 +1,14 @@
+USE CASE 3
+==========
+
+# Emulated Bluetooth device connected to a Bumble python application with virtual controller
+
+Connect an emulated Bluetooth device (ex: an Android emulator, or an embedded device emulator) to a Bumble python application (ex: a GATT server or client).
+
+```
++-----------+             +------------+                +------------++--------++--------+
+| Emulated  |             | Bumble     |    Bumble      | Bumble     || Bumble || Bumble |
+| Bluetooth |<--  HCI  -->| Virtual    |<== Local or ==>| Virtual    || Host   || Python |
+| Device    |  Transport  | Controller |    Remote      | Controller ||        || App    |
++-----------+             +------------+    Link        +------------++--------++--------+
+```

docs/mkdocs/src/use_cases/use_case_4.md

@@ -0,0 +1,14 @@
+USE CASE 4
+==========
+
+# Connecting two emulated Bluetooth devices
+
+Connect two emulated Bluetooth device (ex: an Android emulator, or an embedded device emulator) to each other
+
+```
++-----------+             +------------+                +------------+             +-----------+ 
+| Emulated  |             | Bumble     |    Bumble      | Bumble     |             | Emulated  |
+| Bluetooth |<--  HCI  -->| Virtual    |<== Local or ==>| Virtual    |<--  HCI  -->| Bluetooth |
+| Device    |  Transport  | Controller |    Remote      | Controller |  Transport  | Device    |
++-----------+             +------------+    Link        +------------+             +-----------+
+```

docs/mkdocs/src/use_cases/use_case_5.md

@@ -0,0 +1,20 @@
+USE CASE 5
+==========
+
+# Connecting multiple Bumble python applications
+
+Write several python applications (ex: a GATT client that will connect to a hear rate sensor, or a GATT server exposing a battery level) and connect them together
+
+```
++--------++--------++------------+                        +------------++--------++--------+
+| Bumble || Bumble || Bumble     |                        | Bumble     || Bumble || Bumble |
+| Python || Host   || Controller |<--+                +-->| Controller || Host   || Python |
+| App    ||        ||            |   |   +--------+   |   |            ||        || App    |
++--------++--------++------------+   +-->| Bumble |<--+   +------------++--------++--------+
+                                         | Link   |
++--------++--------++------------+   +-->| Relay  |<--+   +------------++--------++--------+
+| Bumble || Bumble || Bumble     |   |   +--------+   |   | Bumble     || Bumble || Bumble |
+| Python || Host   || Controller |<--+                +-->| Controller || Host   || Python |
+| App    ||        ||            |                        |            ||        || App    |
++--------++--------++------------+                        +------------++--------++--------+
+```

docs/mkdocs/src/use_cases/use_case_6.md

@@ -0,0 +1,14 @@
+USE CASE 6
+==========
+
+# Connecting an emulated Bluetooth device to a physical controller
+
+It can be useful to connect an emulated device (like a phone simulator, or an emulated embedded device) to a physical controller in order to connect to other Bluetooth devices. By doing this via a Bumble HCI bridge, it becomes easy to inspect the HCI packets exchanged with the controller, and possibly filter/change them if needed (for example to support vendor-specific HCI extensions).
+
+```
++-----------+             +--------+             +------------+             +-----------+ 
+| Emulated  |             | Bumble |             | Physical   |             | Bluetooth |
+| Bluetooth |<--  HCI  -->| HCI    |<--  HCI  -->| Controller |{...radio...}| Device    |
+| Device    |  Transport  | Bridge |  Transport  |            |             |           |
++-----------+             +--------+             +------------+             +-----------+
+```