Setting up a new modular robot core

This tutorial is for researchers who want to set up a new modular robot core. First check if someone else has already arranged this for you, for example a research lab manager. If so, you should probably look at how to create a physical modular robot. Also, if you simply want to know how to use a pre-installed physical robot, check the example physical_robot_remote.

Version 1 (V1) and version 2 (V2) of the hardware exists. For anyone outside of the CI Group, V1 is not available; please look at the V2 modular robot.

Preparing the hardware

For both V1 and V2 the following items are required:

  • A housing that will contain the rest of the core hardware. Models to print the core housing can be found on the following git repo: https://github.com/ci-group/revolve-models.

  • A Raspberry Pi (RPi). For V2, this must be a RPi 4 (or newer, but check for compatibility).

  • A HAT (hardware attached on top), as described in the following hardware specific sections.

Hardware setup for a V1 Robot

V1 is only available to CI Group.

  • Obtain and attach a V1 HAT, available in the CI Group lab.

  • Obtain a V1 specific battery, available in the CI Group lab.

Hardware setup for a V2 Robot

For instructions on how to set up the hardware of a V2 core, refer to https://github.com/ci-group/robohat.

Important: For the V2 to work properly the config.txt on the RPi has to be changed. The following file contains the correct config content: https://github.com/ci-group/robohat/blob/main/config.txt. On the RPi adjust the config in /boot/config.txt or on newer systems /boot/firmware/config.txt.

Setting up the RPi

This step is the same for all types of hardware.

  1. Flash the SD card with Raspberry Pi OS (previously Raspbian). Some Important notes:

    • If you are required to pick a username and password, it is recommended to pick pi and raspberry. These are the defaults for most RPi installations.

    • Reminder for CI Group people: if you select a keyboard layout, pick English(US). It can always be changed using the raspi-config tool on the RPi.

    • When setting up the Wi-Fi connection, select your Country. (CI-Group Wi-Fi: ThymioNet)

  2. Boot the RPi and get command line access. Here are some general Tips:

    • You can connect a keyboard and screen.

    • Better is to SSH. This works only if you and the RPi are on the same network. For CI Group, connect it to ThymioNet Wi-Fi.

      • Hint: SSH is not enabled by default. The simplest way to enable it is using the raspi-config.

    • If you want to SSH and don’t know the IP of the RPi, you can use sudo nmap -sP <your ip> on your machine to find all clients on your network.

    • For V2 robots: You can establish a serial connection with the AUX input on the hat. To do so, connect the robohat with your device using a cable. Then use the following command to access the robohat: sudo screen <port to connect> 115200.

      • For linux users, the port is usually: /dev/ttyUSB0.

      • For mac users the port is usually: /dev/cu.usbserial.

Install Revolve2 on the RPi

Setting up Revolve2 on the robot requires different steps, depending on the hardware version. Some general steps for all versions:

  1. Set up a global pyenv. This is to prevent changes to the system’s Python installation.:

    1. Install required packages using:

      sudo apt install -y git libssl-dev libbz2-dev libncurses5-dev libncursesw5-dev libreadline-dev libsqlite3-dev libffi-dev liblzma-dev

      If an 404 error appears in this step, you most likely are on an old RPi OS. To check your os version you can run cat /etc/os-release. It should be version 12 Bookworm or newer.

    2. Install pyenv: curl https://pyenv.run | bash

    3. Add pyenv to bash:

      echo '# Enable pyenv
export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
' >> ~/.bashrc

    4. Log in and out of the RPi.

    5. Get the right Python version (this takes a long time): pyenv install 3.11

    6. Create a global virtualenv: pyenv virtualenv 3.11 global_env & pyenv global global_env

  2. Then install Revolve2 using:

    • V1: pip install "revolve2-modular_robot_physical[botv1] @ git+https://github.com/ci-group/revolve2.git@<revolve_version>#subdirectory=modular_robot_physical".

    • V2: pip install "revolve2-modular_robot_physical[botv2] @ git+https://github.com/ci-group/revolve2.git@<revolve_version>#subdirectory=modular_robot_physical".

  3. Set up the Revolve2 physical robot daemon:

    1. Create a systemd service file: sudo nano /etc/systemd/system/robot-daemon.service

    2. Add the following content to the file (note: fill in the missing information):

      ini
[Unit]
Description=Revolve2 physical robot daemon
After=network-online.target <add this for v1 robots as well: 'pigpiod.service'>

[Service]
Type=simple
ExecStart=/home/<your username>/.pyenv/versions/global_env/bin/python /home/<your username>/.pyenv/versions/global_env/bin/robot-daemon --hardware <here you type either 'v1' or 'v2'>
ExecStop=/bin/kill -15 $MAINPID
Nice=-10
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

    3. Here, the Nice=-10 line sets a high priority for the daemon (lower values are higher priority, with -20 being the highest priority). The -l option in the ExecStart line tells robot-daemon to only listen on the localhost interface. The -n localhost option ensures that robot-daemon only runs if it can connect to localhost (preventing certain failure cases).

    4. Enable and start the service: sudo systemctl daemon-reload & sudo systemctl enable robot-daemon & sudo systemctl start robot-daemon.

    5. Check if it is running properly using: sudo systemctl status robot-daemon

V1 Additional Steps

If you use V1 hardware setup requires additional steps:

  • V1 used pigpiod, which is installed automatically with the modular_robot_physical[botv1] package. This library allows the control of the servos attached to the RPi’s HAT.

  • Enabling pigpiod daemon so it enables at startup (used for the servos).

    1. Setting up a systemd service: The modern way to manage startup services on many Linux distributions is via systemd. You can set up a service for pigpiod.

    2. Create a systemd service file: sudo nano /etc/systemd/system/pigpiod.service

    3. Add the following content to the file:

      ini
[Unit]
Description=Pigpio Daemon
After=network-online.target

[Service]
Type=forking
ExecStart=/usr/bin/pigpiod -l -n localhost
ExecStop=/bin/kill -15 $MAINPID
Nice=-10
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

    4. These settings are identical to the settings for the robot-daemon.

    5. Enable and start the service: sudo systemctl daemon-reload & sudo systemctl enable pigpiod & sudo systemctl start pigpiod.