Basic Usage - robocup-logistics/rcll-get-started GitHub Wiki

Basic Usage

This repository provides the software of the RCLL via containers that can be started conveniently using shell functions.

Prerequisites

A linux distribution running docker, docker-compose, screen and bash is required.

Initial Setup

clone this repository and source the setup.sh script from the root of the repository:

cd ~/
git clone https://github.com/robocup-logistics/rcll-get-started.git
cd rcll-get-started
source setup.sh

This provides the current terminal with environment variables used for configuration of the software and functions used to orchestrate the software of the RCLL. Additionally, it also creates a local_setup.sh file, which you may use to override the provided environment variables. This file is always sourced whenever the setup.sh is sourced.

To make the commands available per default in all of your terminals, consider sourcing the setup.sh in your terminal configuration script (e.g., ~/.bashrc).

Available Commands

  • rc_pull: pull all software
  • rc_start: start all software as configured, setup a screen session with tabs providing the docker logs
  • rc_stop: stop all software
  • rc_restart: restart the software
  • rc_dump_game_reports: dump game reports from mongodb into an archive
  • rc_locate_refbox: shows running refbox instances (useful to check for potential conflicts in network, as only one refbox is supposed to run at a time)
  • rc_name_report: rename game reports from the database
  • rc_restore_game_reports: restore game reports from a dump

Additionally, individual software pieces may be controlled via commands:

  • rc_start_: start the component
  • rc_pull_: pull the component
  • rc_stop_: stop the component
  • rc_enter_: enter a running component with a shell
  • rc_exec_: run command inside of the running container of the component

Configuration

Configuration of the provided software is done via two means: Overriding environment variables and adapting/providing configuration files. The former dictates how containers are setup and started, while the latter are typically then read by the programs to customize them.

Environment Variables

To overwrite the defaults which are set in the setup.sh script, export them in the file local_setup.sh.

There are environment variables controlling the following things:

  • URL and version tag for each container
  • Configuration file/directory location
  • Which optional containers are started on rc_start
  • To which degree the startup of the refbox is automated
  • The arguments passed to the refbox
  • MQTT and MongoDB connection information

Configuration Files

TODO

Component Overview

refbox

Used to just start the refbox and it's frontend without any other tools.

Note that the startup also checks for the existance of a MongoDB on RC_MONGODB_URI.

Generally it is good to take a look at the refbox wiki, which contains a lot of information.

mongodb

The refbox requires a running MongoDB instance (any version compatible with the mongocxx-driver of the refbox). Per default, a new MongoDB 5.0 is started on startup. But it is also possible to use an existing instance. Note that the refbox needs to be configured separately to also use the instance.

Env variables for configuration:

  • RC_MONGODB_START set to true if a mongodb instance should start with the main command, defaults to true
  • RC_MONGODB_HOST hostname or ip address where the instance should run on, defaults to localhost
  • RC_MONGODB_PORT port where the intance should run on, defaults to 27017
  • RC_MONGODB_URI Final URI, defaults to mongodb://${RC_MONGODB_HOST}:${RC_MONGODB_PORT}

mongodb_backend

The refbox logs games into a database, the frontend of the refbox can display that data. In order to do so, a small backend is required that bridges between the database and the frontend.

Env variables for configuration:

  • RC_MONGODB_BACKEND_START set to true if the mongodb backend should be started with the main command, defaults to false
  • RC_MONGODB_BACKEND_DB_NAME name of the database to use, defaults to rcll, which is the default name of the database the refbox uses.

Note that the backend also utilizes the RC_MONGODB_URI variable from the mongodb component.

mqtt_bridge

Note: The image is only available via ghcr.io, so you have to login in order to be able to pull it!

Env variables for configuration:

  • RC_MQTT_START set to true if mqtt bridge should start with the main command
  • RC_MQTT_BROKER broker to connect to
  • RC_MQTT_REFBOX ip of the refbox
  • RC_MQTT_TEAM team name
  • RC_MQTT_KEY crypto key for refbox communication

simulator

start the rcll-simulator and the frontend for it. The ui can then be accessed via http://localhost:4200/``.

Env variables for configuration:

  • SIMULATOR_IMAGE image to use for simulator
  • SIMULATOR_TAG tag to use for simulator
  • SIMULATOR_FRONTEND_IMAGE image to use for simulator frontend
  • SIMULATOR_FRONTEND_TAG tag to use for simulator frontend
  • SIMULATOR_CONFIG_FILE the config file used for the simulator.
⚠️ **GitHub.com Fallback** ⚠️