Contents
Standard Units of Measure and Coordinate Systems
Standard units and coordinate conventions for use in ROS have been formalized in REP-0103.
Naming ROS Resources
Names play an important role in ROS and following naming conventions simplifies the process of learning and understanding large systems. This page documents conventions for common ROS resources, though you should familiarize yourself with the ROS name specification before proceeding.
Packages
The ROS packages occupy a flat namespace, so naming should be done carefully and consistently. There is a standard for package naming in REP-144
Package names should follow common C variable naming conventions: lower case, start with a letter, use underscore separators, e.g. laser_viewer
Package names should be specific enough to identify what the package does. For example, a motion planner is not called planner. If it implements the wavefront propagation algorithm, it might be called wavefront_planner. There's obviously tension between making a name specific and keeping it from becoming overly verbose.
Using catchall names such as utils should be avoided as they do not scope what goes into the package or what should be outside the package.
To check whether a name is taken, consult http://www.ros.org/browse. If you'd like your repository included in that list, see this tutorial: rosdistro/Tutorials/Indexing Your ROS Repository for Documentation Generation
- Our goal is to develop a canonical set of tools for making robots do interesting things. The package name should tell you what the package does, not where it came from. It should be possible for us, as a community, to make this work. An Ubuntu distribution offers approximately 33,000 packages without inserting origin or authorship into names.
- Prefixing a package name is recommended only when the package is not meant to be used more widely (e.g., packages that are specific to the PR2 robot use the 'pr2_' prefix). You might prefix the package name when forking an existing package, but again, the prefix would hopefully communicate what changed, not who changed it.
- Prefixing a package name with 'ros' is redundant for a ROS package. This is not recommended except for very core packages.
Topics / services
Topic and service names live in a hierarchical namespace, and client libraries provide mechanisms for remapping them at runtime, so there is more flexibility than with packages. However, it's best to minimize the need for namespacing and name remapping.
Topic and service names should follow common C variable naming conventions: lower case, with underscore separators, e.g. laser_scan
Topic and service names should be reasonably descriptive. If a planner node publishes a message containing its current state, the associated topic should be called planner_state, not just state.
Messages
Message files are used to determine the class name of the autogenerated code. As such, they must be CamelCased. e.g. LaserScan.msg
NOTE: This is an exception to the convention that all filenames are lower case and underscore separated. Using CamelCase message names will prevent issues from arising due to inconsistent support for filename case sensitivity across various operating systems.
Message fields should be lowercase with underscore separation. e.g. range_min
Nodes
Nodes have both a type and name. The type is the name of the executable to launch the node. The name is what is passed to other ROS nodes when it starts up. We separate these two concepts because names must be unique, whereas you may have multiple nodes of the same type.
When possible, the default name of a node should follow from the name of the executable used to launch the node. This default name can be remapped at startup to something unique.
Node type names
In general, we encourage the node type names to be short because they are scoped by the package name. For example, if your laser_scan package has a viewer for laser scans, simply call it view (instead of laser_scan_viewer). Thus, when you run it with rosrun, you would type:
rosrun laser_scan view
TF frame_ids
See geometry/CoordinateFrameConventions#Naming.
Global Executables
Executables that go into the global $PATH may have one of two prefixes:
ros (e.g. rostopic, roscd)
- Command-line tools that display information to stdout.
rqt_ (e.g. rqt_console)
Tools that use a QT-based graphical user interface (GUI). Before ROS Hydro, these were prefixed with rx and used WxWindows-based interfaces.
The prefix naming enables easy tab completion for finding ROS tools and also creates a natural mapping between GUI and GUI-less versions of tools (e.g. rosconsole vs. rqt_console).
Informational Distance Measurements
Representation of special conditions within distance measurements like "too close" or "too far" in ROS have been formalized in REP-0117.
