- Install Teensyduino (https://www.pjrc.com/teensy/td_download.html)
- 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.
- 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.
- Run Teensyduino and open 'defaultOperation.ino' located in 'GTernal/firmware/defaultOperation' directory.
- Select the Teensy board to be flashed under 'Tools > Port'
- Click the upload icon (right arrow icon).
- Install and run the Raspberry Pi Imager (https://www.raspberrypi.com/software/). The instuction is for Raspberry Pi Imager v.1.8.5
- For 'Raspberry Pi Device,' select the version of the Pi used.
- For 'Operating System,' select 'Raspberry Pi OS (other)' and select 'Raspberry Pi OS Lite (64-bit).' For Raspberry Pi Zero 1s, select 'Raspberry Pi OS Lite (32-bit)'
- For 'Storage,' choose the micro-SD card to be used.
- Click 'NEXT' and 'EDIT SETTINGS.'
- Under 'GENERAL' tab, check 'Set username and password' and type 'pi' for the 'Username' and 'raspberry' for 'Password.'
- Next, check 'Configure wireless LAN' and enter 'SSID' and 'Password' for the router.
- Change 'Wireless LAN country' to 'US.' 'Set locale settings' is optional.
- Under 'SERVICES' tab, check 'Enable SSH' and 'Use password authentication'
- Click 'SAVE' and click 'YES.'
- Produce as many micro-SD cards as the number of robots to be built.
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.'
This section assumes that:
- You have loaded micro-SD card(s) with the Raspberry Pi OS as previously detailed.
- 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.
- Only the new robots to be setup are connected to the WiFi.
Important
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, t is recommended to only turn on the new robots to be set up.
Important
It is recommended to only turn on the new robots to be set up. 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 recommended to only turn on the new robots that need to be set up.
-
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 2.7. The Pi needs some time to boot for the first time.
-
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 5e.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 robots 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.'
- 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. For more information about generating Vicon hats, see https://github.com/skim743/gritsbotx_vicon_hats
- Replace lines 12 and 13 in 'GTernal/docker/docker_run.sh' with the IP address and port of the MQTT host.
Note
The default GTernal firmware requires an MQTT broker. For more information about the MQTT broker, please refer to https://github.com/robotarium/mqtt_broker.
-
Start the setup process by running
cd path-to-parent-directory/GTernal/interfacing ./setup.sh <#-of-robots-being-set-up>e.g., ./setup.sh 10
When prompted 'Enter secrets for robots,' enter the password for the Raspberry Pis, 'raspberry'
The robots will reboot after the setup process.
This section details the manual installation process for the firmware. This process is unnecessary if the automatic setup in the previous section is performed.
Remove plymouth with
sudo apt-get purge --remove plymouth
Disable unused services with
sudo systemctl disable triggerhappy.service
sudo systemctl disable hciuart.service
sudo systemctl disable keyboard-setup.service
sudo systemctl disable dphys-swapfile.service
This section follows from the official (Docker)[https://docs.docker.com/install/linux/docker-ce/ubuntu/]. First, remove old versions of Docker.
sudo apt-get remove docker docker-engine docker.io
Next, install Docker using the convenience script.
curl -fsSL get.docker.com -o get-docker.sh && export VERSION=23.0 && sh get-docker.sh
Now tie Docker to the pi user so that we don't need sudo to use Docker.
sudo usermod -aG docker pi
Install pip for python3
sudo apt-get install python3-pip
To clone the firmware, run
sudo apt-get install git
git clone https://github.com/robotarium/gritsbot_2
Also, install the MAC discovery repository
git clone https://github.com/robotarium/mac_discovery
as well as the python serial library used to communicate to the robot.
python3 -m pip install pyserial
Turn off power management by adding the line
/sbin/iw dev wlan0 set power_save off
in the file /etc/rc.local. This line disables WiFi power management on boot.
From wherever the git repository is cloned, run
cd <path_to_gritsbot_2_repo>/docker
./docker_run.sh
./docker_watch.sh
which will permanently start a Docker container running the firmware and the watchtower container. Watchtower watches containers and automatically updates them from Dockerhub. This watchtower instance checks and updates all running containers, so this instance will also update the MAC container as well.
Start MAC discovery as well with
cd <path_to_mac_discovery_repo>/docker
./docker_run.sh
- Clone the vizier repository with
git clone https://github.com/robotarium/vizier.git
- Install vizier with
cd path-to-parent-directory/vizier
python3 -m pip install .
- 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 1884 --get 21/status
- 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 1884 --publish matlab_api/21 '{"v":1.0,"w":0.0}'
"v" and "w" are the desired linear and angular velocity of a robot, respectively. With this command, the robot will stop after 1 second for safety purposes.