Get Started with TeleOperations Console

This document will take you through the steps of getting the TeleOperations Console up and running ready to be used!

To see individual sections related to their own documentation (or for extra information not covered, visit the wiki):

• The Console (Frontend)
• The Python Server
• The Ezrassor Controller Server
• The Ezrassor Sim Description

NOTE:
The Ezrassor Controller Server and Ezrassor Sim Description go directly to their corresponding repository that they originate from, however, we made modifications to each to better fit our project, and for better readability and scalability.

---

Table of Contents

• Get Started with TeleOperations Console
  • Table of Contents
  • Prerequisites
    • For Windows
      • WSL (recommended)
    • For Linux
  • Troubleshooting
    • For Linux and WSL
  • To Get Started
    • Automated Startup
      • Start Up Services
    • Manual Startup
    • For Developers
      • Rebuilding / Made Changes
      • Fresh Build
      • Other Helpful Commands
        • Container Related
        • Simulation Related
        • Database Related
        • Python Server Related
  • Contributing
  • License

---

Prerequisites

The Teleoperation Console team is going to be building off of the work from the Spring 2024's Capabilities team and is compiling the list of instructions from their repo to recreate their development environment.

The development environment will be running on Ubuntu and has been set up on Ubuntu 22.04 (Jammy). Windows users can use WSL, but it will have to be version 2 (WSL2).

You will need Node.js, npm, and git installed on your device. How to install these will not be within the scope of this document

This development environment uses Python3's virtual environment, Gazebo 'Classic', and ROS2 'Humble'.

For Windows

• Docker Desktop for Windows must be installed.

Note: Currently running the container hasn't worked directly on Windows due to an issue with Gazebo not finding an audio server to play audio on

WSL (recommended)

Ensure the application version of WSL2 is installed.

You can use wsl --install in Windows terminal to follow the instructions to make sure it's the correct version.

Next, do the following steps:

1. Install docker on WSL

sudo apt-get update && sudo apt-get upgrade -y` \
curl -fsSL https://get.docker.com -o get-docker.sh \
sudo sh get-docker.sh 

(ignore any warnings if you get them)

sudo usermod -aG docker $USER 

(allows to run docker without sudo commands)

2. Verify that Docker has been installed:

docker --version
docker compose version

3. Init System service To run and manage the docker daemon service you'll use your operating system's built in init-system.

Recent versions of Linux tend to use systemd (which uses the systemctl command), while older versions of Linux tend to use System V init (which uses the service command).

If you are unsure which system you have run:

ps --no-headers -o comm 1

Then clck to expand the appropriate detail below based on the result

systemtcl

Run the docker engine service and start service (this will turn it on every time WSL opens)

sudo systemctl start --now docker.service
systemctl status docker.service # Check the status

Tip: if you want the service to start everytime you start WSL

Start the docker service with

  sudo systemctl enable --now docker.service

System V

Start the docker service with

 sudo service docker start
 systemctl status docker.service # Check the status

---

1. Now restart WSL by doing wsl --shutdown or open a new terminal.
2. Run a test docker to verify it is working

docker run hello-world

If that runs, you can get started.

For Linux

1. Install Docker

sudo apt-get update
sudo apt-get install docker-compose docker-ce docker-ce-cli containerd.io docker-compose-plugin

Now, you have Docker installed and running on your linux machine.

Troubleshooting

For Linux and WSL

If console is showing you have no 'installation candidate" for the packages when installing docker, from this stackoverflow:

sudo apt-get install \
     ca-certificates \
     curl \
     gnupg \
     lsb-release

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

and update one more time

sudo apt-get update

---

To Get Started

Since this is all locally built and nothing is out on the cloud, create a .env file with these properties (and you can provide the values to whatever you want, except for the ENVIRONMENT and DB_HOST field).

DB_HOST="postgres"
POSTGRES_USER="FSIOperators"
POSTGRES_PASSWORD="somes3curepassword"
POSTGRES_DB="rover_teleoperations"
DB_PORT="5432"
# Developers, change this to "development" if working on server directly please (for hot reload)
ENVIRONMENT="production"

You can find the port and "host" you need by checking the url of the container that is running postgres. If you run into an issue where "postgres" hostname isn't found try using "localhost" for DB_HOST instead.

Automated Startup

We have a few automated processes:

1. Simulation The compose file contains the simulation service ros2-humble, which builds out the container expressed in the root Dockerfile. This sets up the Gazebo simulation and starts up the controller server through the start-sim.sh script.
2. Python Server The compose file contains the python middleman-server service, which will setup the python server through installing all dependencies on build, and will start up the server as well after building through the server-entry.sh script. This service depends on the database.
3. Database Service The compose file contains the postgres service in which it uses a default postgres v16 image to build the database in the container. It then runs an initialization script created (init-scripts/01-table-initialization.sql). This will build out the tables and create the types needed for the python server to handle.

Start Up Services

To simply get everything up and running, there are only 2 commands to know:

NOTE: Please make sure you are in the root directory of the project before running any commands.

# On initial startup, i.e, containers have yet to be built
docker compose up --build

# If containers are already built,
docker compose up

If for some reason something fails or you change/remove the command in compose.yaml, below is how to manually start up all the processes. To start the process, see here.

Manual Startup

To start up a specific service, you will use

docker compose up --build <service-name>

# To start up simulation
docker compose up --build ros2-humble

For Developers

Rebuilding / Made Changes

The python server currently is not supporting hot-reloading when in the docker container. A way to rebuild the python service (or any service) you can run this command

docker compose restart <service-name>

# To rebuild python server
docker compose restart middleman-server

If you made any changes to the packages (ezrassor_controller_server or ezrassor_sim_description), run these following commands inside the docker container (docker exec -it ros2-humble bash) to have the changes applied:

rm -rf build/{package_name} install/{package_name}
colcon build --packages-select {package_name}

NOTE: For the rm command, it must be a singular package, but for colcon build command, you can build multiple packages at once. Just make sure to separate the packages with a space. (i.e, colcon build --packages-select {package_1} {package_2} ...)

Then from there, you can run these commands to start it up without rebuilding.

Fresh Build

If you need to start fresh on the docker containers, run:

WARNING: Running the commands below will delete any containers and/or volumes you currently have. If you want to delete the specific containers and volumes, refer to docker documentation on how to do so (get container id, and go from there).

docker compose down -v
docker compose up --build

Other Helpful Commands

Container Related

You can enter any related container's terminal by just running docker exec -it <container-name> bash

Simulation Related

For using these commands, make sure you are in the respective container.

• For spawning rover:

  ros2 launch ezrassor_sim_description spawn_ezrassor.py robot_name:=ezrassor

• For controller server:

  ros2 launch ezrassor_controller_server controller_server.py

Database Related

Make sure to be in the database container.

• To get into the database

  # These should carry over from your .env file.
  psql -U $POSTGRES_USER -d $POSTGRES_DB

• To see the list of tables: \dt
• Any other SQL queries you want to manually provide in the terminal will work.

Python Server Related

• If you are developing and adding dependencies, please make sure to:
  1. Be working in a virtual environment locally. (Not on the container)
  2. When adding dependencies, make sure to run: pip freeze > requirements.txt This will make sure to update the text file with all the dependencies in which the docker service will use to build out its respective container.

---

Contributing

For a basic rundown on how to contribute to this project using Git and GitHub, see the guide at docs/CONTRIBUTING.md.

---

License

This software is released under the MIT license. View the full license under docs/LICENSE.txt.