{"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":"python","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":[{"wrong":"from btsocket import BTSocket","symbol":"BTSocket","correct":"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,"search_vec":"'0.3.0':36 'ad':44 'adapt':26 'api':19 'bluetooth':17,25,61 'bluez':16,46,62 'btsocket':1,3 'cadenc':40 'command':48 'control':23 'current':33 'enabl':21 'focus':42 'handl':53 'high':11 'high-level':10 'improv':50 'interfac':13 'intern':51 'level':12 'librari':2,7 'linux':30,64 'manag':18,47,65 'new':45 'oper':28 'per':59 'programmat':22 'provid':8 'python':6 'releas':39,58 'socket':52,63 'system':31 'typic':54 'version':34 'year':60","created_at":"2026-04-16T13:41:36.013280+00:00","updated_at":"2026-04-16T13:41:36.013280+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ukBaz/python-btsocket","docs":null,"changelog":null,"pypi":"https://pypi.org/project/btsocket/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}