{"id":7057,"library":"btsocket","title":"btsocket Library","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/ukBaz/python-btsocket","tags":["bluetooth","bluez","socket","linux","management"],"install":[{"cmd":"pip install btsocket","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"BTSocket","correct":"from btsocket import BTSocket"}],"quickstart":{"code":"import btsocket\nimport time\n\ndef main():\n    \"\"\"\n    Demonstrates basic connection and disconnection using btsocket.\n    Requires a functional BlueZ setup and appropriate permissions.\n    \"\"\"\n    print(\"Initializing btsocket...\")\n    try:\n        bt = btsocket.BTSocket()\n        print(f\"BTSocket initialized. Adapter index: {bt.idx}\")\n\n        print(\"Attempting to connect to Bluetooth Management API...\")\n        # This establishes a connection to the local BlueZ Management socket.\n        # Depending on your system, you might need root privileges or to be\n        # part of the 'bluetooth' group for certain operations.\n        bt.connect()\n        print(\"Successfully connected to Bluetooth Management API.\")\n\n        # In a real application, you would perform Bluetooth operations here.\n        print(\"Connected for 1 second...\")\n        time.sleep(1)\n\n        print(\"Disconnecting from Bluetooth Management API...\")\n        bt.disconnect()\n        print(\"Disconnected.\")\n\n    except PermissionError as e:\n        print(f\"Error: Permission denied. {e}\")\n        print(\"Hint: Try running with 'sudo python your_script.py' or ensure your user is in the 'bluetooth' group and BlueZ is correctly configured.\")\n    except FileNotFoundError as e:\n        print(f\"Error: BlueZ management socket not found. {e}\")\n        print(\"Hint: Ensure BlueZ is installed and the 'bluetooth' service is running.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n        print(\"Hint: Check if your Bluetooth adapter is enabled and BlueZ is functioning correctly.\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The Python script lacks the necessary permissions to open the BlueZ management socket or perform Bluetooth operations.","error":"PermissionError: [Errno 13] Permission denied"},{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/var/run/bluetooth/mgmtsocket'"},{"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.","cause":"The system does not have an active Bluetooth adapter or the adapter is disabled/blocked.","error":"btsocket.BluetoothError: No Bluetooth adapter found"}]}