|
| 1 | +# Raspberry Pi Setup Guide |
| 2 | + |
| 3 | +## Install Raspberry Pi OS onto MicroSD card |
| 4 | + |
| 5 | +### Introduction |
| 6 | + |
| 7 | +The microSD card in a Raspberry Pi holds its Operating System and acts as its primary storage area. The Pi will not work without it. |
| 8 | + |
| 9 | +The Raspberry Pi 5 is compatible with many different (primarily Linux-based) operating systems. The one we use is the standard Raspberry Pi OS (also Linux-based). |
| 10 | + |
| 11 | +### Install OS Using Raspberry Pi Imager |
| 12 | + |
| 13 | +To install the Raspberry Pi OS onto a microSD card, we use the Raspberry Pi Imager program. Install it [here](https://www.raspberrypi.com/software/). |
| 14 | + |
| 15 | +*Note: if using the "Download for Linux" option, you will have to right click on the installed `.AppImage` file and select `Properties` → `Permissions` → `Allow Executing File as Program` (this may appear as a checkbox) |
| 16 | + |
| 17 | +When you open the imager, you should see something like this: |
| 18 | + |
| 19 | +* <img width="402" height="159" alt="image" src="https://github.com/user-attachments/assets/b31e03e3-0d25-4b99-b0d5-0168387f715d" /> |
| 20 | + |
| 21 | +Once installed, follow these steps to set up the Raspberry Pi: |
| 22 | +1. Plug the microSD card into your device. |
| 23 | + * If your device has an SD card slot, use a microSD to SD card adapter. This adapter is available in the tbots EDC space as of Jan 2026. |
| 24 | + * If your device only has a USB slot, use a combination of a microSD to SD card adapter and USB SD card reader. Again, both of these adapters are available in the tbots EDC space. |
| 25 | +2. Open and configure the Raspberry Pi Imager program as follows: |
| 26 | + * Raspberry Pi Device: Raspberry Pi 5 |
| 27 | + * Operating System: Raspberry Pi OS (64-bit) |
| 28 | + * Storage: `<your_inserted_micro_SD_card>` |
| 29 | + * Customization: |
| 30 | + * Hostname: `<robot_name>`.local (Ex: `aimbot`.local). The `local` part is autofilled by the Raspberry Pi Imager. |
| 31 | + * Localization → Timezone: America/Vancouver |
| 32 | + * User → Username: robot |
| 33 | + * User → Password: `<password>` (ask someone if you don't know what the correct password is) |
| 34 | + * WiFi → Secure Network → SSID: `<tbots_wifi_name>` (`tbots` as of Jan 2026) |
| 35 | + * WiFi → Password: `<password>` (ask someone if you don't know what the correct password is) |
| 36 | + * Remote Access: Enable SSH and select "Use Password Authentication" |
| 37 | + * Click the "Write" button and wait until complete |
| 38 | + |
| 39 | + Once the write process is complete, the Raspberry Pi OS is set up! You can verify the write was successful using several methods; the following is only one of these methods: |
| 40 | + * Connect the Raspberry Pi to an HDMI output screen using a microHDMI to HDMI cable. |
| 41 | + * You can also use an HDMI to HDMI cable with a microHDMI to HDMI adapter. We have one of these adapters in the tbots EDC space as of Jan 2026. |
| 42 | + * The output screen on the HDMI should appear similar to a default laptop/PC screen. If this is the case, the write was successful. |
| 43 | + * If you do not see the above, and instead see text on a black screen with messages akin to "Unable to read partition as FAT" - the write was not successful. |
| 44 | + |
| 45 | +## Configure Raspberry Pi with Thunderbots Service |
| 46 | + |
| 47 | +### Introduction |
| 48 | + |
| 49 | +We use the Raspberry Pi OS, which is based on the Linux kernel. The Linux kernel uses systemd as its service manager. Our core service is [thunderloop.service](https://github.com/UBC-Thunderbots/Software/blob/master/src/software/embedded/linux_configs/systemd/thunderloop.service). |
| 50 | + |
| 51 | +To run and manage the thunderloop service on the Pi, however, there are many dependencies (drivers, admin control, internet, etc.) that must be set up first. Luckily, all of this setup can be done using one command with an Ansible playbook. |
| 52 | + |
| 53 | +Read more about Ansible in our robot software architecture documentation [here](https://github.com/UBC-Thunderbots/Software/blob/master/docs/robot-software-architecture.md#ansible). |
| 54 | + |
| 55 | +### Configuration |
| 56 | + |
| 57 | +#### Internet Configuration |
| 58 | + |
| 59 | +Before running the Ansible command, we must do the following to configure internet access to the Pi: |
| 60 | +1. Ensure your Raspberry Pi is connected to internet through an ethernet cable. Do this by connecting one end to the Rapsberry Pi and the other to your device (PC/laptop). Ensure your ethernet cable is not broken, as there are many non-functioning ones in the Thunderbots EDC space. |
| 61 | +2. On your device (PC/laptop), configure network settings through the following steps: |
| 62 | + 1. Go to network settings. You should see something like this: |
| 63 | + |
| 64 | + * <img width="446" height="77.5" alt="image" src="https://github.com/user-attachments/assets/20f9b3e5-e629-40c7-ac49-024f34df66ca" /> |
| 65 | + |
| 66 | + 2. Click the settings icon on the right (seen in the image above). |
| 67 | + 3. Under the IPv4 tab, select "Shared to other computers" |
| 68 | + |
| 69 | + * <img width="471.5" height="132.5" alt="image" src="https://github.com/user-attachments/assets/ee776fbc-7fec-4e7d-89da-35b48de4df4f" /> |
| 70 | + |
| 71 | + 4. Under the IPv6 tab, select "Disable" |
| 72 | + * <img width="471.5" height="132.5" alt="image" src="https://github.com/user-attachments/assets/7ad2cba4-42bf-4204-a182-a087e7f632e2" /> |
| 73 | + |
| 74 | + 5. Apply changes |
| 75 | +3. Enable IP forwarding from your device to the Pi with the following command (this has to be reconfigured every time you boot your device): |
| 76 | +```bash |
| 77 | +sudo sysctl -w net.ipv4.ip_forward=1 |
| 78 | +``` |
| 79 | +4. Enable Network Address Translation (NAT) between your Pi and device with the following commands (this has to be reconfigured every time you boot your device): |
| 80 | +```bash |
| 81 | +sudo iptables -t nat -A POSTROUTING -o wlo1 -j MASQUERADE |
| 82 | +sudo iptables -A FORWARD -i eno2 -o wlo1 -j ACCEPT |
| 83 | +sudo iptables -A FORWARD -i wlo1 -o eno2 -m state --state RELATED,ESTABLISHED -j ACCEPT |
| 84 | +``` |
| 85 | + |
| 86 | +#### Thunderloop Service Configuration Through Ansible |
| 87 | +1. SSH into the Raspberry Pi from your device by connecting to the `tbots` WiFi and typing the following in the command terminal: |
| 88 | + * ssh `robot@<robot_name>` (Ex: `ssh robot@aimbot.local`) |
| 89 | + * enter the password when prompted |
| 90 | +2. Verify that the Pi has internet connection by pinging Google's Public DNS Service with the following command: |
| 91 | +```bash |
| 92 | +ping -c 3 8.8.8.8 |
| 93 | +``` |
| 94 | + * If successful, you should see all packets transmitted and received at some point in the return message. Ex: ```3 packets transmitted, 3 received, 0% packet loss, time 2004ms```. |
| 95 | + * If not successful, you will see packets not received. Ex: ```3 packets transmitted, 0 received, 100% packet loss, time 2052ms```. |
| 96 | +3. Exit the SSH connection to the Raspberry Pi with the `exit` command. |
| 97 | +4. Change directory to `Software/src` and run the bazel ansible command: |
| 98 | +```bash |
| 99 | +bazel run //software/embedded/ansible:run_ansible --platforms=//toolchains/cc:robot --//software/embedded:host_platform=PI -- --playbook setup_pi.yml --hosts <robot_name>.local --ssh_pass <robot_password> |
| 100 | +``` |
| 101 | + * Ensure you configure `<robot_name>` and `<password>` in the command above. Copy/pasting the above won't work. |
| 102 | + * This may take a while. |
| 103 | +5. Done! |
| 104 | + |
| 105 | +### Common Errors and Debugging |
| 106 | + |
| 107 | +**Cannot SSH into Pi** |
| 108 | +A: Confirm that your device is connected to the `tbots` WiFi |
| 109 | + |
| 110 | +**Raspberry Pi shuts off (light turns red, HDMI output disconnects if connected) while the Bazel Ansible command is running** |
| 111 | +A: This is a power brownout (voltage drops below required threshold). There are too many peripherals connected. Disconnect some and try again. |
| 112 | + |
| 113 | +**Raspberry Pi unresponsive and LED always solid green** |
| 114 | +A: This is usually an indicator that the Pi's SD Card is corrupted or empty. Operational Raspberry Pi's usually have a flickering LED. Fix by reprovisioning the SD Card with the Raspberry Pi Imager (directions above). |
| 115 | + |
| 116 | + |
| 117 | + |
| 118 | + |
| 119 | + |
| 120 | + |
| 121 | + |
![pre-commit-ci-lite[bot]](https://avatars.githubusercontent.com/in/257897?v=4&size=40){kind=avatar}
0 commit comments