ADHERENT setup configuration

This wiki describes how to configure the setup used for simulations and experiments in the ADHERENT paper. It exploits docker, docker-compose and an adaptation of the tools provided in the development-iit repo. Please follow the steps below to configure the setup and then follow the ADHERENT scripts execution wiki to actually reproduce the results in the paper.

1. Install docker

Install docker by following the Install Docker Engine on Ubuntu guide (Install using the repository is suggested as installation method). Make sure you follow also the post-installation steps in Manage Docker as a non-root user and verify that you can run docker commands without sudo by:

docker run hello-world

2. Install docker-compose

Install docker-compose by following the Install Docker Compose guide and test the installation by running:

docker-compose --version

3. Pull a pre-built docker image

Pull the adherent-docker image (~12G) by:

docker pull ghcr.io/ami-iit/adherent-docker:latest

Alternative (not suggested)

If, instead, you prefer to build the image locally, clone the repo and reach the folder with dockerfiles:

git clone https://github.com/ami-iit/paper_viceconte_2021_ral_adherent.git adherent
cd adherent/dockerfiles

before running:

docker build --rm \
	--build-arg VCS_REF=`git rev-parse --short HEAD` \
	--build-arg BUILD_DATE=`date -u +"%Y-%m-%dT%H:%M:%SZ"` \
	--tag ghcr.io/ami-iit/adherent-docker \
	.

4. Connect the joystick

Connect the joystick to your laptop via bluetooth or usb and make sure that it can be seen as js0 by running:

cat /dev/input/js0

and checking that when you press random buttons the device actually streams data (although non-ascii characters will appear on the terminal). ⚠️ The joystick is required to be connected when executing Step 5 below.

Troubleshooting

If the above test fails, check first that the joystick has been successfully connected to your laptop by verifying that the device appears in the output of dmesg.

Then, look for other possible identifiers of the device js<N> in the /dev/inputs/ folder and repeat the check of running cat /dev/input/js<N> for each of them. Once you find the correct identifier, edit the devices field of docker-compose.yml file (see Section 5 below) accordingly.

5. Create and access the docker container

wget https://raw.githubusercontent.com/ami-iit/paper_viceconte_2021_ral_adherent/main/dockerfiles/docker-compose.yml
docker-compose up -d
docker exec -it adherent bash

6. Unzip the ADHERENT dataset

cd adherent
unzip datasets.zip
rm datasets.zip

7. Stop the docker container

Type exit to exit the current terminal within the docker container and then run:

docker stop adherent

At this stage, you will have a stopped container, ready to be reactivated to follow the ADHERENT scripts execution wiki.

8. Clean the setup

⚠️ This step needs to be performed only if you want to remove the setup configured as above.

Remove the docker container and then the docker image by:

docker rm adherent
docker image rm ghcr.io/ami-iit/adherent-docker:latest

Then uninstall docker-compose and uninstall docker.