ROS Wrapper for RealSense(TM) Cameras
Latest release notes

Important Notice

We are happy to announce that the RealSense GitHub repositories have been successfully migrated to the RealSenseAI organization. Please make sure to update your links to the new RealSenseAI organization for both cloning the repositories and accessing specific files within them.

https://github.com/IntelRealSense/realsense-ros --> https://github.com/realsenseai/realsense-ros

Note: A redirection from the previous name IntelRealSense is currently in place, but we cannot guarantee how long it will remain active. We recommend that all users update their references to point to the new GitHub location.

Table of contents

• ROS1 and ROS2 legacy
• Installation on Ubuntu
• Installation on Windows
• ROS2 LifeCycleNode
• Usage
  • Starting the camera node
  • Camera name and namespace
  • Parameters
  • ROS2-vs-Optical Coordination Systems
  • TF from coordinate A to coordinate B
  • Extrinsics from sensor A to sensor B
  • Topics
  • RGBD Topic
  • Diagnostics Topic
  • RViz2 Plugin
  • Metadata Topic
  • Post-Processing Filters
  • Available Services
  • Available Actions
  • Efficient intra-process communication
  • Logging
• Contributing
• License

ROS1 and ROS2 Legacy

Installation on Ubuntu

sudo apt-get install python3-rosdep -y
sudo rosdep init # "sudo rosdep init --include-eol-distros" for Foxy and earlier
rosdep update # "sudo rosdep update --include-eol-distros" for Foxy and earlier
rosdep install -i --from-path src --rosdistro $ROS_DISTRO --skip-keys=librealsense2 -y

colcon build

ROS_DISTRO=<YOUR_SYSTEM_ROS_DISTRO>  # set your ROS_DISTRO: kilted, jazzy, iron, humble, foxy
source /opt/ros/$ROS_DISTRO/setup.bash
cd ~/ros2_ws
. install/local_setup.bash

Installation on Windows

PLEASE PAY ATTENTION: ROS Wrapper for RealSense™ cameras is not meant to be supported on Windows by our team, since ROS2 and its packages are still not fully supported over Windows. We added these installation steps below in order to try and make it easier for users who already started working with ROS2 on Windows and want to take advantage of the capabilities of our RealSense cameras

ROS2 LifeCycleNode

The USE_LIFECYCLE_NODE cmake flag enables ROS2 Lifecycle Node (rclcpp_lifecycle::LifecycleNode) in the Realsense SDK, providing better node management and explicit state transitions.

However, enabling this flag introduces a limitation where Image Transport functionality (image_transport) is disabled when USE_LIFECYCLE_NODE=ON.
This means that compressed image topics (e.g., JPEG, PNG, Theora) will not be available and
Subscribers must use raw image topics, which may increase bandwidth usage.

Note: Users who do not depend on image_transport will not be affected by this change and can safely enable Lifecycle Node without any impact on their workflow.

📌 Why This Limitation?

At the time Lifecycle Node support was added, image_transport did not support rclcpp_lifecycle::LifecycleNode.
🔗 ROS2 image_transport does not support Lifecycle Node.

To build the SDK with Lifecycle Node enabled:

colcon build --cmake-args -DUSE_LIFECYCLE_NODE=ON

To use standard ROS2 node (default behavior) and retain image_transport functionality:

colcon build --cmake-args -DUSE_LIFECYCLE_NODE=OFF

Lifecycle State Transitions

The RealSense node follows the ROS2 managed lifecycle. Below is a breakdown of each state and the corresponding function calls:

Usage

Start the camera node

with ros2 run:

ros2 run realsense2_camera realsense2_camera_node
# or, with parameters, for example - temporal and spatial filters are enabled:
ros2 run realsense2_camera realsense2_camera_node --ros-args -p enable_color:=false -p spatial_filter.enable:=true -p temporal_filter.enable:=true

with ros2 launch:

ros2 launch realsense2_camera rs_launch.py
ros2 launch realsense2_camera rs_launch.py depth_module.depth_profile:=1280x720x30 pointcloud.enable:=true

Camera Name And Camera Namespace

User can set the camera name and camera namespace, to distinguish between cameras and platforms, which helps identifying the right nodes and topics to work with.

Example

• If user have multiple cameras (might be of the same model) and multiple robots then user can choose to launch/run his nodes on this way.

• For the first robot and first camera he will run/launch it with these parameters:

  • camera_namespace:

    • robot1

  • camera_name

    • D455_1

  • With ros2 launch (via command line or by editing these two parameters in the launch file):

  ros2 launch realsense2_camera rs_launch.py camera_namespace:=robot1 camera_name:=D455_1

  • With ros2 run (using remapping mechanism Reference):

  ros2 run realsense2_camera realsense2_camera_node --ros-args -r __node:=D455_1 -r __ns:=/robot1

  ⚠️ Note: Using ros2 run may produce slightly different topics and services due to parameters not being initialized with the values assigned in rs_launch.py. This may result in additional topics such as IMU data.

  • Result

  > ros2 node list
  /robot1/D455_1
  
  > ros2 topic list
  /parameter_events
  /robot1/D455_1/color/camera_info
  /robot1/D455_1/color/image_raw
  /robot1/D455_1/color/metadata
  /robot1/D455_1/depth/camera_info
  /robot1/D455_1/depth/image_rect_raw
  /robot1/D455_1/depth/metadata
  /robot1/D455_1/extrinsics/depth_to_color
  /robot1/D455_1/extrinsics/depth_to_depth
  /rosout
  /tf_static
  
  > ros2 service list
  /robot1/D455_1/calib_config_read
  /robot1/D455_1/calib_config_write
  /robot1/D455_1/describe_parameters
  /robot1/D455_1/device_info
  /robot1/D455_1/get_parameter_types
  /robot1/D455_1/get_parameters
  /robot1/D455_1/hw_reset
  /robot1/D455_1/list_parameters
  /robot1/D455_1/set_parameters
  /robot1/D455_1/set_parameters_atomically
  

Default behavior if none of these parameters are given:

• camera_namespace:=camera
• camera_name:=camera

> ros2 node list
/camera/camera

> ros2 topic list
/camera/camera/color/camera_info
/camera/camera/color/image_raw
/camera/camera/color/metadata
/camera/camera/depth/camera_info
/camera/camera/depth/image_rect_raw
/camera/camera/depth/metadata
/camera/camera/extrinsics/depth_to_color
/camera/camera/extrinsics/depth_to_depth
/parameter_events
/rosout
/tf_static

> ros2 service list
/camera/camera/calib_config_read
/camera/camera/calib_config_write
/camera/camera/describe_parameters
/camera/camera/device_info
/camera/camera/get_parameter_types
/camera/camera/get_parameters
/camera/camera/hw_reset
/camera/camera/list_parameters
/camera/camera/set_parameters
/camera/camera/set_parameters_atomically

Parameters

Available Parameters:

• For the entire list of parameters type ros2 param list.
• For reading a parameter value use ros2 param get <node> <parameter_name>
  • For example: ros2 param get /camera/camera depth_module.emitter_enabled
• For setting a new value for a parameter use ros2 param set <node> <parameter_name> <value>
  • For example: ros2 param set /camera/camera depth_module.emitter_enabled 1

Parameters that can be modified during runtime:

• All of the filters and sensors inner parameters.
• Video Sensor Parameters: (depth_module and rgb_camera)
  • They have, at least, the <stream_type>_profile parameter.
    • The profile parameter is a string of the following format: <width>X<height>X<fps> (The dividing character can be X, x or ",". Spaces are ignored.)
    • For example: depth_module.depth_profile:=640x480x30 depth_module.infra_profile:=640x480x30 rgb_camera.color_profile:=1280x720x30
    • Note: The param depth_module.infra_profile is common for all infra streams. i.e., infra 0, 1 & 2.
    • If the specified combination of parameters is not available by the device, the default or previously set configuration will be used.
      • Run ros2 param describe <your_node_name> <param_name> to get the list of supported profiles.
    • Note: Should re-enable the stream for the change to take effect.
  • <stream_name>_format
    • This parameter is a string used to select the stream format.
    • <stream_name> can be any of infra, infra1, infra2, color, depth.
    • For example: depth_module.depth_format:=Z16 depth_module.infra1_format:=y8 rgb_camera.color_format:=RGB8
    • This parameter supports both lower case and upper case letters.
    • If the specified parameter is not available by the stream, the default or previously set configuration will be used.
      • Run ros2 param describe <your_node_name> <param_name> to get the list of supported formats.
    • Note: Should re-enable the stream for the change to take effect.
  • If the stream doesn't support the user selected profile <width>X<height>X<fps> + <format>, it will not be opened and a warning message will be shown.
    • Should update the profile settings and re-enable the stream for the change to take effect.
    • Run rs-enumerate-devices command to know the list of profiles supported by the connected sensors.
• enable_<stream_name>:
  • Choose whether to enable a specified stream or not. Default is true for images and false for orientation streams.
  • <stream_name> can be any of infra, infra1, infra2, color, depth, gyro, accel.
  • For example: enable_infra1:=true enable_color:=false
• enable_sync:
  • gathers closest frames of different sensors, infra red, color and depth, to be sent with the same timetag.
  • This happens automatically when such filters as pointcloud are enabled.
• <stream_type>_qos:
  • Sets the QoS by which the topic is published.
  • <stream_type> can be any of infra, infra1, infra2, color, depth, gyro, accel.
  • Available values are the following strings: SYSTEM_DEFAULT, DEFAULT, PARAMETER_EVENTS, SERVICES_DEFAULT, PARAMETERS, SENSOR_DATA.
  • For example: depth_qos:=SENSOR_DATA
  • Pointcloud QoS is controlled with the pointcloud.pointcloud_qos parameter in the pointcloud filter, refer to the Post-Processing Filters section for details.
  • Reference: ROS2 QoS profiles formal documentation
• Notice: <stream_type>_info_qos refers to both camera_info topics and metadata topics.
• tf_publish_rate:
  • double, rate (in Hz) at which dynamic transforms are published
  • Default value is 0.0 Hz (means no dynamic TF)
  • This param also depends on publish_tf param
    • If publish_tf:=false, then no TFs will be published, even if tf_publish_rate is >0.0 Hz
    • If publish_tf:=true and tf_publish_rate set to >0.0 Hz, then dynamic TFs will be published at the specified rate
• unite_imu_method:
  • For the D400 cameras with built in IMU components, below 2 unrelated streams (each with its own frequency) will be created:
    • gyro - which shows angular velocity
    • accel - which shows linear acceleration.
  • Both streams will publish data to its corresponding topics:
    • '/camera/camera/gyro/sample' & '/camera/camera/accel/sample'
    • Though both topics are of same message type 'sensor_msgs::Imu', only their relevant fields are filled out.
  • A new topic called imu will be created, when both accel and gyro streams are enabled and the param unite_imu_method set to > 0.
    • Data from both accel and gyro are combined and published to this topic
    • All the fields of the Imu message are filled out.
    • It will be published at the rate of the gyro.
  • unite_imu_method param supports below values:
    • 0 -> none: no imu topic
    • 1 -> copy: Every gyro message will be attached by the last accel message.
    • 2 -> linear_interpolation: Every gyro message will be attached by an accel message which is interpolated to gyro's timestamp.
  • Note: When the param unite_imu_method is dynamically updated, re-enable either gyro or accel stream for the change to take effect.
• safety_camera.safety_mode:
  • 0 -> Run mode
  • 1 -> Standby mode
  • 2 -> Service mode
• accelerate_gpu_with_glsl:
  • Boolean: GPU accelerated with GLSL for processing PointCloud and Colorizer filters.
  • Note:
    • To have smooth transition between the processing blocks when this parameter is updated dynamically, the node will:
      • Stop the video sensors
      • Do necessary GLSL configuration
      • And then, start the video sensors
    • To enable GPU acceleration, turn ON BUILD_ACCELERATE_GPU_WITH_GLSL during build:

    colcon build --cmake-args '-DBUILD_ACCELERATE_GPU_WITH_GLSL=ON'
    

Parameters that cannot be changed in runtime:

• serial_no:
  • will attach to the device with the given serial number (serial_no) number.
  • Default, attach to the first (in an inner list) RealSense device.
  • Note: serial number should be defined with "_" prefix.
    • That is a workaround until a better method will be found to ROS2's auto conversion of strings containing only digits into integers.
  • Example: serial number 831612073525 can be set in command line as serial_no:=_831612073525.
• usb_port_id:
  • will attach to the device with the given USB port (usb_port_id).
  • For example: usb_port_id:=4-1 or usb_port_id:=4-2
  • Default, ignore USB port when choosing a device.
• device_type:
  • will attach to a device whose name includes the given device_type regular expression pattern.
  • Default, ignore device type.
  • For example:
    • device_type:=d435 will match d435 and d435i.
    • device_type=d435(?!i) will match d435 but not d435i.
• reconnect_timeout:
  • When the driver cannot connect to the device try to reconnect after this timeout (in seconds).
  • For Example: reconnect_timeout:=10
• wait_for_device_timeout:
  • If the specified device is not found, will wait wait_for_device_timeout seconds before exits.
  • Defualt, wait_for_device_timeout < 0, will wait indefinitely.
  • For example: wait_for_device_timeout:=60
• rosbag_filename:
  • Publish topics from rosbag file. There are two ways for loading rosbag file:
  • Command line - ros2 run realsense2_camera realsense2_camera_node -p rosbag_filename:="/full/path/to/rosbag.bag"
  • Launch file - set rosbag_filename parameter with rosbag full path (see realsense2_camera/launch/rs_launch.py as reference)
• initial_reset:
  • On occasions the device was not closed properly and due to firmware issues needs to reset.
  • If set to true, the device will reset prior to usage.
  • For example: initial_reset:=true
• base_frame_id:
  • Suffix for constructing the camera's root frame that all static transformations refer to.
  • Defaults to "link".
  • For example: camera_link is composed of [camera_name]_[base_frame_id]
• tf_prefix:
  • Prefix to be prepended to all frame IDs published by this node (e.g., camera link, optical frames, etc.)
  • Default value is empty string (no prefix)
  • For example: tf_prefix:=robot1/ will result in frames like robot1/camera_link, robot1/camera_color_optical_frame, etc.
• clip_distance:
  • Remove from the depth image all values above a given value (meters). Disable by giving negative value (default)
  • For example: clip_distance:=1.5
• occupancy_occupied_threshold:
  • Cameras that stream a graded occupancy grid (evidence 1..100 per cell) are binarized for ~/occupancy at this value: cells at or above it publish as 100, graded cells below it as -1 (unknown). The raw graded grid is always available on ~/occupancy_certainty.
  • Default: 100 (the camera's own safety criterion). Range [1, 100].
  • Has no effect on devices that stream the legacy 1-bit grid.
  • Read once at startup; a runtime ros2 param set does not take effect.
  • The node auto-detects which of three occupancy grid wire formats an incoming frame carries -- the legacy 1-bit grid, a byte-per-cell graded grid (newer D5xx firmware), or a self-describing MAP1 payload -- with no SDK version requirement beyond occupancy stream support. ~/occupancy_certainty is published for the byte-per-cell and MAP1 formats; the legacy 1-bit format publishes ~/occupancy only.
• linear_accel_cov, angular_velocity_cov: sets the variance given to the Imu readings.
• hold_back_imu_for_frames: Images processing takes time. Therefor there is a time gap between the moment the image arrives at the wrapper and the moment the image is published to the ROS environment. During this time, Imu messages keep on arriving and a situation is created where an image with earlier timestamp is published after Imu message with later timestamp. If that is a problem, setting hold_back_imu_for_frames to true will hold the Imu messages back while processing the images and then publish them all in a burst, thus keeping the order of publication as the order of arrival. Note that in either case, the timestamp in each message's header reflects the time of it's origin.
• publish_tf:
  • boolean, enable/disable publishing static and dynamic TFs
  • Defaults to True
    • So, static TFs will be published by default
    • If dynamic TFs are needed, user should set the param tf_publish_rate to >0.0 Hz
  • If set to false, both static and dynamic TFs won't be published, even if the param tf_publish_rate is set to >0.0 Hz
• diagnostics_period:
  • double, positive values set the period between diagnostics updates on the /diagnostics topic.
  • 0 or negative values mean no diagnostics topic is published. Defaults to 0.
    The /diagnostics topic includes information regarding the device temperatures and actual frequency of the enabled streams.

ROS2(Robot) vs Optical(Camera) Coordination Systems:

• Point Of View:
  • Imagine we are standing behind of the camera, and looking forward.
  • Always use this point of view when talking about coordinates, left vs right IRs, position of sensor, etc..

• ROS2 Coordinate System: (X: Forward, Y:Left, Z: Up)
• Camera Optical Coordinate System: (X: Right, Y: Down, Z: Forward)
• References: REP-0103, REP-0105
• All data published in our wrapper topics is optical data taken directly from our camera sensors.
• static and dynamic TF topics publish optical CS and ROS CS to give the user the ability to move from one CS to other CS.

TF from coordinate A to coordinate B:

• TF msg expresses a transform from coordinate frame "header.frame_id" (source) to the coordinate frame child_frame_id (destination) Reference
• In RealSense cameras, the origin point (0,0,0) is taken from the left IR (infra1) position and named as "camera_link" frame
• Depth, left IR and "camera_link" coordinates converge together.
• Our wrapper provide static TFs between each sensor coordinate to the camera base (camera_link)
• Also, it provides TFs from each sensor ROS coordinates to its corrosponding optical coordinates.
• Example of static TFs of RGB sensor and Infra2 (right infra) sensor of D435i module as it shown in rviz2:

Extrinsics from sensor A to sensor B:

• Extrinsic from sensor A to sensor B means the position and orientation of sensor A relative to sensor B.
• Imagine that B is the origin (0,0,0), then the Extrinsics(A->B) describes where is sensor A relative to sensor B.
• For example, depth_to_color, in D435i:
  • If we look from behind of the D435i, extrinsic from depth to color, means, where is the depth relative to the color.
  • If we just look at the X coordinates, in the optical coordinates (again, from behind) and assume that COLOR(RGB) sensor is (0,0,0), we can say that DEPTH sensor is on the right of RGB by 0.0148m (1.48cm).

administrator@perclnx466 ~/ros2_humble $ ros2 topic echo /camera/camera/extrinsics/depth_to_color
rotation:
- 0.9999583959579468
- 0.008895332925021648
- -0.0020127370953559875
- -0.008895229548215866
- 0.9999604225158691
- 6.045500049367547e-05
- 0.0020131953060626984
- -4.254872692399658e-05
- 0.9999979734420776
translation:
- 0.01485931035131216
- 0.0010161789832636714
- 0.0005317096947692335
---

• Extrinsic msg is made up of two parts:
  • float64[9] rotation (Column - major 3x3 rotation matrix)
  • float64[3] translation (Three-element translation vector, in meters)

Published Topics

The published topics differ according to the device and parameters. After running the above command with D435i attached, the following list of topics will be available (This is a partial list. For full one type ros2 topic list):

• /camera/camera/aligned_depth_to_color/camera_info
• /camera/camera/aligned_depth_to_color/image_raw
• /camera/camera/color/camera_info
• /camera/camera/color/image_raw
• /camera/camera/color/metadata
• /camera/camera/depth/camera_info
• /camera/camera/depth/color/points
• /camera/camera/depth/image_rect_raw
• /camera/camera/depth/metadata
• /camera/camera/extrinsics/depth_to_color
• /camera/camera/imu
• /diagnostics
• /parameter_events
• /rosout
• /tf_static

This will stream relevant camera sensors and publish on the appropriate ROS topics.

Enabling accel and gyro is achieved either by adding the following parameters to the command line:
ros2 launch realsense2_camera rs_launch.py pointcloud.enable:=true enable_gyro:=true enable_accel:=true
or in runtime using the following commands:

ros2 param set /camera/camera enable_accel true
ros2 param set /camera/camera enable_gyro true

Enabling stream adds matching topics. For instance, enabling the gyro and accel streams adds the following topics:

• /camera/camera/accel/imu_info
• /camera/camera/accel/metadata
• /camera/camera/accel/sample
• /camera/camera/extrinsics/depth_to_accel
• /camera/camera/extrinsics/depth_to_gyro
• /camera/camera/gyro/imu_info
• /camera/camera/gyro/metadata
• /camera/camera/gyro/sample

RGBD Topic

RGBD new topic, publishing [RGB + Depth] in the same message (see RGBD.msg for reference). For now, works only with depth aligned to color images, as color and depth images are synchronized by frame time tag.

These boolean parameters should be true to enable rgbd messages:

• enable_rgbd: enable/disable rgbd topic, changeable during runtime
• align_depth.enable: align depth images to rgb images
• enable_sync: let librealsense sync between frames, and get the frameset with color and depth images combined
• enable_color + enable_depth: enable both color and depth sensors

The current QoS of the topic itself, is the same as Depth and Color streams (SYSTEM_DEFAULT)

Example:

ros2 launch realsense2_camera rs_launch.py enable_rgbd:=true enable_sync:=true align_depth.enable:=true enable_color:=true enable_depth:=true 

Diagnostics Topic

The /diagnostics topic provides real-time health monitoring of the camera, including hardware temperatures and stream frequency status. It uses the standard ROS 2 diagnostic_msgs/msg/DiagnosticArray message type.

Enabling Diagnostics

Diagnostics are disabled by default. To enable them, set the diagnostics_period parameter to a positive value (in seconds), which controls how often the diagnostics message is published.

The diagnostics_period parameter is applied only at node startup and is not dynamically reconfigurable at runtime.

Via launch file:

ros2 launch realsense2_camera rs_launch.py diagnostics_period:=1.0

You can also set diagnostics_period in a parameters YAML file that is loaded when starting the node. Changing this parameter while the node is running (e.g. using ros2 param set) will have no effect; you must restart the node for a new value to take effect.

Setting diagnostics_period to 0 (default) or a negative value disables diagnostics publishing.

Diagnostics Content

The /diagnostics topic publishes two categories of information:

1. Temperatures

Reports the camera's hardware temperatures, queried from the device sensors:

• Asic Temperature - the temperature of the camera's ASIC chip
• Projector Temperature - the temperature of the IR projector

These are published under a diagnostic entry named "Temperatures" with the device serial number as the hardware ID.

Note: The temperature diagnostic status level is always reported as OK. There are currently no threshold checks — the status will not change to WARN or ERROR based on temperature values.

2. Stream Frequency

For each enabled stream (e.g. depth, color, infra, gyro, accel), a frequency diagnostic entry is registered that monitors whether the stream is publishing at its expected frame rate. Each entry reports:

• The expected frequency (based on the stream's configured FPS)
• The actual measured frequency
• A status level: OK, WARN, or ERROR depending on how much the actual frequency deviates from the expected value

This is useful for detecting dropped frames or degraded camera performance.

Example Output

ros2 topic echo /diagnostics

header:
  stamp:
    sec: 1234567890
    nanosec: 123456789
status:
- name: "camera: Temperatures"
  hardware_id: "1234567890"
  level: 0          # OK
  message: "OK"
  values:
  - key: "Asic Temperature"
    value: "56.0"
  - key: "Projector Temperature"
    value: "52.5"
- name: "camera: depth"
  hardware_id: "1234567890"
  level: 0          # OK
  message: "Frequency within tolerance"
  values:
  - key: "Frequency (Hz)"
    value: "30.0"

RViz2 Plugin

Custom Visualizations for RealSense Camera RGBD Messages in RViz2

This RViz2 plugin provides advanced and intuitive visualization of RealSense camera RGBD data streams. It allows developers, researchers, and robotics engineers to easily inspect, debug, and present both RGB and depth information directly within RViz2.

Features

RGB and Depth Visualization

• RGB Stream Display: Visualize the color camera stream from RealSense devices.
• Depth Stream Display: View depth data with customizable visualization options.
• Display Modes: Show RGB only, depth only, or both side-by-side.

Depth Visualization Controls

• Min/Max Range Adjustment: Customize depth visualization by setting minimum and maximum depth values (in meters).
• Colormap Options: Toggle between grayscale and jet colormap for depth visualization.

Overlay Mode

• RGB + Depth Overlay: Combine RGB and depth information in a single view.
• Adjustable Alpha Blending: Control the transparency level of the depth overlay on the RGB image.
• Enhanced Perception: See RGB and depth data simultaneously for better environmental understanding.

Image Manipulation

• 180° Rotation: Flip both RGB and depth images for correct orientation when the camera is mounted upside-down.
• Split-Screen View: View RGB and depth images side-by-side with automatic layout adjustments.

Build Instructions

To use this plugin, you must enable it at build time using the -DRVIZ_RGBD_PLUGIN=ON flag with colcon build.
You can do this in two ways:

1. Build only the plugin package:

colcon build --packages-select realsense2_rviz_plugin --cmake-args -DRVIZ_RGBD_PLUGIN=ON

2. Enable the plugin for the entire workspace at build:

colcon build --cmake-args -DRVIZ_RGBD_PLUGIN=ON

Metadata topic

The metadata messages store the camera's available metadata in a json format. To learn more, a dedicated script for echoing a metadata topic in runtime is attached. For instance, use the following command to echo the camera/depth/metadata topic:

python3 src/realsense-ros/realsense2_camera/scripts/echo_metadada.py /camera/camera/depth/metadata

Metadata topic

The metadata messages store the camera's available metadata in a json format. To learn more, a dedicated script for echoing a metadata topic in runtime is attached. For instance, use the following command to echo the camera/depth/metadata topic:

python3 src/realsense-ros/realsense2_camera/scripts/echo_metadada.py /camera/camera/depth/metadata

Post-Processing Filters

The following post processing filters are available:

• align_depth: If enabled, will publish the depth image aligned to the color image on the topic /camera/camera/aligned_depth_to_color/image_raw.

  • The pointcloud, if created, will be based on the aligned depth image.

• colorizer: will color the depth image. On the depth topic an RGB image will be published, instead of the 16bit depth values .

• pointcloud: will add a pointcloud topic /camera/camera/depth/color/points.

  • The texture of the pointcloud can be modified using the pointcloud.stream_filter parameter.
    
  • The depth FOV and the texture FOV are not similar. By default, pointcloud is limited to the section of depth containing the texture. You can have a full depth to pointcloud, coloring the regions beyond the texture with zeros, by setting pointcloud.allow_no_texture_points to true.
  • pointcloud is of an unordered format by default. This can be changed by setting pointcloud.ordered_pc to true.
  • The QoS of the pointcloud topic is independent from depth and color streams and can be controlled with the pointcloud.pointcloud_qos parameter.
    • The same set of QoS values are supported as other streams, refer to <stream_type>_qos in the Parameters section of this page.
    • The launch file should include the parameter with initial QoS value, for example,{'name': 'pointcloud.pointcloud_qos', 'default': 'SENSOR_DATA', 'description': 'pointcloud qos'}
    • The QoS value can also be overridden at launch with command option, for example, pointcloud.pointcloud_qos:=SENSOR_DATA
    • At runtime, the QoS can be changed dynamically but require the filter re-enable for the change to take effect, for example,

      ros2 param set /camera/camera pointcloud.pointcloud_qos SENSOR_DATA
      ros2 param set /camera/camera pointcloud.enable false
      ros2 param set /camera/camera pointcloud.enable true
      

• hdr_merge: Allows depth image to be created by merging the information from 2 consecutive frames, taken with different exposure and gain values.

• depth_module.hdr_enabled: to enable/disable HDR. The way to set exposure and gain values for each sequence:

  • during Runtime:
    • is by first selecting the sequence id, using the depth_module.sequence_id parameter and then modifying the depth_module.gain, and depth_module.exposure.
    • From FW versions 5.14.x.x and above, if HDR is enabled, the preset configs (like exposure, gain, etc.,) cannot be updated.
      • Disable the HDR first using depth_module.hdr_enabled parameter and then, update the required presets.
  • during Launch time of the node:
    • is by setting below parameters
      • depth_module.exposure.1
      • depth_module.gain.1
      • depth_module.exposure.2
      • depth_module.gain.2
    • Make sure to set depth_module.hdr_enabled to true, otherwise these parameters won't be considered.
  • To view the effect on the infrared image for each sequence id use the filter_by_sequence_id.sequence_id parameter.
  • For in-depth review of the subject please read the accompanying white paper.
  • Note: Auto exposure functionality is not supported when HDR is enabled. i.e., Auto exposure will be auto-disabled if HDR is enabled.

• The following filters have detailed descriptions in : https://github.com/realsenseai/librealsense/blob/master/doc/post-processing-filters.md

  • disparity_filter - convert depth to disparity before applying other filters and back.
  • spatial_filter - filter the depth image spatially.
  • temporal_filter - filter the depth image temporally.
  • hole_filling_filter - apply hole-filling filter.
  • decimation_filter - reduces depth scene complexity.
  • rotation_filter - rotates depth and ir frames.

Each of the above filters have it's own parameters, following the naming convention of <filter_name>.<parameter_name> including a <filter_name>.enable parameter to enable/disable it.

Available services

hw_reset:

• reset the device. The call stops all the streams too.
• Call example: ros2 service call /camera/camera/hw_reset std_srvs/srv/Empty

device_info:

• retrieve information about the device - serial_number, firmware_version etc.
• Type ros2 interface show realsense2_camera_msgs/srv/DeviceInfo for the full list.
• Call example: ros2 service call /camera/camera/device_info realsense2_camera_msgs/srv/DeviceInfo

calib_config_read (for specific camera modules):

• Read calibration config.

• Note that reading calibration config is applicable only in Safey Service Mode

• Type ros2 interface show realsense2_camera_msgs/srv/CalibConfigRead for the full request/response fields.

• Call example: ros2 service call /camera/camera/calib_config_read realsense2_camera_msgs/srv/CalibConfigRead

  Click to see the full response of the call example

  response: realsense2_camera_msgs.srv.CalibConfigRead_Response(success=True, error_message='', calib_config='{"calibration_config":{"camera_position":{"rotation":[[0.0,0.0,1.0],[-1.0,0.0,0.0],[0.0,-1.0,0.0]],"translation":[0.0,0.0,0.0]},"crypto_signature":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"roi_0":{"vertex_0":[0,0],"vertex_1":[0,0],"vertex_2":[0,0],"vertex_3":[0,0]},"roi_1":{"vertex_0":[0,0],"vertex_1":[0,0],"vertex_2":[0,0],"vertex_3":[0,0]},"roi_2":{"vertex_0":[0,0],"vertex_1":[0,0],"vertex_2":[0,0],"vertex_3":[0,0]},"roi_3":{"vertex_0":[0,0],"vertex_1":[0,0],"vertex_2":[0,0],"vertex_3":[0,0]},"roi_num_of_segments":0}}')

calib_config_write (for specific camera modules):

• Write calibration config.

• Note that writing calibration config is applicable only in Safey Service Mode

• Type ros2 interface show realsense2_camera_msgs/srv/CalibConfigWrite for the full request/response fields.

  • Only for commnad line usage, user should escape all " with \". Using ros2 services API from rclcpp/rclpy doesn't need escaping. e.g.,:
  Click to see full call example

  ros2 service call /camera/camera/calib_config_write realsense2_camera_msgs/srv/CalibConfigWrite "{calib_config: '{\"calibration_config\":{\"camera_position\":{\"rotation\":[[0.0,0.0,1.0],[-1.0,0.0,0.0],[0.0,-1.0,0.0]],\"translation\":[0.0,0.0,0.0]},\"crypto_signature\":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],\"roi_0\":{\"vertex_0\":[0,0],\"vertex_1\":[0,0],\"vertex_2\":[0,0],\"vertex_3\":[0,0]},\"roi_1\":{\"vertex_0\":[0,0],\"vertex_1\":[0,0],\"vertex_2\":[0,0],\"vertex_3\":[0,0]},\"roi_2\":{\"vertex_0\":[0,0],\"vertex_1\":[0,0],\"vertex_2\":[0,0],\"vertex_3\":[0,0]},\"roi_3\":{\"vertex_0\":[0,0],\"vertex_1\":[0,0],\"vertex_2\":[0,0],\"vertex_3\":[0,0]},\"roi_num_of_segments\":0}}' }"

• JSON calib config example

• Result example: realsense2_camera_msgs.srv.CalibConfigWrite_Response(success=True, error_message='')

safety_preset_read:

• Read safety preset at a given index.

• Type ros2 interface show realsense2_camera_msgs/srv/SafetyPresetRead for the full request/response fields.

• Call example: ros2 service call /camera/camera/safety_preset_read realsense2_camera_msgs/srv/SafetyPresetRead "{index: 63}"

  Click to see the full response of the call example

  realsense2_camera_msgs.srv.SafetyPresetRead_Response(success=True, error_message='', safety_preset=
  '{
    "safety_preset":
    {
        "platform_config": 
        {
            "transformation_link":
            {
                "rotation":
                [
                    [ 0.0,  0.0,  1.0],
                    [-1.0,  0.0,  0.0],
                    [ 0.0, -1.0,  0.0]
                ],
                "translation": [0.0, 0.0, 0.27]
            },
            "robot_height": 1.0,
            "reserved": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
        },
        "safety_zones": 
        {
            "danger_zone":
            {
                "zone_polygon":
                {
                    "p0": {"x": 0.5, "y":  0.1},
                    "p1": {"x": 0.8, "y":  0.1},
                    "p2": {"x": 0.8, "y": -0.1},
                    "p3": {"x": 0.5, "y": -0.1}
                },
                "safety_trigger_confidence": 3,
                "reserved": [0, 0, 0, 0, 0, 0, 0]
            },
            "warning_zone":
            {
                "zone_polygon":
                {
                    "p0": {"x": 0.8, "y":  0.1},
                    "p1": {"x": 1.2, "y":  0.1},
                    "p2": {"x": 1.2, "y": -0.1},
                    "p3": {"x": 0.8, "y": -0.1}
                },
                "safety_trigger_confidence": 3,
                "reserved": [0, 0, 0, 0, 0, 0, 0]
            }
        },
        "masking_zones": 
        {
            "0":
            {
                "attributes": 0,
                "minimal_range": 0.5,
                "region_of_interests":
                {
                    "vertex_0": [0, 0],
                    "vertex_1": [0, 320],
                    "vertex_2": [200, 320],
                    "vertex_3": [200, 0]
                }
            },
            "1":
            {
                "attributes": 0,
                "minimal_range": 0.5,
                "region_of_interests":
                {
                    "vertex_0": [0, 0],
                    "vertex_1": [0, 320],
                    "vertex_2": [200, 320],
                    "vertex_3": [200, 0]
                }
            },
            "2":
            {
                "attributes": 0,
                "minimal_range": 0.5,
                "region_of_interests":
                {
                    "vertex_0": [0, 0],
                    "vertex_1": [0, 320],
                    "vertex_2": [200, 320],
                    "vertex_3": [200, 0]
                }
            },
            "3":
            {
                "attributes": 0,
                "minimal_range": 0.5,
                "region_of_interests":
                {
                    "vertex_0": [0, 0],
                    "vertex_1": [0, 320],
                    "vertex_2": [200, 320],
                    "vertex_3": [200, 0]
                }
            },
            "4":
            {
                "attributes": 0,
                "minimal_range": 0.5,
                "region_of_interests":
                {
                    "vertex_0": [0, 0],
                    "vertex_1": [0, 320],
                    "vertex_2": [200, 320],
                    "vertex_3": [200, 0]
                }
            },
            "5":
            {
                "attributes": 0,
                "minimal_range": 0.5,
                "region_of_interests":
                {
                    "vertex_0": [0, 0],
                    "vertex_1": [0, 320],
                    "vertex_2": [200, 320],
                    "vertex_3": [200, 0]
                }
            },
            "6":
            {
                "attributes": 0,
                "minimal_range": 0.5,
                "region_of_interests":
                {
                    "vertex_0": [0, 0],
                    "vertex_1": [0, 320],
                    "vertex_2": [200, 320],
                    "vertex_3": [200, 0]
                }
            },
            "7":
            {
                "attributes": 1,
                "minimal_range": 0,
                "region_of_interests":
                {
                    "vertex_0": [500, 3300],
                    "vertex_1": [800, 3300],
                    "vertex_2": [800, 3100],
                    "vertex_3": [500, 3100]
                }
            }
        },
        "reserved": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        "environment": 
        {
            "safety_trigger_duration": 1.0,
            "zero_safety_monitoring": 0,
            "hara_history_continuation": 0,
            "reserved1": [0, 0],
            "angular_velocity": 0.0,
            "payload_weight": 0.0,
            "surface_inclination": 15.0,
            "surface_height": 0.05,
            "diagnostic_zone_fill_rate_threshold": 255,
            "floor_fill_threshold": 255,
            "depth_fill_threshold": 255,
            "diagnostic_zone_height_median_threshold": 255,
            "vision_hara_persistency": 1,
            "crypto_signature": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
            "reserved2": [0, 0, 0]
        }
    }
  }')
  

safety_preset_write:

• Write safety preset at given index.

• Note that writing safety presets is applicable only in Safey Service Mode

• Type ros2 interface show realsense2_camera_msgs/srv/SafetyPresetWrite for the full request/response fields.

• Only for commnad line usage, user should escape all " with \". Using ros2 services API from rclcpp/rclpy doesn't need escaping.

  Click to see full call example, writing new Safety Preset to index 63

  ros2 service call /camera/camera/safety_preset_write realsense2_camera_msgs/srv/SafetyPresetWrite "{safety_preset: ' {\"safety_preset\":{\"platform_config\":{\"transformation_link\":{\"rotation\":[[0.0,0.0,1.0],[-1.0,0.0,0.0],[0.0,-1.0,0.0]],\"translation\":[0.0,0.0,0.27]},\"robot_height\":1.0,\"reserved\":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]},\"safety_zones\":{\"danger_zone\":{\"zone_polygon\":{\"p0\":{\"x\":0.5,\"y\":0.1},\"p1\":{\"x\":0.8,\"y\":0.1},\"p2\":{\"x\":0.8,\"y\":-0.1},\"p3\":{\"x\":0.5,\"y\":-0.1}},\"safety_trigger_confidence\":3,\"reserved\":[0,0,0,0,0,0,0]},\"warning_zone\":{\"zone_polygon\":{\"p0\":{\"x\":0.8,\"y\":0.1},\"p1\":{\"x\":1.2,\"y\":0.1},\"p2\":{\"x\":1.2,\"y\":-0.1},\"p3\":{\"x\":0.8,\"y\":-0.1}},\"safety_trigger_confidence\":3,\"reserved\":[0,0,0,0,0,0,0]}},\"masking_zones\":{\"0\":{\"attributes\":0,\"minimal_range\":0.5,\"region_of_interests\":{\"vertex_0\":[0,0],\"vertex_1\":[0,320],\"vertex_2\":[200,320],\"vertex_3\":[200,0]}},\"1\":{\"attributes\":0,\"minimal_range\":0.5,\"region_of_interests\":{\"vertex_0\":[0,0],\"vertex_1\":[0,320],\"vertex_2\":[200,320],\"vertex_3\":[200,0]}},\"2\":{\"attributes\":0,\"minimal_range\":0.5,\"region_of_interests\":{\"vertex_0\":[0,0],\"vertex_1\":[0,320],\"vertex_2\":[200,320],\"vertex_3\":[200,0]}},\"3\":{\"attributes\":0,\"minimal_range\":0.5,\"region_of_interests\":{\"vertex_0\":[0,0],\"vertex_1\":[0,320],\"vertex_2\":[200,320],\"vertex_3\":[200,0]}},\"4\":{\"attributes\":0,\"minimal_range\":0.5,\"region_of_interests\":{\"vertex_0\":[0,0],\"vertex_1\":[0,320],\"vertex_2\":[200,320],\"vertex_3\":[200,0]}},\"5\":{\"attributes\":0,\"minimal_range\":0.5,\"region_of_interests\":{\"vertex_0\":[0,0],\"vertex_1\":[0,320],\"vertex_2\":[200,320],\"vertex_3\":[200,0]}},\"6\":{\"attributes\":0,\"minimal_range\":0.5,\"region_of_interests\":{\"vertex_0\":[0,0],\"vertex_1\":[0,320],\"vertex_2\":[200,320],\"vertex_3\":[200,0]}},\"7\":{\"attributes\":1,\"minimal_range\":0,\"region_of_interests\":{\"vertex_0\":[500,3300],\"vertex_1\":[800,3300],\"vertex_2\":[800,3100],\"vertex_3\":[500,3100]}}},\"reserved\":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],\"environment\":{\"safety_trigger_duration\":1.0,\"zero_safety_monitoring\":0,\"hara_history_continuation\":0,\"reserved1\":[0,0],\"angular_velocity\":0.0,\"payload_weight\":0.0,\"surface_inclination\":15.0,\"surface_height\":0.05,\"diagnostic_zone_fill_rate_threshold\":255,\"floor_fill_threshold\":255,\"depth_fill_threshold\":255,\"diagnostic_zone_height_median_threshold\":255,\"vision_hara_persistency\":1,\"crypto_signature\":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],\"reserved2\":[1,1,1]}}} ', index: 63}"

• JSON safety preset example

• Result example: realsense2_camera_msgs.srv.SafetyPresetWrite_Response(success=True, error_message='')

safety_interface_config_read:

• Read safety interface config.

• Type ros2 interface show realsense2_camera_msgs/srv/SafetyInterfaceConfigRead for the full request/response fields.

• Call example: ros2 service call /camera/camera/safety_interface_config_read realsense2_camera_msgs/srv/SafetyInterfaceConfigRead

  Click to see the full response of the call example

  realsense2_camera_msgs.srv.SafetyInterfaceConfigRead_Response(success=True, error_message='', safety_interface_config='
  {
    "safety_interface_config":
    {
        "m12_safety_pins_configuration":
        {
            "power":
            {
                "direction": "In",
                "functionality": "p24VDC"
            },
            "ossd1_b":
            {
                "direction": "Out",
                "functionality": "pOSSD1_B"
            },
            "ossd1_a":
            {
                "direction": "Out",
                "functionality": "pOSSD1_A"
            },
            "preset3_a":
            {
                "direction": "In",
                "functionality": "pPresetSelect3_A"
            },
            "preset3_b":
            {
                "direction": "In",
                "functionality": "pPresetSelect3_B"
            },
            "preset4_a":
            {
                "direction": "In",
                "functionality": "pPresetSelect4_A"
            },
            "preset1_b":
            {
                "direction": "In",
                "functionality": "pPresetSelect1_B"
            },
            "preset1_a":
            {
                "direction": "In",
                "functionality": "pPresetSelect1_A"
            },
            "gpio_0":
            {
                "direction": "In",
                "functionality": "pPresetSelect5_A"
            },
            "gpio_1":
            {
                "direction": "In",
                "functionality": "pPresetSelect5_B"
            },
            "gpio_3":
            {
                "direction": "In",
                "functionality": "pPresetSelect6_B"
            },
            "gpio_2":
            {
                "direction": "In",
                "functionality": "pPresetSelect6_A"
            },
            "preset2_b":
            {
                "direction": "In",
                "functionality": "pPresetSelect2_B"
            },
            "gpio_4":
            {
                "direction": "Out",
                "functionality": "pDeviceReady"
            },
            "preset2_a":
            {
                "direction": "In",
                "functionality": "pPresetSelect2_A"
            },
            "preset4_b":
            {
                "direction": "In",
                "functionality": "pPresetSelect4_B"
            },
            "ground":
            {
                "direction": "In",
                "functionality": "pGND"
            }
        },
        "gpio_stabilization_interval" : 150,
        "camera_position":
        {
            "rotation":
            [
                [ 0.0,  0.0,  1.0],
                [-1.0,  0.0,  0.0],
                [ 0.0, -1.0,  0.0]
            ],
            "translation": [0.0, 0.0, 0.27]
        },
        "occupancy_grid_params":
        {
            "grid_cell_seed" : 20,
            "close_range_quorum" : 12 ,
            "mid_range_quorum" : 6,
            "long_range_quorum" : 4
        },
        "smcu_arbitration_params":
        {
            "l_0_total_threshold": 100,
            "l_0_sustained_rate_threshold": 20,
            "l_1_total_threshold": 100,
            "l_1_sustained_rate_threshold": 20,
            "l_2_total_threshold": 10,
            "hkr_stl_timeout": 15,
            "mcu_stl_timeout": 10,
            "sustained_aicv_frame_drops": 95,
            "ossd_self_test_pulse_width": 23
        },
        "crypto_signature": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    }
  }
  ')
  

safety_interface_config_write:

• Write safety interface config at given index.

• Note that writing safety interface config is applicable only in Safey Service Mode

• Type ros2 interface show realsense2_camera_msgs/srv/SafetyInterfaceConfigWrite for the full request/response fields.

  • Only for commnad line usage, user should escape all " with \". Using ros2 services API from rclcpp/rclpy doesn't need escaping. e.g.,:
  Click to see full call example

  ros2 service call /camera/camera/safety_interface_config_write realsense2_camera_msgs/srv/SafetyInterfaceConfigWrite "{safety_interface_config: '{\"safety_interface_config\":{\"m12_safety_pins_configuration\":{\"power\":{\"direction\":\"In\",\"functionality\":\"p24VDC\"},\"ossd1_b\":{\"direction\":\"Out\",\"functionality\":\"pOSSD1_B\"},\"ossd1_a\":{\"direction\":\"Out\",\"functionality\":\"pOSSD1_A\"},\"preset3_a\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect3_A\"},\"preset3_b\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect3_B\"},\"preset4_a\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect4_A\"},\"preset1_b\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect1_B\"},\"preset1_a\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect1_A\"},\"gpio_0\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect5_A\"},\"gpio_1\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect5_B\"},\"gpio_3\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect6_B\"},\"gpio_2\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect6_A\"},\"preset2_b\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect2_B\"},\"gpio_4\":{\"direction\":\"Out\",\"functionality\":\"pDeviceReady\"},\"preset2_a\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect2_A\"},\"preset4_b\":{\"direction\":\"In\",\"functionality\":\"pPresetSelect4_B\"},\"ground\":{\"direction\":\"In\",\"functionality\":\"pGND\"}},\"gpio_stabilization_interval\":150,\"camera_position\":{\"rotation\":[[0.0,0.0,1.0],[-1.0,0.0,0.0],[0.0,-1.0,0.0]],\"translation\":[0.0,0.0,0.27]},\"occupancy_grid_params\":{\"grid_cell_seed\":20,\"close_range_quorum\":12,\"mid_range_quorum\":6,\"long_range_quorum\":4},\"smcu_arbitration_params\":{\"l_0_total_threshold\":100,\"l_0_sustained_rate_threshold\":20,\"l_1_total_threshold\":100,\"l_1_sustained_rate_threshold\":20,\"l_2_total_threshold\":10,\"hkr_stl_timeout\":15,\"mcu_stl_timeout\":10,\"sustained_aicv_frame_drops\":95,\"ossd_self_test_pulse_width\":23},\"crypto_signature\":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}}'}"

• JSON safety interface config example

• Result example: realsense2_camera_msgs.srv.SafetyInterfaceConfigWrite_Response(success=True, error_message='')

application_config_read:

• Read application config.

• Note that reading application config is applicable only in Safey Service Mode

• Type ros2 interface show realsense2_camera_msgs/srv/ApplicationConfigRead for the full request/response fields.

• Call example: ros2 service call /camera/camera/application_config_read realsense2_camera_msgs/srv/ApplicationConfigRead

  Click to see the full response of the call example

  response: realsense2_camera_msgs.srv.ApplicationConfigRead_Response(success=True, error_message='', application_config='{"application_config":{"depth_pipe_safety_checks_override":0,"depth_pipeline_config":0,"depth_roi":0,"dev_rules_selection":0,"developer_mode":{"hkr":0,"hkr_simulated_lock_state":0,"sc":0,"smcu":0},"digital_signature":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"ir_for_sip":0,"peripherals_sensors_disable_mask":0,"sht4x_humidity_threshold":23,"sip":{"immediate_mode_safety_features_selection":0,"mechanisms_sampling_interval":[0,0,0,0,0,0,0,0],"tc_consecutives_failures_threshold":3,"mechanisms_thresholds":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"temporal_safety_features_selection":0},"smcu_bypass_directly_to_maintenance_mode":0,"smcu_skip_spi_error":0,"temp_thresholds":{"apm_left":[0,0,0,0],"apm_right":[0,0,0,0],"hkr_core":[0,0,0,0],"imu":[0,0,0,0],"ir_left":[0,0,0,0],"ir_right":[0,0,0,0],"sht4x":[0,0,0,0],"smcu_right":[0,0,0,0]},"triggered_calib_safety_checks_override":0,"voltage_thresholds":{"vdd0v6":0,"vdd0v8":0,"vdd0v8_ddr":0,"vdd1v1":0,"vdd1v2":0,"vdd1v8":0,"vdd3v3":0,"vdd5vo_l":0,"vdd5vo_u":0}}}')

application_config_write:

• Write application config.

• Note that writing application config is applicable only in Safey Service Mode

• Type ros2 interface show realsense2_camera_msgs/srv/ApplicationConfigWrite for the full request/response fields.

  • Only for commnad line usage, user should escape all " with \". Using ros2 services API from rclcpp/rclpy doesn't need escaping. e.g.,:
  Click to see full call example

  ros2 service call /camera/camera/application_config_write realsense2_camera_msgs/srv/ApplicationConfigWrite "{application_config: ''{"application_config":{"depth_pipe_safety_checks_override":0,"depth_pipeline_config":0,"depth_roi":0,"dev_rules_selection":0,"developer_mode":{"hkr":0,"hkr_simulated_lock_state":0,"sc":0,"smcu":0},"digital_signature":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"ir_for_sip":0,"peripherals_sensors_disable_mask":0,"sht4x_humidity_threshold":23,"sip":{"immediate_mode_safety_features_selection":0,"mechanisms_sampling_interval":[0,0,0,0,0,0,0,0],"tc_consecutives_failures_threshold":3,"mechanisms_thresholds":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"temporal_safety_features_selection":0},"smcu_bypass_directly_to_maintenance_mode":0,"smcu_skip_spi_error":0,"temp_thresholds":{"apm_left":[0,0,0,0],"apm_right":[0,0,0,0],"hkr_core":[0,0,0,0],"imu":[0,0,0,0],"ir_left":[0,0,0,0],"ir_right":[0,0,0,0],"sht4x":[0,0,0,0],"smcu_right":[0,0,0,0]},"triggered_calib_safety_checks_override":0,"voltage_thresholds":{"vdd0v6":0,"vdd0v8":0,"vdd0v8_ddr":0,"vdd1v1":0,"vdd1v2":0,"vdd1v8":0,"vdd3v3":0,"vdd5vo_l":0,"vdd5vo_u":0}}}' }"

• JSON application config example

• Result example: realsense2_camera_msgs.srv.ApplicationonfigWrite_Response(success=True, error_message='')

hardware_monitor_command_send:

• Send hardware monitor command
• Type ros2 interface show realsense2_camera/srv/HardwareMonitorCommandSend for the full request/response fields
• Call example: ros2 service call /camera/camera/hardware_monitor_command_send realsense2_camera_msgs/srv/HardwareMonitorCommandSend "{cmd: {opcode: 0x10, param1: 0, param2: 0, param3: 0, param4: 0, data: [] } }"
• A shorter version of the call example (default values for the unsetted params is 0): ros2 service call /camera/camera/hardware_monitor_command_send realsense2_camera_msgs/srv/HardwareMonitorCommandSend "{cmd: {opcode: 0x10} }"

Available actions

triggered_calibration (supported only for D500 devices)

• Type ros2 interface show realsense2_camera_msgs/action/TriggeredCalibration for the full request/result/feedback fields.

  # request
  string json "calib run"  # default value
  ---
  # result
  bool success
  string error_msg
  string calibration
  float32 health
  ---
  # feedback
  float32 progress
  
  

• Before calling triggered calibration, user should set the following parameters:
  • safety_camera.safety_mode: 2 # switch to service mode
  • depth_module.visual_preset: 1 # switch to visual preset #1 in depth module
  • depth_module.emitter_enabled: true # enable emitter in depth module
  • depth_module.enable_auto_exposure: true # enable AE in depth moudle
  • enable_color: false # turn off color stream
  • enable_depth: false # turn off depth stream
  • enable_infra1: false # turn off infra1 stream
  • enable_infra2: false # turn off infra2 stream
  • enable_safety: false # turn off safety stream
  • enable_labeled_point_cloud: false # turn off labeled pointcloud stream
  • enable_occupancy: false # turn off occupancy stream
• To use from command line: ros2 action send_goal /camera/camera/triggered_calibration realsense2_camera_msgs/action/TriggeredCalibration '{json: "{calib run}"}' or even with an empty request ros2 action send_goal /camera/camera/triggered_calibration realsense2_camera_msgs/action/TriggeredCalibration '' because the default behavior is already calib run.

ros2 param set /camera/camera safety_camera.safety_mode 2
ros2 param set /camera/camera depth_module.visual_preset 1
ros2 param set /camera/camera depth_module.emitter_enabled true
ros2 param set /camera/camera depth_module.enable_auto_exposure true
ros2 param set /camera/camera enable_color false
ros2 param set /camera/camera enable_depth false
ros2 param set /camera/camera enable_infra1 false
ros2 param set /camera/camera enable_infra2 false
ros2 param set /camera/camera enable_safety false
ros2 param set /camera/camera enable_labeled_point_cloud false
ros2 param set /camera/camera enable_occupancy false
ros2 action send_goal /camera/camera/triggered_calibration realsense2_camera_msgs/action/TriggeredCalibration '{json: "{calib run}"}' --feedback

• The action gives an updated feedback about the progress (%) if the client asks for feedback. To do that, add --feedback to the end of the command.
• If succeded, the action writes the new calibration table to the flash. It also returns the new calibration table as json string and the health as float32
• If failed, it will return the error message inside the result. For example:

Result:
  success: false
  error_msg: 'TriggeredCalibrationExecute: Aborted. Error: Calibration completed but algorithm failed'
  calibration: '{}'
  health: 0.0

Efficient intra-process communication:

Our ROS2 Wrapper node supports zero-copy communications if loaded in the same process as a subscriber node. This can reduce copy times on image/pointcloud topics, especially with big frame resolutions and high FPS.

You will need to launch a component container and launch our node as a component together with other component nodes. Further details on "Composing multiple nodes in a single process" can be found here.

Further details on efficient intra-process communication can be found here.

Example

Manually loading multiple components into the same process

• Start the component:

  ros2 run rclcpp_components component_container
  

• Add the wrapper:

  ros2 component load /ComponentManager realsense2_camera realsense2_camera::RealSenseNodeFactory -e use_intra_process_comms:=true
  

  Load other component nodes (consumers of the wrapper topics) in the same way.

Limitations

• Node components are currently not supported on RCLPY
• Compressed images using image_transport will be disabled as this isn't supported with intra-process communication

Latency test tool and launch file

For getting a sense of the latency reduction, a frame latency reporter tool is available via a launch file. The launch file loads the wrapper and a frame latency reporter tool component into a single container (so the same process). The tool prints out the frame latency (now - frame.timestamp) per frame.

The tool is not built unless asked for. Turn on BUILD_TOOLS during build to have it available:

colcon build --cmake-args '-DBUILD_TOOLS=ON'

The launch file accepts a parameter, intra_process_comms, controlling whether zero-copy is turned on or not. Default is on:

ros2 launch realsense2_camera rs_intra_process_demo_launch.py intra_process_comms:=true

Logging

For debugging purposes, users can control the ROS wrapper log level and also the SDK log level.

• ROS wrapper log level - set the parameter log_level in the ros2 launch command or in the launch file itself e.g. ros2 launch realsense2_camera rs_launch.py log_level:=warn
• LibRealSense2 SDK log level - export the environment variable called LRS_LOG_LEVEL and set it to the desired log level. e.g. export LRS_LOG_LEVEL=debug