{"id":7051,"library":"bluezoo","title":"bluezoo - BlueZ D-Bus API Mock","description":"bluezoo is a Python library that provides an in-process mock for the BlueZ D-Bus API, primarily for testing Bluetooth-related applications. It intercepts D-Bus calls to 'org.bluez' on the system bus, allowing developers to simulate Bluetooth device behavior without requiring a physical Bluetooth adapter or a running BlueZ daemon. The current version is 1.0.2, and it appears to have a stable release cadence for bug fixes and minor improvements.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/Samsung/BlueZoo","tags":["bluetooth","mocking","testing","dbus","bluez"],"install":[{"cmd":"pip install bluezoo","lang":"bash","label":"Install bluezoo"}],"dependencies":[],"imports":[{"note":"The primary class for activating the mock D-Bus service.","symbol":"BlueZMock","correct":"from bluezoo import BlueZMock"},{"note":"Utility for generating random MAC addresses for mock devices/adapters.","symbol":"generate_random_address","correct":"from bluezoo.util import generate_random_address"}],"quickstart":{"code":"import dbus\nimport dbus.mainloop.glib\nfrom bluezoo import BlueZMock\nfrom bluezoo.util import generate_random_address\n\n# NOTE: dbus-python and pygobject are required in the environment to use bluezoo effectively.\n#       Install them with: pip install dbus-python pygobject\n\n# Make sure dbus-python uses the GLib main loop by default for this process.\n# This is crucial for BlueZ D-Bus interactions.\ndbus.mainloop.glib.DBusGMainLoop(set_as_default=True)\n\n# Use BlueZMock as a context manager to activate the mock D-Bus service.\nwith BlueZMock() as mock:\n    print(\"BlueZMock is active, intercepting BlueZ D-Bus calls.\")\n\n    # 1. Add a mock Bluetooth adapter\n    adapter_path = '/org/bluez/hci0'\n    mock.add_adapter(adapter_path, name='MockAdapter', address=generate_random_address())\n    print(f\"Mock adapter '{adapter_path}' added.\")\n\n    # 2. Add a mock Bluetooth device associated with the adapter\n    device_address = generate_random_address()\n    device_path = f'{adapter_path}/dev_{device_address.replace(\":\", \"_\")}'\n    mock.add_device(\n        device_path,\n        adapter_path=adapter_path,\n        address=device_address,\n        name='MockDevice',\n        rssi=-60\n    )\n    print(f\"Mock device '{device_address}' added to adapter '{adapter_path}'.\")\n\n    # 3. Now, client code (using dbus-python) can interact with these mock objects.\n    # Get the system bus\n    bus = dbus.SystemBus()\n\n    # Get the D-Bus ObjectManager to discover objects\n    obj_manager = dbus.Interface(\n        bus.get_object('org.bluez', '/'),\n        'org.freedesktop.DBus.ObjectManager'\n    )\n    \n    # Get all managed objects and check for our mock adapter and device\n    managed_objects = obj_manager.GetManagedObjects()\n    print(\"\\nVerifying mock objects via D-Bus ObjectManager:\")\n\n    found_adapter = False\n    found_device = False\n\n    for path, interfaces in managed_objects.items():\n        if path == adapter_path and 'org.bluez.Adapter1' in interfaces:\n            print(f\"  Found mock adapter at {path} with name: {interfaces['org.bluez.Adapter1']['Name']}\")\n            found_adapter = True\n        if path == device_path and 'org.bluez.Device1' in interfaces:\n            print(f\"  Found mock device at {path} with address: {interfaces['org.bluez.Device1']['Address']}\")\n            found_device = True\n\n    if not (found_adapter and found_device):\n        print(\"  Error: Mock adapter or device not found via D-Bus as expected!\")\n\nprint(\"\\nBlueZMock is inactive now (outside the 'with' block).\")\nprint(\"D-Bus calls to 'org.bluez' would now target the real BlueZ daemon if running, or fail.\")\n\n# Optional: Demonstrate failure outside the mock context\ntry:\n    bus = dbus.SystemBus()\n    # This call would fail if no real BlueZ daemon is running\n    bus.get_object('org.bluez', '/') \nexcept dbus.exceptions.DBusException as e:\n    print(f\"Attempting to access BlueZ outside mock context resulted in expected error: {e}\")","lang":"python","description":"This quickstart demonstrates how to activate the `BlueZMock` context, add mock Bluetooth adapters and devices, and then verify their presence using standard `dbus-python` calls. It highlights that `bluezoo` allows your code to interact with a simulated BlueZ environment, rather than a real one."},"warnings":[{"fix":"Understand its purpose: strictly for testing code that interacts with BlueZ via D-Bus. For real Bluetooth, ensure BlueZ daemon is running.","message":"bluezoo is a *mocking* library for the BlueZ D-Bus API, intended for testing. It does not provide real Bluetooth functionality. Do not use it as a replacement for a running BlueZ daemon in production or for actual Bluetooth communication.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install required D-Bus client libraries: `pip install dbus-python pygobject`.","message":"To effectively use bluezoo, your environment also needs `dbus-python` and `pygobject` (for `gi.repository.GLib`) installed. While not direct `bluezoo` dependencies, these are essential for client code to interact with the mocked D-Bus service in a realistic way.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your code under test exclusively uses the BlueZ D-Bus API for Bluetooth interactions when using `bluezoo` for mocking.","message":"bluezoo only mocks the D-Bus interface of BlueZ. It does not mock direct kernel Bluetooth sockets (e.g., `bluetooth.socket`), HCI commands, or other low-level interactions. Code that bypasses D-Bus will not be affected by `BlueZMock`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your code that interacts with 'org.bluez' is executed within a `with BlueZMock() as mock:` block when testing, or verify the actual BlueZ daemon is running if you intend to use real hardware.","cause":"This error occurs when `dbus-python` attempts to connect to the 'org.bluez' service, but either the real BlueZ daemon is not running, or `BlueZMock` is not active (e.g., outside its `with` block).","error":"dbus.exceptions.DBusException: org.freedesktop.DBus.Error.ServiceUnknown: The name org.bluez was not provided by any .service files"},{"fix":"Interact with the mocked BlueZ service using standard `dbus-python` patterns, e.g., `bus.get_object('org.bluez', adapter_path)` followed by `dbus.Interface(adapter_object, 'org.bluez.Adapter1')`.","cause":"You are attempting to call D-Bus methods directly on the `BlueZMock` instance. `BlueZMock` intercepts D-Bus calls, but client code still interacts with the D-Bus service via `dbus-python` objects, not the `BlueZMock` object itself.","error":"AttributeError: 'BlueZMock' object has no attribute 'get_adapter_by_path' (or similar methods)"},{"fix":"Install `pygobject`: `pip install pygobject`.","cause":"The `pygobject` library, which provides the `gi.repository.GLib` module necessary for `dbus-python`'s GLib main loop integration, is not installed in your environment.","error":"ImportError: cannot import name 'GLib' from 'gi.repository'"}]}