Note: This tutorial assumes that you have completed the previous tutorials: using rosed.
(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Creating a ROS msg and srv

Description: This tutorial covers how to create and build msg and srv files as well as the rosmsg, rossrv and roscp commandline tools.

Tutorial Level: BEGINNER

Next Tutorial: Writing a simple publisher and subscriber (python) (c++)

Contents

    1. Introduction to msg and srv
  2. Using msg
    1. Creating a msg
    2. Using rosmsg
  3. Using srv
    1. Creating a srv
    2. Using rossrv
  4. Common step for msg and srv
  5. Getting Help
  6. Review
  7. Next Tutorial

Introduction to msg and srv

  • msg: msg files are simple text files that describe the fields of a ROS message. They are used to generate source code for messages in different languages.

  • srv: an srv file describes a service. It is composed of two parts: a request and a response.

msg files are stored in the msg directory of a package, and srv files are stored in the srv directory.

msgs are just simple text files with a field type and field name per line. The field types you can use are:

  • int8, int16, int32, int64 (plus uint*)
  • float32, float64
  • string
  • time, duration
  • other msg files
  • variable-length array[] and fixed-length array[C]

There is also a special type in ROS: Header, the header contains a timestamp and coordinate frame information that are commonly used in ROS. You will frequently see the first line in a msg file have Header header.

Here is an example of a msg that uses a Header, a string primitive, and two other msgs : 

  Header header
  string child_frame_id
  geometry_msgs/PoseWithCovariance pose
  geometry_msgs/TwistWithCovariance twist

srv files are just like msg files, except they contain two parts: a request and a response. The two parts are separated by a '---' line. Here is an example of a srv file: 

int64 A
int64 B
---
int64 Sum

In the above example, A and B are the request, and Sum is the response.

Using msg

Creating a msg

Let's define a new msg in the package that was created in the previous tutorial. 

$ cd ~/catkin_ws/src/beginner_tutorials
$ mkdir msg
$ echo "int64 num" > msg/Num.msg

The example above is the simplest where .msg file contains only 1 line. You can, of course, create more complex file by adding multiple elements per line like this: 

string first_name
string last_name
uint8 age
uint32 score

There's one more step, though. We need to make sure that the msg files are turned into source code for C++, Python, and other languages:

Open package.xml, and make sure these two lines are in it and uncommented: 

  <build_depend>message_generation</build_depend>
  <run_depend>message_runtime</run_depend>

Note that at build time, we need "message_generation", while at runtime, we only need "message_runtime".

Open CMakeLists.txt in your favorite text editor (rosed from the previous tutorial is a good option).

Add the message_generation dependency to the find_package call which already exists in your CMakeLists.txt so that you can generate messages. You can do this by simply adding message_generation to the list of COMPONENTS such that it looks like this: 

# Do not just add this to your CMakeLists.txt, modify the existing text to add message_generation before the closing parenthesis
find_package(catkin REQUIRED COMPONENTS
   roscpp
   rospy
   std_msgs
   message_generation
)

You may notice that sometimes your project builds fine even if you did not call find_package with all dependencies. This is because catkin combines all your projects into one, so if an earlier project calls find_package, yours is configured with the same values. But forgetting the call means your project can easily break when built in isolation.

Also make sure you export the message runtime dependency. 

catkin_package(
  ...
  CATKIN_DEPENDS message_runtime ...
  ...)

Find the following block of code: 

# add_message_files(
#   FILES
#   Message1.msg
#   Message2.msg
# )

Uncomment it by removing the # symbols and then replace the stand in Message*.msg files with your .msg file, such that it looks like this: 

add_message_files(
  FILES
  Num.msg
)

By adding the .msg files manually, we make sure that CMake knows when it has to reconfigure the project after you add other .msg files.

Now we must ensure the generate_messages() function is called.

For ROS Hydro and later, you need to uncomment these lines: 

# generate_messages(
#   DEPENDENCIES
#   std_msgs
# )
  • so it looks like: 
    generate_messages(
  DEPENDENCIES
  std_msgs
)

In earlier versions, you may just need to uncomment one line: 

generate_messages()

$ roscd beginner_tutorials
$ mkdir msg
$ echo "int64 num" > msg/Num.msg

The example above is the simplest, where the .msg file contains only 1 line. You can, of course, create more complex files by adding multiple elements per line like this: 

string first_name
string last_name
uint8 age
uint32 score

There's one more step, though. We need to make sure that the msg files are turned into source code for C++, Python, and other languages. Open CMakeLists.txt in your favorite text editor (rosed from the previous tutorial is a good option) and remove # to uncomment the following line: 

# rosbuild_genmsg()

Now you're ready to generate source files from your msg definition. If you want to do so right now, skip next sections to Common step for msg and srv.

Using rosmsg

That's all you need to do to create a msg. Let's make sure that ROS can see it using the rosmsg show command.

Usage: 

$ rosmsg show [message type]

Example: 

$ rosmsg show beginner_tutorials/Num

You will see: 

  • int64 num

In the previous example, the message type consists of two parts:

  • beginner_tutorials -- the package where the message is defined

  • Num -- The name of the msg Num.

If you can't remember which Package a msg is in, you can leave out the package name. Try: 

$ rosmsg show Num

You will see: 

  • [beginner_tutorials/Num]:
int64 num

Using srv

Creating a srv

Let's use the package we just created to create a srv: 

$ roscd beginner_tutorials
$ mkdir srv

Instead of creating a new srv definition by hand, we will copy an existing one from another package.

For that, roscp is a useful commandline tool for copying files from one package to another.

Usage: 

$ roscp [package_name] [file_to_copy_path] [copy_path]

Now we can copy a service from the rospy_tutorials package: 

$ roscp rospy_tutorials AddTwoInts.srv srv/AddTwoInts.srv

There's one more step, though. We need to make sure that the srv files are turned into source code for C++, Python, and other languages.

Unless you have done so already for messages earlier, add the message_generation dependency to generate messages in CMakeLists.txt: 

# Do not just add this line to your CMakeLists.txt, modify the existing line
find_package(catkin REQUIRED COMPONENTS roscpp rospy std_msgs message_generation)

(Despite its name, message_generation works for both msg and srv.)

Also you need the same changes to package.xml for services as for messages, so look above for the additional dependencies required.

Remove # to uncomment the following lines: 

# add_service_files(
#   FILES
#   Service1.srv
#   Service2.srv
# )

And replace the placeholder Service*.srv files for your service files: 

add_service_files(
  FILES
  AddTwoInts.srv
)

Once again, open CMakeLists.txt and remove # to uncomment the following line: 

# rosbuild_gensrv()

Now you're ready to generate source files from your service definition. If you want to do so right now, skip next sections to Common step for msg and srv.

Using rossrv

That's all you need to do to create a srv. Let's make sure that ROS can see it using the rossrv show command.

Usage: 

$ rossrv show <service type>

Example: 

$ rossrv show beginner_tutorials/AddTwoInts

You will see: 

  • int64 a
int64 b
---
int64 sum

Similar to rosmsg, you can find service files like this without specifying package name: 

$ rossrv show AddTwoInts
[beginner_tutorials/AddTwoInts]:
int64 a
int64 b
---
int64 sum

[rospy_tutorials/AddTwoInts]:
int64 a
int64 b
---
int64 sum

Common step for msg and srv

Next find this section in CMakeLists.txt: 

# generate_messages(
#   DEPENDENCIES
# #  std_msgs  # Or other packages containing msgs
# )

Uncomment it and add any packages you depend on which contain .msg files that your messages use (in this case std_msgs), such that it looks like this: 

generate_messages(
  DEPENDENCIES
  std_msgs
)

Now that we have made some new messages we need to make our package again: 

# In your catkin workspace
$ cd ../..
$ catkin_make
$ cd -

Now that we have made some new messages we need to make our package again: 

$ rosmake beginner_tutorials

Any .msg file in the msg directory will generate code for use in all supported languages. The C++ message header file will be generated in ~/catkin_ws/devel/include/beginner_tutorials/. The Python script will be created in ~/catkin_ws/devel/lib/python2.7/dist-packages/beginner_tutorials/msg. The lisp file appears in ~/catkin_ws/devel/share/common-lisp/ros/beginner_tutorials/msg/.

The full specification for the message format is available at the Message Description Language page.

Getting Help

We've seen quite a few ROS tools already. It can be difficult to keep track of what arguments each command requires. Luckily, most ROS tools provide their own help.

Try: 

$ rosmsg -h

  • You should see a list of different rosmsg subcommands. 

    Commands:
  rosmsg show Show message description
  rosmsg users  Find files that use message
  rosmsg md5  Display message md5sum
  rosmsg package  List messages in a package
  rosmsg packages List packages that contain messages

You can also get help for subcommands 

$ rosmsg show -h
  • This shows the arguments that are needed for rosmsg show: 
    Usage: rosmsg show [options] <message type>

Options:
  -h, --help  show this help message and exit
  -r, --raw   show raw message text, including comments

Review

Lets just list some of the commands we've used so far:

  • rospack = ros+pack(age) : provides information related to ROS packages
  • rosstack = ros+stack : provides information related to ROS stacks

  • roscd = ros+cd : changes directory to a ROS package or stack

  • rosls = ros+ls : lists files in a ROS package

  • roscp = ros+cp : copies files from/to a ROS package

  • rosmsg = ros+msg : provides information related to ROS message definitions
  • rossrv = ros+srv : provides information related to ROS service definitions
  • rosmake = ros+make : makes (compiles) a ROS package
    • You should use catkin_make if you are using a catkin workspace.

Next Tutorial

Now that you've made a new ROS msg and srv, let's look at writing a simple publisher and subscriber (python) (c++).

Wiki: th/ROS/Tutorials/CreatingMsgAndSrv (last edited 2014-11-19 04:54:46 by AkkharaphongEKSIRI)

Except where otherwise noted, the ROS wiki is licensed under the
Creative Commons Attribution 3.0