Generators

Part of the appeal of using the robot YAML configuration file is that it allows us to generate the necessary files to operate the robot at runtime. There are 4 types of files that need to be generated: bash shell scripts, URDF description files, launch files, and parameter files. Each file type has a generator which will use the Clearpath Config to figure out which files need to be created, and what the contents should be. Each generator also has a writer class which contains methods for writting formatted lines specific to the file type.

note

Generator scripts do not need to be modified by the user. Rather the user should modify their robot YAML file to suit their needs.

Bash

The main bash script that needs to be generated is the setup.bash file. This file will source the Humble setup.bash, as well as any additional workspaces. It will also contain environment variables for setting up ROS 2. This file will be sourced by the robot_upstart job, as well as the user terminal. This way we can ensure that the bash environment of the upstart jobs matches the user's.

Description

The description generator will generate a robot.urdf.xacro file which will define the robot. By parsing the robot YAML file, we can determine which platform the robot is using, as well as which mounts, accessories, and sensors will need to be added on top of the platform. This URDF file will later be used with the robot state publisher to publish all of the static transforms that make up the robot.

Semantic Description

The semantic description generator will generate a robot.srdf.xacro and robot.srdf files with will define all manipulator groups, manipulator poses, and link collisions. By default, MoveIt! planners will check all links in the description to ensure collision free paths. If there are several links with complicated geometries, this will be a slow process. Therefore, the generator uses the collision matrix updater to disable the collisions of all links out of range of the manipulator groups defined and minimize the planning time.

Launch

The launch generator creates ROS 2 python launch files. It will create both the platform and sensor launch files by parsing the robot config. Typically, the generated launch file will include a default launch file, and pass in launch arguments as appropriate. Python classes have been defined for adding other launch files, nodes, and processes to the generated launch file, making it intuitive to use.

Parameter

The parameter generator creates .yaml ROS parameter files that are used by the corresponding launch file. Each node has default parameters set that the user can overwrite by setting them in the robot configuration YAML.

Platform Generation

By running the bash, description, launch, and parameter generators, the launch file and all necessary configuration files to run the platform nodes are created in the directory /etc/clearpath/platform. The top level launch file to start all platform related nodes is the platform-service.launch.py, which is generated in the /etc/clearpath/platform/launch directory by the launch generator. Each Clearpath platform robot has its own configuration files, but ultimately all parameter files generated in the same directory and the launch procedure is the same for every platform.

Sensors Generation

Using the parameter and launch file generators, a pair of files is created for each sensor defined in the configuration file. Each sensor is enumerated given its order in sensor section of the robot.yaml. For example, if two cameras are added, then the first will be named camera_0 and the second camera_1, irrespective of the model of camera. Each sensor launch file generated is included in the top level sensors-service.launch.py which is ran by the service.

Manipulation Generation

Using the semantic_description, launch, and parameter file generators, all MoveIt! parameter and launch files are generated with the appropriate namespace. The semantic generator creates a xacro file that is then parsed by the collision updater to generate a static file with all unecessary link collision disabled. The parameter generator parses the default parameters and generates a single moveit.yaml parameter file that contains all MoveIt! parameters and is namespaced accordingly.

Setup folder structure

Once all files are generated, the resulting setup folder structure under /etc/clearpath/ will look like this:

• manipulators
  • launch
    • manipulators-service.launch.py
  • config
    • moveit.yaml
• platform
  • launch
    • platform-service.launch.py
  • config
    • control.yaml
    • imu_filter.yaml
    • localization.yaml
    • teleop_interactive_markers.yaml
    • teleop_joy.yaml
    • twist_mux.yaml
• sensors
  • launch
    • sensors-service.launch.py
    • camera_0.launch.py
    • camera_1.launch.py
    • ...
  • config
    • camera_0.yaml
    • camera_1.yaml
    • ...
• robot.srdf
• robot.srdf.xacro
• robot.urdf.xacro
• robot.yaml
• setup.bash