Skip to content

Commit 7282cea

Browse files
dlechdlech
committed
doc: add troubleshooting page
1 parent 29866b5 commit 7282cea

5 files changed

+154
-6
lines changed

‎.gitattributes

+6-6
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
#
1818
# Merging from the command prompt will add diff markers to the files if there
1919
# are conflicts (Merging from VS is not affected by the settings below, in VS
20-
# the diff markers are never inserted). Diff markers may cause the following
20+
# the diff markers are never inserted). Diff markers may cause the following
2121
# file extensions to fail to load in VS. An alternative would be to treat
2222
# these files as binary and thus will always conflict and require user
2323
# intervention with every merge. To do so, just uncomment the entries below
@@ -40,15 +40,15 @@
4040
#
4141
# image files are treated as binary by default.
4242
###############################################################################
43-
#*.jpg binary
44-
#*.png binary
45-
#*.gif binary
43+
*.jpg binary
44+
*.png binary
45+
*.gif binary
4646

4747
###############################################################################
4848
# diff behavior for common document formats
49-
#
49+
#
5050
# Convert binary document formats to text before diffing them. This feature
51-
# is only available from the command line. Turn it on by uncommenting the
51+
# is only available from the command line. Turn it on by uncommenting the
5252
# entries below.
5353
###############################################################################
5454
#*.doc diff=astextplain

‎CHANGELOG.rst

+1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Added
1515

1616
* Timeout for BlueZ backend connect call to avoid potential infinite hanging. Merged #306.
1717
* Added Interfaces API docs again.
18+
* Troubleshooting documentation.
1819

1920
Changed
2021
~~~~~~~

‎docs/images/win-10-start-cmd-as-admin.png

44.3 KB
Loading

‎docs/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ Contents:
5353
usage
5454
backends/index
5555
api
56+
troubleshooting
5657
contributing
5758
authors
5859
history

‎docs/troubleshooting.rst

+146
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
===============
2+
Troubleshooting
3+
===============
4+
5+
When things don't seem to be working right, here are some things to try.
6+
7+
8+
--------------
9+
Enable Logging
10+
--------------
11+
12+
The easiest way to enable logging is to set the ``BLEAK_LOGGING`` environment variable.
13+
Setting the variable depends on what type of terminal you are using.
14+
15+
Posix (Linux, macOS, Cygwin, etc.)::
16+
17+
export BLEAK_LOGGING=1
18+
19+
Power Shell::
20+
21+
$env:BLEAK_LOGGING=1
22+
23+
Windows Command Prompt::
24+
25+
set BLEAK_LOGGING=1
26+
27+
Then run your Python script in the same terminal.
28+
29+
30+
-------------------------
31+
Capture Bluetooth Traffic
32+
-------------------------
33+
34+
Sometimes it can be helpful to see what is actually going over the air between
35+
the OS and the Bluetooth device. There are tools available to capture HCI packets
36+
and decode them.
37+
38+
Windows 10
39+
==========
40+
41+
No special software is required on Windows to capture Bluetooth traffic, however
42+
special software is required to convert it to a useful format.
43+
44+
Capture
45+
-------
46+
47+
To capture Bluetooth traffic:
48+
49+
1. Open a Command Prompt as Administrator.
50+
51+
* Search start menu for ``cmd``.
52+
* Right-click *Command Prompt* and select *Run as Administrator*.
53+
54+
.. image:: images/win-10-start-cmd-as-admin.png
55+
:height: 200px
56+
:alt: Screenshot of Windows Start Menu showing Command Prompt selected
57+
and context menu with Run as Administrator selected.
58+
59+
2. Run the following command in the Administrator Command Prompt::
60+
61+
logman create trace "bth_hci" -ow -o C:\bth_hci.etl -p {8a1f9517-3a8c-4a9e-a018-4f17a200f277} 0xffffffffffffffff 0xff -nb 16 16 -bs 1024 -mode Circular -f bincirc -max 4096 -ets
62+
63+
.. tip:: ``C:\bth_hci.etl`` can be replaced with any file path you like.
64+
65+
3. Run your Python script in a different terminal (not as Administrator) to reproduce
66+
the problem.
67+
68+
4. In the Administrator Command Prompt run::
69+
70+
logman stop "bth_hci" -ets
71+
72+
73+
Decode
74+
------
75+
76+
Microsoft no longer has tools to directly view ``.etl`` files so in order to
77+
make use of the information, we need to convert it to a different file format.
78+
The `Windows Driver Kit <wdk_>`_ contains a tool to do this.
79+
80+
.. _wdk: https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk
81+
82+
1. Download and install the `Windows Driver Kit <wdk_>`_.
83+
84+
.. tip:: The install may give warnings about additional software not being
85+
installed. These warnings can be ignored since we just need a standalone
86+
executable file from the installation.
87+
88+
2. Run the following command::
89+
90+
"%ProgramFiles(x86)%\Windows Kits\10\Tools\x86\Bluetooth\BETLParse\btetlparse.exe" c:\bth_hci.etl
91+
92+
This will create a file with the same file name and a ``.cfa`` file extension
93+
(and an empty ``.txt`` file for some reason).
94+
95+
3. Download and install `Wireshark`_.
96+
97+
4. Open the ``.cfa`` file in Wireshark to view the captured Bluetooth traffic.
98+
99+
100+
.. _Wireshark: https://www.wireshark.org/
101+
102+
103+
macOS
104+
=====
105+
106+
On macOS, special software is required to capture and view Bluetooth traffic.
107+
You will need to sign up for an Apple Developer account to obtain this software.
108+
109+
1. Go to `<https://developer.apple.com/download/more/>`_ and download *Additional
110+
Tools for Xcode ...* where ... is the Xcode version corresponding to your macOS
111+
version (e.g. 12 for Big Sur, 11 for Mojave, etc.).
112+
113+
2. Open the disk image and in the *Hardware* folder, double-click the *PacketLogger.app*
114+
to run it.
115+
116+
3. Click the *Clear* button in the toolbar to clear the old data.
117+
118+
4. Run your Python script to reproduce the problem.
119+
120+
5. Click the *Stop* button in the toolbar to stop the capture.
121+
122+
.. tip:: The Bluetooth traffic can be viewed in the *PacketLogger.app* or it can
123+
be saved to a file and viewed in `Wireshark`_.
124+
125+
126+
Linux
127+
=====
128+
129+
On Linux, `Wireshark`_ can be used to capture and view Bluetooth traffic.
130+
131+
1. Install Wireshark. Most distributions include a ``wireshark`` package. For
132+
example, on Debian/Ubuntu based distributions::
133+
134+
sudo apt update && sudo apt install wireshark
135+
136+
2. Start Wireshark and select your Bluetooth adapter, then start a capture.
137+
138+
.. tip:: Visit the `Wireshark Wiki`_ for help with configuring permissions
139+
and making sure proper drivers are installed.
140+
141+
3. Run your Python script to reproduce the problem.
142+
143+
4. Click the stop button in Wireshark to stop the capture.
144+
145+
146+
.. _Wireshark Wiki: https://gitlab.com/wireshark/wireshark/-/wikis/CaptureSetup

0 commit comments

Comments
 (0)