auracaster/bumble_mirror
3
0
Fork 1
mirror of https://github.com/google/bumble.git synced 2026-06-12 09:22:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Deployed 7ae3a1d with MkDocs version: 1.3.1

Browse Source
This commit is contained in:
Gilles Boccon-Gibod
2022-12-18 20:55:03 -08:00
parent 3581c8d710
commit 5f0477bd28
53 changed files with 4623 additions and 561 deletions
Download Patch File Download Diff File Expand all files Collapse all files
404.html
+28
View File
@@ -229,6 +229,34 @@
<li class="md-nav__item">
<a href="/development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="/development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
api/examples.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
api/guide.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
api/reference.html
+569 -451
View File
File diff suppressed because it is too large Load Diff
apps_and_tools/console.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/gatt_dump.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/gg_bridge.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/hci_bridge.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/index.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/link_relay.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/pair.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/show.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/unbond.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
apps_and_tools/usb_probe.html
+32 -4
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1221,8 +1249,8 @@
<h1 id="usb-probe-tool">USB PROBE TOOL<a class="headerlink" href="#usb-probe-tool" title="Permanent link">&para;</a></h1>
<p>This tool lists all the USB devices, with details about each device.
For each device, the different possible Bumble transport strings that can
refer to it are listed.
If the device is known to be a Bluetooth HCI device, its identifier is printed
refer to it are listed.
If the device is known to be a Bluetooth HCI device, its identifier is printed
in reverse colors, and the transport names in cyan color.
For other devices, regardless of their type, the transport names are printed
in red. Whether that device is actually a Bluetooth device or not depends on
@@ -1240,12 +1268,12 @@ When installed from PyPI, run as
<p>When running from the source distribution:
<div class="highlight"><pre><span></span><code>$ python3 apps/usb-probe.py
</code></pre></div></p>
<p>or </p>
<p>or</p>
<div class="highlight"><pre><span></span><code>$ python3 apps/usb-probe.py --verbose
</code></pre></div>
<div class="admonition example">
<p class="admonition-title">Example</p>
<div class="highlight"><pre><span></span><code>$ python3 apps/usb_probe.py
<div class="highlight"><pre><span></span><code>$ python3 apps/usb_probe.py
ID 0A12:0001
Bumble Transport Names: usb:0 or usb:0A12:0001
components/controller.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
components/gatt.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
components/host.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
components/security_manager.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
development/code_style.html
+1312
View File
File diff suppressed because it is too large Load Diff
development/contributing.html
+1287
View File
File diff suppressed because it is too large Load Diff
development/python_environments.html
+35 -7
View File
@@ -311,6 +311,34 @@
<li class="md-nav__item">
<a href="contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1287,26 +1315,26 @@
<h1 id="python-environments">PYTHON ENVIRONMENTS<a class="headerlink" href="#python-environments" title="Permanent link">&para;</a></h1>
<p>When you don't want to install Bumble in your main/default python environment,
<p>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.</p>
<p>There are many flavors of python environments and dependency managers.
<p>There are many flavors of python environments and dependency managers.
This page describes a few of the most common ones.</p>
<h2 id="venv">venv<a class="headerlink" href="#venv" title="Permanent link">&para;</a></h2>
<p><code>venv</code> is a standard module that is included with python.
Visit the <a href="https://docs.python.org/3/library/venv.html"><code>venv</code> documentation</a> page for details.</p>
<h2 id="pyenv">Pyenv<a class="headerlink" href="#pyenv" title="Permanent link">&para;</a></h2>
<p><code>pyenv</code> 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.<br />
<p><code>pyenv</code> 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 <a href="https://github.com/pyenv/pyenv"><code>pyenv</code> site</a> for instructions on how to install
and use <code>pyenv</code></p>
<h2 id="conda">Conda<a class="headerlink" href="#conda" title="Permanent link">&para;</a></h2>
<p>Conda is a convenient package manager and virtual environment.
The file <code>environment.yml</code> 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.<br />
working with Bumble.
Visit the <a href="https://docs.conda.io/en/latest/">Conda site</a> for instructions on how to install
and use Conda.
A few useful commands: </p>
A few useful commands:</p>
<h3 id="create-a-new-bumble-conda-environment">Create a new <code>bumble</code> Conda environment<a class="headerlink" href="#create-a-new-bumble-conda-environment" title="Permanent link">&para;</a></h3>
<p><div class="highlight"><pre><span></span><code>$ conda env create -f environment.yml
</code></pre></div>
@@ -1349,13 +1377,13 @@ This will create a new environment, named <code>bumble</code>, which you can the
</a>
<a href="../use_cases/index.html" title="Overview" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
<a href="contributing.html" title="Contributing" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
<span class="md-flex__ellipsis">
<span class="md-footer-nav__direction">
Next
</span>
Overview
Contributing
</span>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
examples/index.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
getting_started.html
+38 -9
View File
@@ -244,6 +244,34 @@
<li class="md-nav__item">
<a href="development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1174,16 +1202,16 @@
<h1 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites" title="Permanent link">&para;</a></h1>
<p>You need Python 3.8 or above. Python &gt;= 3.9 is recommended, but 3.8 should be sufficient if
necessary (there may be some optional functionality that will not work on some platforms with
python 3.8).<br />
python 3.8).
Visit the <a href="https://www.python.org/">Python site</a> for instructions on how to install Python
for your platform.<br />
for your platform.
Throughout the documentation, when shell commands are shown, it is assumed that you can
invoke Python as
<div class="highlight"><pre><span></span><code>$ python
</code></pre></div>
If invoking python is different on your platform (it may be <code>python3</code> for example, or just <code>py</code> or <code>py.exe</code>),
If invoking python is different on your platform (it may be <code>python3</code> for example, or just <code>py</code> or <code>py.exe</code>),
adjust accordingly.</p>
<p>You may be simply using Bumble as a module for your own application or as a dependency to your own
<p>You may be simply using Bumble as a module for your own application or as a dependency to your own
module, or you may be working on modifying or contributing to the Bumble module or example code
itself.</p>
<h1 id="using-bumble-as-a-python-module">Using Bumble As A Python Module<a class="headerlink" href="#using-bumble-as-a-python-module" title="Permanent link">&para;</a></h1>
@@ -1216,13 +1244,14 @@ distribution
</code></pre></div></p>
<h1 id="working-on-the-bumble-code">Working On The Bumble Code<a class="headerlink" href="#working-on-the-bumble-code" title="Permanent link">&para;</a></h1>
<p>When you work on the Bumble code itself, and run some of the tests or example apps, or import the
module in your own code, you typically either install the package from source in "development mode" as described above, or you may choose to skip the install phase. </p>
module in your own code, you typically either install the package from source in "development mode" as described above, or you may choose to skip the install phase.</p>
<p>If you plan on contributing to the project, please read the <a href="development/contributing.html">contributing</a> section.</p>
<h2 id="without-installing">Without Installing<a class="headerlink" href="#without-installing" title="Permanent link">&para;</a></h2>
<p>If you prefer not to install the package (even in development mode), you can load the module directly from its location in the project.
<p>If you prefer not to install the package (even in development mode), you can load the module directly from its location in the project.
A simple way to do that is to set your <code>PYTHONPATH</code> to
point to the root project directory, where the <code>bumble</code> subdirectory is located. You may set
<code>PYTHONPATH</code> globally, or locally with each command line execution (on Unix-like systems).</p>
<p>Example with a global <code>PYTHONPATH</code>, from a unix shell, when the working directory is the root
<p>Example with a global <code>PYTHONPATH</code>, from a unix shell, when the working directory is the root
directory of the project.</p>
<div class="highlight"><pre><span></span><code>$ <span class="nb">export</span> <span class="nv">PYTHONPATH</span><span class="o">=</span>.
$ python apps/console.py serial:/dev/tty.usbmodem0006839912171
@@ -1237,12 +1266,12 @@ $ python run_scanner.py usb:0
<div class="highlight"><pre><span></span><code>$ PYTHONPATH=. python examples/run_advertiser.py examples/device1.json serial:/dev/tty.usbmodem0006839912171
</code></pre></div></p>
<h1 id="where-to-go-next">Where To Go Next<a class="headerlink" href="#where-to-go-next" title="Permanent link">&para;</a></h1>
<p>Once you've installed or downloaded Bumble, you can either start using some of the
<p>Once you've installed or downloaded Bumble, you can either start using some of the
<a href="apps_and_tools/index.html">Bundled apps and tools</a>, or look at the <a href="examples/index.html">examples</a>
to get a feel for how to use the APIs, and start writing your own applications.</p>
<p>Depending on the use case you're interested in exploring, you may need to use a physical Bluetooth
controller, like a USB dongle or a board with a Bluetooth radio. Visit the <a href="hardware/index.html">Hardware page</a>
for more information on using a physical radio, and/or the <a href="transports/index.html">Transports page</a> for more
for more information on using a physical radio, and/or the <a href="transports/index.html">Transports page</a> for more
details on interfacing with either hardware modules or virtual controllers over various transports.</p>
hardware/index.html
+33 -5
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1173,11 +1201,11 @@
<h1 id="hardware">HARDWARE<a class="headerlink" href="#hardware" title="Permanent link">&para;</a></h1>
<p>The Bumble Host connects to a controller over an <a href="../transports/index.html">HCI Transport</a>.
To use a hardware controller attached to the host on which the host application is running, the transport is typically either <a href="../transports/serial.html">HCI over UART</a> or <a href="../transports/usb.html">HCI over USB</a>.
On Linux, the <a href="../transports/vhci.html">VHCI Transport</a> can be used to communicate with any controller hardware managed by the operating system. Alternatively, a remote controller (a phyiscal controller attached to a remote host) can be used by connecting one of the networked transports (such as the <a href="../transports/tcp_client.html">TCP Client transport</a>, the <a href="../transports/tcp_server.html">TCP Server transport</a> or the <a href="../transports/udp.html">UDP Transport</a>) to an <a href="../apps_and_tools/hci_bridge">HCI Bridge</a> bridging the network transport to a physical controller on a remote host. </p>
<p>In theory, any controller that is compliant with the HCI over UART or HCI over USB protocols can be used. </p>
<p>HCI over USB is very common, implemented by a number of commercial Bluetooth dongles. </p>
<p>The Bumble Host connects to a controller over an <a href="../transports/index.html">HCI Transport</a>.
To use a hardware controller attached to the host on which the host application is running, the transport is typically either <a href="../transports/serial.html">HCI over UART</a> or <a href="../transports/usb.html">HCI over USB</a>.
On Linux, the <a href="../transports/vhci.html">VHCI Transport</a> can be used to communicate with any controller hardware managed by the operating system. Alternatively, a remote controller (a phyiscal controller attached to a remote host) can be used by connecting one of the networked transports (such as the <a href="../transports/tcp_client.html">TCP Client transport</a>, the <a href="../transports/tcp_server.html">TCP Server transport</a> or the <a href="../transports/udp.html">UDP Transport</a>) to an <a href="../apps_and_tools/hci_bridge">HCI Bridge</a> bridging the network transport to a physical controller on a remote host.</p>
<p>In theory, any controller that is compliant with the HCI over UART or HCI over USB protocols can be used.</p>
<p>HCI over USB is very common, implemented by a number of commercial Bluetooth dongles.</p>
<p>It is also possible to use an embedded development board, running a specialized application, such as the <a href="https://docs.zephyrproject.org/latest/samples/bluetooth/hci_uart/README.html"><code>HCI UART</code></a> and <a href="https://docs.zephyrproject.org/latest/samples/bluetooth/hci_usb/README.html"><code>HCI USB</code></a> demo applications from the <a href="https://www.zephyrproject.org/">Zephyr project</a>, or the <a href="https://mynewt.apache.org/latest/tutorials/ble/blehci_project.html"><code>blehci</code></a> application from <a href="https://mynewt.apache.org/">mynewt/nimble</a></p>
<p>Some specific USB dongles and embedded boards that are known to work include:</p>
<ul>
images/bumble_layers.svg
+1 -1
View File
File diff suppressed because one or more lines are too long
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 113 KiB

After

Width:  |  Height:  |  Size: 113 KiB

index.html
+28
View File
@@ -454,6 +454,34 @@
<li class="md-nav__item">
<a href="development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
platforms/android.html
+34 -6
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1262,12 +1290,12 @@
<h1 id="android-platform"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.61 15.15c-.46 0-.84-.37-.84-.83s.38-.82.84-.82c.46 0 .84.36.84.82 0 .46-.38.83-.84.83m-9.2 0c-.46 0-.84-.37-.84-.83 0-.46.38-.82.84-.82.46 0 .83.36.83.82 0 .46-.37.83-.83.83m9.5-5.01 1.67-2.88c.09-.17.03-.38-.13-.47-.17-.1-.38-.04-.45.13l-1.71 2.91A10.15 10.15 0 0 0 12 8.91c-1.53 0-3 .33-4.27.91L6.04 6.91a.334.334 0 0 0-.47-.13c-.17.09-.22.3-.13.47l1.66 2.88C4.25 11.69 2.29 14.58 2 18h20c-.28-3.41-2.23-6.3-5.09-7.86Z"/></svg></span> ANDROID PLATFORM<a class="headerlink" href="#android-platform" title="Permanent link">&para;</a></h1>
<p>Using Bumble with Android is not about running the Bumble stack on the Android
OS itself, but rather using Bumble with the Bluetooth support of the Android
OS itself, but rather using Bumble with the Bluetooth support of the Android
emulator.</p>
<p>The two main use cases are:</p>
<ul>
<li>Connecting the Bumble host stack to the Android emulator's virtual controller.</li>
<li>Using Bumble as an HCI bridge to connect the Android emulator to a physical
<li>Using Bumble as an HCI bridge to connect the Android emulator to a physical
Bluetooth controller, such as a USB dongle</li>
</ul>
<div class="admonition warning">
@@ -1277,13 +1305,13 @@ be evolving. The information contained here be somewhat out of sync with the
version of the emulator you are using.
You will need version 31.3.8.0 or later.</p>
</div>
<p>The Android emulator supports Bluetooth in two ways: either by exposing virtual
<p>The Android emulator supports Bluetooth in two ways: either by exposing virtual
Bluetooth controllers to which you can connect a virtual Bluetooth host stack, or
by exposing an way to connect your own virtual controller to the Android Bluetooth
stack via a virtual HCI interface.
Both ways are controlled via gRPC requests to the Android emulator.</p>
<h2 id="launching-the-emulator">Launching the Emulator<a class="headerlink" href="#launching-the-emulator" title="Permanent link">&para;</a></h2>
<p>If the version of the emulator you are running does not yet support enabling
<p>If the version of the emulator you are running does not yet support enabling
Bluetooth support by default or automatically, you must launch the emulator from
the command line.</p>
<div class="admonition tip">
@@ -1299,7 +1327,7 @@ communicate link layer packets between them, thus creating a virtual radio netwo
Configuring a Bumble Device instance to use Root Canal as a virtual controller
allows that virtual device to communicate with the Android Bluetooth stack, and
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
To connect a Bumble host stack to a Root Canal virtual controller instance, use
the bumble <code>android-emulator</code> transport in <code>host</code> mode (the default).</p>
<div class="admonition example">
<p class="admonition-title">Run the example GATT server connected to the emulator</p>
@@ -1330,7 +1358,7 @@ before attaching the virtual controller, then re-enable it once attached.</p>
</div>
<h2 id="other-tools">Other Tools<a class="headerlink" href="#other-tools" title="Permanent link">&para;</a></h2>
<p>The <code>show</code> application that's included with Bumble can be used to parse and pretty-print the HCI packets
from an Android HCI "snoop log" (see <a href="https://source.android.com/devices/bluetooth/verifying_debugging">this page</a>
from an Android HCI "snoop log" (see <a href="https://source.android.com/devices/bluetooth/verifying_debugging">this page</a>
for details on how to obtain HCI snoop logs from an Android device).
Use the <code>--format snoop</code> option to specify that the file is in that specific format.</p>
<div class="admonition example">
platforms/index.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
platforms/linux.html
+36 -8
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1432,8 +1460,8 @@ The 3 main types of physical Bluetooth controllers are:</p>
<div class="admonition tip">
<p class="admonition-title">Conflicts with the kernel and BlueZ</p>
<p>If your use a USB dongle that is recognized by your kernel as a supported Bluetooth device, it is
likely that the kernel driver will claim that USB device and attach it to the BlueZ stack.
If you want to claim ownership of it to use with Bumble, you will need to set the state of the corresponding HCI interface as <code>DOWN</code>.
likely that the kernel driver will claim that USB device and attach it to the BlueZ stack.
If you want to claim ownership of it to use with Bumble, you will need to set the state of the corresponding HCI interface as <code>DOWN</code>.
HCI interfaces are numbered, starting from 0 (i.e <code>hci0</code>, <code>hci1</code>, ...).</p>
<p>For example, to bring <code>hci0</code> down:
<div class="highlight"><pre><span></span><code>$ sudo hciconfig hci0 down
@@ -1450,7 +1478,7 @@ close it, so you may need to bring the interface back <code>UP</code> before usi
<p class="admonition-title">USB Permissions</p>
<p>By default, when running as a regular user, you won't have the permission to use
arbitrary USB devices.
You can change the permissions for a specific USB device based on its bus number and
You can change the permissions for a specific USB device based on its bus number and
device number (you can use <code>lsusb</code> to find the Bus and Device numbers for your Bluetooth
dongle).</p>
<p>Example:
@@ -1474,7 +1502,7 @@ You can bring a HCI controller <code>UP</code> or <code>DOWN</code> with <code>h
<p class="admonition-title">HCI Socket Permissions</p>
<p>By default, when running as a regular user, you won't have the permission to use
an HCI socket to a Bluetooth controller (you may see an exception like <code>PermissionError: [Errno 1] Operation not permitted</code>).</p>
<p>If you want to run without using <code>sudo</code>, you need to manage the capabilities by adding the appropriate entries in <code>/etc/security/capability.conf</code> to grant a user or group the <code>cap_net_admin</code> capability.<br />
<p>If you want to run without using <code>sudo</code>, you need to manage the capabilities by adding the appropriate entries in <code>/etc/security/capability.conf</code> to grant a user or group the <code>cap_net_admin</code> capability.
See <a href="https://manpages.ubuntu.com/manpages/bionic/man5/capability.conf.5.html">this manpage</a> for details.</p>
<p>Alternatively, if you are just experimenting temporarily, the <code>capsh</code> command may be useful in order
to execute a single command with enhanced permissions, as in this example:</p>
@@ -1492,20 +1520,20 @@ lists all available HCI controllers and their state.</p>
<div class="highlight"><pre><span></span><code>pi@raspberrypi:~ $ hciconfig
hci1: Type: Primary Bus: USB
BD Address: 00:16:A4:5A:40:F2 ACL MTU: 1021:8 SCO MTU: 64:1
DOWN
DOWN
RX bytes:84056 acl:0 sco:0 events:51 errors:0
TX bytes:1980 acl:0 sco:0 commands:90 errors:0
hci0: Type: Primary Bus: UART
BD Address: DC:A6:32:75:2C:97 ACL MTU: 1021:8 SCO MTU: 64:1
DOWN
DOWN
RX bytes:68038 acl:0 sco:0 events:692 errors:0
TX bytes:20105 acl:0 sco:0 commands:843 errors:0
</code></pre></div>
</div>
<div class="admonition tip">
<p class="admonition-title">Disabling <code>bluetoothd</code></p>
<p>When the Bluetooth daemon, <code>bluetoothd</code>, is running, it will try to use any HCI controller attached to the BlueZ stack, automatically. This means that whenever an HCI socket transport is released, it is likely that <code>bluetoothd</code> will take it over, so you will get a "device busy" condition (ex: <code>OSError: [Errno 16] Device or resource busy</code>). If that happens, you can always use
<p>When the Bluetooth daemon, <code>bluetoothd</code>, is running, it will try to use any HCI controller attached to the BlueZ stack, automatically. This means that whenever an HCI socket transport is released, it is likely that <code>bluetoothd</code> will take it over, so you will get a "device busy" condition (ex: <code>OSError: [Errno 16] Device or resource busy</code>). If that happens, you can always use
<div class="highlight"><pre><span></span><code>$ hciconfig hci0 down
</code></pre></div>
(or <code>hci&lt;X&gt;</code> with <code>&lt;X&gt;</code> being the index of the controller device you want to use), but a simpler solution is to just stop the <code>bluetoothd</code> daemon, with a command like:
@@ -1564,7 +1592,7 @@ In both cases, the controller can run locally on the Linux host, or remotely on
<div class="highlight"><pre><span></span><code>$ hciconfig
hci0: Type: Primary Bus: Virtual
BD Address: F6:F7:F8:F9:FA:FB ACL MTU: 27:64 SCO MTU: 0:0
UP RUNNING
UP RUNNING
RX bytes:0 acl:0 sco:0 events:43 errors:0
TX bytes:274 acl:0 sco:0 commands:43 errors:0
</code></pre></div></p>
platforms/macos.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
platforms/windows.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1222,7 +1250,7 @@
<h2 id="usb-hci">USB HCI<a class="headerlink" href="#usb-hci" title="Permanent link">&para;</a></h2>
<p>To use a Bluetooth USB dongle on Windows, you need a USB dongle that does not require a vendor Windows driver (the dongle will be used directly through the <a href="https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/winusb"><code>WinUSB</code></a> driver rather than through a vendor-supplied Windows driver).</p>
<p>In order to use the dongle, the <code>WinUSB</code> driver must be assigned to the USB device. It is likely that, by default, when you first plug in the dongle, it will be recognized by Windows as a Bluetooth USB device, and Windows will try to use it with its native Bluetooth stack. You will need to switch the driver, which can be done easily with the <a href="https://zadig.akeo.ie/">Zadig tool</a>.
In the Zadig tool, select your USB dongle device, and associate it with WinUSB.<br />
In the Zadig tool, select your USB dongle device, and associate it with WinUSB.
Once the WinUSB driver is correctly assigned to your device, you can confirm that by checking the settings with the Windows Device Manager control panel. Your device should appear under "Universal Serial Bus Device" (not under "Bluetooth"), and inspecting the driver details, you should see <code>winusb.sys</code> in the list of driver files.</p>
<p><img alt="USB Driver Details" src="winusb_driver.png" /></p>
sitemap.xml
+57 -47
View File
@@ -2,237 +2,247 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-10-11</lastmod>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
<url>
<loc>None</loc>
<lastmod>2022-12-19</lastmod>
<changefreq>daily</changefreq>
</url>
</urlset>
sitemap.xml.gz
BIN
View File
Binary file not shown.
transports/android_emulator.html
+34 -5
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1222,21 +1250,22 @@
<p>The Android emulator transport either connects, as a host, to a "Root Canal" virtual controller
("host" mode), or attaches a virtual controller to the Android Bluetooth host stack ("controller" mode).</p>
<h2 id="moniker">Moniker<a class="headerlink" href="#moniker" title="Permanent link">&para;</a></h2>
<p>The moniker syntax for an Android Emulator transport is: <code>android-emulator:[mode=&lt;host|controller&gt;][mode=&lt;host|controller&gt;]</code>.
Both the <code>mode=&lt;host|controller&gt;</code> and <code>mode=&lt;host|controller&gt;</code> parameters are optional (so the moniker <code>android-emulator</code> by itself is a valid moniker, which will create a transport in <code>host</code> mode, connected to <code>localhost</code> on the default gRPC port for the emulator)</p>
<p>The moniker syntax for an Android Emulator transport is: <code>android-emulator:[mode=&lt;host|controller&gt;][&lt;hostname&gt;:&lt;port&gt;]</code>, where
the <code>mode</code> parameter can specify running as a host or a controller, and <code>&lt;hostname&gt;:&lt;port&gt;</code> can specify a host name (or IP address) and TCP port number on which to reach the gRPC server for the emulator.
Both the <code>mode=&lt;host|controller&gt;</code> and <code>&lt;hostname&gt;:&lt;port&gt;</code> parameters are optional (so the moniker <code>android-emulator</code> by itself is a valid moniker, which will create a transport in <code>host</code> mode, connected to <code>localhost</code> on the default gRPC port for the emulator).</p>
<div class="admonition example example">
<p class="admonition-title">Example</p>
<p><code>android-emulator</code><br />
<p><code>android-emulator</code>
connect as a host to the emulator on localhost:8554</p>
</div>
<div class="admonition example example">
<p class="admonition-title">Example</p>
<p><code>android-emulator:mode=controller</code><br />
<p><code>android-emulator:mode=controller</code>
connect as a controller to the emulator on localhost:8554</p>
</div>
<div class="admonition example example">
<p class="admonition-title">Example</p>
<p><code>android-emulator:localhost:8555</code><br />
<p><code>android-emulator:localhost:8555</code>
connect as a host to the emulator on localhost:8555</p>
</div>
transports/file.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1225,7 +1253,7 @@ This is typically used to open a PTY, or unix driver, not for real files.</p>
<p>The moniker for a File transport is <code>file:&lt;path&gt;</code></p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>file:/dev/ttys001</code><br />
<p><code>file:/dev/ttys001</code>
Opens the pseudo terminal <code>/dev/ttys001</code> as a transport</p>
</div>
transports/hci_socket.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1228,7 +1256,7 @@
<p>The moniker for an HCI Socket transport is either just <code>hci-socket</code> (to use the default/first Bluetooth controller), or <code>hci-socket:&lt;index&gt;</code> where <code>&lt;index&gt;</code> is the 0-based index of a Bluetooth controller device.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>hci-socket</code><br />
<p><code>hci-socket</code>
Use an HCI socket to the first Bluetooth controller (<code>hci0 on Linux</code>)</p>
</div>
<div class="admonition tip">
transports/index.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
transports/pty.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1225,7 +1253,7 @@
Where <code>path</code>, is used, is the path name where a symbolic link to the PTY will be created for convenience (the link will be removed when the transport is closed or when the process exits).</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>pty:virtual_hci</code><br />
<p><code>pty:virtual_hci</code>
Creates a PTY entry and a symbolic link, named <code>virtual_hci</code>, linking to the PTY</p>
</div>
transports/serial.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1225,7 +1253,7 @@
When <code>&lt;speed&gt;</code> is omitted, the default value of 1000000 is used</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>serial:/dev/tty.usbmodem0006839912172,1000000</code><br />
<p><code>serial:/dev/tty.usbmodem0006839912172,1000000</code>
Opens the serial port <code>/dev/tty.usbmodem0006839912172</code> at <code>1000000</code>bps</p>
</div>
transports/tcp_client.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1224,7 +1252,7 @@
<p>The moniker syntax for a TCP client transport is: <code>tcp-client:&lt;remote-host&gt;:&lt;remote-port&gt;</code></p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>tcp-client:127.0.0.1:9001</code><br />
<p><code>tcp-client:127.0.0.1:9001</code>
Connects to port 9001 on the local host</p>
</div>
transports/tcp_server.html
+30 -2
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1222,11 +1250,11 @@
<p>The TCP Client transport uses an incoming TCP connection to a host:port address.</p>
<h2 id="moniker">Moniker<a class="headerlink" href="#moniker" title="Permanent link">&para;</a></h2>
<p>The moniker syntax for a TCP server transport is: <code>tcp-server:&lt;local-host&gt;:&lt;local-port&gt;</code>
where <code>&lt;local-host&gt;</code> may be the address of a local network interface, or <code>_</code> to accept
where <code>&lt;local-host&gt;</code> may be the address of a local network interface, or <code>_</code> to accept
connections on all local network interfaces.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>tcp-server:_:9001</code><br />
<p><code>tcp-server:_:9001</code>
Waits for and accepts connections on port <code>9001</code></p>
</div>
transports/udp.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1224,7 +1252,7 @@
<p>The moniker syntax for a UDP transport is: <code>udp:&lt;local-host&gt;:&lt;local-port&gt;,&lt;remote-host&gt;:&lt;remote-port&gt;</code>.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>udp:0.0.0.0:9000,127.0.0.1:9001</code><br />
<p><code>udp:0.0.0.0:9000,127.0.0.1:9001</code>
UDP transport where packets are received on port <code>9000</code> and sent to <code>127.0.0.1</code> on port <code>9001</code></p>
</div>
transports/usb.html
+47 -2
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -571,6 +599,13 @@
Alternative
</a>
</li>
<li class="md-nav__item">
<a href="#libusb" class="md-nav__link">
Libusb
</a>
</li>
<li class="md-nav__item">
@@ -1263,6 +1298,13 @@
Alternative
</a>
</li>
<li class="md-nav__item">
<a href="#libusb" class="md-nav__link">
Libusb
</a>
</li>
<li class="md-nav__item">
@@ -1345,9 +1387,9 @@ the first USB interface of the device will be used, regardless of the interface
This may be useful for some devices that use a custom class/subclass but may nonetheless work as-is.</p>
<div class="admonition examples">
<p class="admonition-title">Examples</p>
<p><code>usb:04b4:f901</code><br />
<p><code>usb:04b4:f901</code>
The USB dongle with <code>&lt;vendor&gt;</code> equal to <code>04b4</code> and <code>&lt;product&gt;</code> equal to <code>f901</code></p>
<p><code>usb:0</code><br />
<p><code>usb:0</code>
The first Bluetooth HCI dongle that's declared as such by Class/Subclass/Protocol</p>
<p><code>usb:04b4:f901/0016A45B05D8</code>
The USB dongle with <code>&lt;vendor&gt;</code> equal to <code>04b4</code>, <code>&lt;product&gt;</code> equal to <code>f901</code> and <code>&lt;serial&gt;</code> equal to <code>0016A45B05D8</code></p>
@@ -1359,6 +1401,9 @@ The BT USB dongle vendor=0B05 and product=17CB, in "forced" mode.</p>
<h2 id="alternative">Alternative<a class="headerlink" href="#alternative" title="Permanent link">&para;</a></h2>
<p>The library includes two different implementations of the USB transport, implemented using different python bindings for <code>libusb</code>.
Using the transport prefix <code>pyusb:</code> instead of <code>usb:</code> selects the implementation based on <a href="https://pypi.org/project/pyusb/">PyUSB</a>, using the synchronous API of <code>libusb</code>, whereas the default implementation is based on <a href="https://pypi.org/project/libusb1/">libusb1</a>, using the asynchronous API of <code>libusb</code>. In order to use the alternative PyUSB-based implementation, you need to ensure that you have installed that python module, as it isn't installed by default as a dependency of Bumble.</p>
<h2 id="libusb">Libusb<a class="headerlink" href="#libusb" title="Permanent link">&para;</a></h2>
<p>The <code>libusb-1.0</code> shared library is required to use both <code>usb</code> and <code>pyusb</code> transports. This library should be installed automatically with Bumble, as part of the <code>libusb_package</code> Python package.
If your OS or architecture is not supported by <code>libusb_package</code>, you can install a system-wide library with <code>brew install libusb</code> for Mac or <code>apt install libusb-1.0-0</code> for Linux.</p>
<h2 id="listing-available-usb-devices">Listing Available USB Devices<a class="headerlink" href="#listing-available-usb-devices" title="Permanent link">&para;</a></h2>
<h3 id="with-usb_probe">With <code>usb_probe</code><a class="headerlink" href="#with-usb_probe" title="Permanent link">&para;</a></h3>
<p>You can use the <a href="../apps_and_tools/usb_probe.html"><code>usb_probe</code></a> tool to list all the USB devices attached to your host computer.
transports/vhci.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1228,7 +1256,7 @@
<p>The moniker for a VHCI transport is either just <code>vhci</code> (to use the default VHCI device path at <code>/dev/vhci</code>), or <code>vhci:&lt;path&gt;</code> where <code>&lt;path&gt;</code> is the path of a VHCI device.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>vhci</code><br />
<p><code>vhci</code>
Attaches a virtual controller transport to <code>/dev/vhci</code></p>
</div>
transports/ws_client.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1224,7 +1252,7 @@
<p>The moniker syntax for a UDP transport is: <code>udp:&lt;local-host&gt;:&lt;local-port&gt;,&lt;remote-host&gt;:&lt;remote-port&gt;</code>.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>udp:0.0.0.0:9000,127.0.0.1:9001</code><br />
<p><code>udp:0.0.0.0:9000,127.0.0.1:9001</code>
UDP transport where packets are received on port <code>9000</code> and sent to <code>127.0.0.1</code> on port <code>9001</code></p>
</div>
transports/ws_server.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1224,7 +1252,7 @@
<p>The moniker syntax for a UDP transport is: <code>udp:&lt;local-host&gt;:&lt;local-port&gt;,&lt;remote-host&gt;:&lt;remote-port&gt;</code>.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p><code>udp:0.0.0.0:9000,127.0.0.1:9001</code><br />
<p><code>udp:0.0.0.0:9000,127.0.0.1:9001</code>
UDP transport where packets are received on port <code>9000</code> and sent to <code>127.0.0.1</code> on port <code>9001</code></p>
</div>
use_cases/index.html
+30 -2
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1200,7 +1228,7 @@
<div class="md-footer-nav">
<nav class="md-footer-nav__inner md-grid">
<a href="../development/python_environments.html" title="Python Environments" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
<a href="../development/code_style.html" title="Code Style" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
<div class="md-flex__cell md-flex__cell--shrink">
<i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
</div>
@@ -1209,7 +1237,7 @@
<span class="md-footer-nav__direction">
Previous
</span>
Python Environments
Code Style
</span>
</div>
</a>
use_cases/use_case_1.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
use_cases/use_case_2.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
use_cases/use_case_3.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
use_cases/use_case_4.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1175,7 +1203,7 @@
<h1 id="use-case-4">USE CASE 4<a class="headerlink" href="#use-case-4" title="Permanent link">&para;</a></h1>
<h1 id="connecting-two-emulated-bluetooth-devices">Connecting two emulated Bluetooth devices<a class="headerlink" href="#connecting-two-emulated-bluetooth-devices" title="Permanent link">&para;</a></h1>
<p>Connect two emulated Bluetooth device (ex: an Android emulator, or an embedded device emulator) to each other</p>
<div class="highlight"><pre><span></span><code>+-----------+ +------------+ +------------+ +-----------+
<div class="highlight"><pre><span></span><code>+-----------+ +------------+ +------------+ +-----------+
| Emulated | | Bumble | Bumble | Bumble | | Emulated |
| Bluetooth |&lt;-- HCI --&gt;| Virtual |&lt;== Local or ==&gt;| Virtual |&lt;-- HCI --&gt;| Bluetooth |
| Device | Transport | Controller | Remote | Controller | Transport | Device |
use_cases/use_case_5.html
+28
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
use_cases/use_case_6.html
+29 -1
View File
@@ -234,6 +234,34 @@
<li class="md-nav__item">
<a href="../development/contributing.html" class="md-nav__link">
Contributing
</a>
</li>
<li class="md-nav__item">
<a href="../development/code_style.html" class="md-nav__link">
Code Style
</a>
</li>
</ul>
</nav>
</li>
@@ -1175,7 +1203,7 @@
<h1 id="use-case-6">USE CASE 6<a class="headerlink" href="#use-case-6" title="Permanent link">&para;</a></h1>
<h1 id="connecting-an-emulated-bluetooth-device-to-a-physical-controller">Connecting an emulated Bluetooth device to a physical controller<a class="headerlink" href="#connecting-an-emulated-bluetooth-device-to-a-physical-controller" title="Permanent link">&para;</a></h1>
<p>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).</p>
<div class="highlight"><pre><span></span><code>+-----------+ +--------+ +------------+ +-----------+
<div class="highlight"><pre><span></span><code>+-----------+ +--------+ +------------+ +-----------+
| Emulated | | Bumble | | Physical | | Bluetooth |
| Bluetooth |&lt;-- HCI --&gt;| HCI |&lt;-- HCI --&gt;| Controller |{...radio...}| Device |
| Device | Transport | Bridge | Transport | | | |