initial import

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  |            |             |           |
++-----------+             +--------+             +------------+             +-----------+
+```