Skip to content
This repository has been archived by the owner on Feb 3, 2023. It is now read-only.

Software Instructions

Jump to bottom
0xD0M1M0 edited this page Dec 28, 2022 · 9 revisions

Overview

All the software of ExoMy runs on a Raspberry Pi with the standard Raspberry Pi OS operating system and should be independent of the used versions. To realize that a software called Docker is used, that runs an Ubuntu operating system with the ROS framework. The code in the end is mainly written in Python.

Raspberry Pi and Raspberry Pi OS

The original ExoMy uses a Raspberry Pi 4 Model B with the image "Raspberry Pi OS Buster with desktop". At the time of creation this was the newest Raspberry Pi model and had some advantageous properties like:

  • On-board Wi-fi and Bluetooth
  • USB-C power supply
  • Powerful processor

Since Raspberry Pi OS (formerly called Raspbian) is the official OS of the Raspberry Pi it supports the most features of the hardware. The desktop version helps users that are not familiar with command lines yet.

More information about the Raspberry Pi can be found here and about Raspberry Pi OS here.

Docker

Docker is a software that virtualizes an operating system in a defined configuration and therefore ensures always the same system setup for the ExoMy code to run.

Since Docker is a widely used software tool, plenty of tutorials and descriptions can be found online.
The commands needed for ExoMy are listed here, but a more detailed description can be found under Docker Tutorial.

ROS

"The Robot Operating System (ROS) is a set of software libraries and tools that help you build robot applications."[https://www.ros.org/]

ROS helps to write easier and better working code for ExoMy and already has a lot of ready-to-use source code for all kinds of robotic applications.

The idea of ROS is to separate different functionalities in so called nodes and let them communicate over pre defined messages. A node can be written in one of the programming languages: C++ or Python, whereas all source code of ExoMy is written in Python.

Setup

Required Parts:

  • Computer with SD card reader
  • Micro SD card (over 8GB)
  • Raspberry Pi
  • Monitor
  • HDMI cable
  • Keyboard
  • Mouse

Additional for Raspberry Pi 4:

  • USB-C power supply
  • HDMI to Micro HDMI adaptor

Additional for Raspberry Pi 3:

  • Micro USB power supply

Flashing the Operating System

Note: This section is a summarized version of the official Raspberry Pi tutorial.

The Raspberry Pi normally does not come with an operating system installed. The process of putting an operating system on a SD card for the Raspberry Pi, is called flashing and the file that contains the operating system is called an image.

Before you start, don't forget to check the SD card requirements. (ExoMy uses a 16GB SD card with the Raspberry Pi 4 Model B)

When ExoMy was created the Pi Imager tool was not yet available so, but it seems to be very handy. So you can follow either of the two options.

Option 1: Pi Imager Tool (recommended)

There is an official imaging tool for the Raspberry Pi, that will download the image and install it automatically to the SD card:

  • Download the latest version of Raspberry Pi Imager and install it
  • Connect an SD card reader with the SD card inside.
  • Open Raspberry Pi Imager and choose the required OS from the list presented. Choose "Raspberry Pi OS (32-bit)"
  • Choose the SD card you wish to write your image to.
  • Review your selections and click 'WRITE' to begin writing data to the SD card.

Option 2: balenaEtcher

Download the Raspberry Pi OS (based on Debian Buster) with desktop image, which should be in the .zip format.

You will need to use an image writing tool to install the image you have downloaded on your SD card.

balenaEtcher is a graphical SD card writing tool that works on Mac OS, Linux and Windows, and is the easiest option for most users. balenaEtcher also supports writing images directly from the zip file, without any unzipping required. To write your image with balenaEtcher:

  • Download the latest version of balenaEtcher and install it.
  • Connect an SD card reader with the SD card inside.
  • Open balenaEtcher and select from your hard drive the downloaded Raspberry Pi OS .zip file.
  • Select the SD card you wish to write your image to.
  • Review your selections and click 'Flash!' to begin writing data to the SD card.

Configure Raspberry Pi

  • Insert SD
  • Connect HDMI cable
  • Connect keyboard and mouse
  • Connect power supply

Raspberry Pi will boot and you will see the desktop of Raspberry Pi OS, with a configuration dialog:

Follow the configuration steps in the installation wizard:

  • Set country/language/timezone
  • Set username and password (recommended username: pi)
  • Set up screen (usually no changes necessary)
  • Set WiFi
  • Update software (can easily take more than 30 minutes)

Per default some functions of the Raspberry Pi are deactivated. To use them we have to activate them:

Go to Raspberry Pi Configurations:

Change the Hostname and the Password (if not customized already during the inital installation wizard):

Enable Camera, SSH and I2C:

When clicking on OK you are asked to do a reboot. The Raspberry Pi boot again and you come back to the desktop.

Install Software

OS update

Open a terminal with ctrl + alt + t or by clicking on the terminal symbol in the taskbar.

The terminal should show something like:

pi@exomy:~ $

Type following commands line by line and confirm every line with Enter. A lot should happen on the screen. The commands update all programs to the newest version. This may take a while.

sudo apt-get update
sudo apt-get full-upgrade

Be sure to reboot your Raspberry Pi after the upgrade. This can be done over the menu in the top left corner, or by typing sudo reboot in the terminal.

Install Docker

To install Docker run following commands, again one by one.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker pi
sudo reboot now

More information on what is happening here.

Test the docker installation with:

docker run hello-world

The output should be as followed:

Get Source Code

Navigate to your home folder with:

cd

To get all the source code from GitHub run:

git clone https://github.com/esa-prl/ExoMy_Software.git ~/ExoMy_Software

You can check that the cloning was successful by running ls in your terminal, which lists all folders in the current directory. You should see a folder called ExoMy_Software.

Run Docker Containers

We provide a shell script called run_exomy.sh in the Exomy_Software/docker folder, to make the use of the docker containers a bit easier. If you want to know more about the specific commands used, you can check out the run_exomy.sh with a text editor and have a look at the Docker Tutorial.

To see the different options of the script use:

sh ~/ExoMy_Software/docker/run_exomy.sh -h

Or if you are already in the Exomy_Software/docker folder:

sh run_exomy.sh -h

Depending on the state of the project, different configurations of the docker container are used:

Config

This configuration is used to run configuration scripts for the motors as described in the chapter final integration

sh ~/ExoMy_Software/docker/run_exomy.sh -c

Devel

This configuration is used to start the container for development purposes. It installs the source code and sources the environment. You can make modifications to the code and run your custom launch files.

sh ~/ExoMy_Software/docker/run_exomy.sh -d

Autostart

This configuration is used to autostart the software when ExoMy is switched on. ExoMy can then be controlled using the website or with a gamepad.

sh ~/ExoMy_Software/docker/run_exomy.sh -a

Stop Autostart This configuration is used to stop the autostart docker container.

sh ~/ExoMy_Software/docker/run_exomy.sh -s

Additional Features

Some software features are not necessary to run ExoMy, but are a lot of fun.

Setup Wifi Hosting

To control the Raspberry Pi over the web interface it can be connected to your Wifi and be reached over his ip-address. But if you are for example out of the reach of your home Wifi, the Raspberry Pi has the possibility to host its own Wifi you can connect to.

An extensive tutorial can be found here.

Software Description

ExoMy's software uses the ROS framework to organize the different tasks of the robot in separate nodes. Each node runs on it's own, but can communicate with other nodes via messages, that are defined by their type and a topic name. A node can publish a message on a specific topic and all nodes that subscribed on that topic, will receive the message. This architecture allows to separate code, while not loosing the overview and makes the adding of already written code of the Open Source ROS Community fairly easy. ExoMy only needed 3 newly created nodes, the rest of the functionality could be realized with standard ROS nodes.
The following image shows how all the nodes and interfaces of ExoMy are orchestrated:

Home | System Overview | Getting Started | FAQ | Download CAD | Download Code | European Space Agency

Home

Build

Use

Contribute

Help

Clone this wiki locally