{"id":8493,"library":"pylibiio","title":"pylibiio","description":"pylibiio is the Python binding for the libiio library, which provides a robust interface for interacting with Linux Industrial I/O (IIO) devices. These devices include a wide range of ADCs, DACs, accelerometers, gyros, and various sensors. The library facilitates both local communication on embedded Linux targets and remote communication over USB, Ethernet, or Serial, and is actively maintained by Analog Devices, Inc. The current stable version available on PyPI is 0.25, with frequent updates to the underlying C library.","status":"active","version":"0.25","language":"en","source_language":"en","source_url":"https://github.com/analogdevicesinc/libiio","tags":["iio","hardware","analog-devices","linux","embedded","data-acquisition"],"install":[{"cmd":"pip install pylibiio","lang":"bash","label":"Install PyPI package"}],"dependencies":[{"reason":"pylibiio is a Python binding for the libiio C library. The C library must be installed separately at the system level. It is not bundled with the pip package.","package":"libiio","optional":false},{"reason":"Required for USB backend communication with IIO devices.","package":"libusb","optional":true},{"reason":"Required for network (mDNS/Bonjour) device discovery on Linux hosts.","package":"avahi-daemon","optional":true},{"reason":"Required for serial backend communication with IIO devices.","package":"libserialport","optional":true}],"imports":[{"symbol":"iio","correct":"import iio"},{"note":"All core classes like Context, Device, Channel, Buffer are typically accessed via the top-level 'iio' module.","wrong":"from iio import Context","symbol":"Context","correct":"import iio\nctx = iio.Context('local')"},{"symbol":"Device","correct":"import iio\nctx = iio.Context('local')\ndev = ctx.find_device('some_device_name')"}],"quickstart":{"code":"import iio\nimport os\n\n# Try to connect to a local or remote IIO context\n# Use 'local' for devices on the same machine, or 'ip:address' for remote\n# For testing without hardware, you can often use 'dummy'\n# The URI can also be 'usb', 'serial', or an IP address (e.g., 'ip:192.168.1.100')\n# For robust examples, use an environment variable or default to local\nuri = os.environ.get('IIO_URI', 'local') \n\ntry:\n    ctx = iio.Context(uri)\n    print(f\"Connected to IIO context: {ctx.description}\")\n\n    # Scan for available devices\n    print(\"\\nAvailable IIO devices:\")\n    for dev in ctx.devices:\n        print(f\"  - Device: {dev.name} (ID: {dev.id})\")\n        for channel in dev.channels:\n            print(f\"    - Channel: {channel.name} (ID: {channel.id}, Output: {channel.output})\")\n            # Example: Try to read an attribute if it exists\n            try:\n                sample_rate = channel.attrs['sampling_frequency'].value\n                print(f\"      Sampling Frequency: {sample_rate}\")\n            except KeyError:\n                pass\n            except Exception as e:\n                print(f\"      Error reading attribute: {e}\")\n\n    # Example: Find a specific device (replace with a known device on your system)\n    # For a dummy device, you might use 'iio:device0'\n    target_device_name = os.environ.get('IIO_TARGET_DEVICE', 'iio:device0') \n    device = ctx.find_device(target_device_name)\n    if device:\n        print(f\"\\nFound target device: {device.name}\")\n        # Example: Set a device attribute (e.g., gain, if supported)\n        # try:\n        #     if 'gain_control' in device.attrs:\n        #         device.attrs['gain_control'].value = 'manual'\n        #         print(f\"Set gain_control on {device.name}\")\n        # except KeyError:\n        #     pass\n        # except Exception as e:\n        #     print(f\"Error setting device attribute: {e}\")\n\n        # Example: Enable a channel and create a buffer to read data\n        input_channel = device.find_channel('voltage0', is_output=False)\n        if input_channel:\n            input_channel.enabled = True\n            print(f\"Enabled channel: {input_channel.name}\")\n            buffer = iio.Buffer(device, 4096) # 4096 samples\n            print(f\"Created buffer for {device.name}\")\n            # Read data (replace with actual processing)\n            data = buffer.read()\n            print(f\"Read {len(data)} bytes from buffer.\")\n            buffer.close()\n        else:\n            print(f\"Channel 'voltage0' not found on {device.name}.\")\n    else:\n        print(f\"Target device '{target_device_name}' not found.\")\n\n    ctx.close()\n    print(\"\\nDisconnected from IIO context.\")\n\nexcept Exception as e:\n    print(f\"Failed to connect to IIO context or interact with devices: {e}\")\n    print(\"Ensure the libiio C library is installed and IIO devices are available/accessible.\")","lang":"python","description":"This quickstart demonstrates how to establish a connection to an IIO context (local or remote), scan for available devices and their channels, and perform a basic buffered read operation. It includes error handling for common connection issues."},"warnings":[{"fix":"Ensure your installed `libiio` C library version matches the `0.x` series, typically `v0.25` or `v0.26` for compatibility with `pylibiio 0.25`. Avoid mixing major versions.","message":"The `pylibiio` Python bindings (version 0.x) are designed for compatibility with the `libiio` C library versions 0.x. Using `pylibiio` 0.x with `libiio` v1.x (a newer, in-development major version) can lead to runtime errors or unexpected behavior due to API changes.","severity":"breaking","affected_versions":"pylibiio 0.x with libiio 1.x"},{"fix":"Add the installation directory (e.g., `/usr/lib/python3.x/site-packages`) to your `PYTHONPATH` environment variable: `export PYTHONPATH=$PYTHONPATH:/usr/lib/python{python-version}/site-packages`.","message":"On Linux, if `pylibiio` is installed from source (rather than pip), or if `libiio`'s Python bindings are not in a standard path, you may encounter `ModuleNotFoundError` or other import issues unless `PYTHONPATH` is correctly configured.","severity":"gotcha","affected_versions":"All versions on Linux when installed from source or in non-standard locations"},{"fix":"Always use the latest stable version of `pylibiio` from PyPI and ensure your underlying `libiio` C library is also up-to-date and compatible.","message":"Past releases of `pylibiio` (e.g., 0.23, 0.21.1) were 'yanked' from PyPI due to critical issues like a broken `find_channel` method or mismatches with required `libiio` C library versions. While these versions are no longer directly installable via `pip`, it highlights the importance of using the latest stable `pylibiio` version and matching `libiio` C library.","severity":"deprecated","affected_versions":"0.21.1, 0.23"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `pylibiio` is installed: `pip install pylibiio`. If the issue persists, verify `PYTHONPATH` as described in warnings, especially on Linux or when installing from source. On Windows, ensure the `libiio` C library driver is also correctly installed.","cause":"The Python interpreter cannot locate the `iio` module, either because `pylibiio` was not installed, or because the installation path is not in `PYTHONPATH`.","error":"ModuleNotFoundError: No module named 'iio' OR Cannot find iio"},{"fix":"Ensure the `libiio` C library version and `pylibiio` Python binding version are in sync. For `pylibiio 0.25`, the `libiio` C library should also be in the `0.x` series, ideally `0.25` or `0.26`. Uninstall and reinstall both if necessary, making sure to build or install `libiio` from a compatible release.","cause":"This error typically occurs when the `pylibiio` Python bindings are compiled or linked against a different version of the `libiio` C library than what is currently installed or accessible at runtime. The specific symbol missing (e.g., `iio_get_backends_count`) indicates a version mismatch.","error":"ImportError: undefined symbol: iio_get_backends_count (or similar 'undefined symbol' error)"},{"fix":"Try reinstalling `pylibiio` from `conda-forge` if using Anaconda (`conda install -c conda-forge pylibiio`), or reinstall the official `libiio` Windows driver from Analog Devices' GitHub releases page.","cause":"This error can occur on Windows due to an issue with `libiio`'s internal handling or specific Python environment configurations, often related to dependency resolution.","error":"TypeError: 'builtin_function_or_method' object is not subscriptable (especially on Windows when importing pyadi-iio/pylibiio)"}]}