Introduction

Documentation Status Discord Build Status

_bleio for Blinka based on bleak and bluez.

Dependencies

This driver depends on:

It optionally also depends on these Debian packages not install on Raspbian by default:

  • bluez-hcidump

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-blinka-bleio

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-blinka-bleio

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .env
source .env/bin/activate
pip3 install adafruit-blinka-bleio

Support for Duplicate Advertisement scanning on Linux

Note

Read this section if you are using advertising to transmit changing data and need to receive all advertisements to receive this data. One example of using advertising for data is described in the Adafruit Learn Guide Bluetooth LE Sensor Nodes to Raspberry Pi WiFi Bridge.

The regular Linux kernel bluez driver is set up to suppress multiple advertisements sent from the same BLE device. As of this writing, this cannot be changed. If you are using BLE advertisements to send changing data that you retrieve by scanning, the de-duplication can cause you to lose data when scanning via bleak.

To get around this problem, this library can instead look at raw BLE scanning data using the hcidump and hcitool tools and avoid going through the kernel driver. But this requires special setup.

Normally, only root has enough privileges to do see the raw scanning data. Since running as root is dangerous, you can instead use Linux capabilities to grant hcitool and hcidump raw network access. This is very powerful and not something to do casually. To limit access we recommend you change file execution permissions to restrict this capability to users in the bluetooth group.

If you are not using advertising to transmit changing data, you do not need to add these permissions. This library falls back to using bleak for regular scanning if hcitool does not have these extra permissions.

If you explicitly want to choose the backend to ensure consistent behavior, you can do the following:

ble = BLERadio()
ble._adapter.ble_backend = "bleak" # Forces bleak even if hcitool works.
# ble._adapter.ble_backend = "hcitool" # Forces hcitool. Raises exception if unavailable.

To add yourself to the bluetooth group do:

sudo usermod -a -G bluetooth <your username>

You must then logout and log back in to be in the new group.

To set permissions on hcitool and hcidump do:

sudo chown :bluetooth /usr/bin/hcitool /usr/bin/hcidump
sudo chmod o-x /usr/bin/hcitool /usr/bin/hcidump
sudo setcap 'cap_net_raw,cap_net_admin+eip' /usr/bin/hcitool
sudo setcap 'cap_net_raw,cap_net_admin+eip' /usr/bin/hcidump

Usage Example

Do not use this library directly. Use CircuitPython BLE instead: https://github.com/adafruit/Adafruit_CircuitPython_BLE/

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

Documentation

For information on building library documentation, please check out this guide.

Troubleshooting

Raspberry Pi 3b Rev 1.2

The Raspberry Pi 3b’s BLE chip is connected over UART to the main processor without flow control. This can cause unreliability with BLE. To improve reliability, we can slow the UART. To do so, edit /usr/bin/btuart and replace the 921600 with 460800.

Table of Contents

Examples

API Reference

Other Links

Indices and tables