<> <> == Standard Units of Measure and Coordinate Systems == Standard units and coordinate conventions for use in ROS have been formalized in [[http://www.ros.org/reps/rep-0103.html|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 [[Names|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 [[http://www.ros.org/reps/rep-0144.html|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 [[Remapping%20Arguments|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 [[ROS/CommandLineTools|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 [[rosbash#Tab_Completion|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 [[http://www.ros.org/reps/rep-0117.html|REP-0117]].