Raspberry Pi Setup and Provisioning

Raspberry Pi Setup and Provisioning

This page will go over how to set up and provision the Raspberry Pi, or any other microprocessor that PiE is using. As long as the microprocessor is capable of running some distro of Linux that uses apt-get as the package manager (Raspbian, Ubuntu, Debian, and many others), this setup will apply.

When preparing a set of Raspberry Pi's to distribute to the students during competition, there are two distinct steps: setup and provisioning. Setup refers to getting Runtime working on a singular Raspberry Pi from a clean installation of the OS that will be used on the Raspberry Pi. Provisioning refers to copying the micro SD card of the fully setup Raspberry Pi onto many other Raspberry Pis, one for each team that will be participating in the competition, plus a few extra as backup and/or testing.

Setting up the Raspberry Pi (or any microprocessor) involves the following steps:

1. Downloading the image of an appropriate OS for the Raspberry Pi onto your computer
2. Flashing an 8 GB micro SD card with the image downloaded in step 1
3. Opening a terminal into the computer (with Raspberry Pi, this can be done immediately using ssh)
4. Installing Runtime's dependencies
5. Cloning the Runtime Github repo onto the Raspberry Pi
6. Building Runtime
7. Setting up systemd to start Runtime on boot

Provisioning the Raspberry Pi's involves the following steps:

1. Copying the contents of the micro SD card in an already-setup Raspberry Pi onto your computer (this requires 8 GB of space)
2. Flashing the contents of that micro SD card onto additional micro SD cards
3. Deleting and re-cloning the Runtime Github repo
4. Building Runtime
5. Performing any additional setup operations for a specific team, such as setting the team router network SSID and password

Setting up the Raspberry Pi

1) Downloading the image of an appropriate OS for the Raspberry Pi onto your computer

In the past, Runtime has used both the OS that is specially made for the Raspberry Pi (Raspbian) and the most popular Linux distro available (Ubuntu). Both of them work equally well. Raspbian can be found here and Ubuntu can be found here.

When downloading, make sure to download the "Lite" version (for Raspbian a.k.a. Raspberry Pi OS) or the "Server" version (for Ubuntu). This is because the full versions of either OS also contain the GUI and unnecessary software for Runtime (like default applications for desktop use). Runtime won't be needing these--we won't be using the GUI, we just need the OS.

2) Flashing an 8 GB micro SD card with the image downloaded in Step 1

This refers to taking the OS image that you downloaded in Step 1 and writing it to a micro SD card. This micro SD card will then be inserted into a Raspberry Pi so that the Raspberry Pi can use the OS.

Download BalenaEtcher, an app available on both macOS and Windows specifically for writing disk images to SD cards: website.

Once downloaded and installed on your computer, insert the micro SD card to be flashed into your computer using an adapter. Then, open BalenaEtcher and select the micro SD card and the downloaded image, then hit the "Flash!" button. The micro SD card should begin flashing immediately. This will take a while (writing 8 GB of data is not easy!).

On the Raspberry Pi running vanilla Raspbian, ssh is disabled by default. You need to first add an empty file with the name ssh in the root directory of the disk image downloaded in Step 1 before flashing it to the micro SD card in order to enable ssh immediately on bootup. This will become very important in Step 3!

3) Opening a terminal into the computer

This is the trickiest part of the setup process. Depending on the microprocessor being used (Raspberry Pi, Le Potato, something else), and the OS being used, the process that you use might be very different.

To ssh into a computer, you need to know 3 things: the name of the user that you want to ssh in as, the password of the user on the computer, and either the IP address of the computer OR the hostname of the computer (if the computer has avahi-daemon installed). The ssh command works like this:

ssh <username>@<IP address>
ssh <username>@<hostname>.local

If your computer is not able to find a computer at the specified IP address or the specified hostname on the local network, ssh will hang indefinitely. Use the ping command to try to debug this issue, or going into your router settings to try to find the device you're looking for in its list of connected clients. If the user that you specified doesn't exist on the device, ssh will exit with an error.

On the Raspberry Pi, do the following:

• Get a network switch and connect it via Ethernet cable to a router (it doesn't matter if it's connected to the Internet or not, although it would probably be convenient if the router is connected to the Internet)
• Connect the Raspberry Pi to the network switch with an Ethernet cable
• Connect your computer to the network switch with an Ethernet cable
• If running Raspbian, the default hostname is raspberrypi and the default user is pi. If running Debian, the default hostname is ubuntu and the default user is ubuntu. Use these to ssh into the computer.
• If this fails, log in to your router's admin page and find the list of connected clients. Look for the Raspberry Pi (hostname raspberrypi or ubuntu) and note its IP address. Use this IP address in your ssh command to get into the Raspberry Pi.

On the Le Potato, do the following:

• Get a mini HDMI-HDMI cable, a wired mouse, and a wired keyboard. Plug the mouse and keyboard into the Potato, and plug the HDMI cable into a monitor.
• Plug in the Potato and the monitor
• The Potato should boot up and display a terminal on the monitor
• Log in to the Potato using the default password of a ubuntu user, then change the password following the prompts to PiE's preferred password for the potatoes
• Change the hostname of the Potato using hostnamectl set-hostname <new_hostname> so that you know the hostname of the Potato
• Install avahi-daemon using sudo apt-get install avahi-daemon
• Reboot the machine
• Connect the Potato, your computer, and a router to a network switch, the same as above with the Raspberry Pi
• ssh into the Potato from your computer using the hostname you set as the hostname and ubuntu as the default user

4) Installing Runtime's dependencies

From this step on, you can follow the instructions on the README.md page in the Runtime Github repo for installing Runtime. This step consists of basically running a bunch of sudo apt-get commands, installing Cython using pip, and getting and compiling the protobuf-c library from the Internet.

5) Cloning the Runtime Github repo onto the Raspberry Pi

Now it's time to get the Runtime code onto the device. Simply run the command git clone https://github.com/pioneers/runtime.git in the home directory of the default user of the Raspberry Pi, such that the Runtime code is at ~/runtime (/home/pi/runtime on Raspbian, and /home/ubuntu/runtime on Ubuntu). Then run the commands git submodule init and git submodule update to obtain the *.proto files.

6) Building Runtime

cd into the runtime directory and run ./runtime build

7) Setting up systemd to start Runtime on boot

Follow the steps in the README.md in the systemd folder of the Runtime repo.

Provisioning the Raspberry Pi's

1) Copying the contents of the micro SD card in an already-setup Raspberry Pi onto your computer

To be clear, you only need to do this once. Also, this required 8 GB of space, and the commands given in this section only work on Unix-like systems (i.e. not Windows).

• Insert the micro SD card of the fully setup Raspberry Pi into your computer
• Use a disk utility to find the path of the device (on macOS, open a terminal and type diskutil list to see the attached physical devices). The microSD card should show up as something with Linux in it, with a size of a little less than 8 GB (7.95 GB or 7.9 GB is normal). This is the device that you want
• Pick a location where you want the contents of the micro SD card to be stored (I usually like to put it on Desktop or Downloads), and make note of the path to that location
• Open your terminal and run the following: dd bs=1m if=<name_of_device> of=<location_of_file>
• As an example, if my device was at /dev/disk4 and the location I want to put the file is /Users/ben/Downloads/runtime_raspi_2023_setup.img, I would run dd bs=1m if=/dev/disk4 of=/Users/ben/Downloads/runtime_raspi_2023_setup.img
• This command takes a long time!!! (10-15 minutes)

If you want to speed up the process of provisioning all of the Raspberry Pi's, have one person make the copy as detailed in this step, then have the person compress the image and upload it to Google Drive or copy it onto a USB flash drive. Then, anyone who wants to help can download the image from Google Drive or copy the image onto their computers from the USB flash drive.

2) Flashing the contents of that micro SD card onto additional micro SD cards

Use BalenaEtcher again, but this time insert a different micro SD card (that will be used to create another functioning Raspberry Pi). To reduce the chance of confusion or errors, remove the micro SD card that you used in step 1 from your computer.

• For the disk to flash, select the micro SD card you just inserted into your computer.
• For the file to flash, select the file that was created in step 1.

This flash will take a long time!! (10-15 minutes)

3) Deleting and re-cloning the Runtime Github repo

For some reason, when you make a copy of the repo in this way, Git can mess up sometimes. It's safer to simply remove the Runtime folder in the home directory and re-clone it. First ssh into the newly provisioned device, then run:

rm -rf ~/runtime
git clone https://github.com/pioneers/runtime.git

4) Building Runtime

cd into the Runtime directory and run ./runtime build

5) Performing any additional setup operations for a specific team

This includes things like changing the hostname to match the team number (i.e. Team 1 will have team1 as their hostname), entering in the information such as the router SSID and password into the Raspberry Pi so that it will connect to their team routers by default, entering in the information for the competition Wi-Fi SSID and password into the Raspberry Pi so that it will connect to the competition network during competition, and any other game-specific tasks.