Skip to content

Managing Docker Containers

Introduction

The Vertex One is pre-installed with a couple of Docker containers running Avular software packages. These docker containers can communicate with each other using the ROS 2 network.

Working With Docker Containers

To learn more about working with docker containers, please refer to the Docker documentation (External Link).

Existing Containers

Here is an architecture overview of how the containers are built up.

Vertex

Bringup Container (pioneers-bringup)

This container is running the main ROS 2 API to interface with the Avular flight controller. See the Avular Programming Interface page on how to interact with this container.

Realsense 2 Container (pioneers-realsense2) (Optional) (Gen 1 only)

This container is running the ROS 2 Wrapper for the Intel RealSense depth camera. See the RealSense integration page on how to interact with this container.

Default User Container (user-container)

This container is running bare ROS 2 Humble and has the ROS 2 API messages pre-installed. It can be used to easily check ROS 2 messages. The souce code for the user-container is available Public User Container Example Repo to quickly start developing your own container.

Managing Containers Using Avular Script

To manage these containers, the avular script has been developed.

Note

This script can only be called from the onboard computing unit's OS, not from inside of the docker containers.

Mode

With the avular mode command the containers can be switched between production mode and development mode:

In the development mode the ROS 2 network is not active; to set the containers to development mode, execute: avular mode set d.

In the production mode the ROS 2 network is automatically started when the containers launch; to set the containers to production mode, execute: avular mode set p.

Compose

With the avular compose command you can manage the state of the containers. It is a wrapper around docker compose so it has the same functionality with up, down, start and stop. It also allows for easy entering of the container using enter. If the docker compose files need to be changed for adding containers or changing settings then its easy to navigate to the files using avular compose config.

Help

To view the help page of the script, execute: avular -h.

Usage: [COMMAND] [ARGS]
[COMMAND] can be either: 
    'mode' with arguments:
        'get' returns the current mode
        'set' [new_mode]: set a new mode. This does not influence running containers
            'new_mode' can be one of the folllowing: 'production', 'p', 'development', or 'd'
    'compose' with arguments:
        'config' open a new shell sesion in the directory containing the docker-compose files
        'start'  start the docker-compose containers
        'stop'   stop the running docker-compose containers
        'down'   remove all docker-compose application containers
        'up'     start the docker-compose application
        'show'   show the status of the containers of the docker-compose application
        'switch` [new_mode] set a new mode and launch new docker-compose application using the new mode
            'new_mode' can be one of the folllowing: 'production', 'p', 'development', or 'd'
        'enter`   (-d) [container_name]  enter a running container
            '-d'             optional argument, provide it to disable overriding the SSH_AUTH_SOCK env variable
            'container_name' the name of the container to enter
        'logs'   show the logs of all running docker-compose applications 
    'connectivity' with arguments:
        'enable_ap'    (-s) [SSID] (-p) [PASSWORD] This will create an access point (Setting will be stored)
        'enable_client_mode'    (-s) [SSID] (-p) [PASSWORD] Switch the Jetson to client mode, if no SSID and password are provided the hostname will be used with no password
        'disable'   This will disable the current connectivity mode

Provided Example User-Container

To get started, Avular provides the source code to setup your own container and easily communicate using Avular Programming Interface (Compatible with ROS 2). First we will look into the existing user-container, which is built from the example source code.

One of the containers running on the Vertex One is the user-container. This container is set up to contain the basic ROS 2 message files and ROS 2 Humble to easily get data from the flight controller.

As an example, lets check the battery percentage through the API using the container.

See Cerebra Robot Discovery (Gen3) or Cerebra Robot Discovery (Gen4) on how to connect to the onboard computing module.

  1. Start the Vertex One and wait for the onboard computing module to boot
  2. SSH into the online computing module
  3. View a list of all the running containers; execute: avular compose show
  4. Enter the user-container by executing the following command: avular compose enter user-container-prod
  5. View all information contained in the ROS 2 Battery topic once by executing: ros2 topic echo --once /robot/sensor/battery

Note

To view all active ROS 2 topics, execute: ros2 topic list

Setup Your Own Development Container

The source-code and dockerfile of the user-container are available and can be downloaded in the download section. The zip file contains the following:

  • Dockerfile & Entrypoint
  • Messages in ROS 2 packages

The above files can be used to build the user-container from source.

  1. This can be done by first copying the files to the Vertex One.
    • Tip: Use the VSCode: Remote SSH to copy the files.
  2. Then building the dockerfile with docker build --network=host -t custom_container . -f docker/Dockerfile.
  3. Once built, it can be added to the docker compose files. The compose files can be found using avular compose config (This command opens a new shell and navigates to the config files)
    • The docker compose files all share the same base file: docker-compose-common.yml.
    • Use image: custom_container to specify which image needs to be used.
    • For more info on how to configure the docker compose file: Docker Compose file docs
  4. Using avular compose down and avular compose up the new container can be started.

Adding Repositories Into The Containers

To add your own repositories into the containers, you can configure the Dockerfile to copy or pull the required repository.

Note

For building the docker image, you can use the online repository pipelines (e.g. Github/Gitlab) or build it on the onboard computing module itself.

To pull the built docker image on the onboard computing module, access the docker compose files (avular compose config) and add the url of your docker image.