Creating a Hardware Package

For convenience, a hardware package should be created to launch the drivers for an arm or arm group. This consists of:

• A ROS launch file which launches the manipulator drivers and then the Armer drivers

• A yaml configuration file which sets runtime parameters such as the model being launched and the type of backend

These files are packaged togther as a hardware package. To skip to folder structure and naming convention, see the Putting it All Together section of this guide.

Examples of hardware packages can be seen with the armer_panda or the armer_ur packages.

Note

At this point in time, only manipulators with joint velocity controllers are supported by Armer. If an arm does not support this, it cannot be used with Armer.

Creating a Launch File

This is a ROS launch file which starts the manipulator’s drivers as well as the Armer driver. This is achieved by combining the contents of the ROS driver launch file with the armer.launch file found in the Armer driver package.

1. If they have not already been installed, install the ROS drivers for the manipulator. This can generally be done by googling {ROBOT_MODEL} ROS drivers and following their readme instructions.

2. After the drivers have been installed to the relevant workspace, read the ROS driver’s documentation to find the launch file that starts the driver.

   This launch file usually will start the driver node and joint controllers. The launch file sections relevant to starting these should be copied over (or included) into the template below and the file should be named robot_bringup.launch:

   <?xml version="1.0" ?>
   <launch>
       <arg name="config"/>
       <arg name="sim" default="false" />
   
       <!-- Physical Robot -->
       <group unless="$(arg sim)">
   
           <!-- Manipulator driver -->
           <!--INCLUDE OR COPY THE CONTENTS OF THE MANIPULATOR'S ROS DRIVER LAUNCH FILE HERE -->
   
           <!-- Launch armer driver -->
           <include file="$(find armer)/launch/armer.launch">
               <arg name="config" value="$(arg config)" />
           </include>
       </group>
   
       <!-- Simulated Robot -->
       <group if="$(arg sim)">
           <include file="$(find armer)/launch/armer.launch">
               <arg name="config" value="$(arg config)" />
           </include>
       </group>
   </launch>
   

Creating a Configuration File

To configure parameters such as if Armer is interfacing with a simulation or a physical arm, a yaml config file should be created.

Armer uses the Robotics Toolbox to perform calculations and this config file will point to the Robotics toolbox ERobot object so movement can be processed. If the manipulator does not have an existing RTB model or if unsure, see Creating a Robotics Toolbox model.

Create a config for launching the physical robot backend using the following as an example template and saved as {ROBOT_MODEL}_{BACKEND_MODE}.yaml where backend mode is “real” for a physical robot config and “sim” for a Swift sim robot:

robots:
- name: {DESIRED_ROBOT_NAMESPACE}
    model: roboticstoolbox.models.{ROBOTIC_TOOLBOX_MODEL_NAME}
backend:
    type: {DESIRED_BACKEND_TYPE}

Most parameters can be left as defaults, but these are the essential parameters that should be changed for basic functionality.

Key configuration parameters

Field Name	Description	Example	Default
name	namespace to be used	“my_cool_robot”	None
model	robotics toolbox model to use	roboticstoolbox.models.Panda	None
backend	backend to be used	roboticstoolbox.backends.swift.Swift	None

The two current options for backend are:

• roboticstoolbox.backends.swift.Swift (Swift simulation robot)

• armer.backends.ROS.ROS (Physical robot)

Multiple robots can be launched at a time and parameters for each individual instance can be set under the corresponding namespace. For example:

robots:
- name: panda
    model: roboticstoolbox.models.Panda
    origin: [0, 0, 0, 0, 0, -1]
- name: ur5
    model: roboticstoolbox.models.UR5
    origin: [-1, 0, 0, 0, 0, 0]
backend:
- type: roboticstoolbox.backends.swift.Swift

In this example, a Panda and a UR5 arm are being launched with different origin settings. The options for each different robot section is signaled with the - symbol before the name parameter.

The following parameters are available for setting in multi or single robot operations.

Robot parameters

Field Name	Description	Example	Default
joint_state_topic	topic to listen to joint states on	“/my_joint_states”	“/joint_states”
joint_velocity_topic	topic to listen to velocity on	“/my_controller/joint_velocity”	“/joint_group_velocity_controller/command”
origin	set a different origin for the robot	[-1, 0, 0, 0, 0, 0]	[0, 0, 0, 0, 0, 0]
gripper	specify the end effector link	“tool0”	None
logging: frequency	sets the frequency of logging	false	None

Certain arms (such as the UR3) have multiple end effectors so specifying the link must be done by adding a “gripper” field to the robots section with the link name as a string.

The joint_state_topic and joint_velocity_topic are how Armer gets feedback and controls the manipulator via the ROS drivers. If the ROS drivers do not map to the Armer defaults of /joint_states and /joint_group_velocity_controller/command, the topics will need to be specified.

Putting it All Together

For ease of deployment and use, the launch and config file should be packaged into a ROS package. The overall file structure is as follows:

armer_{ROBOT_MODEL}/
    ├─ launch/
    │   ├─ robot_bringup.launch
    ├─ cfg/
    │   ├─ {ROBOT_MODEL}_{BACKEND_MODE}.yaml

1. The name of the package should be armer_{ROBOT_MODEL}.

2. The launch file should be placed in the armer_{ROBOT_MODEL}/launch directory.

3. Relevant config files should be placed in armer_{ROBOT_MODEL}/cfg.

4. The package can be created by running catkin_create_pkg armer_{ROBOT_MODEL}/ in the directory above armer_{ROBOT_MODEL}.

5. The package can be built by running catkin_make in the main workspace directory

6. If all has gone well, the ROS drivers and the Armer drivers should be started after running:

   roslaunch armer_{ROBOT_MODEL} robot_bringup.launch config:={PATH_TO_CONFIG_YAML_FILE} sim:={true/false}
   

Note

For further details on creating a ROS package see http://wiki.ros.org/ROS/Tutorials/CreatingPackage.