initial import

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