Skip to main content

BTZen - library to asynchronously access Bluetooth devices

Project description

BTZen is a library to asynchronously access Bluetooth devices using Python language. It provides simple API over complex D-Bus Bluez interface.


The main features of BTZen are

  1. Connect and access multiple Bluetooth devices in parallel with Python asynchronous coroutines.
  2. GATT notification interface integrated into main API of the library.
  3. Automatic reconnections to devices with a connection manager.
  4. Access to serial devices implementing Stollmann (Telit) protocol.
  5. Support for devices partially following the Bluetooth specification like SensorTag (CC2650STK).
  6. Support for Bluez managed interfaces of devices, i.e. battery level.

The library can be used with any Bluetooth Smart device. It was tested with

  1. SensorTag (CC2650STK) to read temperature, pressure, humidity, light, accelerometer data and state of the buttons.
  2. Mi Smart Scale to read weight data.
  3. OSTC dive computer to read serial device data using Stollmann (Telit) protocol.

The library is tested with default asyncio event loop and its drop-in replacement uvloop. Use of uvloop increases performance of the library.

The scripts in scripts directory demonstrate reading data from various devices.

NOTE: The first version of SensorTag (CC2541DK) is not supported at the moment. If you still own the device and would like it to be supported, please raise an issue.


Use pip to install BTZen library (Cython needs to be installed first), for example:

pip install --user cython
pip install --user btzen

BTZen uses experimental API of Bluez adapter interface to connect to Bluetooth devices. The bluetoothd daemon has to be started with -E option. This can be permanently achieved by copying /usr/lib/systemd/system/bluetooth.service file into /etc/systemd/system/ directory and by modifying the ExecStart line.

Connection Management

BTZen uses ConnectDevice method of Bluez adapter interface to discover and connect to Bluetooth devices. MAC address of a device needs to be known in order to connect.

BTZen connection manager allows to connect and disconnect Bluetooth devices without restarting of an application. If an application is reading data from multiple Bluetooth devices, the application can continue working if, for example, a sensor requires battery change.

Please note

  • when trying to connect to a device using BTZen library, do not start scan with other programs, i.e. bluetoothctl
  • if a device is disconnected with an external program, the external program has to be used to reconnect

Obtaining MAC Address

If Bluetooth device MAC address is not known

  1. Start bluetoothctl.
  2. Start scan.
  3. Save discovered MAC address.
  4. Remove device with remove command of bluetoothctl.
  5. Start BTZen based application using the discovered MAC address.


The library enables programmers to communicate with mutliple devices in parallel without using threads. This avoids context switching of threads and minimizes memory requirements, which makes BTZen more efficient than other, similar libraries. To keep the library as fast as possible, the Cython is used to access Bluez D-Bus API. BTZen can be used with uvloop for even more increased performance of an application.

Support for GATT notification interface allows efficient use of Bluetooth devices. For example, data from sensors like accelerometers can be read only when sensor wakes up and transmits data after sensor has been moved. This limits amount of transferred data and avoids draining battery of the sensor, which will happen if data is polled at regular, short intervals.


BTZen library requires the following software components

  • Python 3.7
  • bluez 5.50
  • sd-bus (part of systemd)
  • Cython 0.29


BTZen library is licensed under terms of GPL license, version 3, see COPYING file for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for btzen, version 0.3.2
Filename, size & hash File type Python version Upload date
btzen-0.3.2.tar.gz (253.7 kB) View hashes Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page