../_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

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()

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.

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#