../_images/tiagopro-icon.png ../_images/tiago-head-icon.png ../_images/kangaroo-icon.png ../_images/tiago-icon.png ../_images/triago-icon.png ../_images/ari-icon.png ../_images/talos-icon.png ../_images/mobile-bases-icon.png

The startup process of the robot and application management

This page explains which applications are started during the boot process of the robot, how to start/stop/restart them, and how to configure the boot process.

The boot process

When the robot boots up, the software required for its operation starts automatically. The startup process can be monitored in the Web user interface.

The startup manager will search for ROS packages in the specified directories. If a package is found in one of the directories, it will ignore the same package in the directories that come after it in the list.

Adding a new workspace

To change the workspace source procedure, for example to add a new ROS workspace, the file at /usr/bin/init_pal_env.sh can be modified to adapt the environment of the startup process.

The PAL Module Manager

The PAL Module Manager is the process that manages the startup of the robot and defines which applications are started. This is done with Modules and Module sets. A Module defines how an application is launched. A Module set defines which of these modules are launched on startup.

Modules

A module represents an execution unit plus some parameters that detail how to and when to run it, also the expected outcome may be specified. Modules are set up using yaml files.

Three ways of running applications are supported. This is the only mandatory module parameter and only one may be specified.

  • run: Executes ROS 2 nodes. Works in the same way as the command ros2 run.

  • launch: Executes ROS 2 launch files. Works in the same way as the command ros2 launch.

  • exec: Executes commands directly.

Module states

Modules can be in different states:

  • LOADED: Module is loaded and ready to start.

  • WAITING: Module has been started but it is waiting for dependencies.

  • RUNNING: Module is loaded and running.

  • FINISHED: Module finished execution on its own. This was an expected outcome.

  • TERMINATED: Module was stopped and ended execution by sending termination signal.

  • KILLED: Module was stopped but fails to end execution, it was force stopped with a kill signal.

  • CRASHED: Module ended execution unexpectedly.

Module parameters

There are additional optional parameters that can be used to modify the behavior of the module.

  • after: Do not start the module until the specified modules are running. Empty by default.

  • waits: Wait until the specified modules are finished in order to start the module. The modules specified in this field must set the parameter finishes: True. Empty by default.

  • dependencies: A list of diagnostics the module will wait for to be ready, i.e., in OK or WARN status. Once all dependencies are ready the module can start. Empty by default.

  • finishes: Specify whether a module is expected to finish execution on it own once started. False by default.

  • termination_timeout: Modules are stopped by sending a termination signal. This parameter sets the amount of time to wait before sending a kill signal when trying to stop a module. Five seconds by default.

  • enable_unbuffer: Whether unbuffering is enabled. Applications normally don’t print their output until it reaches certain amount of bytes then the log is dumped all at once. Unbuffering means any output is printed as soon as it is generated. For logging purposes this is usually preferred. True by default.

  • enable_multilog: Used for log rotation, i.e., the log file is switched after is reaches certain size. Useful for applications that are expected to log large amounts of data. Otherwise, all data is logged to one huge, and potentially infinite, file. For logging purposes, rotation is usually preferred. True by default.

Module example

As mentioned before, modules are specified in yaml files. An example file for a module is shown below:

foo_module:
  run: "foo_package foo_node"

Multiple modules per yaml file can be specified.

foo_module:
  run: "foo_package foo_node"
bar_module:
  launch: "bar_package bar.launch.py"
  dependencies: ["Foo Feature"]

The modules can make use of the robot info parameters to make them more generic. These parameters are kept by the robot_info_publisher node. Use @parameter_name@ and the Module Manager will do the replacement at runtime. The play_motion2 module is a good example:

play_motion2:
  launch: "@robot_type@_bringup @robot_type@_play_motion2.launch.py
          arm_type:=@arm_type@
          base_type:=@base_type@
          end_effector:=@end_effector@
          ft_sensor:=@ft_sensor@"

Modules sets

Module sets define which modules are started when starting the robot. Just like modules, module sets are defined in yaml files. Sets are just a list of modules.

Here is a sample for a simple module set yaml file:

my_set:
  - foo_module
  - bar_module

Multiple module sets per yaml file can be specified.

my_set:
  - foo_module
  - bar_module
my_other_set:
  - my_module

Virtual groups

Virtual groups define a group of modules that can be managed as a group. Just like module sets, virtual groups are set up using yaml files, are just a list of modules.

The key difference with module sets is that they define modules that are started automatically, while virtual groups allow you to manage the group of modules as a single unit.

Here is a sample for a simple vitual group yaml file:

my_virtual_group:
  - foo_module
  - bar_module

Startup customization

The startup process can be customized by registering new modules and module sets. Registering the module is done in the CMakeLists.txt of a ROS package. For a detailed instruction on how to create new modules and module sets see the tutorial Configure an application to launch at start-up. This tutorial also explains how to modify existing modules and module sets.

find_package(pal_module_cmake QUIET)

# Registering a module
if(pal_module_cmake_FOUND)
  pal_register_modules(
    module/my_custom_module.yaml
  )
endif()

# Registering a module set
if(pal_module_cmake_FOUND)
  pal_register_module_sets(
    module/my_custom_module_set.yaml
  )
endif()

# Registering a virtual group
if(pal_module_cmake_FOUND)
  pal_register_virtual_groups(
    module/my_custom_virtual_group.yaml
  )
endif()

Startup command line tools

To interact with the Module Manager there are command line interfaces available. The commands are listed below.

Module commands:

  • pal module list: This command will list all the modules that are loaded in the robot.

  • pal module info <module-name>: This command will print information about the selected module. Pressing TAB will list the modules whose information can be seen.

  • pal module show <module-name>: This command will print the content of the selected module. Pressing TAB will list the modules whose content can be seen.

  • pal module start <module-name>: This command will start a module in the robot. Pressing TAB will list the applications that can be started.

  • pal module stop <module-name>: This command will stop a module in the robot. Pressing TAB will list the applications that can be stopped.

  • pal module restart <module-name>: This command will restart a module in the robot. Pressing TAB will list the applications that can be restarted.

  • pal module log <module-name>: This command will print the name and path of the log file of the selected application. Pressing TAB will list the applications whose log can be seen. Using the command pal module log <module-name> cat, will directly print the log file.

  • pal module enable <module-name>: This command will enable a module in the robot, so it will be run in the next start of the module manager. This does not immediately start the module (use pal module start to this end). Pressing TAB will list the applications that can be enabled.

  • pal module disable <module-name>: This command will disable a module in the robot, so it will not be run in the next start of the module manager. This does not immediately stop the module (use pal module stop to this end). Pressing TAB will list the applications that can be disabled.

Module set commands:

  • pal module_set list: This command will list all the module sets that are loaded in the robot.

  • pal module_set info <module-set-name>: This command will show practical information about the selected module set. Pressing TAB will list the module sets whose information can be seen.

  • pal module_set show <module-set-name>: This command will show the content of the file that defines the selected module set. Pressing TAB will list the module sets whose content can be seen.

Virtual group commands:

  • pal virtual_group list: This command will list all loaded modules along with their current status in each virtual group.

  • pal virtual_group status <virtual-group-name>: This command will print all loaded modules along with their current status in a virtual group. Pressing TAB will list the virtual groups whose status can be seen.

  • pal virtual_group info <virtual-group-name>: This command will print information about a virtual group. Pressing TAB will list the virtual groups whose information can be seen.

  • pal virtual_group show <virtual-group-name>: This command is used to display the content of the file that defines a virtual group. Pressing TAB will list the virtual groups whose content can be seen.

  • pal virtual_group start <virtual-group-name>: This command will start all modules in a virtual group. Pressing TAB will list the virtual groups that can be started.

  • pal virtual_group stop <virtual-group-name>: This command will stop all modules in a virtual group. Pressing TAB will list the virtual groups that can be stopped.

  • pal virtual_group restart <virtual-group-name>: This command will restart all modules in a virtual group. Pressing TAB will list the virtual groups that can be restarted.

  • pal virtual_group enable <virtual-group-name>: This command will enable a virtual group, so all the modules in this virtual group will be started when the module manager starts. Pressing TAB will list the virtual groups that can be enabled.

  • pal virtual_group disable <virtual-group-name>: This command will disable a virtual group, so all the modules in this virtual group will not be started when the module manager starts. Pressing TAB will list the virtual groups that can be disabled.

Module Manager commands:

  • pal module_manager start: This command will start the module manager.

  • pal module_manager stop: This command will stop the module manager.

  • pal module_manager restart: This command will restart the module manager.

  • pal module_manager enable: This command will enable the module manager. It will be started on boot.

  • pal module_manager disable: This command will disable the module manager. It will not be started on boot.

Caution

Disabling the module manager will prevent the robot from starting the applications on boot. This is not recommended.

  • pal module_manager status: This command will show the current status of the service that manages module manager.

  • pal module_manager log: This command will show the logs of the module manager.

Note

This module manager commands are convenience wrappers around the systemctl and journalctl calls.

Module Manager ROS API

The command line interface uses services provided by the Module Manager to interact with it. These services are available in the Module Manager node namespace. Below is a list of all the available services.

See also