adi_iio - ROS2 Package for IIO Integration

::: {.contents depth=”2”} :::

Overview

The adi_iio package bridges the gap between Analog Devices’ IIO hardware and the ROS2 ecosystem. It provides robust, easy-to-integrate interfaces for sensor data acquisition and real-time processing, enabling rapid development of advanced robotics and automation applications.

By facilitating seamless communication and data exchange between IIO devices and ROS2 nodes, the package serves as a comprehensive framework for integrating industrial I/O systems into modern robotics solutions. It provides a collection of services to read/write IIO attributes, and manage IIO buffers. You can also attach topics to the attributes/buffers

This project is intended for both internal developers and external contributors seeking to leverage Analog Devices’ IIO devices within ROS2 environments.

Getting Started

To help you quickly get started with the adi_iio package, we have organized detailed documentation into several sections:

• For information on prerequisites, repository setup, and building the package, refer to the Installation section.
• For information on parameters and services, refer to the Node Description section.
• For building this documentation, refer to Building the Project Documentation Locally.

Getting Help

• Issue Tracker: Report bugs, request features, or submit technical queries via our Issue Tracker.
• Further Guidance: For additional communication guidelines, refer to COMMUNICATION.

Contributing

Contributions are key to our project’s success. Before submitting changes:

• Familiarize yourself with our code and testing conventions.
• Consult the CONTRIBUTING for detailed instructions.
• Ensure your code adheres to our design values and guidelines.

License

This project is licensed under the Apache License, Version 2.0.

Software Architecture

Installation

This section describes how to install the required software to run the adi_iio package.

Prerequisites:

Before installing the adi_iio package, ensure you have the following:

• A compatible version of ROS2 installed (e.g., humble). See the ROS2 Humble Installation Guide for instructions.
• The libiio v0 library installed in the Host (e.g.: x86_64 host running Ubuntu 22.04) as well as the target (e.g.: Raspberry Pi 4). It can be automatically installed via rosdep in systems where ROS2 is installed. Alternatively, you can build a specific version of it from source using the provided installation script (see (Optional) Build libiio from sources).

Build from Source

Source your main ROS2 environment as the underlay (in this example, ROS2 humble):

``` {.sourceCode .bash} source /opt/ros/humble/setup.sh

### Workspace Setup

If you are not using this node in an existing project, create a new
folder `ros2_ws`, then create the `src` folder in `ros2_ws`. Go to src
folder (either in ros2\_ws or in your project), and clone the adi\_iio
repository (make sure to clone the correct branch for your ROS2
version):


``` {.sourceCode .bash}
export COLCON_WS=~/ros2_ws
mkdir -p $COLCON_WS/src
cd $COLCON_WS/src
git clone --branch humble https://github.com/analogdevicesinc/iio_ros2.git

::: {.tip} ::: {.admonition-title} Tip :::

After cloning, your directory structure should look like this:

``` {.sourceCode .bash} ros2_ws/ └── src/ └── iio_ros2/

:::

### Resolving Dependencies

Before building the workspace, you need to resolve the package
dependencies. From the root of your workspace, run the following
command:


``` {.sourceCode .bash}
cd $COLCON_WS
rosdep update
rosdep install -i --from-path src --rosdistro ${ROS_DISTRO} -y --ignore-src

::: {.tip} ::: {.admonition-title} Tip :::

If you already have all your dependencies, the console will return:

``` {.sourceCode .bash} #All required rosdeps installed successfully

:::

::: {#(Optional) Build libiio from sources}
::: {.note}
::: {.admonition-title}
Note
:::

**Optional: Build Libiio from Source**

The [adi\_iio]{.title-ref} package supports an alternative method of
installing the libiio dependency by building it from source. This is
useful if you prefer to use a custom version of libiio instead of
relying on the system-provided `libiio-dev` package via rosdep.

To build libiio from source, run the provided installation script which
offers two options:

-   Set the desired libiio version (default is `libiio-v0`).
-   Specify the staging directory for the source build (default is
    `$HOME/src`).

For example:


``` {.sourceCode .bash}
# Optional exports
export LIBIIO_VERSION=libiio-v0
export STAGING_DIR=$HOME/src

cd ${COLCON_WS}/src/iio_ros2
./ci/install_dependencies.sh

After the script completes, install the remaining package dependencies while skipping the system's libiio development package:

``` {.sourceCode .bash} cd ${COLCON_WS} rosdep install –from-paths src –ignore-src -r -y –skip-keys libiio-dev

:::
:::

### Building the Workspace

You can now build your package using the command:


``` {.sourceCode .bash}
colcon build --event-handlers console_cohesion+

Then source the previously built overlay run:

``` {.sourceCode .bash} source install/setup.sh

Now you can run the `adi_iio` package.

`adi_iio` - Node-Specific Concepts {#node_specific_concepts}
==================================

This section provides a concise overview of the node-specific concepts
for the ROS2 package. It details the conventions for attribute paths,
topic naming, service responses, and buffer operations used when
interfacing with IIO devices.

IIO Path {#iio_path}
--------

Services use the `iio_path` parameter to uniquely identify Industrial
I/O (IIO) devices, channels, and attributes following the IIO context
hierarchy. The `/` character is used to separate different levels of the
hierarchy.

### Context Path

-   **Description:** an empty string is used to represent an IIO
    context.
-   **Format:** `""` (empty string.)

### Context Attribute Path (`attr_path`)

-   **Description:** this path represents an attribute of a context.
-   **Format:** `<context-attribute>`
-   **Example:** `uri`, `hw_vendor`, `hw_serial`, etc.

### Device Path (`device_path`)

-   **Description:** this path represents a device of a context.
-   **Format:** `<device-name>`
-   **Example:** `ad9361-phy`, `ad5592r`, etc.

### Device Attribute Path (`attr_path`)

-   **Description:** this path represents an attribute of a device.
-   **Format:** `<device-name>/<device-attribute>`
-   **Example:** `xadc/sampling_frequency`, etc.

### Channel Path (`channel_path`)

-   **Description:** this path represents a channel of a device.
-   **Format:** `<device-name>/<channel-name>`
-   **Example:** `ad5592r/input_voltage0`, `ad5592r/output_voltage0`,
    `ad9361-phy/voltage0`, etc.
-   **Note:** the channel name has an extended format which uses a
    prefix: `input_` or `output_` to indicate the direction of data flow
    for channels that share the same name. For example,
    `ad5592r/input_voltage0` and `ad5592r/output_voltage0` are both
    valid paths that refer to two different channels of the same device.
    When the prefix is not used (e.g: `ad5592r/voltage0`) but the device
    has both input and output channels, the input channel has priority.

### Channel Attribute Path (`attr_path`)

-   **Description:** this path represents an attribute of a channel.
-   **Format:** `<device-name>/<channel-name>/<channel-attribute>`
-   **Example:** `ad5592r/input_voltage0/scale`,
    `ad5592r/output_voltage0/scale`,
    `/cf-ad9361-lpc/voltage0/sampling_frequency`, etc.

Topic Name Resolution {#topic_name_resolution}
---------------------

The `EnableTopic` services can take an optional `topic_name` parameter.
When enabling the topic, the provided `topic_name` will be used. The
default value for this parameter is `""`. When this default is used, the
specific device/channel attribute name is prefixed with the node name.
For topics that deal with attributes, two topics will be created for
read and write operations. These topics are suffixed with `/read` and
`/write`. To adhere to ROS2 topic naming standards, the hyphen `-` is
replaced by an underscore `_`.

**Example:**

-   An adi-iio node named `radio` that enables the topic
    `/cf-ad9361-lpc/voltage0/sampling_frequency` will publish to
    `/radio/cf_ad9361_lpc/voltage0/sampling_frequency/read` and
    subscribe to
    `/radio/cf_ad9361_lpc/voltage0/sampling_frequency/write` for
    updates.

Service Responses {#service_responses}
-----------------

All service responses contain at least two fields: a boolean indicating
success and a string message.


``` {.sourceCode .}
AttrReadString.srv:

string attr_path
---
bool success
string message

If the service operation is successful, the success boolean is set to true and the message will be "Success". In case of failure, the success boolean is set to false, and the message contains the errno returned by the IIO command along with its string interpretation.

Buffers

A buffer represents continuous data capture from a device. The following operations can be performed with IIO buffers:

• Create buffer: The device starts capturing data.
• Refill buffer: Data is transported from the device to the client via an Int32MultiArray in a service response.
• Enable buffer topic: The node initiates a continuous capture and publishes acquired data on the associated topic.
• Destroy buffer: The device stops capturing data.
• Read buffer: A convenience operation that bundles buffer creation and refill into one service call.

When creating a buffer, a channels array is required as a parameter for the service request. For example:

• {"voltage0"} – for a single channel.
• {"voltage0", "voltage1", "voltage2", "voltage3"} – for multiple channels.

The data is bundled in an Int32MultiArray. Data is interleaved in the buffer such that the dimensions represent the number of samples and the number of channels. For instance, a request that acquires data from channels {"voltage0", "voltage1"} would yield a buffer arranged as follows:

``` {.sourceCode .} {voltage0_sample0, voltage1_sample0, voltage0_sample1, voltage1_sample1, voltage0_sample2, voltage1_sample2, … }

`adi_iio` - Node Description {#Node Description}
============================

Parameters
----------

The node accepts the following parameters:

-   `uri`: The URI of the LibIIO context where the device is connected
    to (e.g.: `ip:192.168.2.1`)

Services
--------

The node provides the following services:

### AttrDisableTopic {#AttrDisableTopic}

**Description:** Disables the topic associated with a specific
attribute.

**Request:**

-   `attr_path` (string): The path to the attribute to be disabled.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### AttrEnableTopic {#AttrEnableTopic}

**Description:** Enables a topic for a specific attribute.

**Request:**

-   `attr_path` (string): The path to the attribute for which a topic
    will be enabled.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### AttrReadString {#AttrReadString}

**Description:** Reads an IIO attribute as a string.

**Request:**

-   `attr_path` (string): The path to the attribute to be read.

**Response:**

-   `value` (string): The value of the attribute.
-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### AttrWriteString {#AttrWriteString}

**Description:** Writes an IIO attribute as a string

**Request:**

-   `attr_path` (string): The path to the attribute to be written.
-   `value` (string): The value to be written to the attribute.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferCreate {#BufferCreate}

**Description:** Creates a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `channels` (string\[\]): The channels to be read from the buffer.
-   `samples_count` (int32): The number of samples for the buffer.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferDestroy {#BufferDestroy}

**Description:** Destroys a buffer.

**Request:**

-   `device_path` (string): The path to the device.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferDisableTopic {#BufferDisableTopic}

**Description:** Disables a topic for a buffer.

**Request:** \* `device_path` (string): The path to the device.

**Response:** \* `success` (bool): Indicates whether the operation was
successful. \* `message` (string): A message providing additional
information.

### BufferEnableTopic {#BufferEnableTopic}

**Description:** Enables a topic for a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `topic_name` (string): The name of the topic to be enabled.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### BufferRead {#BufferRead}

**Description:** Reads data from a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `channels` (string\[\]): The channels to be read from the buffer.
-   `samples_count` (int32): The number of samples to read.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `buffer` (Int32MultiArray): The data read from the buffer.

### BufferRefill {#BufferRefill}

**Description:** Refills a buffer.

**Request:**

-   `device_path` (string): The path to the device.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `buffer` (Int32MultiArray): The data read from the buffer after
    refilling.

### BufferWrite {#BufferWrite}

**Description:** Writes data to a buffer.

**Request:**

-   `device_path` (string): The path to the device.
-   `channels` (string\[\]): The channels where data will be written.
-   `buffer` (Int32MultiArray): The data to be written to the buffer.
-   `cyclic` (bool): Indicates whether the buffer should be cyclic.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.

### ScanContext {#ScanContext}

**Description:** Scans the current IIO context and returns lists of
devices, channels, and attributes formatted as IIO paths which can be
used as request parameters for the other services.

**Request:**

-   None. The operation uses the `uri` provided during node
    initialization to scan for devices.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `devices` (string\[\]): A list of IIO paths to the discovered
    devices.
-   `channels` (string\[\]): A list of IIO paths to the discovered
    channels.
-   `context_attrs` (string\[\]): A list of IIO paths to the discovered
    context attributes.
-   `device_attrs` (string\[\]): A list of IIO paths to the discovered
    device attributes.
-   `channel_attrs` (string\[\]): A list of IIO paths to the discovered
    channel attributes.

### ListDevices {#ListDevices}

**Description:** Lists the IIO device paths found in the current
context.

**Request:**

-   None. The operation uses the `uri` provided during node
    initialization to scan for devices.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `data` (string\[\]): A list containing the IIO device paths.

### ListChannels {#ListChannels}

**Description:** Lists the IIO channel paths found in the targeted
device.

**Request:**

-   `iio_path` (string): The IIO path to the device to be scanned.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `data` (string\[\]): A list containing the IIO channel paths.

### ListAttributes {#ListAttributes}

**Description:** Lists the IIO attribute paths found in the target path.
This can be either a context, device, or channel path.

**Request:**

-   `iio_path` (string): The IIO path to a context,device or channel to
    be scanned.

**Response:**

-   `success` (bool): Indicates whether the operation was successful.
-   `message` (string): A message providing additional information.
-   `data` (string\[\]): A list containing the IIO attribute paths.

Launch
------

To launch the node, you can use the provided launch file
`adi_iio_bringup.launch.py`. This launch file uses the the `uri`
parameter defined in the `config/adi_iio.yaml` file.

The project also contains a small python script to visualize the
waveform using matplotlib plots. The `topic` parameter is used to
subscribe to the topic where the waveform is published and plot the
waveforms.


``` {.sourceCode .bash}
ros2 launch adi_iio adi_iio_bringup.launch.py
python3 visualize_iio_waveform.py --topic /m2k_adc

Building the Project Documentation Locally {#Building the Project Documentation Locally}

This guide describes how to build the project documentation locally using rosdoc2. Follow the steps below to set up your environment, build the documentation, and view the results.

Prerequisites

• Python 3: Ensure you have Python 3 installed.
• Virtual Environment: It is highly recommended to set up a Python virtual environment to avoid conflicts with other projects.
• Dependencies: All required dependencies are listed in doc/requirements.txt.

Setting Up the Virtual Environment

1. Create the Virtual Environment

``` {.sourceCode .bash} python3 -m venv .venv

2.  **Activate the Virtual Environment**

    
``` {.sourceCode .bash}
    source .venv/bin/activate
    

1. Install the Required Dependencies

``` {.sourceCode .bash} pip3 install -r doc/requirements.txt

4.  **Source the Virtual Environment**

    
``` {.sourceCode .bash}
    source .venv/bin/activate
    

Generate the Documentation

With the environment set up, build the documentation by running the following script which automatically install the required dependencies and build the documentation:

``` {.sourceCode .bash} cd ${COLCON_WS}/src/iio_ros2 ./ci/build_doc.sh

```

You can now view the generated documentation by opening the _build/docs_output/adi_iio/index.html file in your web browser.

Contributing Guidelines

Thank you for your interest in contributing to iio_ros2. Whether it’s a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

• Contributing Guidelines
  • How to Contribute
    • Contributing source code
      • Code Style
      • How to Contribute Source Code
      • Pull Request Rules
    • Bug reports
      • Before Submitting a Bug Report
      • How to Submit a Good Bug Report
    • Feature Requests
      • Before Submitting an Enhancement Suggestion
      • How to Submit a Good Enhancement Suggestion
    • Contributing documentation
      • Documentation Best Practices
  • Becoming a Trusted Committers
  • Licensing
  • Resources:

How to Contribute

Contributing source code

We follow a development process designed to reduce errors, encourage collaboration, and make high quality code. Review the following to get acquainted with this development process.

Code Style

To ensure consistency and maintain high quality across the project, please adhere to the following practices:

• It is recommended to create a Python3 virtual environment (vevnv) to manage and keep your development environment isolated

• The project follows the ROS2 coding style. This ensures that code is written uniformly and is easily maintainable.

• Install a ROS distribution and source the underlay to access the Ament Lint CLI Utilities.

• A pre-commit configuration file is provided, which includes hooks that automatically check code compliance.

  • Important: Hooks that modify file content need to be executed manually by the developer. The default hooks only perform checks.

  • For issues that can be automatically resolved, a make fix target is available. It is recommended to run this target manually to apply automatic corrections before you commit changes.

How to Contribute Source Code

• Create a fork of this repository. This will create your own personal copy of the package. All of your development should take place in your fork. If you are not sure how to do this, check out GitHub help

  • Create a create a remote pointing to the upstream remote repository.

  • Work out of a new branch, one that is not a release main branch, ideally a develop branch targeted for the currently supported ROS distribution, such as humble-develop. Remember to periodically rebase to have the latest code available.

• Write your code and remember to:
  • Always keep your branch updated with the original upstream.
  • Always sign-off you commits.
  • Run make fix before committing changes and make fixes according to the guidelines.
  • Look at the existing code and try to maintain the existing style and pattern as much as possible.

• Resolve compiler warnings or at least make sure you code does not add new ones.

• Submit a pull request to the upstream repository following the PR rules.

• Check Continuous Integration (CI): the moment you submit a pul request, a few jobs will be started which try to compile the code and run automated tests. Pay attention to any CI failures reported in the pull request, and stay involved in the conversation. On the Github UI, checks can be:
  • ✅: Passed, all good!
  • 🟡: Pending, results haven’t been received yet.
  • ❌: Failed, something is wrong.

Pull Request Rules

• Commit message includes a Signed-off-by: [name] < email > to the commit message. This ensures you have the rights to submit your code, by agreeing to the Developer Certificate of Origin. If you can not agree to the DCO, don’t submit a pull request, as we can not accept it.

  • DCO is a declaration of ownership, basically saying that you created the contribution and that it is suitable to be covered under an open source license (not proprietary).

  • If your user.name and user.email configurations are set up in git, then you can simply run git commit -signoff to have your signature automatically appended.

• Commit should be atomic, meaning it should do one thing only. A pull request may contain multiple commits if necessary to fix a bug or implement a feature.
• Commits should have good commit messages. Check out The git book for some pointers and tools to use.
• Typically, the title of the commit should have the path to the changed dir/[file], and then explaining in a few words what has been done, like: ci: add style check workflow for cpp files
• Write a concise PR description, containing all the needed details.
• Pull requests will be merged only after they have been reviewed, tested and approved by the code owners.

Bug reports

Before Submitting a Bug Report

Before creating a new issue, please search the repository’s open and recently closed issues to see if the same or a similar problem has already been reported. If the issue exists and is still open, add a comment to that issue. Otherwise, feel free to create a new one.

How to Submit a Good Bug Report

To help us resolve issues effectively, follow these guidelines when creating a bug report:

1. Use a clear and descriptive title to summarize the problem.
2. Describe the exact steps to reproduce the issue in detail. Provide enough information for someone to follow your steps exactly.
3. Include specific examples such as links to files, projects, or copy-pasteable snippets that demonstrate the issue.
4. Describe the observed behavior after performing the steps and explain what the problem is with that behavior.
5. Explain the expected behavior and why it differs from the observed behavior.
6. Attach screenshots or GIFs to visually demonstrate the issue whenever possible.
7. If the issue wasn’t triggered by a specific action, describe what you were doing before the problem occurred and include relevant details.

Provide more background by answering the following questions:

• Did the issue start recently (e.g., after updating to a new version) or has it always been present?
• If recent, can you reproduce the issue in an older version? Specify the most recent version where the issue does not occur.
• Is the issue consistently reproducible? If not, describe the frequency and conditions under which it happens.

Configuration and environment details: include the following information in your report:

• Version of adi_iio you’re using.
• Operating system name and version.
• Details about system-level dependencies and their compatibility.

By providing this information, you’ll help us understand and address the issue more efficiently.

Feature Requests

This guide will help you submit enhancement suggestions, including new features or improvements to existing functionality. Following these guidelines ensures maintainers and the community can understand your suggestion and identify related ideas.

Before Submitting an Enhancement Suggestion

• Ensure you’re using the latest software version; newer versions may already include your desired feature.
• Check if an existing library provides the functionality you’re requesting.

How to Submit a Good Enhancement Suggestion

Enhancement suggestions are tracked as GitHub issues. After determining the relevant repository, create an issue and include the following details:

1. Use a clear and descriptive title to summarize the suggestion.
2. Describe the suggested enhancement in detail, providing a step-by-step explanation of how it should work.
3. Provide specific examples to illustrate your suggestion, including code snippets as Markdown code blocks.
4. Describe the current behavior and explain the desired behavior, including why the change would be beneficial.
5. Attach screenshots or GIFs to visually explain your suggestion, if applicable.
6. Justify why this enhancement would benefit most users and explain why it shouldn’t be implemented as a separate application.
7. Include version details:
   • Version of the repository you’re using.
   • Name and version of your operating system.

By following these steps, you’ll help ensure your suggestion is well-understood and can be considered effectively.

Contributing documentation

Thank you for your interest in contributing to the project’s documentation! For an in-depth understanding of the documentation system’s design and structure, refer to the Documentation Guidelines

Documentation Best Practices

We follow the documentation guidelines outlined in Analog Devices Documentation Guidelines. Please review these guidelines to ensure consistency and quality in your contributions.

Becoming a Trusted Committers

Becoming a Trusted Committer is about consistently contributing value to the project and supporting its community. Here are some suggestions to help you grow into this role:

1. Contribute Regularly: Submit high-quality contributions, including code, documentation, and reviews, that align with the project’s standards and best practices.

2. Collaborate Actively: Engage positively with maintainers and contributors by participating in discussions, offering constructive feedback, and fostering a collaborative environment.

3. Follow Best Practices: Adhere to the project’s coding, documentation, and contribution guidelines to set a strong example for others.

4. Be Responsive: Actively review pull requests, respond to issues, and assist other contributors in a timely and respectful manner.

5. Take Ownership: Show initiative by taking responsibility for specific areas of the project, ensuring their quality, maintenance, and alignment with project goals.

Licensing

Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.

Resources:

• How to write a good commit message and another resource.
• Write better commits, build better projects.
• Good commit example (but extreme one).
• How should a PR look like and anatomy of a PR.
• Submitting patches.