1 ROS project structure

1.1 catkin workspace

Catkin workspace is the directory where catkin software packages are created, modified, and compiled. Catkin's workspace can be intuitively described as a warehouse, which contains various ROS project projects to facilitate system organization, management and calling.

• Create workspace:

mkdir -p ~/catkin_ws/src # Create folder
cd ~/catkin_ws/src # Enter the folder
catkin_init_workspace # Initialize the current directory into a ROS workspace
cd .. # Return to the upper directory
catkin_make # Build the code in the workspace.

The structure of catkin is very clear. It includes three paths: src, build, and devel. It may also include others under some compilation options. But these three folders are the default for the catkin compilation system. Their specific functions are as follows:

src/: ROS catkin software package (source code package)

build/: cache information and intermediate files of catkin (CMake)

devel/: Generated target files (including header files, dynamic link libraries, static link libraries, executable files, etc.), environment variables

A simple workspace looks like this:

workspace_folder/ -- WORKSPACE
   src/ -- SOURCE SPACE
     CMakeLists.txt -- 'Toplevel' CMake file, provided by catkin
     package_1/
       CMakeLists.txt -- CMakeLists.txt file for package_1
       package.xml -- Package manifest for package_1
     ...
     package_n/
       CMakeLists.txt -- CMakeLists.txt file for package_n
       package.xml -- Package manifest for package_n

1.2 ROS software package

Package is not only a software package on Linux, but also the basic unit of catkin compilation. The object we use catkin_make to compile is each ROS package.

+--PACKAGE
     +-- CMakeLists.txt
     +-- package.xml
     +-- src/
     +-- include/
     +-- scripts/
     +-- msg/
     +-- srv/
     +-- urdf/
     +-- launch/

• CMakeLists.txt: defines the package name, dependencies, source files, target files and other compilation rules of the package, which is an indispensable component of the package.

• package.xml: describes the package name, version number, author, dependencies and other information, which is an essential component of the package.

• src/: stores ROS source code, including C++ source code (.cpp) and Python module (.py)

• include/: stores the header files corresponding to the C++ source code

• scripts/: stores executable scripts, such as shell scripts (.sh), Python scripts (.py)

• msg/: stores customized format messages (.msg)

• srv/: stores custom format services (.srv)

• urdf/: stores the robot's model description (.urdf or .xacro) and 3D model files (.sda, .stl, .dae, etc.)

• launch/: stores launch files (.launch or .xml)

Create your own package:

• Command format:

The catkin_create_pkg command will ask you to enter package_name. If necessary, you can also add some other dependent software packages later:

catkin_create_pkg <package_name> [depend1] [depend2] [depend3]

• For example:

catkin_create_pkg beginner_tutorials std_msgs rospy roscpp

2 ROS communication architecture

2.1 Master and node

1 Master

Node manager. Each node must register with the master before starting and manage the communication between nodes.

2 roscore

Starting the master will also start rosout (log management) and parameter server (parameter manager)

3 nodes

ROS processes and instances of running executable files in pkg.

$rosrun [pkg_name] [node_name] #Start
$rosnode list #List currently running node information
$rosnode info [node_name] #Display detailed information of a node
$rosnode kill [node_name] #End a node

4 launch

Start the master and multiple nodes.

$roslaunch [pkg_name] [file_name.launch]

2.2 Service and Topic

We provide some services and topics for interacting with mycobot.

1 Service

Enter in the command line:

source ~/catkin_ws/devel/setup.bash #Add environment variables
roslaunch mycobot_320_communication communication_service.launch

Support parameters:

• port: connection serial port string
• baud: baud rate

Open new command line:

# Display active service information
rosservice list

#/get_joint_angles
#/get_joint_coords
#/set_joint_angles
#/set_joint_coords
#/switch_gripper_status
#/switch_pump_status

Related commands and instructions:

2 Topic

Enter in the command line:

source ~/catkin_ws/devel/setup.bash
roslaunch mycobot_320_communication communication_topic.launch

Support parameters:

• port: connection serial port string
• baud: baud rate

Open new command line:

# Display active service information
rostopic list

#/mycobot/angles_goal
#/mycobot/coords_goal
#/mycobot/angles_real
#/mycobot/coords_real
#/mycobot/pump_status
#/mycobot/gripper_status

Related commands and instructions:

The difference between service and topic:

You can go to service and topic to learn more about the use of these two functions

2.3 Introduction to msg and srv

• msg: msg files are simple text files describing ROS message fields. They are used to generate source code for messages in different languages (c++ or python, etc.).
• srv: srv file is used to describe services. It consists of two parts: request and response. msg files are stored in the package's msg directory, while srv files are stored in the srv directory.

1 rosmsg

rosmsg is a command line tool for displaying information about ROS message types.

rosmsg demo:

rosmsg show # Display message description
rosmsg info # Display message information
rosmsg list # List all messages
rosmsg md5 # Display md5 encrypted message
rosmsg package # Display all messages under a certain function package
rosmsg packages # List function packages containing messages

• rosmsg list Will list all msg in current ROS

• rosmsg packages List all packages containing messages

• rosmsg package List all msg under a certain package

//rosmsg package # package name
rosmsg package turtlesim

• rosmsg show Show message description

//rosmsg show # Message name
rosmsg show turtlesim/Pose
# result:
float32 x
float32y
float32 theta
float32 linear_velocity
float32 angular_velocity

• rosmsg info The function is the same as rosmsg show

• rosmsg md5 A verification algorithm to ensure the consistency of data transmission

2 rossrv

rossrv is a command line tool used to display information about ROS service types. The syntax is highly similar to rosmsg.

rossrv show # Display service message details
rossrv info # Display service message related information
rossrv list # List all service information
rossrv md5 # Display md5 encrypted service messages
rossrv package # Display all service messages under a certain package
rossrv packages # Display all packages containing service messages

• rossrv list All srv messages currently in ROS will be listed

• rossrv packages List all packages containing service messages

• rossrv package List all msg under a certain package

//rossrv package # package name
rossrv package turtlesim

• rossrv show Show message description

//rossrv show # Message name
rossrv show turtlesim/Spawn
# result:
float32 x
float32y
float32 theta
string name
---
string name

• rossrv info The function is the same as rossrv show

• rossrv md5 Use md5 verification (encryption) for service data

3 Introduction to URDF

• Unified Robot Description Format, unified robot description format, referred to as URDF. The urdf function package in ROS contains a C++ parser for URDF. The URDF file uses XML format to describe the robot model.
• URDF cannot be used alone and needs to be combined with Rviz or Gazebo. URDF is just a file and needs to be rendered into a graphical robot model in Rviz or Gazebo.

3.1 urdf file description

Code Example:

Here we only intercept part of the code for display:

<?xml version="1.0"?>
<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="firefighter" >

<xacro:property name="width" value=".2" />


   <link name="base">
     <visual>
       <geometry>
        <mesh filename="package://mercury_description/urdf/mercury_a1/base.dae"/>
       </geometry>
       <origin xyz = "0.0 0 0 " rpy = " 0 0 0"/>
     </visual>
     <collision>
       <geometry>
        <mesh filename="package://mercury_description/urdf/mercury_a1/base.dae"/>
         </geometry>
         <origin xyz = "0.0 0 0 " rpy = " 0 0 0"/>
     </collision>
   </link>

   <link name="joint1">
     <visual>
       <geometry>
        <mesh filename="package://mercury_description/urdf/mercury_a1/joint1.dae"/>
       </geometry>
       <origin xyz = "0.0 0 -0.08 " rpy = " 0 0 0"/>
     </visual>
     <collision>
      <geometry>
        <mesh filename="package://mercury_description/urdf/mercury_a1/joint1.dae"/>
       </geometry>
       <origin xyz = "0.0 0 -0.08 " rpy = " 0 0 0"/>
     </collision>
   </link>

   <link name="joint2">
     <visual>
       <geometry>
        <mesh filename="package://mercury_description/urdf/mercury_a1/joint2.dae"/>
       </geometry>
     <origin xyz = "0.0 0 0.0 " rpy = " 3.14159 0 -1.5708 "/>
     </visual>
     <collision>
       <geometry>
        <mesh filename="package://mercury_description/urdf/mercury_a1/joint2.dae"/>
       </geometry>
       <origin xyz = "0.0 0 0.0 " rpy = " 3.14159 0 -1.5708"/>
     </collision>
   </link>

   <joint name="joint1_to_base" type="revolute">
     <axis xyz="0 0 1"/>
     <limit effort = "1000.0" lower = "-3.1066" upper = "3.1066" velocity = "0"/>
     <parent link="base"/>
     <child link="joint1"/>
     <origin xyz= "0 0 0.175" rpy = "0 0 0"/>
   </joint>

   <joint name="joint2_to_joint1" type="revolute">
     <axis xyz="0 0 1"/>
     <limit effort = "1000.0" lower = "-1.4311" upper = "2.2689" velocity = "0"/>
     <parent link="joint1"/>
     <child link="joint2"/>
     <!-- <origin xyz= "0 0 0" rpy = "1.5708 3.14159 0"/> -->
     <origin xyz= "0 0 0" rpy = "-1.5708 0 0"/>
   </joint>

</robot>

It can be seen that the urdf file is not complicated and is mainly composed of two parts: link and joint.

3.2 link section

The link element describes a rigid body with inertia, visual characteristics, and collision properties

3.2.1 Properties

name: A name used to describe the link itself

3.2.2 Elements

• <inertial> (optional)
  • Inertia characteristics of connecting rod
  • <origin> (optional, defaults to identity if not specified)
    • Define the reference coordinates of the inertial reference system relative to the connecting rod coordinate system. This coordinate must be defined at the center of gravity of the connecting rod, and its coordinate axis may not be parallel to the inertial main axis.
    • xyz (optional, defaults to zero vector) Represents the offset in the x, y, z x,y,zx,y,z directions, in meters.
    • rpy(optional: defaults to identity if not specified) Indicates the rotation of the coordinate axis in the RPY direction, in radians.
  • <mass> Quality attributes of connecting rods
  • <inertia> 3×3 rotational inertia matrix, consisting of six independent quantities: ixx, ixy, ixz, iyy, iyz, izz.
• <visual> (optional)
  • Visual properties of connecting rods. Used to specify the shape of the connecting rod display (rectangle, cylinder, etc.). The same connecting rod can have multiple visual elements. The shape of the connecting rod is formed by two elements. In general, if the model is more complex, it can be drawn by Solidwork and then generated STL call. Simple shapes such as adding an end effector can be written directly. At the same time, the position of the geometric shape can be adjusted here according to the gap between the theoretical model and the actual model.
  • <namel> (optional) The name of the connecting rod geometry.
  • <origin> (optional, defaults to identity if not specified)
    • The coordinate system of the geometry relative to the coordinate system of the connecting rod.
    • xyz (optional: defaults to zero vector) Represents the offset in the x, y, z x,y,zx,y,z directions, the unit is meters.
    • rpy (optional: defaults to identity if not specified) Indicates the rotation of the coordinate axis in the RPY direction, in radians.

• <geometry> (required)
  • The shape of the visualization object can be one of the following:
  • <box> Rectangle, elements include length, width, and height. The origin is at the center.
  • <cylinder> Cylinder, elements include radius and length. Origin center.
  • <sphere> Sphere, element contains radius. The origin is at the center.
  • <mesh> The grid is determined by the file, and a scale is provided to define its boundaries. It is recommended to use Collada .dae file. .stl file is also supported, but it must be a local file.
• <material> (optional)
  • Visualize component materials. It can be defined outside the link tag, but it must be within the robot tag. When defined outside the link tag, the name of the link must be quoted.
  • <color>(optional) Color, consisting of red/green/blue/alpha, with size in the range [0,1].
  • <texture>(optional) Material properties, defined by file.

• <collision> (optional)
  • Collision properties of connecting rods. Collision properties are different from the visual properties of links, and simple collision models are often used to simplify calculations. The same link can have multiple collision attribute labels, and the link's collision attribute representation is composed of the set of geometries it defines.
  • <name> (optional) Specifies the name of the connecting rod geometry
  • <origin> (optional, defaults to identity if not specified)
    • The reference coordinate system of the collision component is relative to the reference coordinate system of the link coordinate system.
    • xyz (optional, default zero vector) Represents the offset in the x, y, z x,y,zx,y,z directions, the unit is meters.
    • rpy (optional, defaults to identity if not specified) Indicates the rotation of the coordinate axis in the RPY direction, in radians.
  • <geometry> Same as the geometry element description above

Detailed elements and the functions of each element can be viewed in Official Documents

3.3 joint part

The joint section describes the kinematics and dynamics of the joint and specifies the joint's safety limits.

3.3.1 Properties of joint:

name:

Specify a unique name for the joint

type:

Specifies the type of joint, where type can be one of the following:

• revolute - A hinge joint that rotates along an axis, the range of which is specified by upper and lower limits.
• Continuous - A continuous hinge joint that rotates about an axis with no upper and lower limits.
• Prismatic - A sliding joint that slides along an axis, the range of which is specified by upper and lower limits.
• Fixed - This is not a true joint as it cannot move. All degrees of freedom are locked. This type of joint does not require axes, calibration, dynamics, limits or safety_controller.
• Float - This joint allows movement in all 6 degrees of freedom. +Plane - This joint allows movement in a plane perpendicular to the axis.

3.3.2 Elements of joint

• <origin> (optional, defaults to identity if not specified) In the transformation from parent link to child link, the joint is located at the origin of the child link. Modifying this parameter can adjust the position of the connecting rod. It can be used to adjust the error between the actual model and the theoretical model. However, it is not recommended to modify it significantly because this parameter affects the connecting rod stl. The position can easily affect the collision detection effect.

  • xyz (optional: defaults to zero vector) Represents the offset in the x, y, z x,y,zx,y,z axis direction, unit meter.
  • rpy (optional: defaults to zero vector) Represents the angle of rotation around a fixed axis: roll around the x-axis, pitch around the y-axis, and yaw around the z-axis, expressed in radians.

• <parent> (required)

  • The name of the parent link is a mandatory attribute.
  • link The name of the parent link is the name of this link in the robot structure tree.

• <child> (required)

  • The name of the child link is a mandatory attribute.
  • link The name of the child link is the name of this link in the robot structure tree.

• <axis>(optional: default is (1,0,0))

  • The axis of the joint is in the coordinate system of the joint. This is the axis of rotation (revolute joint), the axis of movement of the prismatic joint, and the standard plane of the planar joint. This axis is specified in the joint coordinate system. Modifying this parameter can adjust the axis around which the joint rotates. It is often used to adjust the direction of rotation. If the rotation direction of the model is opposite to the actual direction, just multiply by -1. Fixed and floating joint types do not need this element. +xyz(required) Represents the x, y, z x,y,zx,y,z components of the axis vector, which are normalized vectors.

• <calibration> (optional)

  • The reference point of the joint, used to correct the absolute position of the joint.
  • rising (optional) When the joint moves forward, the reference point triggers a rising edge.
  • falling (optional) When the joint moves forward, the reference point triggers a falling edge.

• <dynamics>(optional)

  • This element is used to specify the physical properties of the joint. Its value is used to describe the joint's modeling performance, especially during simulation.

<limit> (required when the joint is a rotation or translation joint)

• This element is a joint kinematics constraint.
• lower (optional, default 0) An attribute that specifies the lower bound of the joint's motion range (the unit for a revolute joint is radians, and the unit for a prismatic joint is meters). This attribute is ignored for continuous joints.
• upper (optional, default 0) An attribute that specifies the upper limit of the joint's motion range (the unit for a revolute joint is radians, and the unit for a prismatic joint is meters). This attribute is ignored for continuous joints.
• effort (required) This property specifies the maximum force when the joint is running.
• velocity (required) This property specifies the maximum speed at which the joint runs.

<mimic>(optional)

• This tag is used to specify a defined joint to mimic an existing joint. The value of this joint can be calculated using the following formula: value = multiplier * other_joint_value + offset
• joint(required) The name of the joint to be imitated.
• multiplier(optional) Specify the multiplier factor in the above formula.
• offset(optional) Specify the offset term in the above formula. The default value is 0

<safety_controller> (optional)

• This element is a security control restriction. The data under this element will be read into move_group, but it is actually invalid. Move_group will skip the restriction here and directly read the parameter content under limit. At the same time, setting this element may cause planning fail.
• soft_lower_limit (optional, default 0) This attribute specifies the lower bound of the joint safety control boundary, which is the starting limit point of joint safety control. This value needs to be greater than the lower value in the above limit.
• soft_upper_limit (optional, default 0) This attribute specifies the upper bound of the joint safety control boundary, which is the starting limit point of joint safety control. This value needs to be less than the upper value in the above limit.
• k_position (optional, default 0) This attribute is used to describe the relationship between position and velocity.
• k_velocity (required) This property is used to describe the relationship between force and velocity.

Detailed elements and the role of each element can be viewed at http://wiki.ros.org/urdf/XML/joint

4 Commonly used command tools

In ROS, there are many commonly used command line tools, which can help you develop, debug, manage ROS nodes, etc. The following are some commonly used ROS command line tools:

4.1 Compile workspace

caktin_make

4.2 roscore

Start the ROS master node. Before running a ROS node, you usually need to start roscore first

roscore

4.3 rosrun

Run the specified ROS node.

rosrun package_name node_name

4.4 roslaunch

Use the Launch file to start one or more ROS nodes.

roslaunch package_name launch_file.launch

4.5 rosnode

View running ROS node information.

rosnode list
rosnode info node_name

4.6 rostopic

View information about running ROS topics.

rostopic list
rostopic echo topic_name

4.7 rosservice

View and call ROS services.

rosservice list
rosservice call service_name

4.8 rosparam

Get and set ROS parameters.

rosparam get parameter_name
rosparam set parameter_name value

4.9 rosmsg

View ROS message types.

rosmsg show message_type

4.10 rosdep

Install dependencies of ROS packages.

rosdep install package_name

4.11 Environment variables

View the ROS_PACKAGE_PATH environment variable

echo $ROS_PACKAGE_PATH

← Previous page | Next page →