ICEY documentation

ICEY is a new client API for modern asynchronous programming in the Robot Operating System (ROS) 2. It uses C++20 coroutines with async/await syntax for service calls and TF lookups. ICEY allows you to model data flows based on streams and promises. These features simplify application code and make asynchronous data flows clearly visible.

Problems ICEY solves:

• Deadlocks are impossible since there is no need to manually spin the ROS executor (event loop) inside callbacks.

• There are no memory leaks during service calls — every request is cleaned up automatically after the specified timeout.

• All callbacks can be asynchronous functions (i.e., coroutines), which makes it possible to call and co_await other asynchronous operations inside callbacks.

• A consistent async/await-based API for all asynchronous operations, including service calls and TF lookup.

• Topic synchronization without boilerplate code

ICEY is fully compatible with the ROS 2 API since it is built on top of rclcpp. This allows for gradual adoption. It supports all major ROS features: parameters, subscriptions, publishers, timers, services, clients, and TF. Additionally, ICEY supports lifecycle nodes using a single API. ICEY operates smoothly with the message_filters package, using it for synchronization. ICEY is also extensible, as demonstrated by its support for image transport camera subscription/publishers. ICEY supports ROS 2 Humble and ROS 2 Jazzy.

The icey_examples package contains many different example nodes, demonstrating the capabilities of ICEY.

Basics

• Your first ICEY-Node
  • Install
  • Using ICEY in an existing node (gradual adoption)
  • Convenience classes: icey::Node and icey::LifecycleNode
  • First example
• Publish and subscribe
  • The Stream concept
  • Subscribe
  • Publishers
  • References
• Timers
  • Key differences to regular ROS are:
• Parameters
  • Parameter structs
  • Declaring single parameters
  • References
• Async flow: Synchronizing and filtering Streams
  • Publish
  • Filter
  • Synchronization
  • Error handling: unwrap_or
  • Timeout
  • Buffer
  • Control flow: Multiple inputs and multiple outputs
• Coroutine basics
  • Why are coroutines a good fit for ROS ?
• Services using async/await
  • Client
  • Server
• References
• Using transforms (TF)
  • Looking up transforms:
  • Synchronizing with a transform
  • Subscribing to transforms
  • Publishing transforms
• Lifecycle nodes

Advanced

• Extending ICEY: support for image_transport
  • Declaring a custom Stream
  • Creating the subscription
  • Putting values in the stream
  • Error handling
  • Using the new Stream
• API Reference
  • Table of Contents
• Developing ICEY
  • Run tests:
  • Debug example node
  • Run with GDB
  • GDB 101:
  • Debug unit test:
  • Run clang-tidy:
  • Build documentation