classAddress:''' Bluetooth Address (see Bluetooth spec Vol 6, Part B - 1.3 DEVICE ADDRESS) NOTE: the address bytes are stored in little-endian byte order here, so
@@ -1368,6 +1389,11 @@ address[0] is the LSB of the address, address[5] is the MSB.
RANDOM_IDENTITY_ADDRESS:'RANDOM_IDENTITY_ADDRESS',}
+ # Type declarations
+ NIL:Address
+ ANY:Address
+ ANY_RANDOM:Address
+
# pylint: disable-next=unnecessary-lambdaADDRESS_TYPE_SPEC={'size':1,'mapper':lambdax:Address.address_type_name(x)}
@@ -1400,7 +1426,9 @@ address[0] is the LSB of the address, address[5] is the MSB.
address_type=data[offset-1]returnAddress.parse_address_with_type(data,offset,address_type)
- def__init__(self,address,address_type=RANDOM_DEVICE_ADDRESS):
+ def__init__(
+ self,address:Union[bytes,str],address_type:int=RANDOM_DEVICE_ADDRESS
+ ):''' Initialize an instance. `address` may be a byte array in little-endian format, or a hex string in big-endian format (with optional ':'
@@ -1515,18 +1543,7 @@ the type is set to PUBLIC_DEVICE_ADDRESS.
Source code in bumble/hci.py
-
def__init__(
+ self,address:Union[bytes,str],address_type:int=RANDOM_DEVICE_ADDRESS
+):''' Initialize an instance. `address` may be a byte array in little-endian format, or a hex string in big-endian format (with optional ':'
@@ -1586,14 +1618,14 @@ the type is set to PUBLIC_DEVICE_ADDRESS.
Source code in bumble/hci.py
-
1797
-1798
-1799
-1800
-1801
-1802
-1803
-1804
def__str__(self):
+
1810
+1811
+1812
+1813
+1814
+1815
+1816
+1817
def__str__(self):''' String representation of the address, MSB first '''
@@ -1628,21 +1660,7 @@ the type is set to PUBLIC_DEVICE_ADDRESS.
Source code in bumble/hci.py
-
classHCI_Packet:''' Abstract Base class for HCI packets '''
+ hci_packet_type:int
+
@staticmethoddeffrom_bytes(packet):packet_type=packet[0]
@@ -1675,6 +1714,9 @@ the type is set to PUBLIC_DEVICE_ADDRESS.
def__init__(self,name):self.name=name
+ def__bytes__(self)->bytes:
+ raiseNotImplementedError
+
def__repr__(self)->str:returnself.name
@@ -1716,29 +1758,7 @@ the type is set to PUBLIC_DEVICE_ADDRESS.
Source code in bumble/hci.py
-
classHCI_Command(HCI_Packet):''' See Bluetooth spec @ Vol 2, Part E - 5.4.1 HCI Command Packet '''hci_packet_type=HCI_COMMAND_PACKET
- command_classes={}
+ command_classes:Dict[int,Type[HCI_Command]]={}@staticmethoddefcommand(fields=(),return_parameters_fields=()):
@@ -1944,34 +1986,34 @@ the type is set to PUBLIC_DEVICE_ADDRESS.
Source code in bumble/hci.py
-
@staticmethoddefcommand(fields=(),return_parameters_fields=()):''' Decorator used to declare and register subclasses
@@ -2028,16 +2070,16 @@ the type is set to PUBLIC_DEVICE_ADDRESS.
Source code in bumble/hci.py
-
Usage: bumble-bench central [OPTIONS] TRANSPORT
+
+ Run as a central (initiates the connection)
+
+Options:
+ --peripheral ADDRESS_OR_NAME Address or name to connect to
+ --connection-interval, --ci CONNECTION_INTERVAL
+ Connection interval (in ms)
+ --phy [1m|2m|coded] PHY to use
+ --help Show this message and exit.
+
+
To test once device against another, one of the two devices must be running
+the peripheral command and the other the central command. The device
+running the peripheral command will accept connections from the device
+running the central command.
+When using Bluetooth LE (all modes except for rfcomm-server and rfcomm-clientutils),
+the default addresses configured in the tool should be sufficient. But when using
+Bluetooth Classic, the address of the Peripheral must be specified on the Central
+using the --peripheral option. The address will be printed by the Peripheral when
+it starts.
+
Independently of whether the device is the Central or Peripheral, each device selects a
+mode and and role to run as. The mode and role of the Central and Peripheral
+must be compatible.
In the following examples, we have two USB Bluetooth controllers, one on usb:0 and
+the other on usb:1, and two consoles/terminals. We will run a command in each.
+
+
GATT Throughput
+
Using the default mode and role for the Central and Peripheral.
+
In the first console/terminal:
+
$ bumble-bench peripheral usb:0
+
+
In the second console/terminal:
+
$ bumble-bench central usb:1
+
+
In this default configuration, the Central runs a Sender, as a GATT client,
+connecting to the Peripheral running a Receiver, as a GATT server.
+
+
+
+
@@ -1243,7 +1257,7 @@ a Bluetooth host, and we are connecting it to a virtual controller attached to a
@@ -1280,7 +1294,7 @@ a Bluetooth host, and we are connecting it to a virtual controller attached to a
diff --git a/apps_and_tools/index.html b/apps_and_tools/index.html
index 99f62fd3..2fdbf7c3 100644
--- a/apps_and_tools/index.html
+++ b/apps_and_tools/index.html
@@ -856,8 +856,8 @@
+
+
+
+
@@ -1286,7 +1300,7 @@ You may want to configure your own environment to "format on save" with bl
diff --git a/development/contributing.html b/development/contributing.html
index 51592de4..dbdcb04f 100644
--- a/development/contributing.html
+++ b/development/contributing.html
@@ -856,8 +856,8 @@
+
+
+
+
@@ -1261,7 +1275,7 @@ To run the basic checks (essentially: running the tests, the linter, and the for
diff --git a/development/python_environments.html b/development/python_environments.html
index 614d7c8e..6f26b0f4 100644
--- a/development/python_environments.html
+++ b/development/python_environments.html
@@ -921,8 +921,8 @@
+
+
+
+
@@ -1399,7 +1413,7 @@ This will create a new environment, named bumble, which you can the
diff --git a/examples/index.html b/examples/index.html
index db67ab61..b6a91389 100644
--- a/examples/index.html
+++ b/examples/index.html
@@ -844,8 +844,8 @@
+
+
+
+
@@ -1232,7 +1246,7 @@ On Linux, the VHCI Transport can be used t
@@ -1269,7 +1283,7 @@ On Linux, the VHCI Transport can be used t
diff --git a/index.html b/index.html
index f0741318..6f4b5418 100644
--- a/index.html
+++ b/index.html
@@ -1064,8 +1064,8 @@
+
+
+
+
@@ -1609,8 +1623,7 @@ The project initially only supported BLE (Bluetooth Low Energy), but support for
eventually added. Support for BLE is therefore currently somewhat more advanced than for Classic.
Warning
-
This project is still very much experimental and in an alpha state where a lot of things are still missing or broken, and what's there changes frequently.
-Also, there are still a few hardcoded values/parameters in some of the examples and apps which need to be changed (those will eventually be command line arguments, as appropriate)
+
This project is still in an early state of development where some things are still missing or broken, and what's implemented may change and evolve frequently.
The goal of this project is to offer a suite of components that can be put together to implement a number of tasks related to Bluetooth. That's fairly open-ended, but at the very least, it should be possible to:
@@ -1765,7 +1778,7 @@ Some platforms support features that not all platforms support
diff --git a/platforms/android.html b/platforms/android.html
index 54c9e4df..1fabd572 100644
--- a/platforms/android.html
+++ b/platforms/android.html
@@ -844,8 +844,8 @@
Connecting the Bumble host stack to the Android emulator's virtual controller.
Using Bumble as an HCI bridge to connect the Android emulator to a physical
- Bluetooth controller, such as a USB dongle
+ Bluetooth controller, such as a USB dongle, or other HCI transport.
Warning
Bluetooth support in the Android emulator is a recent feature that may still
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.
+You will need version 33.1.4.0 or later.
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
+by exposing a 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.
+Both ways are controlled via gRPC requests to the Android emulator controller and/or
+from the Android emulator.
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
@@ -1319,43 +1360,69 @@ the command line.
The Android emulator's virtual Bluetooth controller is called Root Canal.
-Multiple instances of Root Canal virtual controllers can be instantiated, they
-communicate link layer packets between them, thus creating a virtual radio network.
-Configuring a Bumble Device instance to use Root Canal as a virtual controller
+
The -packet-streamer-endpoint <endpoint> command line option may be used to enable
+Bluetooth emulation and tell the emulator which virtual controller to connect to.
If the emulator doesn't have Bluetooth emulation enabled by default, use the
+-packet-streamer-endpoint default option to tell it to connect to Netsim.
+If Netsim is not running, the emulator will start it automatically.
+
The Android emulator's virtual Bluetooth controller is called Netsim.
+Netsim runs as a background process and allows multiple clients to connect to it,
+each connecting to its own virtual controller instance hosted by Netsim. All the
+clients connected to the same Netsim process can then "talk" to each other over a
+virtual radio link layer.
+Netsim supports other wireless protocols than Bluetooth, but the relevant part here
+is Bluetooth. The virtual Bluetooth controller used by Netsim is sometimes referred to
+as Root Canal.
+
Configuring a Bumble Device instance to use netsim 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
-the bumble android-emulator transport in host mode (the default).
+To connect a Bumble host stack to a netsim virtual controller instance, use
+the Bumble android-netsim transport in host mode (the default).
-
Run the example GATT server connected to the emulator
By default, the Bumble android-netsim transport will try to automatically discover
+the port number on which the netsim process is exposing its gRPC server interface. If
+that discovery process fails, or if you want to specify the interface manually, you
+can pass a hostname and port as parameters to the transport, as: android-netsim:<host>:<port>.
+
+
Run the example GATT server connected to the emulator via Netsim on a localhost, port 8877
If you want to connect multiple Bumble devices to netsim, it may be useful to give each one
+a netsim controller with a specific name. This can be done using the name=<name> transport option.
+For example: android-netsim:localhost:8877,name=bumble1
This is an advanced use case, which may not be officially supported, but should work in recent
-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).
+versions of the emulator.
+
The first step is to run the Bumble HCI bridge, specifying netsim as the "host" end of the
+bridge, and another controller (typically a USB Bluetooth dongle, but any other supported
+transport can work as well) as the "controller" end of the bridge.
+
To connect a virtual controller to the Android Bluetooth stack, use the bumble android-netsim transport in controller mode. For example, with port number 8877, the transport name would be: android-netsim:_:8877,mode=controller.
-
Launch the emulator with VHCI forwarding
-
In this example, we launch an emulator AVD named "Tiramisu"
-
$ emulator -forward-vhci -avd Tiramisu
+
Connect the Android emulator to the first USB Bluetooth dongle, using the hci_bridge application
Then, you can start the emulator and tell it to connect to this bridge, instead of netsim.
+You will likely need to start the emulator from the command line, in order to specify the -packet-streamer-endpoint <hostname>:<port> option (unless the emulator offers a way to control that feature from a user/ui menu).
+
+
Launch the emulator with a netsim replacement
+
In this example, we launch an emulator AVD named "Tiramisu", with a Bumble HCI bridge running
+on port 8877.
+
Attaching a virtual controller use the VHCI forwarder while the Android Bluetooth stack
-is running isn't supported. So you need to disable Bluetooth in your running Android guest
+
Attaching a virtual controller while the Android Bluetooth stack is running may not be well supported. So you may need to disable Bluetooth in your running Android guest
before attaching the virtual controller, then re-enable it once attached.
-
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.
-
-
Connect the Android emulator to the first USB Bluetooth dongle, using the hci_bridge application
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
@@ -1421,7 +1488,7 @@ Use the --format snoop option to specify that the file is in that s
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).
+
+
Warning
+
Bluetooth support in the Android emulator has recently changed. The older mode, using
+the android-emulator transport name with Bumble, while still implemented, is now
+obsolete, and may not be supported by recent versions of the emulator.
+Use the android-netsim transport name instead.
+
+
The Android "netsim" transport either connects, as a host, to a Netsim virtual controller
+("host" mode), or acts as a virtual controller itself ("controller" mode) accepting host
+connections.
The moniker syntax for an Android Emulator transport is: android-emulator:[mode=<host|controller>][<hostname>:<port>], where
-the mode parameter can specify running as a host or a controller, and <hostname>:<port> can specify a host name (or IP address) and TCP port number on which to reach the gRPC server for the emulator.
-Both the mode=<host|controller> and <hostname>:<port> parameters are optional (so the moniker android-emulator by itself is a valid moniker, which will create a transport in host mode, connected to localhost on the default gRPC port for the emulator).
+
The moniker syntax for an Android Emulator "netsim" transport is: android-netsim:[<host>:<port>][<options>],
+where <options> is a ','-separated list of <name>=<value> pairs.
+Themodeparameter name can specify running as a host or a controller, and:can specify a host name (or IP address) and TCP port number on which to reach the gRPC server for the emulator (in "host" mode), or to accept gRPC connections (in "controller" mode).
+Both themode=and:parameters are optional (so the monikerandroid-netsimby itself is a valid moniker, which will create a transport inhostmode, connected tolocalhost` on the default gRPC port for the Netsim background process).
Example
-
android-emulator
-connect as a host to the emulator on localhost:8554
+
android-netsim
+connect as a host to Netsim on the gRPC port discovered automatically.
Example
-
android-emulator:mode=controller
-connect as a controller to the emulator on localhost:8554
+
android-netsim:_:8555,mode=controller
+Run as a controller, accepting gRPC connection on port 8555.
Example
-
android-emulator:localhost:8555
-connect as a host to the emulator on localhost:8555
+
android-netsim:localhost:8555
+connect as a host to Netsim on localhost:8555
+
+
+
Example
+
android-netsim:localhost:8555
+connect as a host to Netsim on localhost:8555
+
+
+
Example
+
android-netsim:name=bumble1234
+connect as a host to Netsim on the discovered gRPC port, using bumble1234 as the
+controller instance name.
@@ -1323,7 +1357,7 @@ connect as a host to the emulator on localhost:8555
diff --git a/transports/file.html b/transports/file.html
index 3ca661d4..5d76556e 100644
--- a/transports/file.html
+++ b/transports/file.html
@@ -887,8 +887,8 @@
+
+
+
+
@@ -1318,7 +1332,7 @@ Use an HCI socket to the first Bluetooth controller (hci0 on Linux)
diff --git a/transports/index.html b/transports/index.html
index fe5dcfb7..decc4260 100644
--- a/transports/index.html
+++ b/transports/index.html
@@ -856,8 +856,8 @@
+
+
+
+
@@ -1216,7 +1230,8 @@ Several types of transports are supported:
PTY: a PTY (pseudo terminal) is used to send/receive HCI packets. This is convenient to expose a virtual controller as if it were an HCI UART
VHCI: used to attach a virtual controller to a Bluetooth stack on platforms that support it.
HCI Socket: an HCI socket, on platforms that support it, to send/receive HCI packets to/from an HCI controller managed by the OS.
-
Android Emulator: a gRPC connection to an Android emulator is used to setup either an HCI interface to the emulator's "Root Canal" virtual controller, or attach a virtual controller to the Android Bluetooth host stack.
+
Android Emulator: a gRPC connection to the Android emulator's "netsim"
+ virtual controller, or from the Android emulator, is used to setup either an HCI interface to the emulator's "netsim" virtual controller, or serve as a virtual controller for the Android Bluetooth host stack.
File: HCI packets are read/written to a file-like node in the filesystem.
@@ -1274,7 +1289,7 @@ Several types of transports are supported:
diff --git a/transports/pty.html b/transports/pty.html
index 304912e3..329ddcbb 100644
--- a/transports/pty.html
+++ b/transports/pty.html
@@ -887,8 +887,8 @@
+
+
+
+
@@ -1310,7 +1324,7 @@ UDP transport where packets are received on port 9000 and sent to <
diff --git a/transports/usb.html b/transports/usb.html
index 862f7c3f..a04ddb76 100644
--- a/transports/usb.html
+++ b/transports/usb.html
@@ -948,8 +948,8 @@
+
+
+
+
@@ -1310,7 +1324,7 @@ UDP transport where packets are received on port 9000 and sent to <
diff --git a/transports/ws_server.html b/transports/ws_server.html
index 88f75019..0db9e77d 100644
--- a/transports/ws_server.html
+++ b/transports/ws_server.html
@@ -887,8 +887,8 @@
+
+
+
+
@@ -1310,7 +1324,7 @@ UDP transport where packets are received on port 9000 and sent to <
diff --git a/use_cases/index.html b/use_cases/index.html
index 3d050ab8..8d70c4f7 100644
--- a/use_cases/index.html
+++ b/use_cases/index.html
@@ -856,8 +856,8 @@