DHZT_ROS_Developer_Guide 大華中天ROS風格指南

DHZT_ROS_Developer_Guide 大華中天ROS風格指南

0. 前言

0.1 版本

• 1.0版本(2019.3.12)：本文檔參考了 ROS 官方風格指南及曉萌團隊開發指南，並進行了一定程度的擴充。團隊成員應該儘量按照 ROS 基本的開發風格以及適用於本項目組的特定規則進行代碼開發。如果有細節不統一的地方或者對本文檔某處不是很認同，請在組內討論統一之後，修改本指南。

0.2 背景

良好一致的ROS代碼開發風格及命名統一有助於對代碼的理解以及重複利用，並能夠極大的方便對ROS節點、話題、服務器的調用。因此，我們應當使用統一的 ROS 開發風格，提升ROS架構的可讀性，降低後續開發者的維護難度。

1. ROS 命名指南

Tip

所有命名的通用的標準是：

• 命名要足夠詳細（不要吝嗇長度），讓開發者能通過名字知道你的意圖。

1.1 Packages

Tip

包的命名要全部小寫、使用統一的項目前綴，並且要足夠詳細。

• 包的名字必須遵守 C++ 變量命名的規範：全部小寫、以字母開始、單詞之間使用下劃線連接。比如：dhrobot_driver。
• 每個包的名字前都要有項目的根或子前綴。要求：如果包是作用於整個機器人或多個模塊的，那麼包的前綴應該爲 dhrobot_。比如：dhrobot_launch。如果包的作用域是針對於機器人的某一個模塊的話，那包的前綴應是在原先根前綴 dhrobot_ 的基礎上再添加相應模塊的名字來構成。比如：dhrobot_arm_、dhrobot_base_、dhrobot_vision_ 等。
• 仿真項目請修改根前綴爲 dhrobot_sim_，其他規則與上面一樣。
• 如果包的內容是基於其他第三方包的話，請在名字中進行指定。比如：一個基於 Moveit 的機械臂逆解算插件，就可以命名爲 dhrobot_arm_moveit_ik_plugin。
• 元包（Metapackages）的命名比較特殊。因爲元包包含了若干個子包，所以在給元包命名的時候，取一個能概括所有子包含義的名字是很有必要的。
• 其他的請參照 ROS Hector 團隊代碼倉庫中包的命名規範。

1.2 Messages

Tip

所有 .msg、.srv、.action 文件命名使用組內特定的規則。

• 所有 .msg、.srv、.action 文件命名規則爲：首先添加 dh_ 前綴，之後添加每個文件具體的功能描述。描述部分必須使用駝峯命名法。例如：dh_GripperCommand.action。

1.3 Launch / Config /Xacro

Tip

所有機器人啓動、配置、描述文件命名全部小寫，並且描述的儘可能清楚。

1.4 Nodes

Tip

命名要小寫，節點的類型（程序的名字）可以與包名中的某些單詞重複，但一定要保證通過名字能準確知道其功能。

節點有類型和名字。節點類型指的是可執行程序的名字，而節點名字指的是啓動後生成的，可以與其他節點通信的名字。

• 節點名字與節點類型一樣。要全部小寫、使用下劃線作爲單詞間的連接，並用有意義的單詞來命名。
• 通常，節點名字要與節點類型相同。但如果要啓動多個同樣類型的節點，請更改節點名字，使它們互不相同。
• 通常，若一個功能包下只有一個節點，應將節點名稱與功能包名稱保持一致。

1.5 Topic / Service / Action

Tip

命名小寫、具有描述性、且添加適合的前綴來明確名字的作用範圍。

topic、service 和 action 的名字是節點服務端、客戶端之間通信的橋樑。它們存在於一個分層的命名空間中，客戶端便可以提供機制在運行時來重映射它們的名字。因此，它們相較於包的命名更加靈活。

• topic、service 和 action 的名字遵循 C++ 變量命名指南：小寫、下劃線。
• 命名應該足夠的具有描述性。並且最好添加相應的前綴來指明 topic、service、action 的作用範圍。比如：假設機械臂關節節點要通過 topic 發佈關節狀態數據，那命名成 /joint_states 要比 /states 好。
• 機器人發佈的話題統一加上機器人的前綴dhrobot/,例如**/dhrobot_arm/joint_states** 。
• 如果某些程序發佈的 topic、service、action 名字沒有使用前綴，請在 launch 文件中使用 <remap>來重映射。比如：節點 robot_state_publisher 默認訂閱的 topic 是 /joint_states，使用重映射可以使其訂閱 /dhrobot_arm/joint_states 上的數據。

2. ROS 格式指南

Tip

所有格式的通用標準是：

• 在 ROS 包中，除代碼外，其他跟 ROS 有關的文件都需要使用官方指定的 2 格縮進。
• 所有文件的末尾都要留出一個空行，不能多也不能少。

2.1 Package.xml

Tip

使用項目組內特定的風格。

package.xml 是每個 ROS 包都必須包含的，可以通過使用 catkin_create_pkg 自動生成，其他詳細介紹請看 ROS package。以下是 package.xml 的格式風格。

• 正常情況下，使用推薦的Format 2方式進行package.xml的編寫,具體介紹查看 ROS package_Format2。
• version版本標籤的含義爲：主版本-子版本-修改次數。現在所有包的主版本默認爲 1 ，子版本和修改次數默認爲 0 。即初始化爲 1.0.0。之後，主、子版本和修改次數的值會伴隨 ROS 包的修改而不斷變化。當修改次數達到一定值時，可以將子版本加 1，而修改次數重新歸零。以此類推，如果子版本數增到一定程度時，就可以將主版本加 1，而其他兩個歸零。對於修改到什麼程度就可以向子版本或主版本進 1，請各模塊負責人自己決定。舉個例子：1.0.0 -> 1.0.20 -> 1.1.0 -> 1.2.10 -> 2.0.0。
• 內容全部使用 2 格縮進。
• 所有在 package.xml 中被註釋的都要刪除掉，只留下最後精簡過的、有用的信息。
• <maintainer> 和 <author> 的區別在於，<maintainer> 是包的主要或最早開發者，而 <author> 則是之後爲包提供修改的開發者。顯然，出現在 <maintainer> 的名字也應該出現在 <author> 中。如果有其他開發者修補了 Bug 或進行了增量式的開發，請將名字寫在 <author> 標籤之後。
• 因爲 ROS 使用的軟件許可證協議是 BSD，所以我們所有的包也要以 BSD 協議發佈出去。
• 空格和空行的使用請嚴格遵循下面完整例子所實現的那樣。
• 如果包是元包（Metapackages），請在 package.xml 的末尾處添加以下內容：

 <export>
   <metapackage />
 </export>

以下是個完整的例子：

<?xml version="1.0"?>
<package format="2">
<package>
  <name>dhrobot_driver</name>
  <version>1.0.0</version>
  <description>The dhrobot_driver package.</description>

  <maintainer email="[email protected]">author</maintainer>

  <license>BSD</license>

  <author email="[email protected]">author</author>

  <buildtool_depend>catkin</buildtool_depend>

  <build_depend>roscpp</build_depend>
  <build_depend>rospy</build_depend>
  <build_depend>std_msgs</build_depend>
  <build_depend>dhrobot_msgs</build_depend>
  <build_depend>geometry_msgs</build_depend>
  <build_depend>sensor_msgs</build_depend>
  <build_depend>actionlib_msgs</build_depend>
  <build_depend>tf</build_depend>
  
  <build_export_depend>tf</build_export_depend>
  <build_export_depend>roscpp</build_export_depend>
  <build_export_depend>rospy</build_export_depend>
  <build_export_depend>std_msgs</build_export_depend>
 
  <exec_depend>roscpp</exec_depend>
  <exec_depend>rospy</exec_depend>
  <exec_depend>std_msgs</exec_depend>
  <exec_depend>nav_msgs</exec_depend>
  <exec_depend>geometry_msgs</exec_depend>
  <exec_depend>dhrobot_msgs</exec_depend>
  <exec_depend>actionlib_msgs</exec_depend>
  <exec_depend>tf</exec_depend>

</package>

2.2 CMakeLists.txt

Tip

使用項目組內特定的風格。

CMakeLists.txt 是 CMake 編譯系統的輸入文件，用來描述如何構建代碼。更多詳細的介紹請看 ROS CMakeLists.txt。以下簡單地介紹編寫或修改 CMakeLists.txt 所使用的格式風格。

• 內容全部使用 2 格縮進。
• 每個命令之間要空 1 行。
• 所有在 CMakeLists.txt 中被註釋的都要刪除掉，只留下最後精簡過的、有用的信息。
• 每個命令中的元素最好每行只寫一個，而且要對齊。這樣看起來更清楚。
• 針對於元包（MetaPackages），請在 CMakeLists 中寫入以下內容：

cmake_minimum_required(VERSION 2.8.3)
project(<PACKAGE_NAME>)
find_package(catkin REQUIRED)
catkin_metapackage()

以下是完整的例子：

cmake_minimum_required(VERSION 2.8.3)
project(dhrobot_driver)

find_package(catkin REQUIRED COMPONENTS
  roscpp
  rospy
  std_msgs
  dhrobot_msgs
  actionlib_msgs
  actionlib
  geometry_msgs
  sensor_msgs
  nav_msgs
  tf
)

catkin_package()

include_directories(
  include
  ${catkin_INCLUDE_DIRS}
)

add_executable(
  robot_driver src/robot_driver.cpp
  include/robot_driver.h
)

target_link_libraries(
  robot_driver
  ${catkin_LIBRARIES}
  libDHRobotAPIso.so
)

2.3 Launch

Tip

使用項目組內特定的風格。

launch 文件作爲 roslaunch 命令的輸入，可以啓動多個 ROS 節點並在參數服務器上設置參數。更多有關詳細內容請關注 ROS launch。以下簡介 launch 文件的格式風格。

• 所有內容 2 格縮進。
• 每個標籤之間要空 1 行。如果是相同標籤，則之間可以不空行。
• 每個標籤的開頭，最好能有一行註釋來解釋標籤所要實現的功能。
• 每個標籤的結束內容要與 /> 之間空一格。
• 每個標籤內部的 = 前後是沒有空格的。
• 針對根標籤內部可以嵌入子標籤的情況，請子標籤縮進 2 個空格。
• 如果標籤一行太長，則請適當的換行。換行之後請與上一行的元素對齊。
• <node> 的基本聲明順序爲：name， pkg， type。

<node name="joy" pkg="joy_node" type="joy_node" />

• <arg> 的基本聲明順序爲：name，value。

<arg name="joystick" default="true" />

• <param> 的基本聲明順序爲：name， type， value。

<param name="joy_node/dev" type="string" value="/dev/input/js0" />

• <rosparam> 的基本聲明順序爲：command，file。

<rosparam command="load" file="$(find rosparam)/example.yaml" />

以下是完整的例子：

<?xml version="1.0"?>
<launch>
  <include file="$(find yocs_cmd_vel_mux)/launch/standalone.launch"/>

  <arg name="joy_dev" default="/dev/input/js0" />
  <arg name="joystick" default="true" />

  <group>

    <rosparam command="load" file="$(find dhrobot_remote_teleop)/config/teleop.yaml" />
    <param name="joy_node/dev" value="$(arg joy_dev)" />
    <node name="joy_node" pkg="joy" type="joy_node" />
    <node name="joy_tele" pkg="dhrobot_remote_teleop" type="joy_tele" />

  </group>

</launch>

2.4 License

Tip

使用基於 BSD 的項目組軟件開發許可證協議。

因爲，ROS 開發使用的是 BSD 軟件開發許可證協議。所以我們項目組在發佈代碼和軟件包的時候，也要使用 BSD 許可證協議。以下簡介格式指南。

• 每個 ROS 軟件包的目錄下都要放置一個名爲 LICENSE 的許可證文件。
• 每個 C++ 代碼的頭文件和源文件都要在開始放置許可證協議。
• 每個 Python 代碼的頭部都要放置許可證協議。

以下是相應的例子：

Software License Agreement (BSD License)

Copyright (c) 2018, Dalian DHZT inc
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

 * Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials provided
   with the distribution.
 * Neither the name of the copyright holder nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

/*********************************************************************
 *  Software License Agreement (BSD License)
 *
 *  Copyright (c) 2018, Dalian DHZT inc
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above
 *     copyright notice, this list of conditions and the following
 *     disclaimer in the documentation and/or other materials provided
 *     with the distribution.
 *   * Neither the name of the copyright holder nor the names
 *     of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written
 *     permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 ********************************************************************/

"""
 ********************************************************************
 *  Software License Agreement (BSD License)
 *
 *  Copyright (c) 2018, Dalian DHZT inc
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *
 *   * Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *   * Redistributions in binary form must reproduce the above
 *     copyright notice, this list of conditions and the following
 *     disclaimer in the documentation and/or other materials provided
 *     with the distribution.
 *   * Neither the name of the copyright holder nor the names
 *     of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written
 *     permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
 *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 ********************************************************************
"""

2.5 URDF/XACRO

Tip

使用項目組內特定的風格。

urdf文件是一種統一機器人描述格式，具體詳細介紹請看 URDF。

• 爲了實現機器人模型的整理，對某些部件進行重複利用，減少代碼量，推薦使用xacro格式對機器人描述文件進行二次整理，具體詳細介紹請看 XACRO。
• 因爲我們通常通過solidworks插件進行urdf模型的轉換 轉換插件，爲了減少工作量，urdf/xacro對模型的描述順序與轉換後保持一致。
• 兩種描述文件都是基於XML格式文件，爲了減少工作量，建議採用在線格式化工具對XML進行文本整理 XML在線格式化工具。
• 每個joint、link標籤段落前後之間要空 1 行。
• 如果標籤一行太長，則請適當的換行。換行之後請與上一行的元素對齊。
  以下是個完整的xacro例子：

<?xml version="1.0"?>

<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="dhrobot_arm">  
  <xacro:macro name="dhrobot_arm" params="parent *origin"> 
   
    <joint name="arm_base_joint" type="fixed"> 
      <xacro:insert_block name="origin"/>  
      <parent link="${parent}"/>  
      <child link="arm_base_link"/> 
    </joint>  
   
    <link name="arm_base_link"> 
      <inertial> 
        <origin xyz="-0.0001152 0.0025412 0.070685" rpy="0 0 0"/>  
        <mass value="0.40818"/>  
        <inertia ixx="0.00071856" ixy="-1.5281E-06" ixz="-3.2548E-07" iyy="0.00073839" iyz="-2.4896E-06" izz="0.000698"/> 
      </inertial>  
      <visual> 
        <origin xyz="0 0 0" rpy="0 0 0"/>  
        <geometry> 
          <mesh filename="package://dhrobot_description/meshes/arm_base_link.STL"/> 
        </geometry>  
        <material name=""> 
          <color rgba="0.75294 0.75294 0.75294 1"/> 
        </material> 
      </visual>  
      <collision> 
        <origin xyz="0 0 0" rpy="0 0 0"/>  
        <geometry> 
          <mesh filename="package://dhrobot_description/meshes/arm_base_link.STL"/> 
        </geometry> 
      </collision> 
    </link>  
   
    <link name="arm_link_1"> 
      <inertial> 
        <origin xyz="-2.3512E-06 -0.18768 0.0080021" rpy="0 0 0"/>  
        <mass value="0.40127"/>  
        <inertia ixx="0.0041563" ixy="-8.3909E-07" ixz="-1.564E-07" iyy="0.00039337" iyz="-0.00039466" izz="0.0040618"/> 
      </inertial>  
      <visual> 
        <origin xyz="0 0 0" rpy="0 0 0"/>  
        <geometry> 
          <mesh filename="package://dhrobot_description/meshes/arm_link_1.STL"/> 
        </geometry>  
        <material name=""> 
          <color rgba="0.75294 0.75294 0.75294 1"/> 
        </material> 
      </visual>  
      <collision> 
        <origin xyz="0 0 0" rpy="0 0 0"/>  
        <geometry> 
          <mesh filename="package://dhrobot_description/meshes/arm_link_1.STL"/> 
        </geometry> 
      </collision> 
    </link>  
   
    <joint name="arm_joint_1" type="revolute"> 
      <origin xyz="0 0 0.08" rpy="-1.5708 -7.886E-16 -6.6443E-18"/>  
      <parent link="arm_base_link"/>  
      <child link="arm_link_1"/>  
      <axis xyz="0 0 -1"/>  
      <limit lower="-1.57" upper="1.57" effort="0" velocity="0"/> 
    </joint>  
   
    <link name="arm_link_2"> 
      <inertial> 
        <origin xyz="0.00079585 0.0055011 0.16292" rpy="0 0 0"/>  
        <mass value="0.22761"/>  
        <inertia ixx="0.001119" ixy="-1.1536E-05" ixz="-6.9692E-06" iyy="0.0010183" iyz="-4.3124E-05" izz="0.00022538"/> 
      </inertial>  
      <visual> 
        <origin xyz="0 0 0" rpy="0 0 0"/>  
        <geometry> 
          <mesh filename="package://dhrobot_description/meshes/arm_link_2.STL"/> 
        </geometry>  
        <material name=""> 
          <color rgba="1 1 1 1"/> 
        </material> 
      </visual>  
      <collision> 
        <origin xyz="0 0 0" rpy="0 0 0"/>  
        <geometry> 
          <mesh filename="package://dhrobot_description/meshes/arm_link_2.STL"/> 
        </geometry> 
      </collision> 
    </link>  
   
    <joint name="arm_joint_2" type="revolute"> 
      <origin xyz="0.00011599 -0.315 -0.00031591" rpy="1.5708 3.324E-16 -1.3271E-16"/>  
      <parent link="arm_link_1"/>  
      <child link="arm_link_2"/>  
      <axis xyz="0 0 -1"/>  
      <limit lower="-3.14" upper="3.14" effort="0" velocity="0"/> 
    </joint>  
   
  </xacro:macro> 
</robot>

3. ROS 管理指南

3.1 目錄位置

Tip

刪除沒用的空目錄。其他文件的放置位置要合理。

以下路徑都是相對於 ROS 包 <PACKAGE_NAME> 根目錄的。

• C++ 代碼頭文件要放到 include/<PACKAGE_NAME>/ 目錄下。
• C++ 源文件放到 src/ 目錄下。
• Python 文件要放到 scripts/ 目錄下。
• Python 生成的模塊要放到 src/<PACKAGE_NAME>/ 目錄下。
• lanucn 文件要放到 launch/ 目錄下。
• rviz 可視化配置文件要放到 rviz/ 目錄下。
• urdf 機器人描述文件要放到 urdf/ 目錄下。
• 機器人零件模型要放到 meshes/ 目錄下。
• gazebo 仿真環境配置文件要放到 world/ 目錄下。
• message 文件要放到 msg/ 目錄下。
• service 文件要放到 srv/ 目錄下。
• action 文件要放到 action/ 目錄下。
• 其他配置文件要放到 config/ 目錄下。

另外，與機器人本身驅動相關性不高的demo等演示性或者實驗性質的程序放到ROS 包 <dhrobot_demo>下。

3.2 節點通信類型

Tip

根據模塊之間通信需求，合理使用。

3.3 元包

Tip

可以將功能相近的若干個包組織在一個元包內。

更新於2019.3.12