-
Notifications
You must be signed in to change notification settings - Fork 0
/
ros-guidelines.tex
166 lines (141 loc) · 6.13 KB
/
ros-guidelines.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
\chapter{ROS guidelines}
The ROS version to be used is the \textbf{ROS Groovy} version (released in January 2013).\\
The following rules are a copy of the slides created by Lorenz M\"osenlechner \footnote{\url{https://robohow.org/_media/meetings/first-integration-workshop/ros-best-practices.pdf}}.\\
The ROS libraries are by default installed in the /opt/ros folder.
\textbf{Never} edit those files. Prefer using ROS overlays \footnote{\url{http://www.ros.org/wiki/fuerte/Installation/Overlays}} instead,
and use the tool support \textit{rosws} to create, modify and manage overlays.
Multiple overlays with different versions can exist in parallel, e.g.:
\begin{itemize}
\item Overlay for development.
\item Overlay for demos.
\item Overlay for experimenting with bleeding edge code of other people.
\end{itemize}
\section{ROS Overlays}
\paragraph{Creation}
The creation of an overlay with rosws is realized as follows:\\
\begin{tt}
sudo apt-get install python-rosinstall\\
rosws init \textasciitilde/fuerte /opt/ros/fuerte \# Create a new overlay\\
\# Load the created file setup.bash in .bashrc (optional)\\
\# echo "source \textasciitilde/fuerte/setup.bash" >> \textasciitilde/.bashrc \\
\end{tt}
\paragraph{Add packages}
To add a local directory (e.g. a sandbox for experimental packages), do:\\
\begin{tt}
mkdir \textasciitilde/fuerte/sandbox\\
rosws set \textasciitilde/fuerte/sandbox\\
\end{tt}
\paragraph{Installation}
Install packages from a rosinstall file:\\
\begin{tt}
rosws merge robohow-cram.rosinstall\\
rosws update\\
\end{tt}
Install a (released) stack from source:\\
\begin{tt}
roslocate info turtlebot | rosws merge -\\
rosws update
\end{tt}
The rosinstall files correspond to a YAML description of repositories to install.
They are ideal for repository snap shots and collaboration, and enable to specify versions, e.g:
\begin{verbatim}
- git:
local-name: cram_pl
uri: http://code.in.tum.de/git/cram-pl.git
version: 0.1.5
- svn:
local-name: knowrob
uri: http://code.in.tum.de/pubsvn/knowrob/tags/latest
\end{verbatim}
\section{Naming Conventions}
\paragraph{File names}
\begin{itemize}
\item Package names are lower case.
\item Packages and stacks must not contain dashes (“-”), only underscores (“$\_$”).
\item Messages, services and actions are named in camel case:
\begin{tt}geometry\_msgs/PoseStamped \end{tt}
\item Do not use the word “action” in an action definition (e.g.: Foo.action, not FooAction.action).
\end{itemize}
\paragraph{Topics, parameters, actions, services}
\begin{itemize}[noitemsep]
\item Nodes, topics, services, actions, parameters are all lower case with underscores as separator.
\item Never use global names, always node local topic, service, action and parameter names.
\item Use ros::NodeHandle handle("\textasciitilde")\\
\begin{tabular}{ll}
\textbf{Bad} & \textbf{Good}\\
ros::NodeHandle nh; & ros::NodeHandle nh("\textasciitilde");\\
nh.advertise$<$Foo$>$("foo", 10); & nh.advertise$<$Foo$>$("foo", 10);\\
Topics: $\rightarrow$ /foo &
Topics: $\rightarrow$ /node\_name/foo
\end{tabular}
\end{itemize}
\section{Best Practices}
\paragraph{Topics vs. Services vs. Actions}
\begin{itemize}
\item Use \textit{topics} for publishing continuous streams of data, e.g. sensor data, continuous detection results, . . .\\
\item Use \textit{services} only for short calculations.\\
\item Use \textit{actions} for all longer running processes, e.g. grasping, navigation, perception, . . .
\end{itemize}
\paragraph{ROS package}
\begin{itemize}
\item ROS packages are cheap, create many.
\item One package per functionality.
\item Create separate packages that contain only messages, services and
actions (separation of interface and implementation).
\begin{itemize}
\item Keep your dependencies clean:
\item only depend on what you need
\item specify all dependencies
\item do not use implicit dependencies
\end{itemize}
\item Provide launch files.
\item Group packages in stacks.
\end{itemize}
\paragraph{Misc}
\begin{itemize}
\item Use standard data types when possible.
\item Do not define matrix data types for transforms but use geometry\_msgs/PoseStamped.
\item Do not require a specific startup order for nodes: use \begin{tt}waitForService\end{tt}, \begin{tt}waitForTransform\end{tt}, \begin{tt}waitForServer\end{tt}, . . .
\item Use ros::Time, ros::Duration and ros::Rate instead of system time.
\item Do not use command line parameters but the ROS parameter server.
\item Use rosconsole utilities for logging (ROS\_INFO, ROS\_DEBUG, \ldots).
\item Never call cmake by hand in a package!
\end{itemize}
\section{Third Party Libraries}
\begin{itemize}
\item If possible, try to use libraries from Debian packages.
\item Specify rosdep dependencies (tool for installing system packages).
\item If you need to compile a library from source create a ROS wrapper
package that downloads and compiles the package.
\item Do not use sudo in wrapper packages.
\item Do not require manual system wide installations.
\item Do not copy libraries into packages that need them.
\end{itemize}
\section{Collaboration}
% Use version control systems (e.g. git or svn)
% Create tags for stable versions that others can use.
\begin{itemize}
\item Provide a rosinstall file.
\item Create a short Wiki page for each package
\item Document what the node does.
\item Document topics, services and actions that are required and
provided.
\item Document ROS parameters and their default values.
\item Data can be recorded and exchanged using bag files.
\end{itemize}
\section{Relase of the software}
To realize a release of your software, it is mandatory to
\begin{itemize}
\item Test your software using willowgarage buildfarm (see \url{http://www.ros.org/wiki/regression_tests} for more details).
\item Use the ros release system \url{http://www.ros.org/wiki/release}.
It will creates the binary deb and the source deb (repackaged tarball of the source) for you.
\end{itemize}
\section{ROS Bag Files}
%\note{definition of a ros bag}
Recording of a bag:
\begin{tt}rosbag record <topic> <topic> ...\end{tt}\\
Play a bag:
\begin{tt}rosbag play foo.bag\end{tt}\\
Play a bag using recorded time (important when stamped data and
TF was recorded):\\
\begin{tt}rosbag play --clock foo.bag\end{tt}