see https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc/mgmt-api.txt for details on how to use the API:
- Raspberry Pi 3B+
- Raspberry Pi 4
Built with Python 3.7, Python 2 is untested. The package can be built with bdist-wheels, but is served as a source distribution, meaning the C wrapper is compiled locally when running pip install. This is slightly slower, but makes the library more portable.
- libbluetooth-dev : the headers and source code for this extension are entirely contained within this repo, but the python module is dynamically linked against lbluetooth.so on the Linux machine.
- libreadline-dev : the lreadline.so shared library is usually installed by default, but C header files are required to build this module from source.
$ sudo apt-get install libbluetooth-dev libreadline-dev
$ sudo pip3 install btmgmt
# most of the BTMGMT commands require root privileges, so the library should be
# installed to the root python environment.
Clone the repository, then cd into the root of the repo.
Install with:
$ sudo python3 setup.py install
The package can be uninstalled as normal with pip.
# Demonstrative only: see example scripts for more information
import btmgmt
# Run command and get exit code: any output is printed to stdout
exit_code = btmgmt.command("command", "parameter1", "parameter2")
# Run command and get exit code + stdout in a tuple
response = btmgmt.command_str("command", "parameter1", "parameter2")
response = (exit_code, stdout_string)
# Variable number of arguments allowed depending on the command e.g:
btmgmt.command("power", "on")
btmgmt.command("help")
btmgmt.command("scan-params")
# etc...
If you do not want to run as root, simply set the capabilities of the process (in this case, Python) to have CAP_NET_ADMIN.
sudo setcap cap_net_admin+eip $(readlink -f $(which python3))
You can verify that this is OK by running the above command with verify flag:
sudo setcap -v cap_net_admin+eip $(readlink -f $(which python3))
select <index> Select a different index
version Get the MGMT Version
commands List supported commands
config Show configuration info
info Show controller info
extinfo Show extended controller info
auto-power Power all available features
power <on/off> Toggle powered state
discov <yes/no/limited> [timeout] Toggle discoverable state
connectable <on/off> Toggle connectable state
fast-conn <on/off> Toggle fast connectable state
bondable <on/off> Toggle bondable state
linksec <on/off> Toggle link level security
ssp <on/off> Toggle SSP mode
sc <on/off/only> Toogle SC support
hs <on/off> Toggle HS support
le <on/off> Toggle LE support
advertising <on/off> Toggle LE advertising
bredr <on/off> Toggle BR/EDR support
privacy <on/off> Toggle privacy support
class <major> <minor> Set device major/minor class
disconnect [-t type] <remote address> Disconnect device
con List connections
find [-l|-b] [-L] Discover nearby devices
find-service [-u UUID] [-r RSSI_Threshold] [-l|-b] Discover nearby service
stop-find [-l|-b] Stop discovery
name <name> [shortname] Set local name
pair [-c cap] [-t type] <remote address> Pair with a remote device
cancelpair [-t type] <remote address> Cancel pairing
unpair [-t type] <remote address> Unpair device
keys Load Link Keys
ltks Load Long Term Keys
irks [--local <index>] [--file <file path>] Load Identity Resolving Keys
block [-t type] <remote address> Block Device
unblock [-t type] <remote address> Unblock Device
add-uuid <UUID> <service class hint> Add UUID
rm-uuid <UUID> Remove UUID
clr-uuids Clear UUIDs
local-oob Local OOB data
remote-oob [-t <addr_type>] [-r <rand192>] [-h <hash192>] [-R <rand256>] [-H <hash256>] <addr> Remote OOB data
did <source>:<vendor>:<product>:<version> Set Device ID
static-addr <address> Set static address
public-addr <address> Set public address
ext-config <on/off> External configuration
debug-keys <on/off> Toogle debug keys
conn-info [-t type] <remote address> Get connection information
io-cap <cap> Set IO Capability
scan-params <interval> <window> Set Scan Parameters
get-clock [address] Get Clock Information
add-device [-a action] [-t type] <address> Add Device
del-device [-t type] <address> Remove Device
clr-devices Clear Devices
bredr-oob Local OOB data (BR/EDR)
le-oob Local OOB data (LE)
advinfo Show advertising features
advsize [options] <instance_id> Show advertising size info
add-adv [options] <instance_id> Add advertising instance
rm-adv <instance_id> Remove advertising instance
clr-adv Clear advertising instances
appearance <appearance> Set appearance
version Display version
quit Quit program
exit Quit program
help Display help about this program
export Print evironment variables