refactor doc

docs/mkdocs/mkdocs.yml

@@ -5,6 +5,8 @@ use_directory_urls: false
 nav:
   - Introduction: index.md
   - Getting Started: getting_started.md
+  - Development:
+    - Python Environments: development/python_environments.md
   - Use Cases:
     - Overview: use_cases/index.md
     - Use Case 1: use_cases/use_case_1.md

docs/mkdocs/src/apps_and_tools/index.md

@@ -7,6 +7,6 @@ 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
+  * [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.
+  * [Link Relay](link_relay.md) - WebSocket relay for virtual RemoteLink instances to communicate with each other.
 

docs/mkdocs/src/development/python_environments.md

@@ -0,0 +1,45 @@
+PYTHON ENVIRONMENTS
+===================
+
+When you don't want to install Bumble in your main/default python environment, 
+using a virtual environment, where the package and its dependencies can be
+installed, isolated from the rest, may be useful.
+
+There are many flavors of python environments and dependency managers. 
+This page describes a few of the most common ones.
+
+
+## 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 site](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
+```

docs/mkdocs/src/getting_started.md

@@ -20,7 +20,7 @@ You may be simply using Bumble as a module for your own application or as a depe
 module, or you may be working on modifying or contributing to the Bumble module or example code
 itself.
 
-# Working With Bumble As A Module
+# Using Bumble As A Python Module
 
 ## Installing
 
@@ -29,48 +29,13 @@ 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
+    python environment, or in a virtual environment, such as a `venv`, `pyenv` or `conda` environment.
-
+    See the [Python Environments page](development/python_environments.md) page for details.
-### 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`. Run in a command shell in the directory where you downloaded the source
-
+distribution
-Install with `pip`
 ```
 $ python -m pip install -e .
 ```
@@ -129,3 +94,8 @@ Setting `PYTHONPATH` locally with each command would look something like:
 ```
 $ PYTHONPATH=. python examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171
 ```
+
+# Where To Go Next
+Once you've installed or downloaded Bumble, you can either start using some of the 
+[Bundled apps and tools](apps_and_tools/index.md), or look at the [examples](examples/index.md)
+to get a feel for how to use the APIs, and start writing your own applications.

docs/mkdocs/src/platforms/android.md

@@ -46,7 +46,7 @@ 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"
+!!! example "Run the example GATT server connected to the emulator"
     ``` shell
     $ python run_gatt_server.py device1.json android-emulator
     ```
@@ -57,7 +57,7 @@ This is an advanced use case, which may not be officially supported, but should
 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"
+!!! example "Launch the emulator with VHCI forwarding"
     In this example, we launch an emulator AVD named "Tiramisu"
     ```shell
     $ emulator -forward-vhci -avd Tiramisu
@@ -70,10 +70,20 @@ You will likely need to start the emulator from the command line, in order to sp
 
 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"
+!!! example "Connect the Android emulator to the first USB Bluetooth dongle, using the `hci_bridge` application"
     ```shell
     $ bumble-hci-bridge android-emulator:mode=controller usb:0
     ```
 
+## Other Tools
 
+The `show` application that's included with Bumble can be used to parse and pretty-print the HCI packets
+from an Android HCI "snoop log" (see [this page](https://source.android.com/devices/bluetooth/verifying_debugging) 
+for details on how to obtain HCI snoop logs from an Android device).
+Use the `--format snoop` option to specify that the file is in that specific format.
+
+!!! example "Analyze an Android HCI snoop log file"
+    ```shell
+    $ bumble-show --format snoop btsnoop_hci.log
+    ```