From d364f4e7296ad10ad7c86c005e2c2a00ff59c8d9 Mon Sep 17 00:00:00 2001
From: Peter Harper <peter.harper@raspberrypi.com>
Date: Tue, 3 Oct 2023 15:48:33 +0100
Subject: [PATCH] Add a README for bluetooth debugging

Fixes #426
---
 README.md           |  2 ++
 pico_w/bt/README.md | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+)
 create mode 100644 pico_w/bt/README.md

diff --git a/README.md b/README.md
index 1b693554a..ad7eee6d3 100644
--- a/README.md
+++ b/README.md
@@ -153,6 +153,8 @@ default being *background*. This can be changed by passing `-DBTSTACK_EXAMPLE_TY
 examples can be built (which may be slow) by passing `-DBTSTACK_EXAMPLE_TYPE=all`
 Freertos versions can only be built if `FREERTOS_KERNEL_PATH` is defined.
 
+The Bluetooth examples that use audio require code in [pico-extras](https://github.com/raspberrypi/pico-extras). Pass `-DPICO_EXTRAS_PATH=${HOME}/pico-extras` on the cmake command line or define `PICO_EXTRAS_PATH=${HOME}/pico-extras` in your environment and re-run cmake to include them in the build.
+
 App|Description
 ---|---
 [picow_bt_example_a2dp_sink_demo](https://github.com/bluekitchen/btstack/tree/master/example/a2dp_sink_demo.c) | A2DP Sink - Receive Audio Stream and Control Playback.
diff --git a/pico_w/bt/README.md b/pico_w/bt/README.md
new file mode 100644
index 000000000..7c0c3e545
--- /dev/null
+++ b/pico_w/bt/README.md
@@ -0,0 +1,18 @@
+# Pico W Bluetooth Examples
+
+The source for most of the Bluetooth examples is stored in `pico-sdk/lib/btstack/example`.
+There's a standalone example in `pico-examples/pico_w/bt/standalone`.
+
+## Debugging
+
+To debug Bluetooth issues you can enable [btstack](https://github.com/bluekitchen/btstack) debug output which also enables packet logging.
+Define `WANT_HCI_DUMP=1` in your CMakeLists.txt file. Uncomment this line to enable debug in the btstack examples.
+
+	target_compile_definitions(picow_bt_example_common INTERFACE
+	    #WANT_HCI_DUMP=1 # This enables btstack debug
+	    )
+
+## Packet logging
+
+To view packet logs, save the output from the debug port (e.g. the uart) to a file and afterwards run `pico-sdk/lib/btstack/tool/create_packet_log.py <filename>`.
+This will generate a file with the same name except for a `pklg` extension. This can be opened in the [Wireshark](https://www.wireshark.org) application to analyze communications activity.