Built-In Message Support

MATLAB^® supports a large library of ROS message types. This topic covers how MATLAB works with ROS Messages by describing message structure, limitations for ROS messages, and supported ROS data types. Refer to the full list of built-in message types at the end of this article.

For information about ROS 2 messages, see Work with Basic ROS 2 Messages.

ROS Messages

In MATLAB, ROS messages are stored as message structures or message objects. Message structures are the recommended format as they have better performance over objects when performing initial creation, reading them from rosbag files, accessing nested properties, and performing communication operations over the ROS network. Also, message structures are the only supported message format when generating code through MATLAB Coder™. For more information on the ROS messages in MATLAB, see Work with Basic ROS Messages.

ROS Message Structures

A ROS message structure is stored as a MATLAB structure data type with fields based on the message type. Each message type has a specific set of fields with their corresponding values that are individually stored and accessed. You can specifically point to and modify each field on its own. The MessageType field of each message contains the message type as a character vector. Also, you can use the rosShowDetails function to view the contents of the message.

Here is a sample 'geometry_msgs/Point', created in MATLAB using rosmessage. It contains 3 fields corresponding to a 3-D point in XYZ coordinates.

pointMsg = rosmessage('geometry_msgs/Point','Dataformat','struct')

pointMsg = 

  struct with fields:

    MessageType: 'geometry_msgs/Point'
              X: 0
              Y: 0
              Z: 0

You can access and modify each field by using the pointMsg structure.

pointMsg.Y = 2

pointMsg = 

  struct with fields:

    MessageType: 'geometry_msgs/Point'
              X: 0
              Y: 2
              Z: 0

ROS Message Objects

For ROS message objects, all the rules of handle objects apply, including copying, modifying, and other performance considerations. For more information on handle objects, see Handle Object Behavior. Each handle points to the object for that specific message, which contains the information relevant to that message type. The message type has a built-in structure for the data it contains.

ROS messages store the data relevant to that message type in a way similar to structure arrays. Each message type has a specific set of properties with their corresponding values that are individually stored and accessed. You can specifically point to and modify each property on its own. The MessageType property of each message contains the message type as a character vector. Also, you can use the showdetails function to view the contents of the message.

Here is a sample 'geometry_msgs/Point', created in MATLAB using rosmessage. It contains 3 properties corresponding to a 3-D point in XYZ coordinates.

pointMsg = rosmessage('geometry_msgs/Point')

pointMsg = 

  ROS Point message with properties:

    MessageType: 'geometry_msgs/Point'
              X: 0
              Y: 0
              Z: 0

  Use showdetails to show the contents of the message

You can access and modify each property by using the pointMsg handle.

pointMsg.Y = 2

pointMsg = 

  ROS Point message with properties:

    MessageType: 'geometry_msgs/Point'
              X: 0
              Y: 2
              Z: 0

  Use showdetails to show the contents of the message

Limitations of ROS Messages in MATLAB

Because ROS messages use independent properties, certain messages with multiple values cannot be validated. Because each value can be set separately, the message does not validate the properties as a whole entity. For example, a quaternion message contains w, x, y, and z properties, but the message does not enforce that the quaternion as a whole is valid. When modifying properties, you should ensure you are maintaining the rules required for that message.

Message properties can also have a variety of data types. MATLAB uses the rules set by ROS to determine what these data types are. However, if they are to be used in calculations, you might have to cast the data types to another value. The ROS data types do not convert directly to MATLAB data types. For a detailed list of ROS data types and their MATLAB equivalent, see ROS Data Type Conversions.

Note

Updating any built-in message is not recommended.

ROS Data Type Conversions

ROS message types have predetermined properties and data types for the values of those properties. These data types must be mapped to MATLAB data types to be used in MATLAB. This table summarizes how ROS data types are converted to MATLAB data types.

ROS Data Type	Description	MATLAB
bool	Boolean / Unsigned 8-bit integer	`logical`
int8	Signed 8-bit integer	`int8`
uint8	Unsigned 8-bit integer	`uint8`
int16	Signed 16-bit integer	`int16`
uint16	Unsigned 16-bit integer	`uint16`
int32	Signed 32-bit integer	`int32`
uint32	Unsigned 32-bit integer	`uint32`
int64	Signed 64-bit integer	`int64`
uint64	Unsigned 64-bit integer	`uint64`
float32	32-bit IEEE^® floating point	`single`
float64	64-bit IEEE floating point	`double`
string	ASCII string (utf-8 only)	`char`
time	Seconds and nanoseconds as signed 32-bit integers	`Time` object (see `rostime`)
duration	Seconds and nanoseconds as signed 32-bit integers	`Duration` object (see `rosduration`)

Supported Messages

Here is an alphabetized list of supported ROS packages. A package can contain message types, service types, or action types.

To get a full list of supported message types, call rosmsg list in the MATLAB Command Window.

ROS Toolbox supports different ROS and ROS 2 versions as specified in Recommended ROS and ROS 2 Distributions, but your own ROS installation may have different message versions. To overwrite our current message catalog, you can utilize the Custom Message Support to generate new message definitions.

When specifying message types, input character vectors must match the character vector listed in rosmsg list exactly. To use custom message types, MATLAB also provides a custom message support package. For more information, see ROS Custom Message Support.

ackermann_msgs
actionlib
actionlib_msgs
actionlib_tutorials
adhoc_communication
app_manager
applanix_msgs
ar_track_alvar
arbotix_msgs
ardrone_autonomy
asmach_tutorials
audio_common_msgs
axis_camera
base_local_planner
baxter_core_msgs
baxter_maintenance_msgs
bayesian_belief_networks
blob
bond
brics_actuator
bride_tutorials
bwi_planning
bwi_planning_common
calibration_msgs
capabilities
clearpath_base
cmvision
cob_base_drive_chain
cob_camera_sensors
cob_footprint_observer
cob_grasp_generation
cob_kinematics
cob_light
cob_lookat_action
cob_object_detection_msgs
cob_perception_msgs
cob_phidgets
cob_pick_place_action
cob_relayboard
cob_script_server
cob_sound
cob_srvs
cob_trajectory_controller
concert_msgs
control_msgs
control_toolbox
controller_manager_msgs
costmap_2d
create_node
data_vis_msgs
designator_integration_msgs
diagnostic_msgs
dna_extraction_msgs
driver_base
dynamic_reconfigure
dynamic_tf_publisher
dynamixel_controllers
dynamixel_msgs
epos_driver
ethercat_hardware
ethercat_trigger_controllers
ethzasl_icp_mapper
explorer
face_detector
fingertip_pressure
frontier_exploration
gateway_msgs
gazebo_msgs
geographic_msgs
geometry_msgs
gps_common
graft
graph_msgs
grasp_stability_msgs
grasping_msgs
grizzly_msgs
handle_detector
hector_mapping
hector_nav_msgs
hector_uav_msgs
hector_worldmodel_msgs
household_objects_database_msgs
hrpsys_gazebo_msgs
humanoid_nav_msgs
iai_content_msgs
iai_kinematics_msgs
iai_pancake_perception_action
image_cb_detector
image_exposure_msgs
image_view2
industrial_msgs
interaction_cursor_msgs
interactive_marker_proxy
interval_intersection
jaco_msgs
joint_states_settler
jsk_footstep_controller
jsk_footstep_msgs
jsk_gui_msgs
jsk_hark_msgs
jsk_network_tools
jsk_pcl_ros
jsk_perception
jsk_rviz_plugins
jsk_topic_tools
keyboard
kingfisher_msgs
kobuki_msgs
kobuki_testsuite
laser_assembler
laser_cb_detector
leap_motion
linux_hardware
lizi
manipulation_msgs
map_merger
map_msgs
map_store
mavros
microstrain_3dmgx2_imu
ml_classifiers
mln_robosherlock_msgs
mongodb_store
mongodb_store_msgs
monocam_settler
move_base_msgs
moveit_msgs
moveit_simple_grasps
multimaster_msgs_fkie
multisense_ros
nao_interaction_msgs
nao_msgs
nav_msgs
nav2d_msgs
nav2d_navigator
nav2d_operator
navfn
network_monitor_udp
nmea_msgs
nodelet
object_recognition_msgs
octomap_msgs
p2os_driver
pano_ros
pcl_msgs
pcl_ros
pddl_msgs
people_msgs
play_motion_msgs
polled_camera
posedetection_msgs
pr2_calibration_launch
pr2_common_action_msgs
pr2_controllers_msgs
pr2_gazebo_plugins
pr2_gripper_sensor_msgs
pr2_mechanism_controllers
pr2_mechanism_msgs
pr2_msgs
pr2_power_board
pr2_precise_trajectory
pr2_self_test_msgs
pr2_tilt_laser_interface
program_queue
ptu_control
qt_tutorials
r2_msgs
razer_hydra
rmp_msgs
robot_mechanism_controllers
robot_pose_ekf
roboteq_msgs
robotnik_msgs
rocon_app_manager_msgs
rocon_service_pair_msgs
rocon_std_msgs
rosapi
rosauth
rosbridge_library
roscpp
roscpp_tutorials
roseus
rosgraph_msgs
rospy_message_converter
rospy_tutorials
rosruby_tutorials
rosserial_arduino
rosserial_msgs
rovio_shared
rtt_ros_msgs
s3000_laser
saphari_msgs
scanning_table_msgs
scheduler_msgs
schunk_sdh
segbot_gui
segbot_sensors
segbot_simulation_apps
segway_rmp
sensor_msgs
shape_msgs
shared_serial
sherlock_sim_msgs
simple_robot_control
smach_msgs
sound_play
speech_recognition_msgs
sr_edc_ethercat_drivers
sr_robot_msgs
sr_ronex_msgs
sr_utilities
statistics_msgs
std_msgs
std_srvs
stdr_msgs
stereo_msgs
stereo_wall_detection
tf
tf2_msgs
theora_image_transport
topic_proxy
topic_tools
trajectory_msgs
turtle_actionlib
turtlebot_actions
turtlebot_calibration
turtlebot_msgs
turtlesim
um6
underwater_sensor_msgs
universal_teleop
uuid_msgs
velodyne_msgs
view_controller_msgs
visp_camera_calibration
visp_hand2eye_calibration
visp_tracker
visualization_msgs
wfov_camera_msgs
wge100_camera
wifi_ddwrt
wireless_msgs
yocs_msgs
zeroconf_msgs

For ROS 2 custom message support package, see ROS 2 Custom Message Support.