ROS机器人高效编程（原书第3版）勘误、问题及资料汇总

ROS机器人高效编程（原书第3版）勘误、问题及资料汇总--持续更新

如果小伙伴发现书中错误，恳请批评指正，非常感谢。勘误在文末。

补充一行代码装ROS，适用于14.04LTS（indigo）和16.04LTS（Kinetic）：

14.04：

wget https://raw.githubusercontent.com/oroca/oroca-ros-pkg/master/ros_install.sh && ./ros_install.sh %NAME_CATKIN_WS% %NAME_ROS_DISTRO_LOWERCASE%

(indigo示例如下)
wget https://raw.githubusercontent.com/oroca/oroca-ros-pkg/master/ros_install.sh && chmod 755 ./ros_install.sh && ./ros_install.sh catkin_ws_oroca indigo

16.04：

curl https://raw.githubusercontent.com/oroca/oroca-ros-pkg/master/ros_install.sh | bash -s %NAME_CATKIN_WS% %NAME_ROS_DISTRO_LOWERCASE%

(Kinetic示例如下)
curl https://raw.githubusercontent.com/oroca/oroca-ros-pkg/master/ros_install.sh | bash -s cws_oroca kinetic

|附资料：

第2版镜像链接；第3版镜像链接；ROS官网介绍；Github。

https://github.com/rosbook/effective_robotics_programming_with_ros

注意：请不要使用catkin_make编译，使用catkin build。具体如下：

ROS机器人高效编程 - 原书第三版

ROS机器人高效编程 - 原书第三版教程源代码。

作者

• 阿尼尔 马哈塔尼
• 路易斯 桑切斯
• 亚伦 马丁内斯
• 恩里克 费尔南德斯

安装

按照这里提供的官方说明，在兼容的Ubuntu发行版上安装ROS Kinetic。推荐Ubuntu 16.04 LTS。

安装OpenCV非免费版本库：

sudo apt-get install software-properties-common python-software-properties
sudo add-apt-repository --yes ppa:xqms/opencv-nonfree
sudo apt-get install libopencv-nonfree-dev libopencv-nonfree2.4v5

创建一个工作区：

mkdir -p ~/dev/catkin_ws/src
cd ~/dev/catkin_ws/src
wstool init

下载moveit_simple_grasps存储库，因为它不再是debian的官方版本：

wstool set moveit_simple_grasps -y --git git@github.com：efernandez / moveit_simple_grasps.git

下载此代码库：

wstool set ros_book --git git@github.com:rosbook/effective_robotics_programming_with_ros.git
wstool up -j8

安装依赖项：

cd ..
rosdep install --from-paths src -iy

编译源代码：

source /opt/ros/$(rosversion -d)/setup.bash
catkin build -j4 -p4 --cmake-args -DCMAKE_BUILD_TYPE=RelWithDebInfo
source devel/setup.bash

教程目录：

• 第01章：ROS入门（在安装过程中不涉及源代码）
• 第02章：ROS架构和概念
• 第03章：可视化和调试工具
• 第04章：3D建模与仿真
• 第05章：导航功能包集入门 - 机器人设置
• 第06章：导航功能包集进阶 - 其他设置
• 第07章：使用MoveIt!
• 第08章：在ROS下使用传感器和执行器
• 第09章：计算机视觉
• 第10章：点云

----

|勘误：

书中代码部分有缺漏或排版问题，请参考对应源代码，如138，213，稍后会补充详细。

01. 216页，（此外，发布的消息将会在setup中宣传）更正为：此外，在setup中订阅发布的消息：

02. 225页，

03. 226页，（/imu/data主题是sensor_msg/imu）更正为：/imu/data主题对应的数据类型是sensor_msg/imu

04. 

~持续更新~

如果困惑于使用哪一个版本的ROS，这里推荐Kinetic和Indigo，具体可以参考ROS年度指标报告。

ROS官方已经发布了2017年的年度ROS指标报告。您可以从这里下载15，并将其添加到 Metrics wiki第34页，您可以在其中找到所有以前版本的链接。

ROS官方在2011年开始收集指标。查看历史，可以看到社区的发展和演变。

衡量开源社区是非常困难的。公开和可再发行的性质意味着我们绝对不认识所有使用它的人，而且这是开放的一部分。这些指标可以提供对社区趋势的洞察，但不应被视为详尽无遗或甚至接近完整，而应视为一致的快照。（报告体现了趋势和发展）我们有关于设置镜像的公开说明，这些采集不包括私人或公共镜像的统计数据。公共镜像列在http://wiki.ros.org/Mirrors

每年我们都会提供相同的指标，以便观察趋势。不过，我们也希望更新这些指标，以纳入新的统计资料或涵盖未来我们认为有趣趋势的新方面。例如，我们从去年开始对架构的使用进行抽样，因为对armhf和arm64的兴趣越来越大，而i386现在已经不再是最受欢迎的架构。

在汇编这份报告时，有几个数据显示出来。最大的是，去年，我们将package.ros.org 5的唯一身份访问量增加了一倍以上。这是社区规模最大的代理商之一。诸如下载计数和带宽使用的其他统计数据可能高度依赖于在任何给定时间段内哪些软件包被释放。

两个统计数字是值得注意的异常值。一个是discourse.ros.org 1上的用户数量，目前有一个垃圾邮件攻击，新的未验证的用户被半自动创建。他们没有超过验证阶段，不能发布。但是，该网站包含他们的用户数，我没有一个很好的方式来排除未经验证的用户。7天后，系统会自动清除。另一个有点偏斜的统计数字是机器人的数量。今年我们从wiki.ros.org/Robots切换到http://robots.ros.org 4在切换过程中，有一个审查过程。但是，很明显，新网站的提交也是下降的。我们需要考虑使其更容易访问，因为我相信这个指标现在报表不足。

ROS官网机器人合集：http://robots.ros.org

----

ROS开发者指南

目录

1. ROS开发者指南
   1. 源代码管理
   2. Bug追溯
   3. 代码布局
   4. 功能包
   5. GUI 工具包
   6. 代码构建
   7. 证书
   8. 版权
   9. 调试
   10. 测试
   11. 文档汇总
   12. 正式发布
   13. 标准化
   14. 弃用规则
   15. 大数据文件，大测试文件

ROS是一个庞大的系统，许多人协同开发。为了合理的管理，我们已经写好了开发指导说明。请按照下面的指导说明，合理布局你的代码。

参考:

• Quality assurance process
• ROS C++ Style Guide
• ROS Python Style Guide
• ROS Javascript Style Guide
• Naming Conventions
• CommonProcedures

源代码管理

支持使用Git，Mercurial,Subversion, 和Bazaar进行代码管理。由于ROS社区是分散的，欢迎你将代码托管到任何公共访问的地方(比如GitHub, Bitbucket, Google Code). 主要的ROS基础代码会被发布到github.com的几个组织单元several organization units下面。关于建议的仓库使用说明参考RecommendedRepositoryUsage

• 只添加手动编写的源代码文件，以及必须的构建功能包的相关文件. 不要添加机器自动生成的文件，比如目标文件(*.o)，库文件(.a, .so, .dll), 或者自动配置脚本文件.
  • svn add 将会递归到子目录里添加所有文件. 在svn add之前先操作下 make clean .
  • 不要添加大的二进制文件: 通过web服务器上传，下载到本地的构建文件夹去.
• 尽早且经常性提交自己的代码.不在源码管理范围内的任何文件都应该作为草稿（scratch）存储。
• 尽量保持每次的提交集中到一处特殊的更改，而不是一次提交多方面的更改，这样更容易回溯代码。
• 每一次的提交都写清更改说明.
• 不要打乱构建结构. 在check in之前确保你的代码能够顺利编译.

Bug追溯

针对每一个功能包，利用单独的bug tracker，实现bug报告，增强请求，和任务分配。经常性的，在本站的页面上，你会看的一些具体的bug tracker的相关链接。

对于代码的托管GitHub作为一个仓库的通用的bug tracker。

代码维护者将会为每个报告的问题创建一个里程式标记(milestone)。当问题被定位时，可以给报告者一个合适的反馈。这些里程标记就是ROS正式版(比如 Groovy or Hydro) 或者细分版本(比如 Hydro beta 1). 更多的是，当问题没被修复时，会赋以标记untargeted。这可能是由于开发者的时间紧迫或者可靠性的考虑。

为了让用户表达自己的想法，针对已发布的软件版本，测试是否已经修复bug，维护者应该要么，在关闭问题报告的时候，发布一个尝试版本，要么为每一个更细化的版本设置标记，在下个里程标记之前，标记问题报告。这样一来，对用户来说，让所包含的问题本身来决定发布版的bug是否已经被修复。

当你发现一个bug时，开启一个指派（ticket）。当你需要新功能的时候，打开一个指派。邮件或者发布到answers.ros.org或者邮件列表都有可能被遗忘。但是，指派的方式反而就不会那么容易忘记。

• 指派的时候尽量遵循这些原则.
  • 尽量包含bug重现时，需要的指令。They should include instructions for reproducing the bug.
  • 尽量描述问题出现时的，系统运行状态。（用的什么系统版本，涉及的功能包有哪些。
• 不要畏惧指派。许多开发者都会指派给他们自己，比如利用Trac。

如果你不确定出现问题时涉及的的功能包或者问题确实是一个bug，请首先访问answers.ros.org。

代码布局

package功能包由代码组织而成，而功能包组成一个单独的仓库responsitory。功能包是作为代码构建的基本单位。

尤其注意！建议，在GitHub上，在仓库的根目录创建一个README.md，用来向用户说明代码仓库的具体细节。建议，在ROS wiki页面设置链接到指定的包含的软件包。参照 this article 获取更多的帮助.

功能包

ROS功能包和系统的构建依赖于manifest.xml。

• 每一个功能包都必须，在功能包所在的顶层目录，存在一个manifest.xml文件.
• 最基本的，manifest必须包含下面的三部分
  • description
  • author
  • license

下面举一个roscpp节点的一个模板例子：

<package>
  <description brief="BRIEF DESCRIPTION">
     LONGER DESCRIPTION
  </description>
  <author>You/you@willowgarage.com</author>
  <license>BSD</license>
  <url>http://www.ros.org/wiki/YOURPACKAGE</url>
  <depend package="roscpp"/>
</package>

下面是rospy的一个例子:

<package>
  <description brief="BRIEF DESCRIPTION">
     LONGER DESCRIPTION
  </description>
  <author>You/you@willowgarage.com</author>
  <license>BSD</license>
  <url>http://www.ros.org/wiki/YOURPACKAGE</url>
  <depend package="rospy"/>
</package>

GUI 工具包

我们已经移植了所有最新的GUI到rqt，这些GUI都是QT基础的GUI框架。在fuerte使用wxWidgets之前，因交叉编译的兼容性太差，大部分已有的代码被重建。 因此对于新的GUI设计，考虑使用rqt。开发说明从这里获取(including license consideration when writing in python)。

代码构建

基本的代码构建工具是CMake(more).

• 每一个创建的功能包的顶层目录都必须存在CMakeLists.txt .
• 现在，每一个功能包都必须有一个Makefile, 短而精巧.
• 那些没有经过构建步骤的功能包不需要任何的构建文件。

证书

ROS 是开源.旨在让来自五湖四海的不同的用户和开发者们，从学生到企业家们，都可以得到帮助获取支持。

• 我们倾向自由的开源证书，促进代码的商业化.
• 倾向建议使用证书BSD 证书. 尽可能，新的代码都应该在BSD证书下发布。所有的ROS代码都是BSD证书下发布的选择BSD的原因
• 其他任何的OSI促成的证书都是可接受的(for non-core code).
• 我们强烈建议使用非对称版权的证书（比如BSD），来进行ROS .msg和.srv文件的发布，所以不妨碍那些自动产生的源代码文件和数据结构.
• 工程中的所有文本状态的证书都应该放到顶层的LICENSES文件目录下。如果你天剑了一个并不包括在LICENSE目录下的证书，添加下证书状态即可。
• 每一个源代码文件，都应该在顶层，包含一个证书的简略版注释。方便的，LICENSES目录下也应该包含证书的简略说明，并且需要不同的语言书写。
  • 对于我们发布的第三方的代码，证书和版权会被予以保护
• 我们将严格遵守第三方软件，例如：
  • 如果库有证书GPL声明 or LGPL 声明，如果你修改了，则你必须发布修改后的代码。理想情况下，你必须发送一个补丁给库的维护者。保持如果修改后的代码的公共访问权限也是必要的.
  • 如果你的功能包使用了GPL'd库，然后你的功能包也必须进行GPL声明。
  • 如果你的功能包使用了GPL'd库，那么你就不能使用与GPL不兼容的授权协议GPL-incompatible license. 例如，Creative Commons Attribution-Noncommercial-Share Alike 证书是与GPL不兼容的，因为他强加了一些GPL不能做的约束条件(换句话说，就是要求的属性，禁止商业使用等).
• 尽可能的，每一个ROS功能包都以一种单一证书形式予以管理。
  • 一般性的特殊案例：BSD证书代码（比如 ROS core），在一个功能包，也会用到GPL证书声明的代码。为了配合GPL，BSD声明的代码，是在BSD和GPL多证书下声明的，用户可以选择使用哪个证书协议。这当然也不是声明大问题，因为GPL增加了一些BSD不要求的一些限制条件。
• ROS功能包和通信系统允许细致的证书协议。因为节点通过ROS消息进行通信，多节点通信的代码不是连接到一起。因此，功能包提供了一种“证书壁垒（license boundary）”。
  • 例外:当一个功能包是库的形式，并且确实链接到其他的功能包。这种情况下，各个证书会被混合声明在目标代码里。
• 引用: Maintaining Permissive-Licensed Files in a GPL-Licensed Project: Guidelines for Developers

版权

遵循Berne Convention版权，作为作者自动拥有版权，而不管有没有一个正式的声明。无论如何，显式的版权声明有助于长期性项目的管理。

• 每一个源文件都应该在文件顶层上，包含一个版权说明注释，例如 Copyright 2008 Jim Bob. 这个就是一个证书的简概说明.
• 如果只自己使用，版权属于自己。
• 如果受雇于某些人，或者公司（比如Willow Garage），版权就属于公司。

调试

ROS里的调试工具，包括但不限于：

• GDB
• Oprofile
• Valgrind

一般性建议:

• 如果一个程序，比如foo, crashes, 首先使用 GDB:
  • 可以通过添加一些必要的参数:
  • (gdb) run arg1 arg2 arg3
  • 当程序崩溃crashes时，利用gdb的bt指令来进行追溯和探究。
• 对于一些棘手的bug，尤其涉及到内存崩溃的。试着实用工具valgrind:
  • valgrind -v foo arg1 arg2 arg3
  • Valgrind可以追踪所有的内存访问呢，一把可以找到问题的原因。同样，可以发现你没有发现的其他问题。注意的就是，Valgrind会拖慢你程序运行的节奏，看起运行缓慢。
• master和rospy的日志会默认创建到ROS_ROOT/log。但是，roscpp的客户端节点日志默认不会创建。如果你正在以nasty模式调试时，你可以设置构建的第二个参数WRITE_LOG_FILE（伴随其他的选项ANONYMOUS_NAME等）。其他选择是，如果你不想重新编译节点，你可以在命令行中添加log:=BLAHBLAH，BLAHBLAH可以是任何东西，也可以什么也不是。

测试

我们进行两个级别的测试:

• 库: 在库的层面上，我们使用用标准的单元测试框架。C++时，我们使用gtest.,Python时，我们使用unittest.
• 消息: 在消息层面上，我们使用rostest.建立系统节点，运行一个测试节点，然后逐步拆分系统。

我们已经构建了best practices and policies ，进行编写和运行测试test。

如果你在ROS系统下，开发ros-pkg 或者wg-ros-pkg，安装build farm 启动测试构代码搭建和自动测试在不同的芯片体系下。如果在你提交后，搭建或者测试停止工作，你应该获得一封邮件来告知相关的错误，希望来修复它。参考AutomatedTesting指导说明。

文档汇总

• 所有的代码都应该参照 QAProcess.进行文档汇总。包括:
  • 所有外部的可见的代码级的API
  • 所有外部的可见的ROS级的API

正式发布

ROS社区代码的发布流程参考release页面

标准化

• 在代码应该用到ROS的服务的地方，遵循以下规则
  • 调用rosout打印消息
  • 参考Clock应用到时基服务例程。

弃用规则

一旦有人使用的你的代码，你就有责任不要对他们所谓的对代码大幅改动，进行釜底抽薪。相反的，使用deprecation,意味着，对于它的移除用清单的形式，标记指定的特性或者内容不再支持。给用户些时间去适应，作为一个发布版的过程循环，就和移除一样。

弃用发生在多级情况下，包括:

• API features : 你想从库中，删除一个方法。首先需要再API文档中标记它被弃用了。在DOxgyen中，使用@deprecated. 如果语言支持相关语法，也可以在源码中标注。比如C/C++，利用 __attribute__ ((deprecated)). 在下一次的发布版中，就要注意弃用的标记在修改清单中，标有未来的发布版本中你希望删除的部分。如果代码未来会被广泛应用，将其标记的明显些，然后在后面附上注释。在未来的正式发布版中，删除即可。
• Packages : 意思就是，你想删除一个功能包。在wiki文档中标记为弃用（比如吧DEPRECATED标记在文档开头），声明你想要什么时候删除。更改说明，包含那些弃用的声明，会被带到下一次的发布版中。当功能包被广泛使用的时候，你就应该使用email，尽量将警告发给那些使用的用户。

大数据文件，大测试文件

大文件（大小超过1MB）经常不属于*-ros-pkg仓库代码，尤其是他们一般仅仅用在单元测试时。不管某些人是否构建了你的功能包，大的文件会影响checkout的仓库的时间和效率。

大的数据文件应该被托管到公共的web主网页。在web服务器上，你也可以仅仅放置你所需要的文件。文件的托管可以在download.ros.org. 请联系ros-release@lists.ros.org 获取更多信息。在你打开上传请求之前，鼓励你去查找是否已存在你所需要的文件。

下载文件，请使用catkin_download_test_data. 如果，你在更早的rosbuild时候，使用rosbuild_download_test_data(URL MD5SUM) 宏定义。比如：

catkin_download_test_data(
    ${PROJECT_NAME}_saloon.bag
    http://downloads.foo.com/bags/saloon.bag
    DESTINATION ${CATKIN_DEVEL_PREFIX}/${CATKIN_PACKAGE_SHARE_DESTINATION}/test
    MD5 01603ce158575da859b8afff5b676bf9)

rosbuild_download_test_data(http://code.ros.org/svn/data/robot_pose_ekf/zero_covariance.bag test/zero_covariance.bag 0a51b4f5001f446e8466bf7cc946fb86)

----