Registry / communication / btsocket

btsocket

JSON →
library0.3.0pypypi✓ verified 87d ago

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.

pip install btsocket
INSTALL
IMPORT
SIG · BTSOCKET
B
btsocket
communicationpythonv0.3.0
Install
1.5s avg
Import
—
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.9MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BTSocket
✓ import btsocket
✗ from btsocket import BTSocket

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()
Debug
Known issues
gotchabtsocket 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.
affects: All versions
gotchaMany 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.
affects: All versions
gotchaFor `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.
affects: All versions
Upgrade
Version history
0.3.0latest on PyPI · released Jun 10, 2024
Audit
Dependencies

No dependency data recorded yet.

Agent activity
45 hits · last 30 days
node
40
OpenAI (training)
1
Resources
btsocket — pip install btsocket · libregistry