Skip to main content

​
Overview

Cerulion RCL Hooks is a powerful integration tool that automatically hijacks ROS 2 messages before serialization and publishes them directly to Cerulion’s shared memory transport system. Think of it as a high-performance interceptor that seamlessly transfers your ROS 2 nodes to Cerulion, enabling sub-microsecond payload-agnostic latencies without requiring any changes to your existing ROS code or drivers.

​
What are RCL Hooks?

RCL Hooks is a shared library that intercepts ROS 2’s RCL (ROS Client Library) API calls. When your ROS nodes publish messages, the hooks automatically:
  • Hijack the message before ROS serialization occurs
  • Publish directly to Cerulion shared memory (no serialization required)
  • Stop forwarding to ROS subscribers (messages are hijacked, not mirrored)
RCL stands for “ROS Client Library” - it’s the low-level API that ROS 2 uses for communication. By intercepting these calls before serialization, we can hijack messages and route them to Cerulion’s high-performance shared memory transport without modifying your application code. ROS 2 nodes seamlessly transfer to Cerulion, and your drivers won’t know the difference.

​
Why Use RCL Hooks?

Zero Code Changes

Your existing ROS 2 nodes and drivers work seamlessly without any modifications. No code changes needed.

Seamless Transition

ROS 2 nodes seamlessly transfer to Cerulion - your drivers won’t know the difference. The transition is completely transparent.

Sub-Microsecond Latencies

Hijacks messages before serialization and publishes to shared memory, enabling payload-agnostic sub-microsecond latencies that make your code run faster.

Automatic Discovery

Automatically detects and hijacks any topic your node publishes, including images, sensor data, and transforms.

​
How It Works

The hooks use a technique called LD_PRELOAD to inject themselves into your ROS process. Here’s the high-level flow:
  1. Library Injection: When you launch a ROS node with LD_PRELOAD, the hooks library loads first
  2. Symbol Interception: The hooks intercept calls to ROS functions like rcl_publish() before they reach ROS serialization
  3. Message Hijacking: When your node publishes a message, the hooks hijack it before serialization occurs
  4. Shared Memory Publishing: The message is published directly to Cerulion shared memory (no serialization - that’s why it’s faster)
  5. Seamless Transfer: ROS 2 nodes seamlessly transfer to Cerulion. Messages stop going to ROS subscribers, but your drivers operate normally without knowing the difference
This approach hijacks messages at the lowest level before ROS serialization, enabling Cerulion to achieve sub-microsecond latencies by publishing directly to shared memory. Unlike ROS 2 which continues to serialize locally (making it slower), Cerulion bypasses serialization entirely.

​
What Gets Hijacked?

The hooks automatically hijack:
  • Image streams - Camera feeds, compressed images, depth images
  • Sensor data - IMU readings, camera info, sensor metadata
  • Transform data - TF static transforms and dynamic transforms
  • Any ROS topic - As long as a schema exists for the message type
The hooks only hijack topics that have corresponding schemas. Schemas define how to map ROS message fields to Cerulion’s format. Common schemas are included, and you can add more for custom message types.

​
Key Concepts

​
LD_PRELOAD

LD_PRELOAD is a Linux feature that lets you load a library before other libraries. This allows the hooks to intercept function calls before they reach the original ROS library.

​
Message Handling

Cerulion RCL Hooks does NOT serialize data. Instead, it hijacks messages before ROS serialization occurs and publishes them directly to Cerulion shared memory. This payload-agnostic approach enables sub-microsecond latencies. Key difference: ROS 2 continues to serialize locally (making it slower), while Cerulion bypasses serialization entirely by publishing directly to shared memory. This is why Cerulion is faster - it doesn’t perform the expensive serialization step that ROS 2 requires.

​
Schema Files

Schemas are YAML files that describe ROS message types. They tell Cerulion how to:
  • Map ROS message fields to Cerulion’s format
  • Handle special types (like images, arrays, nested messages)
  • Validate message structure
Schemas live in the schemas_ros2/ directory and are loaded automatically when new message types are encountered.

​
Benefits at a Glance

  • ✅ No application changes - Works with any ROS 2 node without rewriting drivers
  • ✅ Seamless transition - ROS 2 nodes seamlessly transfer to Cerulion
  • ✅ Drivers don’t know the difference - Complete transparency for ROS 2 drivers
  • ✅ Automatic discovery - Detects and hijacks topics automatically
  • ✅ Sub-microsecond performance - Payload-agnostic latencies via shared memory
  • ✅ No serialization overhead - Faster than ROS 2 which continues to serialize locally

​
Next Steps

Ready to get started? Follow these guides:

Installation

Learn how to build the RCL Hooks shared library

Usage

Discover how to run ROS nodes with the hooks enabled