btsocket

What it is and what it does

btsocket is a low-level Python wrapper around the BlueZ Bluetooth Management API on Linux. It provides access to the kernel's mgmt socket interface for controlling Bluetooth adapters—powering them on/off, discovering devices, and managing connections—without the ability to read or write data on connected devices themselves. The library requires root or CAP_NET_ADMIN capability for most operations.

The package splits functionality into three layers: a socket layer (working around a Python limitation to access the user channel), a protocol layer for encoding and decoding binary mgmt commands and responses, and a programming paradigm layer offering both synchronous (blocking) and callback-driven (event-based) APIs. It is explicitly positioned as an early-stage proof of concept and not recommended as a first Bluetooth library for newcomers.

Use it for:

• Automate Bluetooth adapter power management and discovery on embedded Linux systems
• Build home automation scripts that scan for and manage Bluetooth device presence
• Develop educational projects exploring the BlueZ stack and low-level Bluetooth protocol
• Monitor and control Bluetooth adapters programmatically in system administration tools
• Create event-driven applications that react to Bluetooth device discovery or connection changes

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Python library for controlling BlueZ Bluetooth adapters on Linux via the Management API, supporting both synchronous and event-driven command patterns.

Yes, if you need direct access to BlueZ's management API on Linux and are comfortable with root-level operations and early-stage code. No, if you are new to Bluetooth, need data I/O on connected devices, or require a mature, actively maintained library. The aging maintenance status suggests caution for production use.

Install

btsocket on PyPI

pip install btsocket

uv add btsocket

poetry add btsocket

Installing btsocket

Before you install

Low install friction with no runtime dependencies. Maintenance is aging—last release was over a year ago and the repository shows limited activity (18 stars), though it remains unarchived.

License in practice

MIT license is permissive; you may use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install btsocket

from btsocket import btmgmt_sync
response = btmgmt_sync.send('SetPowered', 0, 1)

Requires root or CAP_NET_ADMIN capability; Linux-only; works around Python socket limitation documented at https://bugs.python.org/issue36132

Verify before relying

• Whether the library works with modern Python versions (requires_python is unspecified)
• Current state of the Python socket bug at https://bugs.python.org/issue36132 and whether it affects current releases
• Compatibility with recent BlueZ versions and Linux kernel releases

Package facts

Evidence: btsocket-0.3.0-py2.py3-none-any.whl

Keywords: BlueZ, Bluetooth, Management, MGMT, API

Tags

More Home Automation packages