Reterminal setup

Reterminal setup#

Overview#

This page documents the general steps needed to perform an initial set up, or reset, of the reTerminal device that we will be using throughout the class.

The general steps are:

Install necessary dependencies for reimaging a Pi on a host computer
Reimage and configure the reTerminal’s operating system.
Connect to the reTerminal remotely and ensure the remote connection services are working:
1. Graphical desktop session using a VNC client.
2. CLI session using ssh

These instructions are mostly adapted from the instructions available at [@GettingStartedReTerminal2023].

Prerequisites#

You can perform this lab on any computer that you are able to run applications with “elevated permissions”.

on the Lab computers, you will need to use the “run with elevated permissions” mode at a few steps. This will be explained in class.
on a personal Windows machine, you can follow all of these instructions normally, using “admin” mode when prompted for elevated permissions.
if you are using a personal macOS or Linux machine, I have not written the instructions with you in mind – you can do this lab, but make sure to adjust the instructions to your OS accordingly

Hardware required#

You need to prepare the following hardware before getting started with reTerminal:

Ethernet cable or Wi-Fi connection
USB Type-C cable
reTerminal kit case, containing
- small screw driver (black handle)
- reTerminal power adapter

Software required#

There are two tools to install for this lab:

Raspberry Pi (RPi) USB Device Boot daemon
Raspberry Pi Imager

Instructions for installing each follow below.

Elevated Permissions

We will sometimes need elevated permissions in order to install or operate software.

On the Lab Computers, you can achieve elevated permissions by right-clicking on the executable and selecting the option: “Run with elevated access”.
- You will be asked for your college username and password.
  - Click on the password field to get focus (the program doesn’t focus on the password by default, which is very annoying)
- You will then be asked for a reason for elevating permissions. Copy-paste: “6P3-W25 Raspberry Pi Setup”
On your personal computers, the options will depend on your OS:
- Windows: The same as the Lab Computers, but use “Run as administrator” instead.
- macOS/Linux: use your terminal environment to run the executable and sudo to elevate your permissions

RPi USB Device Boot installation#

The instructions for installing and using this software vary greatly depending on your host operating system.

You can find all instructions in the README of the repository for the software: raspberrypi/usbboot.

I’ve adapted those instructions for each possible operating system in the section below.

Windows

Download the repository source code using git clone.
- Use your developer environment, i.e. your WSL instance, to do this (not git bash)
(important) Move the cloned usbboot folder to your home directory in the C:\ drive
- Pro tip: do this in the terminal using the mv command, e.g. mv /path/to/usbboot /mnt/c/Users/Michael.Haaf/Downloads
in Windows Explorer, locate rpiboot_setup.exe within the usbboot/win32/ directory.
Run the executable with elevated permissions (see [@nte-elevated])
- If the software has already been installed, press Yes to overwrite the existing installation
- By doing so, we will ensure that the software is the latest version (which will be important).
Raspberry pi drivers will begin to be installed on your computer.
- This process takes a few minutes. Keep the window open and move on to the next steps in the lab.
When this process is finished, you should now have the folder C:\Program Files (x86)\Raspberry Pi\ on your computer.

macOS/Linux

(On macOS / Linux): read the README of the repository and follow those instructions instead.

WSL

Not recommended at this time.

Raspberry Pi Imager installation#

Follow software from the official Raspberry Pi website.. This software is straightforward to install.
NOTE: this should already be installed on the Lab computers. Check to see if Raspberry Pi Imager is an application you can open before installing.

Reimage the reTerminal#

Below is a brief overview of the three step process for reimaging the reTerminal:

Disassemble the back cover and flip a switch to have direct access to the eMMc storage
- Do not disassemble the entire device! It is only necessary to remove the heatsink.
Reimage and configure the OS using the Raspberry Pi Imager software.
Return the memory selector switch to the original position and reassemble.

reTerminal Disassembly#

**Only remove the heatsink** in order to access the memory switch. It is *not* necessary fully disassemble the reTerminal like they do in the video.#

Watch the video in @fig-dissasembly to understand the disassembly process (2 mins).
Follow Steps 1, 2, & 3 in the reTerminal documentation to remove the heatsink. Flash Raspberry Pi OS/ 64-bit Ubuntu OS or Other OS to eMMC. Use the following hardware from your reTerminal kit:
- small screw driver (black handle)
- kit case (store the plastic nubs and removed screws in your case. Don’t lose the screws!)

After the following the above steps, you will have:

removed the heatsink
toggled the eMMc memory switch (see @fig-flash-mode).

Your reTerminal is now ready for a firmware flash.

Memory select switch behind the reTerminal’s heatsink in the “down” position.

New OS image & Configuration#

To re-image the reTerminal, follow the steps below.

Launch `rpiboot`#

Double check you have finished the installation
Launch the rpiboot executable file with elevated permissions (see [@nte-elevated])
- On Windows, this should be C:\Program Files (x86)\Raspberry Pi\rpiboot.exe
- On a personal macOS/Linux: I think it’s rpiboot.sh in the installation directory, but check the project README to be sure
Keep the rpiboot window open throughout the next steps of this lab.

After launching, you should see a terminal window with something like the following dialog appear:

RPIBOOT: build-date Jan 22 2023 version 20221215-105525 864863bc
Waiting for BCM2835/6/7/2711...

The rpiboot program creates a daemon (a dedicated background process) that will detect when a reTerminal device is connected in flash mode (i.e. the eMMc switch toggled “down” as in @fig-flash-mode).

Connect the reTerminal to the USB port of your machine.#

Find a USB-C to USB 3.0 Cable and plug it into a 3.0 port on your computer.
- USB-C to USB-C is also fine.
Plug the other end of the cable into your reTerminal
- NOTE: if the screen of the reTerminal turns on when you plug in the USB cable, you have missed a step in the disassembly process. In this case, stop, unplug the device, and read the previous instructions more carefully.
rpiboot will detect and attach the reTerminal’s internal memory as a storage device.
At this stage, you should see some dialog appear in the RPIBOOT program:

Sending bootcode4.bin…
Received 4 bytes
somethingsomethingsomething
Etc. etc.
Loading startup.elf file
Warning: file not interpreted as such-and-such
Finished

Your output will not exactly match the example I have provided. Here are some guidelines:

The program may close on its own, or may not. Either way is fine.
You can ignore the “warnings” that appear at the end of the logs.
You can ignore the “There is a problem with this drive” Windows notification.
The program should NOT repeatedly loop at Sending bootcode4.bin...
- if this is the case, and no other messages appear, try the previous steps again, make sure you pay attention to details.

Basically, unless the program is stuck in a loop, you should continue to the next step.

Run Rasperry Pi (RPi) Imager#

Run the program on your desktop with elevated permissions (see [@nte-elevated])
Before making any selections, press Control+Shift+X to open the “OS Customizations” Advanced Options menu.
Make the following customizations (you will need to click through all 3 tabs at the top).
- Set a unique hostname (suggestion: your github username)
- Enable SSH with password authentication.
- Set a unique username and password.
  - Do not use the defaults or forget these. You will need to reimage your reTerminal if you do.
- Configure the wireless LAN for the lab network:
  - SSID: P326-hotspot
    - NOTE: there is no whitespace. Take care your SSID matches exactly.
  - Password: 6P3-W25-pallet-overcast
    - NOTE: take care your password matches exactly
  - Wireless LAN country: CA
- Set locale settings: America/Montreal
- Disable telemetry.
- Enable “eject media” and “play sound when finished”.
- Take note of your hostname, username, and password (see Moodle for place to enter this information)
  - You will be responsible for maintaining your system.
  - If you get locked out, you may have to re-image the system.
- Press “SAVE” when finished.
Once you’ve finished making the above customizations, there are three main configuration choices to make:
- Raspberry Pi Device: Raspberry Pi 4
- Operating System: Raspberry Pi OS 64-bit (Recommended)
- Storage: RPi-MSD-0001 (31.3GB). DO NOT SELECT ANY OTHER STORAGE DEVICE.
  - If this storage device does not appear, you need to re-do the rpiboot steps
Once Raspberry Pi Images starts, writing the image to the reTerminal’s memory can take 10-15 minutes.
- Do not disconnect the reTerminal during flashing!

Reassembly#

Once the writing and verification process is completed, disconnect the USB-C cable from the reTerminal.
Return the memory select switch to the original position. (Do you know why? If not, Reread the part about why we toggled it down in the first place!)
Don’t re-assemble the heatsink+terminal cover yet – we have a few more steps to take first.
Plug the raspberry pi into the wall using the Pi Power Supply cable in your reTerminal kit. You may need an extension cord/power bar– you can find one at the front of the class.

First Boot#

Your reTerminal has been re-imaged! Make sure you have completed the reassembly steps, particularly that you have toggled the memory select switch back up to normal boot mode.

At this point, we are now going to start running commands directly on the reTerminal itself. Follow the steps below:

Plug your reTerminal into the wall using the power supply. There are power bars in the lab that you can use if you need more outlets.
- In general, the reTerminal is powered using the provided power supply in your lab kit.
Plug your reTerminal into the lab monitor using the provided microHDMI to HDMI converter
Plug your reTerminal into the ethernet using the lab computer ethernet.
Plug the lab keyboard and mouse into your reterminal USB.

On first boot, your reTerminal screen will not turn on – this is why we need the microHDMI connection to the external monitor.

The first task we need to take care of is fixing the reTerminal screen display drivers.

Display driver fix#

Once your are logged into the reTerminal and you can see the display on the lab monitor, follow the steps below:

Read and follow the steps outlined here: “Install reTerminal drivers after flashing new Raspberry Pi OS/ Ubuntu OS or Other OS”, up to and including sudo reboot.
- NOTE: recall that you have installed a 64-bit OS on your reTerminal. Do not follow any 32-bit OS steps in the above instructions.
If the above steps have been completed successfully, your device should reboot and BOTH the raspberry pi screen AND the HDMI connection should work (this takes several seconds, give it a minute before you panic).
- Make sure your Pi is connected to the wall power supply, NOT to your computer (the pi screen needs more power than your lab computer can provide).

If your keyboard is in French mode on the raspberry pi, you can follow the instructions here to set it back into English (US) mode.

Update & Upgrade#

A good first step for any OS installation is to ensure all system packages are at the latest version.

Follow the three steos in the official guide for the reTerminal FAQ Wiki: How to upgrade Raspberry Pi OS and the installed packages - For any steps that ask you to make a choice, just pick the defaults.

Set up Remote connections#

Going forward, we want to be able to use the reTerminal without having to plug it into an external monitor.

Fixing the device screen was one step – however, we would also like to be able to use the reTerminal without relying on the small touchscreen either.

We are going to rely on remote connections to the reTerminal in general in this class – that is, connecting to the reTerminal using an IP Address.

Because the lab network has firewalls, however, we cannot do so directly using the lab ethernet or the campus WIFI.

To fix this problem, we are going to use a remote networking tool called Tailscale. Follow the steps below:

Set up Tailscale#

First, create an account on Tailscale. You have the following choices for authentication:

(Recommended) Your GitHub account
Your school email address

If you’re curious to know more about Tailscale before you sign up, please ask me! You can also read about it here:

In the big picture: Tailscale will allow us to establish direct remote connections between our raspberry Pi and our developer environments by creating a Wireguard VPN mesh network for us.

To be clear, Tailscale is free, you will not need any of the paid features.

After you have made an account, you will need to set it up on your pi and your developer environments, see instructions below.

On the raspberry pi#

Follow these instructions

You can do the “Install with one command” step, OR follow the manual steps if you prefer.

NOTE: you will probably need to also run the following command on your raspberry pi:

sudo apt install curl

On your lab computer#

Install on your WSL by Following these instructions
- You can do the “Install with one command” step, OR follow the manual steps if you prefer.
ALSO install on the main Windows machine by following these instructions
- You may need to use elevated permissions for this, see [@nte-elevated]

NOTE: you will probably need to also run the following command on your WSL:

sudo apt install curl

On your personal computer#

Depending on your operating system:

Windows:
- Install on your WSL by Following these instructions
- You can do the “Install with one command” step, OR follow the manual steps if you prefer.

NOTE: you will probably need to also run the following command on your WSL:

sudo apt install curl

macOS: Follow these instructions
Linux: Follow these instructions

You can do the “Install with one command” step, OR follow the manual steps if you prefer.

Verify your tailscale setup#

On either your lab/personal developer environment, OR your raspberry pi, run the command:

tailscale status

You should see the IP address for both your reTerminal AND your lab/personal developer environment. Take note of these IP addresses before moving on to the next steps.

Set up VNC#

In this section you will connect to the graphical desktop environment remotely using a VNC session. This will allow you to control the raspberry pi from your lab computer over the graphical shell of the lab computer, in addition to SSH.

Once connected to the provided power cable, the reTerminal will boot and automatically login into the graphical desktop environment as the default user.
The reTerminal has a touch screen which you are welcome to use for the next steps. However, I recommend plugging in your lab keyboard and/or mouse for these next few steps. Let me know if you need a keyboard/mouse.
Enable the VNC client in the Raspberry Pi Configuration menu.
- Click on the Raspberry Pi icon (top right).
- Select Preferences > Raspberry Pi Configuration.
- Open the Interfaces tab.
- Enable the VNC server (disabled by default).
Open a terminal on your Raspberry Pi. Double check your IP address using tailscale status
At your lab computer, start the VNC Viewer client (RealVNC). You can run this program without elevated access.
- RealVNC is already installed on the lab computers. If working on a personal device, you can install it here
- NOTE: you DO NOT need to make an account or sign up for RealVNC. There is an option to
Connect to your Raspberry Pi using VNC Viewer in your lab computer.
Enter the hostname you assigned to your Raspberry Pi in Part 1, step 5 or the IP address you noted in step 5.
1. Use the username and password you configured in Part 1, step 5.

Set up SSH#

The SSH server inside your Raspberry Pi should already be enabled by default (from Part 1, step 5).

To double check that the ssh server is enabled on your Pi: follow the official instructions on Setting up the SSH Server on the Raspberry Pi.

Connecting over CLI#

You can establish an SSH connection to the reTerminal from your developer environment. If your connection is successful you should see the a similar prompt:

user-name@hostname:~ $

where hostname and user-name correspond to the choices you made during your imaging of the pi.

Follow the official Raspberry Pi instructions (NOTE: Linux instructions apply to WSL!) Secure Shell from Linux or Mac OS

For Lab 3, I ask you to obtain the reTerminal’s MAC address.

You can do so running ifconfig command in an ssh session, and checking the properties of the wireless network card (wlan0):

Run the command ifconfig or the command ip address
Look for the wireless network adapter wlan0:
The MAC address will be listed there.I
- Style points: use grep and pipe to grab the MAC address directly to your clipboard

Connecting over VSCode#

You can use VS Code in your lab workstation to create a development environment inside the Raspberry Pi which will be controlled from the lab workstation.

If you would like to know more about how this extension works, visit Remote Development using SSH.

Below is a 5min video that illustrates how the Remote - SSH extension works:

VS Code Remote Development using SSH to a Raspberry Pi

In your lab workstation, ensure you have installed the following VS Code extensions:
1. Remote - SSH, by Microsoft.
2. Python extension, by Microsoft.
Connect your lab workstation to your Raspberry Pi by following the Remote - SSH extension’s official instructions: Getting started. Once VS Code is connected to the reTerminal, you are now in a new development environment inside the reTerminal. Complete the following tasks:
Install the VS Code Python extension (this time inside the reTerminal, not in your lab workstation like in step 1).
1. If necessary, follow the guide: Getting Started with Python in VS Code
On the Raspberry Pi, open the folder lab1 in the home directory of the reTerminal (created in Part 3, step 4).
Create a new file named lab-script.py inside the folder lab1 and include the code:
1. print(‘Hello from inside the pi!’)
Execute your code from within VS Code using the play button.

Categories

Reterminal setup

Contents

Reterminal setup#

Overview#

Prerequisites#

Hardware required#

Software required#

RPi USB Device Boot installation#

Raspberry Pi Imager installation#

Reimage the reTerminal#

reTerminal Disassembly#

New OS image & Configuration#

Launch `rpiboot`#

Connect the reTerminal to the USB port of your machine.#

Run Rasperry Pi (RPi) Imager#

Reassembly#

First Boot#

Display driver fix#

Update & Upgrade#

Set up Remote connections#

Set up Tailscale#

On the raspberry pi#

On your lab computer#

On your personal computer#

Verify your tailscale setup#

Set up VNC#

Set up SSH#

Connecting over CLI#

Connecting over VSCode#

Categories

Reterminal setup

Contents

Reterminal setup#

Overview#

Prerequisites#

Hardware required#

Software required#

RPi USB Device Boot installation#

Raspberry Pi Imager installation#

Reimage the reTerminal#

reTerminal Disassembly#

New OS image & Configuration#

Launch rpiboot#

Connect the reTerminal to the USB port of your machine.#

Run Rasperry Pi (RPi) Imager#

Reassembly#

First Boot#

Display driver fix#

Update & Upgrade#

Set up Remote connections#

Set up Tailscale#

On the raspberry pi#

On your lab computer#

On your personal computer#

Verify your tailscale setup#

Set up VNC#

Set up SSH#

Connecting over CLI#

Connecting over VSCode#

Launch `rpiboot`#