The robot’s start-up process and application management#

Caution

This page only applies to ROS 1

This page explains which services (ROS nodes) are started during the robot’s boot process, 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 WebCommander, as shown in the figure below:

The start-up manager will look for ROS packages in the following directories in order to execute them. If a package is found in one of the directories, it will not be looked for any further on directories lower in the list.

/home/pal/deployed_ws (this is where your own code is stored. See Tutorial: Deploying ROS packages on the robot to know more)
/opt/pal/gallium
/opt/ros/noetic

Adding a new workspace#

In case where the workspace resolution process needs to be changed, the file at /usr/bin/init_pal_env.sh can be modified to adapt the environment of the startup process.

Start-up configuration files#

The nodes to be launched at start-up are defined from startup definitions stored in ~/.pal/pal_startup or /opt/pal/gallium/share/pal_startup_base/config. ~/.pal/pal_startup takes precedence: you can add here custom startup definitions to change the default behaviour of the robot.

The startup definitions are YAML files that are loaded as ROS parameters during the robot’s start-up.

There are two classes of files:

configuration files that describe how to start each ROS node (the apps files),
files that determine which applications must be started for each computer on the robot (the start-up lists).

These files are located in the pal_startup_base package’s share/config directory. User-specific ones can be added as well to ~/.pal/pal_startup (see Configure an application to launch at start-up to learn more).

Application files#

Each application/service that has to be launched at start-up needs a corresponding apps/<service>.yaml.

For example, /opt/pal/gallium/share/pal_startup_base/config/apps/touch_web.yaml contains a YAML description on how to start the application touch_web, that manages the touchscreen of the robot:

roslaunch: "pal_touch_web_display touch_display.launch"
dependencies: ["Functionality: Startup control: pal_chrome"]
finishes: True

The required attributes are:

One of roslaunch, rosrun or bash: used to determine how to start the application. The value of roslaunch, rosrun or bash is the rest of the commands that you would use in a terminal (you can use bash magic inside, such as rospack find my_cfg_dir). There are also some keywords that are replaced by the robot’s information in order to make scripts more usable. @robot@ is replaced by the robot name as used in our ROS packages (ie REEMH3 is reem, REEM-C is reemc, ARI is ari…)
dependencies: a list of dependencies that need to be running without error before starting the application. Dependencies can be seen in the WebCommander Diagnostics Tab. If an application has no dependencies, it should be set to an empty list [].

Optional attributes:

timeout: applications whose dependencies are not satisfied after 10 seconds are reported as an error. This timeout can be changed with the timeout parameter.
auto_start: Determines whether this application must be launched as soon as its dependencies are satisfied, if not specified defaults to True.

Examples:

apps/localizer.yaml:

roslaunch: "@robot@_2dnav localization.launch localization:=orb"
dependencies: ["Functionality: Mapper", "Functionality: Odometry", "Hardware: Torso Front RGBD"]

apps/web_commander.yaml:

rosrun: "pal_webcommander web_commander.sh"
dependencies: []

Start-up lists#

The other type of YAML configuration files are lists that determine what to start for each robot’s computer. They are placed within the config/ directory, in a sub-directory named after the hostname that should start them, for instance control for the default computer in all of PAL Robotics’ robots, or multimedia for robots with a dedicated multimedia computer. We call these subdirectories groups.

Note

On ARI, only the control group is available.

Each directory contains one or several YAML lists with the name of the applications to start (ie, their apps/ YAML filename).

Examples:

control/core.yaml:

# Core
- ros_bringup
- diagnostic_aggregator
- web_commander

# Deployer
- deployer

# Utilities
- computer_monitor_control
- remote_shell_control
- rosbridge
- ros_topic_monitor
- diagnostic_reporter

# Statistics
- statsdcc

Additional startup groups#

Besides the control and multimedia groups for robots that have more than one computer, additional directories can be created in the config directory at the same level as the control directory.

These additional groups are typically used to group together different applications in a separate tab in the WebCommander, such as the Startup Extras optional tab.

A startup_manager pal_startup_node.py instance is required to handle each startup group.

For instance if a group called interaction_demo is needed to a manage the nodes of a grasping demo started in the control computer, a directory will have to be created called interaction_demo containing at least one start-up list (.yaml file) as described in the previous section.

Additionally it is recommended that we add to the control own startup list a new application (in apps/) that will start the startup manager of the interaction_demo so it is available from the start:

apps/interaction_demo.yaml:

rosrun: "pal_startup_manager pal_startup_node.py interaction_demo"
dependencies: []

Customise how an application is launched#

To modify how the application eg touch_web is launched, copy the contents from the original touch_web.yaml file from the pal_startup_base package to /home/pal/.pal/pal_startup/apps/ and modify it as desired.

This new file will take precedence over the system-installed one.

Start-up ROS API#

Each start-up node can be individually controlled using a ROS API that consists of the following services, where {startup_id} must be substituted for the name of the corresponding startup group (ie control, multimedia, interaction_demo, etc.).

service /pal_startup_{startup_id}/start
- Arguments are app (name of the application as written YAML files for the application start configuration files), and
- args (optional command line arguments).
- Returns a string indicating if the app was started successfully.
service /pal_startup_{startup_id}/stop
- Arguments are app (name of the application as written YAML files for the application start configuration files).
- Returns a string containing if the app was stopped successfully.
service /pal_startup_{startup_id}/get_log
- Arguments are app (name of the application as written YAML files for the application start configuration files), and
- nlines (number of lines of the log file to return).
- Returns up to the last nlines of logs generated by the specified app.
service /pal_startup_{startup_id}/get_log_file
- Arguments are app (name of the application as written YAML files for the application start configuration files).
- Returns the path of the log file of the specified app.

Start-up command line tools#

pal-start: This command will start an application in the background of the computer it is executed on, if it is stopped. Pressing TAB will list the applications that can be started.
pal-stop: This command will stop an application launched via pal_startup in the computer it is executed on, if it is started. Pressing TAB will list the applications that can be stopped.
pal-restart: This command will start and stop an application launched via pal_startup in the computer it is executed on, if it is started. Pressing TAB will list the applications that can be restarted.
pal-log: 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.

Startups are shown in the Startup tab of the WebCommander.

The same results of above commands is achieved by pressing the right buttons of each startup, e.g. Show log corresponds to pal-log, Stop or Start buttons correspond to pal-start or pal-stop.

Example to stop a startup app from the terminal window:

ssh pal@<robot>-0c

pal-stop pal_interaction_profiles

Notice how in the WebCommander, the pal_interaction_profiles startup is orange, indicating it was stopped under user request. Start it again and visualize the logs:

pal-start pal_interaction_profiles

pal-log pal_interaction_profiles tail -f

This is a useful tool to debug potential issues of the robot.

The robot’s start-up process and application management#

The boot process#

Adding a new workspace#

Start-up configuration files#

Application files#

Start-up lists#

Additional startup groups#

Customise how an application is launched#

Start-up ROS API#

Start-up command line tools#

See also#