RV2 Package Launcher Management

File Tree

• rv2_startup

  rv2_startup
  ├── content
  │   ├── scripts
  │   │   ├── cyclonedds.xml
  │   │   ├── run-internet-check.sh
  │   │   └── run-network-check.sh
  │   └── packages.yaml (generated by `update-repo-list`)
  ├── launch
  │   ├── scripts
  │   │   ├── <package_name>_<id> (generated by `create`)
  │   │   │   ├── .config (if package uses `config_file` instead of `params_file`)
  │   │   │   ├── cyclonedds.xml (generated by `create-service`)
  │   │   │   ├── params.yaml
  │   │   │   ├── system.yaml
  │   │   │   └── ...
  │   │   └── ...
  │   └── services
  │       ├── rv2_startup_<package_name>_<id>.service (generated by `create-service`)
  │       └── ...
  ├── log
  │   └── <YYYY_MM_DD>.log (generated by `setup.sh`)
  ├── setup.sh
  ├── config.yaml (Grab from FTP server)
  └──README.md
  

• RV2 Package Structure

  rv2_ros2_ws (ROS2 workspace)
  ├── src
  │   ├── <rv2_package>
  │   │   ├── include/<package_name>
  │   │   │   └── ...
  │   │   ├── launch
  │   │   │   └── launch.py
  │   │   ├── params (or config)
  │   │   │   ├── params.yaml
  │   │   │   └── system.yaml (optional)
  │   │   ├── scripts
  │   │   │   ├── custom.sh (optional)
  │   │   │   ├── script_after_build.sh (optional)
  │   │   │   ├── script_before_build.sh (optional)
  │   │   │   └── source_env.sh (optional)
  │   │   ├── src
  │   │   │   └── ...
  │   │   ├── CMakeLists.txt
  │   │   ├── package.xml
  │   │   ├── requirements_apt.txt (optional)
  │   │   ├── requirements_pip.txt (optional)
  │   │   └── ...
  │   └── ...
  └── ...
  

  NOTE: If the package is a non-launchable package, the launch and params directories will not be used.

  NOTE: If the package is a non-launchable package, the custom.sh and source_env.sh scripts will not be used.

  NOTE: If the package use config instead of params directory, the .config file will be generated in the package launcher directory, and the and ros2 launch command will use the config_file argument instead of params_file.

• Global Packages

  Now the package launcher support the global packages that follows the rv2_package structure. The global packages usually placed in the /opt/ros/${ROS_DISTRO}/shared directory.

  NOTE: The global packages will not be built by the build command.

  WARNING: User should avoid using same package name in the global packages and the ROS2 workspace.

• Non-launchable Packages

  The non-launchable packages may be the interface packages that contains ROS2 interfaces such as msg, srv etc., or component packages for nodes. The non-launchable packages can be create and build but not create-service since the packages are not a launchable package.

  To create a non-launchable package or component, add the --pkg-no-launch flag to the command. The created directory will be empty.

  NOTE: If --pkg-no-launch provided, the--pkg-id flag is not required, and the package launcher name will be <package_name>_nolaunch.

Terminology

• Package Launcher: A package launcher is a directory that contains the params.yaml and system.yaml files. The package launcher is used to manage the ROS2 package and the service. The package launcher name should be composed of the package name and the ID: <package_name>_<id>.

• Service: A systemd service file that manages the package launcher. The service file name should be composed of the package name and the ID: rv2_startup_<package_name>_<id>.service.

• Package Name: A ROS2 package name defined in the package.xml. should be under the repository directory.

• Repository Name: A repository directory name. A repository directory contains one or more ROS2 packages.

Quick Start

Prerequisites

• OS: Ubuntu 22.04
• ROS2: Humble

Installation

• Setup the environment using curl

  curl -fsSL ftp://61.220.23.239/rv2-example/deploy.sh | bash

  The package will be installed in ${HOME}/rv2_startup.

• Setup the environment using git

  1. Install required packages

     sudo apt update
     sudo apt install -y python3-yaml

  2. Clone the repository

     git clone https://github.com/cocobird231/rv2_startup.git ${HOME}/rv2_startup

  3. Grab config.yaml

     wget -O ${HOME}/rv2_startup/config.yaml ftp://61.220.23.239/rv2-example/config.yaml

  WARNING: The rv2_startup directory should be placed in the home directory.

Usage

First Time Setup

1. Config the config.yaml file in ${HOME}/rv2_startup. Set the ROS2_WS_PATH to the ROS2 workspace path. If FTP server is used, set the FTP_SERVER_PATH and FTP_SERVER_REPO_VERSION properly.

   # config.yaml
   ENVIRONMENT_SETUP:
       ROS2_WS_PATH: "~/rv2_ros2_ws"
       FTP_SERVER_PATH: ""
       FTP_SERVER_REPO_VERSION: ""

2. Update the repository list from the FTP server. (Optional)

   . setup.sh update-repo-list

3. Update the repositories under the ROS2 workspace source directory. (Optional)

   . setup.sh update-repos

Create a Package Launcher

The package launcher name should be composed of the package name and the ID: <package_name>_<id>. The <package_name> is the ROS2 package name defined in the package.xml, and the <id> is the unique ID of the package launcher.

1. Create a new package launcher.

   . setup.sh create --pkg-name <package_name> --pkg-id <id>

   The package launcher directory <package_name>_<id> will be created in the rv2_startup/launch/scripts, and the files under repository params directory will be copied to the package launcher directory.

   NOTE: If the package is not for launch, add the --pkg-no-launch flag to the command. The created directory will be empty.

2. Config the system.yaml file in the package launcher directory. Set the network field properly.

   # system.yaml
   launch:
       params: "params.yaml"
       launch: "launch.py"
       use_root: false
   
   network:
       interface: "eth0"
       internet_required: false

   The interface should be the network interface that the program will use. If internet_required set to true, the program will check the internet connection before starting the program.

   NOTE: Ignore this step if the package is an non-launchable package.

3. Create a systemd service and runfile. The service will be enabled after service creation.

   . setup.sh create-service --pkg-name <package_name> --pkg-id <id>

   The service file rv2_startup_<package_name>_<id>.service will be created in rv2_startup/launch/services directory, and runfile.sh will be created in the package launcher directory.

   NOTE: Ignore this step if the package is an non-launchable package.

4. Build the ROS2 workspace.

   . setup.sh build

   The ROS2 workspace will be built accrording to the packages in the rv2_startup/launch/scripts. The global packages will not be built.

5. Start the service, or reboot the system to start the service automatically.

   sudo systemctl start rv2_startup_<package_name>_<id>.service

   WARNING: The service will fail to start if the package is not built.

NOTE: The order of step 3 and 4 can be swapped. The step 4 could be ignored if all the package launchers are using global packages.

Remove a Package Launcher

1. Remove the <package_name>_<id> package launcher.

   . setup.sh remove --pkg-name <package_name> --pkg-id <id>

   The package launcher directory <package_name>_<id> will be removed from the rv2_startup/launch/scripts, and the service will be removed, the service file rv2_startup_<package_name>_<id>.service will be removed from the rv2_startup/launch/services.

   NOTE: If want to keep the package launcher directory, use the remove-service command instead of remove to remove the service only.

   NOTE: If want to remove all the package launchers, use the --all flag instead of --pkg-name and --pkg-id.

Re-create a systemd Service

If the package launcher directory <package_name>_<id> exists, run the following command to re-create the service.

. setup.sh create-service --pkg-name <package_name> --pkg-id <id>

The remove-service will be called before creating the service.

Show Logs

Logs of the setup.sh Script

• Show more information while running the setup script.

  . setup.sh --debug

  NOTE: The --debug option controls the debug message printed in the terminal. The debug message will always be written to the log files.

• The log files located at ${HOME}/rv2_startup/log/<YYYY_MM_DD>.log.

• If using --gui-mode, the log messages will formed with specific prefixes, suffixes, and delimiters. The mode is designed for the GUI application for easier parsing the log messages to the GUI.

Logs of the systemd Service

• Show the logs of the rv2_startup_<package_name>_<id>.service.

  sudo journalctl -u rv2_startup_<package_name>_<id>.service

Description

config.yaml

The config.yaml file is used to define the package launcher settings. The file should be placed in the ${HOME}/rv2_startup directory.

ENVIRONMENT_SETUP:
    ROS2_WS_PATH: "~/rv2_ros2_ws"
    FTP_SERVER_PATH: ""
    FTP_SERVER_REPO_VERSION: ""

# The following parameters are used to search the ROS2 package under global shared directory.
ROS2_SHARE_PKG_NAME_REGEX:
    RV2_PKG_NAME_REGEX: "^rv2_[a-z0-9_]+"
    # Customized package name regex can be added here.

• ROS2_WS_PATH (string): The path to the ROS2 workspace. (Required)
• FTP_SERVER_PATH (string): The path to the FTP server. (Optional)
• FTP_SERVER_REPO_VERSION (string): The version of the repository on the FTP server. (Optional)
• RV2_PKG_NAME_REGEX (string): The regular expression to search the ROS2 package under the global shared directory. (Optional)

WARNING: If the FTP_XXX not set properly, the restore-repos, update-repos and update-repo-list commands will not work, and list can only use scripts and services. The rest of the commands will work normally.

packages.yaml

The packages.yaml file is stored under rv2_startup/content directory. The file describes the repositories that can be tracked and fetched from online git servers.

The packages.yaml file can be generated by the update-repo-list command, users can also manually create the file with the following format:

packages:
    rv2_package_example:
        description: "RV2 Example Package"
        url: "https://github.com/cocobird231/rv2_package_example.git"
        packages:
            - rv2_package_example

    <repo_name>:
        description: "Some description"
        url: "<git repository url>"
        packages:
            - <package_name>
            - <package_name2>
            - <package_name3>

NOTE: The <repo_name> will be the directory name while fetching the repository into the ROS2 workspace source directory.

NOTE: The <package_name> should be the ROS2 package name defined in the package.xml.

NOTE: If the packages.yaml is customized, do not run the update-repo-list command, or the file will be overwritten.

Commands

• --pkg-name <package_name>:

  The name of the ROS2 package (Defined in package.xml). The name should follow the regular expression [a-z0-9_-]+.

• --pkg-id <id>:

  The unique ID of the package launcher. The ID must fit the regular expression [a-zA-Z0-9\.]+. The ID should follow the regular expression [a-zA-Z0-9\.]+.

• --pkg-no-launch:

  Set the flag if <package_name> package is not for launch. The --pkg-id flag is not required if the flag is provided, and the package launcher name will be <package_name>_nolaunch.

  WARNING: The package can not create a service since the package is not a launchable package.

• create {--pkg-name <package_name>} {--pkg-id <id>|--pkg-no-launch}:

  Create a new package launcher. The package launcher directory <package_name>_<id> will be created in the rv2_startup/launch/scripts, and the file under params directory will be copied to the package launcher directory.

  WARNING: If the package is not for launch, use the --pkg-no-launch flag. The directory <package_name>_nolaunch will be created in the rv2_startup/launch/scripts, and the directory will be empty.

• create-service {--pkg-name <package_name>} {--pkg-id <id>}:

  Create a systemd service.

  1. First run custom.sh if exists in the repository scripts directory.
  2. Create runfile.sh in the package launcher directory. If source_env.sh exists in the repository scripts directory, the source_env.sh will be appended to the runfile.sh before the ros2 launch command.
  3. Create a systemd service file rv2_startup_<package_name>_<id>.service in the rv2_startup/launch/services directory.

  WARNING: The system.yaml file should be placed in the package launcher directory, and the network field should be set properly.

  WARNING: The command does not support the non-launchable package (package created with --pkg-no-launch flag).

  WARNING: The command will remove the service if the service already exists. The service will be enabled after service creation.

• remove-service {{--pkg-name <package_name>} {--pkg-id <id>}|--all}:

  Remove a systemd service. The service and file of rv2_startup_<package_name>_<id>.service will be removed, and the runfile.sh will be removed from the package launcher directory.

  • --all: Remove all the services without specifying the package name and ID.

• remove {{--pkg-name <package_name>} {--pkg-id <id>}|--all}:

  Remove a package launcher. The remove-service command will be executed before removing the package launcher directory.

  • --all: Remove all the package launchers without specifying the package name and ID.

• build [--clean] [--depend]:

  Build the ROS2 workspace. The ROS2 workspace will be built according to the packages in the rv2_startup/launch/scripts.

  • --clean: Clean the build, install and log directories before building.
  • --depend: Force install the dependencies before building (include rosdep install).

• restore-repos:

  Restore the repositories under the ROS2 workspace source directory. The repositories will be restored according to the packages.yaml file which is generated under rv2_startup/content by the update-repo-list command.

  WARNING: This command will not modify the repositories which are not listed in the packages.yaml file.

  WARNING: The changes in the repositories will be lost after running this command.

• update-repos [--clean]:

  Update the repositories under the ROS2 workspace source directory. The repositories will be updated according to the packages.yaml file which is generated under rv2_startup/content by the update-repo-list command.

  • --clean: Clean the repositories before updating.

  WARNING: This command will not modify the repositories which are not listed in the packages.yaml file.

  WARNING: Without the --clean option, the changes in the repositories will be kept after running this command.

• update-repo-list:

  Update the repository list from the FTP server. The packages.yaml file will be generated under rv2_startup/content.

  WARNING: The FTP_SERVER_PATH and FTP_SERVER_REPO_VERSION should be set properly in the config.yaml file.

• list {all|pkgs|scripts|services}:

  List the package launchers and repositories.

  • all: List all the package launchers and repositories. The printed information: <pkg_launcher_name> <pkg_launcher_status> <package_name> <package_status>

    • <pkg_launcher_name> (string): The package launcher directory.
    • <pkg_launcher_status> (0|1): 0 for no service, 1 for service installed.
    • <package_name> (string): The ROS2 package name.
    • <package_status> (0|1|2|3):
      • 0: Package in global share.
      • 1: Custom package in local src.
      • 2: Package tracked (in packages.yaml) but not fetched.
      • 3: Package fetched.

  • pkgs: List the repositories. The printed information: <package_name> <package_status>

    • <package_name> (string): The ROS2 package name.
    • <package_status> (0|1|2|3):
      • 0: Package in global share.
      • 1: Custom package in local src.
      • 2: Package tracked (in packages.yaml) but not fetched.
      • 3: Package fetched.

  • scripts: List the package launchers. The printed information: <pkg_launcher_name> ... <pkg_launcher_name>

  • services: List the package launchers that have services. The printed information: <pkg_launcher_name> ... <pkg_launcher_name>

• --gui-mode:

  The flag will formed the output and log messages with specific prefixes, suffixes, and delimiters. The mode is designed for the GUI application for easier parsing the log messages to the GUI.

• --debug:

  Print more information while running the setup script. The debug message will always be written to the log files.