DOCSEARCHbyAlgolia
Submit Docs

python-bluezero

repository·main·Indexed 19 days ago

https://github.com/ukbaz/python-bluezero

A high-level Python library designed to simplify interaction with the BlueZ Bluetooth stack on Linux. It provides a simplified API for common Bluetooth tasks including GATT client/server roles, beacon broadcasting, and device scanning. The library is organized into three abstraction levels: Level 1 for hardware/profile specific tasks (e.g., micro:bit, Eddystone), Level 10 for standard BLE roles (broadcaster, central, observer, peripheral), and Level 100 for low-level BlueZ/DBus control.

Tokens
3.9K
Snippets
23
Records
40
Agent score
59%

What's inside python-bluezero

  1. Overview of python-bluezero

    main

    python-bluezero is a simple Python interface to the BlueZ stack. Its primary goal is to provide a simplified API for accessing Bluetooth functionality with zero boilerplate code. It achieves this by making calls to the BlueZ D-Bus API using sensible defaults, allowing developers to implement Bluetooth features without needing to manage the BlueZ API or write their own event loops.

    Requirements & Assumptions:

    • Target Platform: Linux releases with BlueZ 5.50 (e.g., Raspberry Pi OS Buster).
    • Underlying Technology: Uses BlueZ D-Bus API.

  2. Core Bluetooth Roles in python-bluezero

    main

    The library provides abstractions for the different roles a Bluetooth device can take:

    • Adapter: Managing the local Bluetooth hardware (checking status, power, and scanning).
    • GATT Client (Central role): Connecting to and interacting with peripheral devices (e.g., polling a micro:bit).
    • Beacon: Acting as a broadcaster for specific formats like Eddystone URL.
    • Scanner: Searching for and identifying various beacon formats (Eddystone URL, Eddystone UID, AltBeacon, and iBeacon).
    • GATT Server (Peripheral role): Acting as a Bluetooth device that provides services and characteristics (e.g., transmitting CPU temperature or simulating a UART connection).

  3. Use the micro:bit module for micro:bit integration

    main
    The bluezero.microbit module provides specialized classes for interacting with micro:bit hardware. It includes support for the Microbit class, MIpower class, and BitBot class. Use these classes to implement micro:bit-specific Bluetooth functionality.

  4. Understand the Bluezero API complexity levels

    main

    The python-bluezero library organizes its functionality into three levels of abstraction to help users choose the right tool based on their expertise and requirements:

    • Level 1 (High Abstraction): Designed for minimal friction. The API is highly Pythonic and does not require knowledge of Bluetooth, DBus, or event loops. It is typically used for specific hardware (like the BBC micro:bit) or standard public Bluetooth profiles (like Heart Rate Monitors) where UUIDs are handled internally.
    • Level 10 (Medium Abstraction): Requires some Bluetooth knowledge, specifically knowing the UUIDs of services and characteristics. The API remains Pythonic and simplifies event loops without exposing DBus terminology.
    • Level 100 (Low Abstraction): Provides maximum control but requires expertise in Bluetooth, DBus, and event loops. This level may expose non-Pythonic DBus function names and is tightly coupled to the Linux kernel and the BlueZ Daemon, making it difficult to port to other operating systems.

  6. Compile and install BlueZ from source

    main

    If your Linux distribution provides a version older than 5.43, you must build BlueZ from source. This requires deb-src entries in your /etc/apt/sources.list.

    1. Install build dependencies: sudo apt-get build-dep bluez
    2. Download and extract the source from the official BlueZ website.
    3. Configure with experimental mode enabled: ./configure --prefix=/usr --mandir=/usr/share/man --sysconfdir=/etc --localstatedir=/var --enable-experimental --enable-maintainer-mode
    4. Compile and install: make -j 4 && sudo make install

    Warning for Raspberry Pi 3 users: Installing the latest BlueZ may break the controller connection. Refer to the Bluezero GitHub issue #30 for patching instructions.

    sudo apt-get build-dep bluez

# After downloading and extracting source:
./configure --prefix=/usr \
            --mandir=/usr/share/man \
            --sysconfdir=/etc \
            --localstatedir=/var \
            --enable-experimental \
            --enable-maintainer-mode

make -j 4 && sudo make install

  7. Install required BlueZ packages

    main

    Bluezero relies on the BlueZ DBus interface and requires BlueZ version 5.43 or later. For most modern Linux distributions, you can install the necessary base packages using apt-get.

    Note: If you are building BlueZ from source, you do not need bluez-test-scripts, bluez-hcidump, or python-bluez via apt.

    sudo apt-get install bluetooth
sudo apt-get install bluez-tools

  8. Configure D-Bus permissions for GATT Server (Peripheral role)

    main
    To use the GATT Server (Peripheral role) functionality, you must modify your system's D-Bus configuration file to grant permissions for ukBaz.bluezero. Failure to do this will prevent the library from acting as a peripheral.

  10. Verify BlueZ version compatibility

    main

    Bluezero relies on the BlueZ DBus interface. It is recommended to use BlueZ version 5.64 (the default in Ubuntu 22.04.4 LTS) to ensure API compatibility. You can check your installed version using the bluetoothctl command.

    To check the version, run:

    bluetoothctl -v
    $ bluetoothctl -v
5.64

  11. Enable BlueZ experimental mode

    main

    Some BlueZ DBus API functionality used by Bluezero is behind an experimental flag. You can enable this by modifying the bluetooth.service file to include the --experimental flag.

    1. Apply the flag using sed: sudo sed -i '/^ExecStart.*bluetoothd\s*$/ s/$/ --experimental/' /lib/systemd/system/bluetooth.service
    2. Reload and restart the service: sudo systemctl daemon-reload sudo service bluetooth restart
    3. Verify the version using bluetoothctl: bluetoothctl -> version
    sudo sed -i '/^ExecStart.*bluetoothd\s*$/ s/$/ --experimental/' /lib/systemd/system/bluetooth.service

sudo systemctl daemon-reload
sudo service bluetooth restart