btsocket Library

0.3.0 · active · verified Thu Apr 16

btsocket is a Python library providing a high-level interface to the BlueZ Bluetooth Management API. It enables programmatic control over Bluetooth adapters and operations on Linux systems. The current version is `0.3.0`, with a release cadence that focuses on adding new BlueZ management commands and improving internal socket handling, typically with a few releases per year.

Common errors

```
PermissionError: [Errno 13] Permission denied
```
cause The Python script lacks the necessary permissions to open the BlueZ management socket or perform Bluetooth operations.

fix Run the script with `sudo` (e.g., `sudo python your_script.py`) or add the user to the `bluetooth` group and restart your session. Ensure the BlueZ daemon has appropriate permissions itself.
```
FileNotFoundError: [Errno 2] No such file or directory: '/var/run/bluetooth/mgmtsocket'
```
cause The BlueZ management socket file does not exist, typically because BlueZ is not installed, the 'bluetooth' service is not running, or it's configured to use a different path.

fix Install BlueZ packages (e.g., `sudo apt-get install bluez` on Debian/Ubuntu), then start and enable the 'bluetooth' service (`sudo systemctl start bluetooth && sudo systemctl enable bluetooth`). Verify the socket path or check BlueZ logs.
```
btsocket.BluetoothError: No Bluetooth adapter found
```
cause The system does not have an active Bluetooth adapter or the adapter is disabled/blocked.

fix Check your system's Bluetooth status (`bluetoothctl show`, `hciconfig`, `rfkill list`). Ensure the adapter is enabled and not hard-blocked or soft-blocked. Power cycle the adapter if necessary.

Warnings

gotcha btsocket is a wrapper around the Linux BlueZ Bluetooth Management API. It relies heavily on BlueZ being installed, configured, and running correctly on your system. It is not a cross-platform solution for Bluetooth.
Fix: Ensure you are running on a Linux system with BlueZ (bluez-libs, bluez-utils, or similar packages) installed and the 'bluetooth' service enabled and running.
gotcha Many BlueZ Management API operations, especially connecting to the management socket or performing certain adapter controls, require elevated privileges (e.g., running as root or being part of the `bluetooth` user group).
Fix: Run your script with `sudo` or add your user to the `bluetooth` group (`sudo usermod -aG bluetooth $USER` and log out/in) to grant necessary permissions. Always prioritize the least restrictive permissions necessary.
gotcha For `btsocket` to function, a physical or virtual Bluetooth adapter must be present and enabled on the system. If no adapter is found or it's disabled, operations will fail.
Fix: Verify your Bluetooth adapter status using system tools (e.g., `bluetoothctl show`, `hciconfig`, `rfkill list`). Ensure it's not blocked and is powered on.

Install

pip install btsocket Install latest version

Imports

BTSocket
```
from btsocket import BTSocket
```

Quickstart

This quickstart demonstrates how to initialize the `BTSocket` object, connect to the BlueZ Management API, and then disconnect. It handles common `PermissionError` and `FileNotFoundError` exceptions that might occur if BlueZ is not properly set up or permissions are insufficient. Replace the `time.sleep(1)` with actual Bluetooth management commands for real-world usage.

import btsocket
import time

def main():
    """
    Demonstrates basic connection and disconnection using btsocket.
    Requires a functional BlueZ setup and appropriate permissions.
    """
    print("Initializing btsocket...")
    try:
        bt = btsocket.BTSocket()
        print(f"BTSocket initialized. Adapter index: {bt.idx}")

        print("Attempting to connect to Bluetooth Management API...")
        # This establishes a connection to the local BlueZ Management socket.
        # Depending on your system, you might need root privileges or to be
        # part of the 'bluetooth' group for certain operations.
        bt.connect()
        print("Successfully connected to Bluetooth Management API.")

        # In a real application, you would perform Bluetooth operations here.
        print("Connected for 1 second...")
        time.sleep(1)

        print("Disconnecting from Bluetooth Management API...")
        bt.disconnect()
        print("Disconnected.")

    except PermissionError as e:
        print(f"Error: Permission denied. {e}")
        print("Hint: Try running with 'sudo python your_script.py' or ensure your user is in the 'bluetooth' group and BlueZ is correctly configured.")
    except FileNotFoundError as e:
        print(f"Error: BlueZ management socket not found. {e}")
        print("Hint: Ensure BlueZ is installed and the 'bluetooth' service is running.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
        print("Hint: Check if your Bluetooth adapter is enabled and BlueZ is functioning correctly.")

if __name__ == "__main__":
    main()

view raw JSON →