Debugging Reterminal Issues

Debugging Reterminal Issues#

So far, there have been two primary causes for the reTerminal screen to stop working:

  1. System update using apt: during the semester, some changes that break raspberry pi and reTerminal compatibility are introduced, necessitating another update and another run of the Display driver fix scripts.

  2. Errors introduced from mistakes when editing firmware files like /boot/firmware/*.txt and/or /boot/cmdline.txt and/or /boot/config.txt

  3. Errors introduced from an incomplete upgrade (interrupted before finishing).

In the first case, the reTerminal boots just fine, but the screen doesn’t work. In the second and third cases, the reTerminal fails to boot at all.

For each of these cases, I have a set of troubleshooting steps you can take to resolve these issues.

If you can ssh into your reTerminal#

Most likely it is the case that your reterminal is still connecting to the internet and accessible over ssh, even when the screen is not working.

  1. Double check that you can see your reterminal in tailscale by running tailscale status on your developer machine. ssh into the device using this IP address.

    1. If for some reason your device is offline on tailscale, try to determine its local ip address using your router webpage (at home). ssh into reterminal using this ip address

  2. Once you have an ssh connection, follow the steps from the course notes: Display driver fix scripts

If you cannot ssh into your reTerminal#

Finding the problem#

  1. Ask the teacher for a micro-usb to HDMI connector

  2. Plug the HDMI end into a workstation monitor, and the micro-usb end into your reTerminal (in the port labelled HDMI)

  3. Plug your reTerminal into a power supply to boot the reTerminal

  4. The monitor will show logs of your reTerminal booting. Observe these logs closely. You are looking for specific error messages.

  5. Write down the specific error messages. Search the course notes for any concepts you don’t understand. Think back: have you made any changes to the /boot files that seem related to these errors?

  6. If you have a good idea of what happened and what needs to be fixed, proceed to the next section. Feel free to double check your understanding with the teacher at this point – for educational purposes, I may not give you the answer directly, but I can guide you in a direction that will help save you some time.

Solving /boot/ firmare file problems#

If indeed the error comes from an incorrect /boot configuration file setting, we can fix the error without reimaging the pi. Instead, we will mount the reTerminal storage on to a workstation and then fix the firmware files directly on that workstation.

The steps will look similar to Lab 1, except we won’t be reimaging the device at the end. You should open Reterminal Setup instructons for reference while you are working. The following steps will be necessary:

  1. Make sure your reTerminal is entirely unplugged and powered off.

  2. Disassemble your reTerminal, up to the step where you can toggle the Firmware Flash switch. Toggle the switch. This step will let you mount the storage device onto your workstation.

  3. On your lab workstation, find the program rpibootloader and run it. You should not need elevated access.

  4. While the rpibootloader program is running, plug your reTerminal into the workstation using a USB-C to USB-3 connector.

  5. You should see the rpibootloader acknowledge connection to your reterminal. A dozen or so logs will be printed to the rpibootloader program window. Once this is done: navigate to Windows Explorer (the file manager) and you should see the reTerminal (~28-32GB) as a connected drive on the workstation

  6. You can now access all files on the reterminal filesystem.

  7. The firmware files can now be edited directly to fix any mistakes made.

  8. Just in case, you can also recover any files you need that are stored on the reterminal in the /home/your-username directory.

Contents