Skip to navigation

ROS 2 - ZED Mono Node

Open in ClaudeOpen in ChatGPT

The easiest way to start a ZED ROS 2 node for a monocular camera is by using the command line:

ros2 launch zed_wrapper zed_camera.launch.py camera_model:=<camera model>

where <camera model> must be replaced with one of zedxonegs, zedxone4k, or zedxonecore. Use zedxonegs for a ZED X One GS or a ZED X One S.

Published Topics

The ZED node publishes data to the following topics:

  • Status

    • ~/status/heartbeat: heartbeat signal to monitor if the node is alive from other nodes (custom message).
    • ~/status/svo: status of the SVO playback (only advertised when an SVO file is used as input).
  • Image streams

    The image topic names are created using the following naming convention: ~/<sensor_type>/<color_model>/<rect_type>/image

    Starting from version 5.1.0 of the ROS 2 Wrapper the new convention replaces the previous formats such as ~/<sensor_type>/image_<rect_type>_<color_model> and ~/<sensor_type>_<rect_type>/image_<rect_type>_<color_model> (e.g., ~/left/image_rect_color, ~/rgb_raw/image_raw_gray). Please update your launch files and scripts to use the new topic names.

    • RGB channel
      • ~/rgb/color/rect/image: Color rectified image.
      • ~/rgb/color/rect/camera_info: Color camera calibration data.
      • ~/rgb/gray/rect/image: Grayscale rectified image.
      • ~/rgb/gray/rect/camera_info: Grayscale camera calibration data.
      • ~/rgb/color/raw/image: Color unrectified image.
      • ~/rgb/color/raw/camera_info: Color raw calibration data.
      • ~/rgb/gray/raw/image: Grayscale unrectified image.
      • ~/rgb/gray/raw/camera_info: Grayscale raw calibration data.

Since v5.5.0 of the ROS 2 Wrapper the distortion_model and the distortion coefficients published in the camera_info topics are read from the ZED SDK (>= 5.4) instead of a hard-coded per-model table that the lens does not always follow: a fisheye ZED X One now reports equidistant instead of rational_polynomial. Rectified parameters are reported as plumb_bob with zero coefficients.

  • Sensors data

    • ~/imu/data
    • ~/imu/data_raw
    • ~/temperature
    • ~/left_cam_imu_transform

Image Transport

The ROS 2 wrapper supports the stack image_transport introduced with ROS 2 Crystal Clemmys.

Starting from version 5.3 of the ROS 2 Wrapper, image messages are published through rclcpp::TypeAdapter for more efficient handling:

  • The base raw topic is handled by a TypeAdapter publisher. Intra-process subscribers (e.g., other nodes running in the same component container) receive a StampedSlMat object (a wrapper around the native sl::Mat) directly, without any serialization overhead. Inter-process subscribers transparently receive a standard sensor_msgs/msg/Image message thanks to the automatic TypeAdapter conversion.
  • The transport-specific variants are handled by an image_transport publisher. Its raw transport is disabled to avoid publishing duplicate messages, since the raw stream is already provided by the TypeAdapter publisher described above.

To prevent silent data corruption caused by incompatible plugin/encoding combinations, the advertised image transports are filtered by topic type. Visual image topics (color and grayscale images) advertise only:

  • compressed: JPEG or PNG compressed image
  • theora: Ogg Theora compressed image
  • zstd: lossless Zstandard-compressed image (available starting with ROS 2 Jazzy Jalisco)

For proper association between images and their corresponding camera information, the ZED ROS 2 Wrapper also publishes camera_info topics for all compressed image streams:

  • ~/rgb/color/rect/image/camera_info
  • ~/rgb/gray/rect/image/camera_info
  • ~/rgb/color/raw/image/camera_info
  • ~/rgb/gray/raw/image/camera_info

When the isaac_ros_nitros package is installed and NITROS is not disabled via the debug.disable_nitros parameter, NITROS publishers take priority and neither the TypeAdapter nor the image_transport publishers are created. Please refer to the dedicated section about NVIDIA® Isaac ROS Nitros for more details.

NVIDIA® Isaac ROS Nitros

The ZED ROS 2 Wrapper supports NITROS with NVIDIA® Isaac™ ROS 3.2. Isaac™ ROS 5 removed the NITROS packages: with Isaac™ ROS 5, the ZED node publishes standard ROS 2 messages and IPC is enabled automatically. See the ZED Isaac™ ROS Integration Overview.

The ZED ROS 2 Wrapper supports the NVIDIA® Isaac™ ROS Nitros package for zero-copy transport of ROS messages using NVIDIA® GPUDirect® RDMA.

NVIDIA® Isaac ROS Nitros integration is enabled and used only if the required packages are manually installed. They are not added as a dependency because this is an optional feature.

Starting from version 5.3 of the ROS 2 Wrapper, Intra-Process Communication (IPC) is handled automatically: it is disabled when NITROS is enabled and enabled when NITROS is disabled. You can use the debug.disable_nitros parameter to disable NITROS and force IPC to be enabled if needed. See the ZED Stereo Node page for how the enable_ipc launch argument interacts with NITROS.

For more information about the installation and usage of the NVIDIA® Isaac™ ROS packages, please refer to the dedicated section of the documentation: ZED Isaac™ ROS Integration Overview.

CUDA zero-copy transport

Starting with v5.6.0, on ROS 2 Lyrical and newer, the ZED ROS 2 Wrapper supports the rosidl::Buffer message fields and shares the images retrieved on the GPU without copies. In ROS 2 Lyrical, the uint8[] data field of the sensor_msgs/msg/Image message is a rosidl::Buffer, whose memory can live on the GPU: the cuda buffer backend shares this GPU memory between a publisher and its subscribers.

The general.buffer_backend parameter selects how the images are published:

  • cuda (default): the images stay in GPU memory. The subscribers that accept the cuda backend and run on the same host, with the same GPU and the same Linux user, receive the GPU memory of the ZED node without copies. All the other subscribers, such as RViz2, ros2 bag, Python nodes, and nodes on other hosts, automatically receive standard CPU data, with no change on their side.
  • cpu: the node always publishes standard CPU data, as in the previous versions.

An invalid value is replaced by cuda, with a warning. On ROS 2 Humble and Jazzy, the parameter is ignored.

The CUDA zero-copy transport requires the cuda_buffer package when the wrapper is built, the cuda_buffer_backend plugin when the node runs, and the rmw_fastrtps_cpp middleware (Fast DDS), the default of ROS 2 Lyrical, or the rmw_zenoh_cpp middleware (Zenoh) v0.10.5 or newer. When a requirement is missing, the node publishes standard CPU data. At startup, the node logs the transport in use in the line that starts with * Buffer transport:, and the reason when it falls back to CPU data.

With the cuda backend, the node still publishes standard CPU data, for all the subscribers of a topic, in these cases:

  • An rclcpp Intra-Process Communication (IPC) subscriber is connected to the topic: IPC delivers the messages without the buffer backend negotiation. To receive CUDA buffers in a node loaded in the ZED container, disable IPC for that node.
  • The topic uses the TRANSIENT_LOCAL durability, not supported by the cuda backend.

The compressed image_transport topics always carry CPU data, and do not change how the uncompressed image topics are published. The topics published with NITROS are not affected.

The CUDA zero-copy transport guide of the Isaac™ ROS 5 integration explains how the transport works and how to set it up. To receive the CUDA buffers in your own C++ nodes, follow the image tutorial.

QoS profiles

All the topics are configured by default to use the following ROS 2 QoS profile:

  • Reliability: RELIABLE
  • History (Depth): KEEP_LAST (10)
  • Durability: VOLATILE
  • Lifespan: Infinite
  • Deadline: Infinite
  • Liveliness: AUTOMATIC
  • Liveliness lease duration: Infinite

Read the official ROS 2 documentation about the QoS and the related settings for details.

The QoS settings can be modified by changing the relative parameters in the YAML files, as described in this official ROS 2 design document.

When creating a subscriber, be sure to use a compatible QoS profile according to the following tables:

Compatibility of QoS durability profiles:

PublisherSubscriberConnectionResult
VolatileVolatileYesVolatile
VolatileTransient localNo-
Transient localVolatileYesVolatile
Transient localTransient localYesTransient local

Compatibility of QoS reliability profiles:

PublisherSubscriberConnectionResult
Best effortBest effortYesBest effort
Best effortReliableNo-
ReliableBest effortYesBest effort
ReliableReliableYesReliable

In order for a connection to be made, all of the policies that affect compatibility must be compatible. For instance, if a publisher-subscriber pair has compatible reliability QoS profiles, but incompatible durability QoS profiles, the connection will not be made.

For a detailed list of all the compatibility settings, please refer to the official ROS 2 documentation.

Configuration parameters

Specify your launch parameters in the common_mono.yaml, zedxonegs.yaml, zedxone4k.yaml, and zedxonecore.yaml files available in the folder zed_wrapper/config.

General parameters

Namespace: general

common_mono.yaml

ParameterDescriptionValue
camera_timeout_secSince v5.6.0 of the ROS 2 Wrapper. Seconds between two attempts to open the camera at start-up. With camera_max_reconnect, also sets how long the node waits for a camera disconnected while runningint
camera_max_reconnectSince v5.6.0 of the ROS 2 Wrapper. Attempts to open the camera at start-up. The node also waits camera_timeout_sec x camera_max_reconnect seconds for a camera disconnected while running or rebooted, then stops (see exit_on_failure)int
exit_on_failureSince v5.6.0 of the ROS 2 Wrapper. true stops the whole process when the node fails for good, false stops this node only. Set by zed_camera.launch.py, see When the node stopstrue, false
serial_numberSelect a ZED X One camera by its Serial Numberint
camera_idSelect a ZED X One camera by its ID (0 for first, 1 for second…)int
bus_typeBus searched when the camera is selected with camera_id. AUTO searches any bus, USB and GMSL restrict the search to that transport, MIPI targets a camera on a MIPI capture card (e.g. a ZED X One Core) and HOLOSCAN a camera reached over Camera-over-Ethernet through a Holoscan sensor bridge. The ZED SDK matches the bus type exactly, so a value other than AUTO hides the cameras reached over another bus. Ignored when the camera is selected with serial_numberstring, ‘AUTO’, ‘USB’, ‘GMSL’, ‘MIPI’ [ZED SDK >= 5.5], ‘HOLOSCAN’ [ZED SDK >= 5.5]
pub_resolutionThe resolution used for output. ‘NATIVE’ to use the same general.grab_resolution - CUSTOM to apply the general.pub_downscale_factor downscale factor to reduce bandwidth in transmissionstring, ‘NATIVE’, ‘CUSTOM’
pub_downscale_factorRescale factor used to rescale image before publishing when ‘pub_resolution’ is ‘CUSTOM’double
pub_frame_rateSince v5.6.0 of the ROS 2 Wrapper. Publishing rate of the images. 0.0 (default) publishes every grabbed framedouble
sync_pub_to_timestampSince v5.6.0 of the ROS 2 Wrapper. Select the frames to publish on their image timestamp, so that several GMSL cameras capturing at the same instant publish the same captures. See Synchronized publishing of GMSL camerastrue, false
gpu_idSelect a GPU device for image processingint
buffer_backend[ROS 2 Lyrical and newer] rosidl::Buffer backend used to publish the images. cuda keeps the images in GPU memory and shares them without copies with the subscribers on the same host and GPU that accept the cuda backend, while all the other subscribers automatically receive CPU data; cpu always publishes CPU data. Ignored on older ROS 2 distributions. See CUDA zero-copy transportstring, ‘cuda’, ‘cpu’
optional_opencv_calibration_fileOptional path where the ZED SDK can find a file containing the calibration information of the camera computed with OpenCV.string
publish_statusEnable publishing of the node status topicstrue, false
sdk_timestamp_clock[ZED SDK >= 5.3] Clock source behind every SDK timestamp (images and sensors). SYSTEM_CLOCK is the wall clock and is affected by NTP/PTP, MONOTONIC_CLOCK is immune to clock steps but still frequency-slewed by NTP/PTP, MONOTONIC_RAW_CLOCK [ZED SDK >= 5.4] is immune to both steps and slewing. Process-wide: the first node in a composition winsstring, ‘SYSTEM_CLOCK’, ‘MONOTONIC_CLOCK’, ‘MONOTONIC_RAW_CLOCK’
max_system_clock_step_ms[ZED SDK >= 5.3] Largest backward host clock adjustment (NTP/PTP step, manual date change) that the SDK applies to a single sample, in milliseconds. It therefore sets how fast the SDK catches up with a clock step: 4.0 is the ZED SDK default and suits slew-only setups, a negative value makes step corrections land instantly, as PTP deployments expect, and 0.0 freezes the offset captured on first use. It is applied only when sdk_timestamp_clock is SYSTEM_CLOCK, and it is always overridden by the ZED_SDK_MAX_SYSTEM_CLOCK_STEP_MS environment variabledouble
timestamp_reference[ZED SDK >= 5.5] Time reference used to stamp the published data. IMAGE is the start of the sensor readout; IMAGE_CENTER_OF_EXPOSURE is the middle of the frame exposure, half an exposure earlier, which aligns the frames with sensors that are timestamped at the instant they measure, such as a LiDAR or the joints of a robotstring, ‘IMAGE’, ‘IMAGE_CENTER_OF_EXPOSURE’
sdk_use_monotonic_clock[DEPRECATED] Use sdk_timestamp_clock instead. Still read for backward compatibility: when true and sdk_timestamp_clock is left at SYSTEM_CLOCK, the SDK clock is set to MONOTONIC_CLOCK. The node logs a deprecation warningtrue, false

timestamp_reference: 'IMAGE_CENTER_OF_EXPOSURE' requires an input that carries a per-frame exposure, that is a ZED X One GS or a ZED X One 4K, live, from an SVO or from a stream. On any other camera the node warns once and falls back to IMAGE. It is not applied to the sensors data, to the SVO /clock topic, nor in simulation.

Since v5.6.0 of the ROS 2 Wrapper, when the camera is disconnected while the node is running, the node waits general.camera_timeout_sec x general.camera_max_reconnect seconds (25 by default) for it to come back. If it does, the node resumes publishing; otherwise, the node closes the camera and stops as described in When the node stops. Previous versions either waited forever while the ZED SDK was reopening the camera, or were killed as soon as the ZED SDK reported the camera as not detected.

While the camera is disconnected, the node diagnostic reports Camera disconnected: waiting for it to come back (N / 25 sec), and the Disconnections entry counts the disconnections of the session with the time of the last reconnection.

zedxonegs.yaml, zedxone4k.yaml, and zedxonecore.yaml

ParameterDescriptionValue
camera_modelType of StereoLabs camerastring, zedxonegs, zedxone4k, zedxonecore
camera_nameUser name for the camera, can be different from camera modelstring
grab_resolutionThe native camera grab resolution. The valid values depend on the camera model, see the table below. An invalid value is rejected with a warning and replaced by ‘AUTO’string
grab_frame_rateZED SDK internal grabbing rateint, ‘15’,‘30’,‘60’,‘120’

Valid grab_resolution values per camera model:

Camera modelValid values
zedxonegs, zedxonecore’HD1200’, ‘HD1080’, ‘SVGA’, ‘AUTO’
zedxone4k’HD4K’, ‘QHDPLUS’, ‘HD1200’, ‘HD1080’, ‘AUTO’

A grab_frame_rate of 120 FPS requires the SVGA resolution, so it is not available with the ZED X One 4K. On the ZED X One 4K, HD4K and QHDPLUS run at 15 FPS, and HD1200 and HD1080 at up to 60 FPS.

When the node stops

Since v5.6.0 of the ROS 2 Wrapper, a node that fails for good (the camera cannot be opened at start-up or does not come back after a disconnection or a reboot, invalid configuration, critical camera error) closes the camera and stops cleanly. The general.exit_on_failure parameter decides what happens next:

  • true: the whole process stops. zed_camera.launch.py sets this value when it creates the container, so the launch then ends and ros2 launch returns. The process exits with code 0, so a supervisor must restart it on any exit (e.g. systemd Restart=always, not Restart=on-failure).
  • false (default): only this node stops, and the other nodes of the same container keep running, for example the other cameras started with zed_multi_camera.launch.py. zed_camera.launch.py sets this value when the node is loaded in an existing container (container_name launch argument). The node diagnostic reports Node stopped with the reason; unload the node with ros2 component unload before loading it again.

Previous versions stopped the whole container when a node could not open its camera, usually with a crash, which also stopped the cameras of the other nodes in it.

Simulation input parameters

Namespace: simulation

common_mono.yaml

ParameterDescriptionValue
sim_enabledEnable simulation inputtrue, false
sim_addressAddress of the simulation serverstring
sim_portPort of the simulation serverint

Simulation support for the ZED X One monocular cameras is available starting from v5.5.0 of the ROS 2 Wrapper. Launch the node with sim_mode:=true plus the optional sim_address, sim_port and use_sim_time arguments to publish images and IMU data from the simulated camera. With use_sim_time:=true the node waits for a valid /clock and stamps every topic with the simulation time.

Since v5.6.0 of the ROS 2 Wrapper [ZED SDK >= 5.6 on the simulator and on the node side], the video parameters (video.*, including their dynamic changes) are sent to the simulated camera, and the simulator applies the ones it supports. A setting the simulator does not support is reported once at the INFO level and not applied. With older ZED SDK versions the video parameters are ignored in simulation. See Using the ZED with ROS 2 in Isaac™ Sim to set up the simulated camera.

Streaming input parameters

Namespace: stream

common_mono.yaml

ParameterDescriptionValue
stream_addressAddress of the local streaming serverstring
stream_portPort of the local streaming server (only even values are valid)int

SVO input parameters

Namespace: svo

common_mono.yaml

ParameterDescriptionValue
svo_pathSpecify SVO filenamestring, relative file paths are not allowed
svo_encoding_preset[ZED SDK >= 5.3] SVO encoder speed/quality preset used by the start_svo_rec servicestring, ‘DEFAULT’, ‘ULTRAFAST’, ‘FAST’, ‘MEDIUM’, ‘SLOW’
encryption_key[ZED SDK >= 5.3] Optional key/passphrase used to encrypt the SVO files created by the start_svo_rec service (AES-256-CTR). Accepted as a path to a 32-byte key file, a 64-character hex key, or a passphrase. Empty disables encryptionstring
decryption_key[ZED SDK >= 5.3] Optional decryption key/passphrase used when opening encrypted SVO filesstring
use_svo_timestampsUse the SVO timestamps to publish data. If false, data will be published at the system timetrue, false
publish_svo_clockWhen use_svo_timestamps is true allows you to publish the SVO clock to the /clock topic. This is useful for synchronous rosbag playbacktrue, false
svo_loopRestart the SVO if the end of the file is reachedtrue, false
svo_realtimeif true SVO will be played trying to respect the original framerate eventually skipping frames, otherwise every frame will be processedtrue, false
play_from_frameStart playing the SVO from a specific frame IDint

SVO encryption requires OpenSSL (libcrypto) at runtime. The value of svo.encryption_key is never written to the log, and the same value must be set as svo.decryption_key to play the recording back: if the key is lost the recorded data is unrecoverable.

Streaming server parameters

Namespace: stream_server

common_mono.yaml

ParameterDescriptionValue
stream_enabledenable the streaming server when the camera is opentrue, false
codecDifferent encoding types for image streaming: ‘H264’, ‘H265’string
portPort used for streaming. Port must be an even number. Any odd number will be rejected.int
bitrateStreaming bitrate (in Kbits/s) used for streaming. See docint, [1000 - 60000]
gop_sizeThe GOP size determines the maximum distance between IDR/I-frames. Very high GOP size will result in slightly more efficient compression, especially on static scenes. But latency will increase.int, [max 256]
adaptative_bitrateBitrate will be adjusted depending on the number of packets dropped during streaming. If activated, the bitrate can vary between [bitrate/4, bitrate].true, false
chunk_sizeStream buffers are divided into X number of chunks where each chunk is chunk_size bytes long. You can lower chunk_size value if network generates a lot of packet lost: this will generate more chunks for a single image, but each chunk sent will be lighter to avoid inside-chunk corruption. Increasing this value can decrease latency.int, [1024 - 65000]
target_framerateFramerate for the streaming output. This framerate must be below or equal to the camera framerate. Allowed framerates are 15, 30, 60 or 100 if possible. Any other values will be discarded and camera FPS will be taken.int

Video parameters

Namespace: video

common_mono.yaml

ParameterDescriptionValue
saturation*Image saturationint, [0,8]
sharpness*Image sharpnessint, [0,8]
gamma*Image gammaint, [0,8]
auto_whitebalance*Enable the auto white balancetrue, false
whitebalance_temperature*White balance temperatureint [28,65]
auto_exposure*Enable or disable auto exposure control (false: manual, true: auto)true, false
exposure_time*Defines the real exposure time in microseconds. Recommended to control manual exposureint, [28,30000]
auto_exposure_time_range_min*Defines the minimum range of exposure auto control in micro secondsint, [28,30000]
auto_exposure_time_range_max*Defines the maximum range of exposure auto control in micro secondsint, [28,30000]
exposure_compensation*Defines the Exposure-target compensation made after auto exposure. Reduces the overall illumination target by a factor of F-stops. 50 means no compensation. Since v5.6.0, -1 leaves the camera value unchanged (the node does not set it)int, [-1 - 100]
auto_analog_gain*Enable or disable auto analog gain control (false: manual, true: auto)true, false
analog_gain*Defines the real analog gain (sensor) in mDB. Recommended to control manual sensor gainint, [1000-16000].
auto_analog_gain_range_min*Defines the minimum range of sensor gain in automatic controlint
auto_analog_gain_range_max*Defines the maximum range of sensor gain in automatic controlint
auto_digital_gain*Enable or disable auto digital gain control (false: manual, true: auto)true, false
digital_gain*Defines the real digital gain (ISP) as a factor. Recommended to control manual ISP gainint, [1-256]
auto_digital_gain_range_min*Defines the minimum range of digital ISP gain in automatic controlint
auto_digital_gain_range_max*Defines the maximum range of digital ISP gain in automatic controlint
denoising*Defines the level of denoising applied on the imageint, [0-100]
ae_antibanding*[ZED SDK >= 5.3] Auto-exposure anti-banding modeint, -1=not set (since v5.6.0, the camera keeps its own value), 0=OFF, 1=AUTO, 2=50Hz, 3=60Hz
enable_24bit_outputEnable BGR 24-bit output for images (instead of 32-bit)true, false
publish_rgbEnable publishing of RGB image streamstrue, false
publish_rawEnable publishing of raw (unrectified) image streamstrue, false
publish_grayEnable publishing of grayscale image streamstrue, false

* Dynamic parameter

The node accepts exposure_time and the auto_exposure_time_range_* values from 28 to 30,000 µs, but the camera applies only the exposure range of the model and video mode:

  • ZED X One GS and ZED X One S: from 39 µs (21 µs in SVGA) to one frame period, up to 65,000 µs at 15 fps.
  • ZED X One 4K: from 16 µs to one frame period, up to 39,000 µs at 15 fps. In HDR mode, from 1,024 µs to one frame period, up to 66,666 µs at 15 fps.

Exposures longer than 30 ms, possible at 15 fps, cannot be set from the node. With ZED SDK 5.6, a value outside the camera range is not applied, and the node logs no warning.

zedxone4k.yaml

ParameterDescriptionValue
enable_hdrWhen set to true, the camera is set in HDR mode. HDR is available with HD1200 and QHDPLUS, and QHDPLUS is only available in HDR modetrue, false

Sensors parameters

Namespace: sensors

common_mono.yaml

ParameterDescriptionValue
publish_imu_tfEnable/disable the IMU TF broadcastingtrue, false
sensors_pub_rate*Frequency of publishing of sensors datadouble
imu_sampling_rate[ZED SDK >= 5.6] IMU sampling rate. DEFAULT is the camera default (200 Hz on ZED X One cameras); HZ_400 gives twice the IMU samples: set sensors_pub_rate to 400.0 to publish all of them. ZED X family only, with ZED X driver 1.5.0 or newerstring, ‘DEFAULT’, ‘HZ_200’, ‘HZ_400’
imu_accelerometer_range[ZED SDK >= 5.6] Accelerometer full-scale range. DEFAULT is the camera default (±12 g on ZED X One cameras). A smaller range gives a finer resolution, a larger one avoids saturation under strong accelerations. ZED X family only, with ZED X driver 1.5.0 or newerstring, ‘DEFAULT’, ‘G_3’, ‘G_6’, ‘G_12’, ‘G_24’
imu_gyroscope_range[ZED SDK >= 5.6] Gyroscope full-scale range. DEFAULT is the camera default (±1000 deg/s on ZED X One cameras). ZED X family only, with ZED X driver 1.5.0 or newerstring, ‘DEFAULT’, ‘DPS_250’, ‘DPS_500’, ‘DPS_1000’, ‘DPS_2000’
publish_imuAdvertise the IMU topic that is published only if a node subscribes to ittrue, false
publish_imu_rawAdvertise the raw IMU topic that is published only if a node subscribes to ittrue, false
publish_cam_imu_transfAdvertise the CAMERA-IMU transformation topic that is published only if a node subscribes to ittrue, false
publish_tempAdvertise the temperature topics that are published only if a node subscribes to themtrue, false

Since v5.6.0 of the ROS 2 Wrapper, the IMU sampling rate and ranges actually used by the camera are logged at start-up. With a ZED X driver older than 1.5.0, or with another camera model, the IMU keeps its default configuration and the ZED SDK logs a warning.

* Dynamic parameter

Starting from v5.5.0 of the ROS 2 Wrapper the sensors stream is read independently of grab(), so the IMU publishing delay no longer depends on general.grab_frame_rate. The node polls the sensors well above the hardware ODR, so no sample is lost.

sensors.sensors_pub_rate is now decimated against the measured sample interval instead of the rate the ZED SDK advertises, so it is honored on cameras whose IMU does not run at the advertised rate: with ZED SDK 5.5 or earlier, a ZED X One GS advertises 400 Hz but delivers 200 Hz, and sensors_pub_rate: 100 used to produce a steady 50 Hz.

Two consequences of the reduced CPU usage of the sensors thread: a new subscriber to a sensors topic can wait up to 250 ms for its first message, and a subscriber whose QoS is incompatible with the publisher no longer triggers publishing (it could never receive the data anyway).

Advanced parameters

Namespace: advanced

These are advanced threading parameters. Do not modify them unless you are confident of what you are doing. The SCHED_FIFO and SCHED_RR scheduling policies require root privileges, the CAP_SYS_NICE capability, or an RTPRIO limit (ulimit -r) at least equal to the requested priority.

With GMSL2 cameras, ZED SDK >= 5.6 and ZED X driver >= 1.5.0 run the capture and sensors threads of the camera at SCHED_RR priority 5. The ZED SDK installer grants this priority to the members of the zed group, from their next login. A node started by a systemd service that does not run as root needs LimitRTPRIO=5 in the [Service] section, and a Docker container needs --ulimit rtprio=5 (or --cap-add=SYS_NICE). Otherwise, these threads run at normal priority and the ZED SDK logs how to allow it. Giving the node threads a higher real-time priority than 5 can delay the camera capture. Reference: sched(7).

common_mono.yaml

ParameterDescriptionValue
change_thread_priorityMaster switch for the other advanced parameters: the thread scheduling policy and the priorities below are applied only when this is truetrue, false
thread_sched_policyThread scheduling policystring, ‘SCHED_OTHER’, ‘SCHED_BATCH’, ‘SCHED_FIFO’, ‘SCHED_RR’
thread_grab_priorityPriority of the grab thread (only with ‘SCHED_FIFO’ and ‘SCHED_RR’)int, [1 (LOW) - 99 (HIGH)]
thread_sensor_priorityPriority of the sensors thread (only with ‘SCHED_FIFO’ and ‘SCHED_RR’)int, [1 (LOW) - 99 (HIGH)]

Debug parameters

Namespace: debug

common_mono.yaml

ParameterDescriptionValue
sdk_verboseSet the verbose level of the ZED SDKint, 0 -> disable
sdk_verbose_log_filePath to the file where the ZED SDK will log its messages. If empty, no file will be created. The log level can be set using the sdk_verbose parameter.string
use_pub_timestampsUse the current ROS time for the message timestamp instead of the camera timestamp. This is useful to test data communication latency.true, false
debug_commonEnable general debug log outputstrue, false
debug_dyn_paramsEnable dynamic parameters update debug log outputstrue, false
debug_video_depthEnable video debug log outputstrue, false
debug_camera_controlsEnable camera controls debug log outputstrue, false
debug_sensorsEnable sensors debug log outputstrue, false
debug_simEnable simulation mode debug log outputstrue, false
debug_tfEnable TF broadcasting debug log outputstrue, false
debug_streamingEnable streaming debug log outputstrue, false
debug_advancedEnable advanced debug log outputstrue, false
debug_nitrosEnable Nitros debug log outputstrue, false
disable_nitrosIf available, disable NITROS usage for debugging and testing purposestrue, false

Up to v5.4 the sdk_use_monotonic_clock parameter was declared in the debug namespace of common_mono.yaml, while the node reads it from the general namespace, so it was silently ignored. It is now declared in the right namespace, and it is superseded by general.sdk_timestamp_clock.

Dynamic parameters

The ZED node lets you reconfigure many parameters dynamically during the execution of the node. All the dynamic parameters are indicated with a * in the list above and with the tag [DYNAMIC] in the comments of the YAML files.

You can set the parameters using the CLI command ros2 param set, e.g.:

ros2 param set /zed/zed_node video.exposure_time 5000

If the parameter is set successfully, you will get a confirmation message:

Set parameter successful

In the case you tried to set a parameter that’s not dynamically reconfigurable, or you specified an invalid value, you will get this type of error:

ros2 param set /zed/zed_node video.exposure_time 0
Setting parameter failed: Parameter {video.exposure_time} doesn't comply with integer range.

A video setting accepted by the node parameter can still be refused by the camera, when the camera model or the input (SVO, stream, simulation) does not support it, or when the camera rejects the value. Since v5.6.0 of the ROS 2 Wrapper [ZED SDK >= 5.6], the node logs a single warning naming the setting and the reason, and does not retry it until the video parameters change again. Older ZED SDK versions reported such settings as applied. To stop the node from setting video.exposure_compensation or video.ae_antibanding on a camera that refuses it, set the parameter to -1: the camera keeps its own value.

You can also use the Configuration -> Dynamic Reconfigure plugin of the rqt tool to dynamically set parameters by using a graphic interface.

image

Transform frames

The ZED ROS 2 wrapper broadcasts multiple coordinate frames that each provides information about the camera’s position and orientation. If needed, the reference frames can be changed in the launch file.

  • <camera_name>_camera_link is the camera mounting point. It corresponds to the threaded fixing hole at the bottom of the camera.
  • <camera_name>_camera_center is the center of the camera body.
  • <camera_name>_camera_frame is the position and orientation of the camera CMOS sensor.
  • <camera_name>_camera_frame_optical is the position and orientation of the camera optical frame.
  • <camera_name>_imu_link is the origin of the inertial data frame.
Frames

Services

The ZED node provides the following services:

  • ~/enable_streaming (std_srvs/srv/SetBool): enable/disable a local streaming server.
  • ~/start_svo_rec (zed_msgs/srv/StartSvoRec): Start recording an SVO file. If no filename is provided the default zed_one.svo2 is used. A filename without a path is saved in the working directory of the node process.
  • ~/stop_svo_rec (std_srvs/srv/Trigger): Stop an active SVO recording.
  • ~/pause_svo_rec (std_srvs/srv/SetBool): Pause (data: true) and resume (data: false) an active SVO recording without closing the file. It returns success: false when no recording is active, and the diagnostic reports SVO Recording: PAUSED while paused.
  • ~/toggle_svo_pause (std_srvs/srv/Trigger): set/reset SVO playing pause. Only available if svo.svo_realtime is false and if an SVO has been chosen as input source.
  • ~/set_svo_frame (zed_msgs/srv/SetSvoFrame): Set the SVO playback frame to the specified value. Only available if an SVO has been chosen as input source.
  • ~/reboot_camera (std_srvs/srv/Trigger): Reboots the camera without restarting the node: the node closes the camera, reboots it, reopens it and resumes publishing. The call returns when the camera is back, after about 10 seconds, or fails if the camera does not come back within general.camera_timeout_sec x general.camera_max_reconnect seconds, and the node then stops as after a disconnection (see When the node stops). Available for the GMSL cameras with a live input.

Since v5.6.0 of the ROS 2 Wrapper, ~/reboot_camera reboots the camera from a running node. While it runs no data is published and the other services of the node wait. An active SVO recording is stopped, and the streaming server is started again. The diagnostic reports Camera rebooting while it runs, then the Reboots entry gives the number of reboots with the time and result of the last one. Rebooting a GMSL camera restarts the GMSL capture of the device: the other GMSL cameras can stop for a few seconds, and their nodes wait for them as for a disconnection.

Services can be called using the rqt graphical tool by enabling the plugin Plugins -> Services -> Service caller.

It is possible to call a service also by using the CLI command ros2 service call.

For example, to start the local streaming server:

ros2 service call /zed/zed_node/enable_streaming std_srvs/srv/SetBool "{data: True}"

and the service server will reply:

requester: making request: std_srvs.srv.SetBool_Request(data=True)
response:
std_srvs.srv.SetBool_Response(success=True, message='Streaming Server started')

Assigning a GPU to a camera

To improve performance, you can specify the gpu_id of the graphic card that will be used for the image processing in the common_mono.yaml configuration file. The default value (-1) will select the GPU with the highest number of CUDA cores. When using multiple cameras, you can assign each camera to a GPU to increase performance.

Node Diagnostic

The ZED ROS 2 node publishes useful diagnostic information aggregated into the /diagnostics topic using the diagnostic_updater package.

Diagnostic information can be analyzed and parsed by using ROS 2 tools, like for example the Runtime Monitor plugin of rqt.

Available information:

  • Uptime
  • Camera disconnections: count and time of the last reconnection (since v5.6.0 of the ROS 2 Wrapper)
  • Grab frequency and processing time
  • Frame drop rate
  • Input mode
  • Image publishing rate and processing time
  • IMU TF broadcasting rate
  • IMU data publishing rate
  • Camera internal temperature
  • Scene Illuminance
  • SVO playback status
  • SVO recording status, including the PAUSED state
  • Streaming server status