Choosing Sensor Message Types
Qt ROS2 provides QML-friendly wrappers for the standard sensor_msgs and nav_msgs message types. This page helps you pick the right message type for your hardware and explains which messages SLAM and navigation stacks expect or produce.
Note: All message types listed here are from sensor_msgs, nav_msgs, or geometry_msgs unless stated otherwise. Audio is a known gap — see Audio sensors and speech.
Distance and ranging sensors
| Sensor Type | Message Type | Notes |
|---|---|---|
| 2D lidar / laser range-finder | laserScan (LaserScan) | Single planar sweep; provides ranges and optional intensities. |
| Multi-echo 2D lidar | multiEchoLaserScan (MultiEchoLaserScan) | Like LaserScan but each range bin can report multiple return distances. Useful for glass, vegetation, or fog detection. |
| 3D lidar / depth camera (unordered or 2D-organized) | pointCloud2 (PointCloud2) | Flexible binary blob; supports arbitrary per-point fields (x, y, z, intensity, …). |
| Ultrasonic / infrared range sensor | range (Range) | Single-beam measurement with min/max range bounds and radiation type field (ultrasound, infrared). |
Camera sensors
| Sensor Type | Message Type | Notes |
|---|---|---|
| RGB or mono camera | image (Image) | Uncompressed; the Qt wrapper exposes a QImage property for direct use in QML. Encoding field selects colour format (rgb8, rgba8, bgr8, mono8, mono16, …). |
| Compressed camera stream (JPEG / PNG) | compressedImage (CompressedImage) | Smaller over-the-wire size; the Qt wrapper decodes to a QImage on demand. |
| Camera calibration parameters | cameraInfo (CameraInfo) | Accompanies Image messages; carries intrinsics, distortion, and projection matrices. Subscribe alongside Image on a synchronised pair of topics. |
| Region of interest within a camera image | regionOfInterest (RegionOfInterest) | Embedded in CameraInfo; also used standalone to flag a crop window. |
Inertial and navigation sensors
| Sensor Type | Message Type | Notes |
|---|---|---|
| IMU (accelerometer + gyroscope ± magnetometer) | imu (Imu) | Reports orientation, angular velocity, and linear acceleration each with a 3×3 covariance matrix. Set covariance diagonal to -1 if a field is not measured. |
| GPS / GNSS receiver | navSatFix (NavSatFix) | Latitude, longitude, altitude and position covariance; status field indicates fix quality (no fix, fix, SBAS fix, GBAS fix). |
| Magnetic compass | magneticField (MagneticField) | 3-axis field vector in Tesla with covariance. |
| External time reference (GPS PPS, NTP, PTP) | timeReference (TimeReference) | Stamps a measurement from an external clock so the ROS graph can correlate it with system time. Useful for hardware-synchronised camera rigs and lidar sweeps. |
Power and battery
| Sensor Type | Message Type | Notes |
|---|---|---|
| Battery or power supply | batteryState (BatteryState) | Covers voltage, current, temperature, charge, capacity, and state-of-charge percentage (0.0–1.0). Enum constants identify chemistry (LiPo, NiMH, …), health (good, overheat, dead, …), and charging status (charging, discharging, full, …). Multi-cell packs can report per-cell voltage and temperature arrays. |
Environmental sensors
| Sensor Type | Message Type | Notes |
|---|---|---|
| Barometer / pressure sensor | fluidPressure (FluidPressure) | Absolute pressure in Pascals with variance. |
| Temperature sensor | temperature (Temperature) | Temperature in degrees Celsius with variance. |
| Humidity sensor | relativeHumidity (RelativeHumidity) | Relative humidity as a ratio (0.0–1.0) with variance. |
| Illuminance / ambient light | illuminance (Illuminance) | Illuminance in lux with variance. |
Actuators and kinematics
These messages describe the state of joints and limbs rather than sensors in the traditional sense, but they flow through the same sensor pipeline.
| Use Case | Message Type | Notes |
|---|---|---|
| Robot arm or wheeled-robot joint positions | jointState (JointState) | Reports position (rad or m), velocity, and effort per named joint. Any of the three arrays may be left empty if not measured. Subscribe to /joint_states to drive a 3D model or display telemetry. |
| Floating-base or multi-DOF joints | multiDOFJointState (MultiDOFJointState) | Generalises JointState to joints with more than one degree of freedom; each joint carries a full Transform, Twist, and Wrench. |
SLAM and navigation
SLAM (Simultaneous Localization and Mapping) algorithms consume sensor data and publish map and pose estimates. A Qt dashboard typically subscribes to SLAM outputs to display a live map and robot position.
SLAM inputs
Feed at least one ranging source and optionally an IMU into a SLAM node:
| Input | Message Type |
|---|---|
| 2D lidar sweep | laserScan (LaserScan) on /scan |
| 3D lidar or depth cloud | pointCloud2 (PointCloud2) on /points |
| Wheel odometry (pre-SLAM estimate) | odometry (Odometry) on /odom |
| Inertial measurement | imu (Imu) on /imu |
SLAM outputs
| Output | Message Type | Notes |
|---|---|---|
| Occupancy grid map | occupancyGrid (OccupancyGrid) on /map | 2D grid where each cell is free (0), occupied (100), or unknown (-1). Subscribe to render a live floor plan. |
| Corrected robot pose | poseWithCovarianceStamped (PoseWithCovarianceStamped) | SLAM-corrected pose with uncertainty ellipse; broadcast on /pose. |
| Odometry estimate | odometry (Odometry) on /odom | Combines pose and twist with covariances; used by the navigation stack. |
| Planned path | path (Path) on /plan | Sequence of poses from the current position to the navigation goal. |
Note: SLAM and navigation stacks also broadcast coordinate-frame transforms on the /tf and /tf_static topics using the tf2_msgs/TFMessage type. Qt ROS2 does not currently wrap tf2_msgs, so transforms must be read through a bridging node or a dedicated C++ subscriber if your application needs them directly.
Audio sensors and speech
Standard ROS 2 (and the Qt ROS2 Bridge) does not include a message type for raw audio data. The community package audio_common_msgs (from the audio_common stack) provides AudioData and AudioStamped messages and is widely used, but it is not part of the core ROS 2 distribution and is not currently wrapped by Qt ROS2.
Typical approaches for audio in a ROS 2 system:
| Task | Common approach |
|---|---|
| Capture microphone audio | A dedicated ROS node streams audio_common_msgs/AudioData; outside ROS, use Qt Multimedia (QAudioSource) and bridge results into ROS via a publisher. |
| Speech-to-text transcription | A Whisper- or cloud-ASR-based node publishes the transcript as std_msgs/String on a topic such as /speech_recognition/result. Subscribe with string (String) in QML. |
| Text-to-speech output | Send a std_msgs/String command to a TTS node; audio playback happens inside that node or via Qt Multimedia on the Qt side. |
| LLM response piped to speech | Publish the LLM text output as std_msgs/String; a downstream TTS node converts it to speech. The full pipeline (mic → ASR → LLM → TTS → speaker) runs as ROS nodes; the Qt UI subscribes to the intermediate text topics for display and can publish user text input to inject into the chain. |
Remote control and teleoperation
Sending velocity or steering commands to a robot is covered separately. See Teleoperation and Remote Control for joy (Joy), twist (Twist), and on-screen joystick patterns.
See also Qt ROS2 QML Types.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
