adi_iio – ROS2 Package for IIO Integration

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 guides:

Note: Some links in this README work only in the CI-built documentation.

• For information on prerequisites, repository setup, and building the package, please refer to the Installation Guide.

• For instructions on how to build the project documentation locally, please refer to the Building the Documentation Guide.

• To learn how to launch the package and begin processing sensor data, see the Quick Start Guide.

• For information regarding node parameters, service interfaces, and topic communications, please refer to the Node Description Guide.

• For more in-depth information for developers on how to contribute to this project, please refer to the Contributing Section of this document.

Getting Help

• Issue Tracker: Report bugs, request features, or submit technical queries via our Issue Tracker.

• FAQ: Consult our FAQ Document for answers to common questions.

• 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.md 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 LICENSE.

Changelog

Refer to our CHANGELOG file for version history and release notes.

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.