{"id":8644,"library":"simplepyble","title":"SimplePyBLE","description":"SimplePyBLE provides Python bindings for SimpleBLE, a fully cross-platform Bluetooth Low Energy (BLE) library written in C++. It is designed for simplicity and ease of use, offering a consistent API across Windows, macOS, and Linux, with some support for iOS and Android. The library is currently at version 0.12.1 and maintains an active release cadence, with frequent updates addressing features, stability, and bug fixes.","status":"active","version":"0.12.1","language":"en","source_language":"en","source_url":"https://github.com/simpleble/simpleble","tags":["bluetooth","ble","iot","hardware","asyncio","cross-platform"],"install":[{"cmd":"pip install simplepyble","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.8 or newer.","package":"python","optional":false},{"reason":"Required for D-Bus integration on Linux systems. Install via system package manager (e.g., apt).","package":"libdbus-1-dev","optional":false}],"imports":[{"note":"Standard import for synchronous BLE operations.","symbol":"Adapter","correct":"from simplepyble import Adapter"},{"note":"Import for asyncio-compatible, asynchronous BLE operations, introduced in v0.12.1. This is the recommended way for async applications.","symbol":"Adapter","correct":"from simplepyble.aio import Adapter"}],"quickstart":{"code":"import asyncio\nfrom simplepyble.aio import Adapter\n\nasync def main():\n    adapters = Adapter.get_adapters()\n    if not adapters:\n        print(\"No adapters found. Ensure Bluetooth is on and permissions are granted.\")\n        return\n\n    # Use the first adapter found\n    adapter = adapters[0]\n    print(f\"Selected adapter: {adapter.identifier()} [{adapter.address()}]\")\n\n    # Use the adapter within an async context manager\n    async with adapter:\n        print(\"Scanning for 5 seconds...\")\n        await adapter.scan_for(5000) # Scan for 5000 milliseconds\n\n        peripherals = adapter.scan_get_results()\n        if not peripherals:\n            print(\"No peripherals found.\")\n            return\n\n        print(\"Found peripherals:\")\n        for i, peripheral in enumerate(peripherals):\n            print(f\"  [{i}] {peripheral.identifier()} [{peripheral.address()}] - Connectable: {peripheral.is_connectable()}\")\n\n        # Example: Connect to the first connectable peripheral found\n        connectable_peripherals = [p for p in peripherals if p.is_connectable()]\n        if connectable_peripherals:\n            selected_peripheral = connectable_peripherals[0]\n            print(f\"Attempting to connect to: {selected_peripheral.identifier()}\")\n            await selected_peripheral.connect()\n            print(f\"Successfully connected to {selected_peripheral.identifier()}\")\n\n            # Discover services and characteristics (example)\n            services = selected_peripheral.services()\n            for service in services:\n                print(f\"  Service: {service.uuid()}\")\n                for characteristic in service.characteristics():\n                    print(f\"    Characteristic: {characteristic.uuid()} (Can Read: {characteristic.can_read()})\")\n            \n            await selected_peripheral.disconnect()\n            print(f\"Disconnected from {selected_peripheral.identifier()}\")\n        else:\n            print(\"No connectable peripherals found to demonstrate connection.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"This asynchronous quickstart demonstrates how to initialize an adapter, scan for Bluetooth Low Energy (BLE) peripherals, and connect to a discovered device. It uses the `simplepyble.aio` module, which offers an `asyncio`-compatible API with automatic callback cleanup and context manager support for robust asynchronous operations."},"warnings":[{"fix":"Review the new license terms (BUSL-1.1) for compliance with your project's use case. Contact SimpleBLE maintainers for commercial licensing inquiries if needed.","message":"As of v0.9.0 (January 2025), SimpleBLE (and thus SimplePyBLE) has changed its license to Business Source License 1.1 (BUSL-1.1). Commercial use requires a commercial license, though free licenses are offered for small projects. Ensure your project's licensing is compatible.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Upgrade to simplepyble v0.10.3 or newer to benefit from stability fixes related to threading and GIL management.","message":"Versions prior to v0.10.3 (June 2025) and v0.10.2 (June 2025) experienced several deadlocks and GIL issues within the Python bindings, particularly on Windows when interacting with WinRT threading models. This could lead to application freezes or crashes.","severity":"gotcha","affected_versions":"<0.10.3"},{"fix":"For asynchronous applications, use `from simplepyble.aio import Adapter` and follow the `asyncio` patterns. For older versions, consider upgrading or using separate threads for blocking BLE operations if a responsive UI is required.","message":"The `simplepyble.aio` module, providing an `asyncio`-compatible API, was introduced in v0.12.1 (February 2026). If you are using an older version or trying to implement asynchronous operations with the synchronous API, you might encounter blocking behavior or need to manually manage threads.","severity":"gotcha","affected_versions":"<0.12.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure that the 'Desktop development with C++' workload is installed in Visual Studio, including 'MSVC v143 - VS 2022 C++ x64/x86 build tools' and 'Windows 10/11 SDK'. If problems persist, consider trying a slightly older Python version for which pre-built wheels might be available.","cause":"This error typically occurs during `pip install simplepyble` on Windows, especially with newer Python versions (e.g., 3.13), indicating that necessary C++ build tools or SDK components are missing for compiling the underlying C++ library.","error":"FileNotFoundError: [WinError 2] The system cannot find the file specified"},{"fix":"Install the latest Microsoft Visual C++ Redistributable for your system (x64 and/or x86) from the official Microsoft website. Ensure any other system-level dependencies are correctly installed and visible in the system's PATH.","cause":"This error appears when attempting to `import simplepyble` on Windows, even after a seemingly successful installation. It means the Python bindings (`_simplepyble.pyd`) cannot find required runtime DLLs on the system's PATH, such as Visual C++ Redistributables.","error":"DLL load failed while importing _simplepyble: The specified module could not be found."},{"fix":"Install the necessary development packages. For Debian/Ubuntu-based systems, run: `sudo apt-get update && sudo apt-get install libdbus-1-dev`. Adapt for other distributions (e.g., `dnf install dbus-devel` on Fedora, `pacman -S dbus` on Arch).","cause":"During `pip install simplepyble` on Linux, this indicates a failure to compile the C++ backend. A common reason is missing system development headers, particularly for D-Bus.","error":"ERROR: Failed building wheel for simplepyble"},{"fix":"Verify that your Bluetooth hardware is enabled and turned on. On Linux, ensure your user has permissions to access Bluetooth devices (e.g., `sudo usermod -a -G bluetooth $USER` and reboot). Restart the Bluetooth service if necessary (e.g., `sudo systemctl restart bluetooth`).","cause":"When `Adapter.get_adapters()` returns an empty list or your program immediately exits with this message, it usually means no Bluetooth adapter is active, available, or the application lacks the necessary permissions to access it.","error":"No adapters found"}]}