Setup Process for GTernal

1 - Repository Setup

During the setup process, each robot runs an automatic setup script which clones the firmware from a GitHub repository. By default, the setup script clones the official GTernal repository. This needs to be changed to clone your repository with updated configuration files. If you are not familiar with Git or GitHub, please refer to here: https://docs.github.com/en/get-started/quickstart/fork-a-repo

1. Fork this GTernal repository.
2. Clone the forked repository to your computer.
3. Update 'GTernal/config/env_variables.sh'
4. Push the change to your repository.

2 - Program Teensy

1. Install Teensyduino (https://www.pjrc.com/teensy/td_download.html)
2. Copy and paste all library folders in GTernal/firmware/Teensy/libraries to Arduino/libraries.

Note

The absolute path for the Arduino/libraries directory is OS dependent, and this can be found here: https://support.arduino.cc/hc/en-us/articles/4412950938514-Open-the-Sketchbook

Note

The firmware for Teensy requires ArduinoJson 5.13 which is included in GTernal/firmware/Teensy/libraries. ArduinoJson 6 is currently not compatible with the firmware.

3. Connect a Teensy to the computer using a micro-USB cable.

Note

The micro-USB cable needs to be directly connected to the Teensy and not the micro-USB port on the robot PCB.

4. Run Teensyduino and open defaultOperation.ino located in GTernal/firmware/defaultOperation directory.
5. Select the Teensy board to be flashed under Tools > Port
6. Click the upload icon (right arrow icon).

3 - Make the Base Image for Raspberry Pi

1 - Install Raspberry Pi OS on an SD Card

1. Install and run the Raspberry Pi Imager (https://www.raspberrypi.com/software/). The instuction is for Raspberry Pi Imager v.1.8.5
2. For 'Raspberry Pi Device,' select the version of the Pi used.
3. For 'Operating System,' select Raspberry Pi OS (other) and select Raspberry Pi OS (Legacy, 64-bit) Lite. For Raspberry Pi Zero 1s, select Raspberry Pi OS (Legacy, 32-bit) Lite.
4. For 'Storage,' choose the micro-SD card to be used.
5. Click 'NEXT' and 'EDIT SETTINGS.'
6. Under 'GENERAL' tab, check 'Set username and password' and type pi for the 'Username' and raspberry for 'Password.'
7. Next, check 'Configure wireless LAN' and enter 'SSID' and 'Password' for the router.
8. Change 'Wireless LAN country' to 'US.' 'Set locale settings' is optional.
9. Under 'SERVICES' tab, check 'Enable SSH' and 'Use password authentication'
10. Click 'SAVE' and click 'YES.'

Note

Whenever the Raspberry Pi Imager is restarted, make sure to re-type the passwords for the Pi and the Wifi. The Raspberry Pi Imager seems to be ruining the passwords saved in the advanced setting when the program is restarted even if the 'Image customization options' is set to 'to always use.'

2 - Setup the Base Image

1. Insert the SD card from the previous step into a Raspberry Pi and power it on. It should automatically connect to the wifi specified in Step 2.1.7. The Pi needs some time to boot for the first time.

2. Identify the MAC address of the Raspberry Pi. On a Linux comptuer, this can be done by running

   sudo arp-scan -I <network-device-name> -l -t 100 -r 5
   

   Alternatively, you can navigate to the router settings page (typically '192.168.1.1' or '10.0.0.1') using a web browser. The new Pi will appear as 'RASPBERRYPI.'

3. Add the MAC address to 'path-to-parent-directory/GTernal/config/mac_list.json' file as

   "<MAC-address-of-Pi>":"base_image"
   

   e.g., { "d8:3a:dd:bc:0c:3c":"base_image" }

4. On your computer, run

   cd <path-to-parent-directory>/GTernal/interfacing
   ./setup.sh setup_base_image
   

   When prompted for password, enter the password of your computer. When prompted 'Enter secrets for robots,' enter the password for the Raspberry Pis, raspberry. This will automatically setup the SD card as the base image. Wait for 'DONE SETTING UP BASE IMAGE' message on the terminal.

5. In case of using another network for the robot for actual deployment, edit the wireless LAN credentials. First, ssh into the robot.

   ssh pi@<ip-address-of-robot>
   

   Then, edit the wpa_supplicant.conf file to update the wireless LAN credentials.

   sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
   

6. (Optional) Pull the base firmware image to reduce the setup time.

   • If the wireless LAN credential has changed in the previous step, restart the Raspberry Pi.
     

      ssh pi@<ip-address-of-robot>
      sudo reboot
     

   • Follow the instructions in Section 4 up to 4.1.2.
     
   • Next, ssh into the robot.

     ssh pi@<ip-address-of-robot>
     

   • Run

     cd <path-to-parent-directory>/GTernal/docker/base_image/
     ./docker_pull.sh
     

7. On the ssh terminal, shutdown the Pi by running

   sudo reboot
   

8. Remove the SD card from the Pi and insert it to your computer.

9. On your computer, identify the name of the SD card by running

   sudo fdisk -l
   

   The device name will be something like '/dev/sdb'. Look for the device with the storage size that matches the capacity of the SD card.

Note

You must enter the device name without any numbers. For example, if you see '/dev/sdb1' and '/dev/sdb2', the device name is /dev/sdb.

8. Create the image of the SD card on your computer by running

   sudo dd if=<name-of-the-sd-card> of=<desired-directory>/GTernal_base_image.img bs=4M status=progress
   

   e.g., sudo dd if=/dev/sdb of=~/GTernal_base_image.img bs=4M status=progress
   
9. Shrink the size of the base image by running

   wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
   
   chmod +x ./pishrink.sh
   
   sudo ./pishrink.sh <path-to-the-base-image>/GTernal_base_image.img
   

   e.g., sudo ./pishrink.sh ~/GTernal_base_image.img

3 - Clone the Base Image

1. Insert a new SD card into your computer to load the base image.
2. Identify the name of the SD card by running

   sudo fdisk -l
   

3. Run

   sudo mount | grep <device-name>
   

   e.g. sudo mount | grep /dev/sdb to check if any of the partitions of the SD card is mounted.
   If the output is not blank, run

   sudo umount <device-name1> <device-name2> ... <device-nameN>
   

   e.g. sudo umount /dev/sdb1 /dev/sdb2
   to unmount all listed partitions of the device.
4. Load the SD card with the base image by running

   sudo dd if=<path-to-the-base-image>/GTernal_base_image.img of=<name-of-the-sd-card> status=progress
   

   e.g., sudo dd if=~/GTernal_base_image.img of=/dev/sdb bs=4M status=progress
   

Note

The status message may stop updating at some point. Please continue waiting for the write process to finish.

5. Load as many SD cards as needed with the base image. More detailed instructions on cloning an SD card image can be found here: https://beebom.com/how-clone-raspberry-pi-sd-card-windows-linux-macos/

4 - Load the Raspberry Pi with the Default firmware

This section assumes that:

1. You have micro-SD cards loaded as detailed in the previous section.
2. You have fully assembled robots.

Note

Check if the Pi and Teensy are connected through UART. If the Pi is not connected with a programmed Teensy as instructed in Step 1, the firmware will not be started by the setup script properly in the following steps.

3. Only the new robots to be setup are connected to the WiFi.

Warning

The current automatic setup script looks for all robots with the MAC addresses specified in 'GTernal/config/mac_list.json' file and starts the setup process for the robots. Therefore, it will start the setup process even for the robots already with the firmware installed if they are connected to the WiFi. Since this may cause problems for the existing robots, it is advised to only turn on the new robots to be set up.

1 - Firmware Docker Image Setup

The "docker_run.sh" script makes each robot pull the firmware image from either Docker Hub of a local Docker registry instead of building the firmware docker image directly on each robot. This saves a lot of time when building multiple robots. Also, with "v2tec/watchtower" image running on the robots, each robot downloads and runs the newest firmware image uploaded to the Docker Hub automatically. Therefore, it is unnecessary to manually update the firmware of each robot when a new firmware image is built and pushed to Docker Hub/local Docker registry.

1 - Build the Base Firmware Image

1. Inspect and update the environment variables in config/env_variables.sh
2. Build the base image

   cd <path-to-parent-directory>/GTernal/docker/base_image/
   ./docker_build.sh
   

2 - Tag the Base Image and Push it to a Docker Registry

2.1 - Docker Hub (Online)

1. Log into the Docker Hub with

   docker login
   

2. Run

   cd <path-to-parent-directory>/GTernal/docker/base_image/
   ./docker_push.sh
   

2.2 - Local Docker registry (Local)

1. Start a local Docker registry

   cd <path-to-parent-directory>/GTernal/docker/
   ./docker_registry.sh
   

2. Run

   cd <path-to-parent-directory>/GTernal/docker/base_image/
   ./docker_push_local.sh
   

3 - Build the Firmware Image

1. Build the firmware image

   cd <path-to-parent-directory>/GTernal/docker/
   ./docker_build.sh
   

4 - Tag the Firmware Image and Push it to a Docker Registry

4.1 - Docker Hub (Online)

1. Run

   cd <path-to-parent-directory>/GTernal/docker/
   ./docker_push.sh
   

4.2 - Local Docker registry (Local)

1. Run

   cd <path-to-parent-directory>/GTernal/docker/
   ./docker_push_local.sh
   

2 - Robot Setup

1. Insert the loaded micro-SD cards to the robots' Raspberry Pis and power the robots up using the switch on each PCB. They should automatically connect to the wifi specified in Step 3.7.

2. On your computer, check if all the Raspberry Pis are connected to the WiFi router by running

   sudo arp-scan -I <network-device-name> -l -t 100 -r 5
   

   e.g., sudo arp-scan -I enp4s0 -l -t 100 -r 5

   Check if the number of Raspberry Pis found by the above command matches the total number of Raspberry Pis being set up. Wait a few more minutes and check again if not all Pis show up in the list.

Note

The <network-device-name> can be found by running 'ifconfig' command into the terminal. There may be multiple network devices on your computer. The right device is the one connected to the same WiFi network as the Raspberry Pis. Typically, the local IP address assigned by a network router is '192.168.x.x' or '10.0.x.x.'

3. Assign an unallocated robot ID# for the MAC address of a Raspberry Pi found in the previous step. Then, add/replace the robot ID# and the MAC address of the Raspberry Pi in 'GTernal/config/mac_list.json'

Note

When assigning an index to a new robot, assign an Aruco tag ID or the ID engraved on a Vicon hat plate. Make sure not to use any numbers that are already assigned to other robots. The lasercutting design files for the Vicon hats can be found in GTernal/GTernal_design_files

4. Start the setup process by running

   cd path-to-parent-directory/GTernal/interfacing
   ./setup.sh setup_from_base <#-of-robots-being-set-up>
   

   e.g., ./setup.sh setup_from_base 10

   When prompted 'Enter secrets for robots,' enter the password for the Raspberry Pis, 'raspberry'

Note

The config/mac_list.json file of the robots will be updated to the config/mac_list.json file on your computer via SCP.

5 - Test Robots

1. Clone the mqtt_broker repo

   git clone https://github.com/robotarium/mqtt_broker.git
   

2. Run the MQTT broker Docker container

   cd <path-to-parent-directory>/mqtt_broker/docker/
   ./docker_run.sh <ip-address-of-your-computer>
   

3. Clone the vizier repository with

   git clone https://github.com/robotarium/vizier.git
   

4. Install vizier with

   cd path-to-parent-directory/vizier
   python3 -m pip install .
   

5. Check the status of a robot with

   python3 -m vizier.vizier --host <ip-address-of-MQTT-host> --get <robot#>/status
   

   e.g., python3 -m vizier.vizier --host 192.168.1.8 --get 21/status

6. Send a motor command to a robot with

   python3 -m vizier.vizier --host <ip-address-of-MQTT-host> --publish matlab_api/<robot#> '{"v":1.0,"w":0.0}'
   

   e.g., python3 -m vizier.vizier --host 192.168.1.8 --publish matlab_api/21 '{"v":1.0,"w":0.0}'

   "v" and "w" are the desired linear and angular velocity of the robot, respectively. With this command, the robot will stop after 1 second for safety purposes.