Skip Navigation

System Setup

For this milestone, you will connect your Raspberry Pi to the Internet. Once connected, you will switch to the CCU tealpi5 kernel, configure 3D graphics support, charge the RTC battery, and enable the display of boot messages during system startup.

Page Contents

Milestone Worksheet

Please download the following worksheet Milestone 3. To be sure your browser downloads the file instead of trying to open it, right-click the following link and choose “Save As,” “Save Link As,” or similar language from the menu. (Each browser is a little different in what wording it uses.)

Background

Please read the following background lessons:

As you complete these readings, fill in the top part of the Milestone Worksheet.

Procedure

Step 1: Boot the Pi

Boot the Raspberry Pi either by plugging it into power (if unplugged) or pressing the power button (if plugged in). Log in as the root user, using the password you set in the previous milestone.

Step 2: Connect to the Network

If you have an Ethernet cable and can plug your Pi directly into your router, a network switch, or an Ethernet port, follow the Wired Network instructions. If you’re going to use your home WiFi or the hotspot on your phone, follow the WPA PSK Wireless Network instructions. If you’re on campus (or are connecting to a similar WPA Enterprise system), follow the Eduroam Network instructions.

Wired Network

Configuring a wired network is quite simple. Use an Ethernet cable to connect your Pi to the network, then run:

setup-interfaces

In this interactive script, do the following:

  1. You’ll be prompted to set up eth0 first. Just press Enter to accept eth0 when asked which interface to set up.
  2. Press Enter again to accept the default value of “dhcp” for the IP address.
  3. When prompted for wlan0, type done and press Enter.
  4. Press Enter one more time to answer n to doing any manual network configuration.

Once you have your configuration done, start and enable the network service by running:

rc-service networking start
rc-update add networking

WPA PSK Wireless Network

To connect to a WPA wireless network that uses a pre-shared key, like the kind you probably have at home or on your cell phone hotspot, we’re going to use iwd in standalone mode, which will handle both the wireless authentication and the DHCP client tasks.

First, we need to enable standalone mode by editing /etc/iwd/main.conf:

vi /etc/iwd/main.conf

Most of the things we need are already present in this file, but they’re commented out by default. Do the following:

  1. Remove the ‘#’ (comment sign) before the [General] section heading.
  2. Uncomment EnableNetworkConfiguration=True
  3. Uncomment the [Network] section heading.
  4. Uncomment NameResolvingService=resolvconf

Unless you know that your network uses IPv6 addresses (unlikely), add the following line to the [Network] section:

EnableIPv6=false

Save and exit Vi.

Now you can start and enable both the dbus and iwd services. The iwd service requires the dbus service, so start it first:

rc-service dbus start
rc-service iwd start
rc-update add dbus
rc-update add iwd

To connect to your home network or cell phone, run the following command:

iwctl

This command is interactive and is basically its own shell. Be sure the wlan0 device is visible and powered on by running:

device list

In the unlikely event that the device is not powered on, run:

device wlan0 set-property Powered on

Now we need to scan for wireless networks:

station wlan0 scan

Wait a minute for the scan to finish, then list the results using:

station wlan0 get-networks

The results may jump around a little if scanning is still in progress. Find the SSID of your home network or cell phone hotspot, and run:

station wlan0 connect SSID

Replace SSID with the SSID of your network. Enter the network password when prompted.

Wait a minute for the connection to be established, then run:

device wlan0 show
station wlan0 show

Check that the second command shows that an IP address has been received from the network. If not, you might have mistyped your network password.

Once you’re connected, you can quit iwctl using:

exit

Eduroam Wireless Network

To connect to a WPA Enterprise network like eduroam on campus, we’re going to use iwd in standalone mode, which will handle both the wireless authentication and the DHCP client tasks.

First, we need to enable standalone mode by editing /etc/iwd/main.conf:

vi /etc/iwd/main.conf

Most of the things we need are already present in this file, but they’re commented out by default. Do the following:

  1. Remove the ‘#’ (comment sign) before the [General] section heading.
  2. Uncomment EnableNetworkConfiguration=True
  3. Uncomment the [Network] section heading.
  4. Uncomment NameResolvingService=resolvconf

CCU eduroam is an IPv4-only network, so add the following line to the [Network] section:

EnableIPv6=false

Save and exit Vi.

To configure the eduroam network, we need to create an iwd configuration file from scratch by running:

vi /var/lib/iwd/eduroam.8021x

In that file, type in the following. Replace USER@coastal.edu with your CCU email address, and replace PASSWORD with your CCU password.

[Security]
EAP-Method=PEAP
EAP-Identity=USER@coastal.edu
EAP-PEAP-Phase2-Method=MSCHAPV2
EAP-PEAP-Phase2-Identity=USER@coastal.edu
EAP-PEAP-Phase2-Password=PASSWORD

[Settings]
AutoConnect=true

Now you can start and enable both the dbus and iwd services. The iwd service requires the dbus service, so start it first:

rc-service dbus start
rc-service iwd start
rc-update add dbus
rc-update add iwd

Wait a minute, then run:

ip a s

If you connected successfully, you will see an IPv4 “inet” address in your wlan0 output (typically in the 10.something range).

Troubleshooting iwd

If you’re running into any problems connecting with iwd, run:

tail /var/log/messages

Look for lines that contain iwd, and see if you can determine the problem from the error message. More likely than not, your password or email address (if using eduroam) has been entered incorrectly. WPA PSK networks can be fixed by running the iwctl command again. To make changes to the eduroam network, you will need to edit its configuration file and then restart the iwd service (rc-service iwd restart).

Step 3: Configure Software Repositories and Set the Time

Since we used a custom Alpine Linux installation environment, we were able to perform an offline installation of the distribution. Offline installations aren’t actually supported with the official installers, so the process of setting up software repositories in our installed environment is a little different from the normal method. While we’re at it, let’s go ahead and add the CCU tealrepo software repository so that we can install a nicer kernel.

Recall from the background reading that we need an RSA public key for the CCU software repository. Since we’re using the custom Alpine Linux distribution that I built for this class, the RSA key is already present. Verify by running:

ls /etc/apk/keys

Be sure the teal-repo@coastal.edu-66dcca7c.rsa.pub file is present.

Now edit the /etc/apk/repositories file using Vi, and change it to read:

https://dl-cdn.alpinelinux.org/alpine/v3.21/main
https://dl-cdn.alpinelinux.org/alpine/v3.21/community
https://mirror.coastal.edu/tealrepo/packages/v3.21
@testing https://dl-cdn.alpinelinux.org/alpine/edge/testing

Save the file and exit Vi. Now, notice in the above set of repositories that we’re using HTTPS for the download protocol. HTTPS uses Transport Layer Security (TLS) certificates to secure the connection. Each TLS certificate has a set of dates in it, including the date at which the certificate becomes valid and the date at which the certificate expires. Most TLS certificates are valid for a period of up to a year or so. Run the following command to check the current date and time setting on your Pi:

date

If you have a brand new Pi, it is probably pretty close to January 1, 1970 right now, meaning that your TLS certificates won’t be valid until over 50 years from now. We need to fix this issue by fast-forwarding the Pi’s Real Time Clock (RTC) to today’s date. Look at your phone or another computer to get a reasonably accurate date and time for today. If it’s currently in the afternoon, you need to convert the current time into 24-hour (or military time). Thus, if the current time is 1:45 PM, then the current 24-hour/military time is 13:45. To set the date, use something like this command:

date -s '2025-02-07 13:45'

Change the above date and time to match the current date and time!

Be sure you don’t get any error messages with the above command. If it is successful, the newly set date and time will be printed in a friendly format (like “Fri Feb 7 12:07:00 EST 2025”). Right now, we have set the time only for the operating system. We need to save this time in the Raspberry Pi’s RTC by running:

hwclock --systohc

Once the time is set, update the repository metadata by running:

apk update

You should see where the metadata have been downloaded for all 4 repositories. The last line of the output should start with “OK:” and provide the total number of packages available across all repositories. If you get an error message and something about a permission denied error and the words “SSL,” then your clock isn’t set correctly. Otherwise, check your Internet connection if you see a different error message.

Step 4: Switch to the tealpi5 Kernel

Out of the box, Alpine Linux on the Raspberry Pi is using the “rpi” kernel. This kernel is a long-term support (LTS) kernel that has patches specific to the Raspberry Pi applied to it.

Take a look at /boot/config.txt by running:

cat /boot/config.txt

This file contains 4 effective lines (ones that are not comments or blanks). The line that begins with kernel= specifies the name of the kernel to boot, and it has a corresponding initial ramdisk (initfs) file on the initramfs line. 64-bit CPU features are enabled by another line, and then the usercfg.txt file is included from the last line.

A number of files, including various device tree binary (.dtb) files in the /boot directory, will be overwritten by a new kernel package. For this reason, we must do a slightly risky change of kernel, in which we uninstall the Alpine-provided rpi kernel and install the CCU-provided tealpi5 kernel. To accomplish this switch, run the following commands, and be sure they complete successfully! Without an installed kernel, your Pi will NOT boot!

apk del linux-rpi
apk add linux-tealpi5

Look at the /boot/config.txt file again:

cat /boot/config.txt

Verify that the kernel and initramfs files now end in -tealpi5.

If everything looks OK, reboot to the new kernel:

reboot

After the Pi reboots, log in as root, and run:

uname -r

Verify that the kernel ends in -tealpi5, indicating that you’re using the CCU kernel.

Step 5: Enable 3D Graphics and RTC Battery Charging

To get the newer, better supported 3D graphics driver working on the Raspberry Pi, we need to edit some boot-time device tree configurations. While we’re doing these edits, we might as well also enable charging of the RTC battery. To make these changes, run:

vi /boot/usercfg.txt

You will see a brand new, empty file. Put the following lines into it:

dtparam=audio=on
dtparam=rtc_bbat_vchg=3000000
dtoverlay=vc4-kms-v3d
max_framebuffers=2
disable_fw_kms_setup=1

These lines do the following things:

  1. Enable HDMI audio support.
  2. Charge the RTC battery at 3 volts (3,000,000 microvolts).
  3. Enable the 3D driver.
  4. Enable both HDMI ports.
  5. Leave the graphics setup to the Linux kernel.

Double-check that you haven’t made an errors, since errors in this file could cause your Pi not to boot properly or otherwise malfunction. Be especially careful that you typed in 6 zeroes after 3 for the rtc_bbat_vchg value.

Save and exit Vi.

Step 6: Install the 3D Driver

Run the following command:

apk add mesa-dri-gallium

Be sure that command completes successfully, indicating that the 3D driver has been installed. Test by rebooting the Pi:

reboot

After the Pi reboots, log in as root, then run:

ls /dev/dri/card0

If the /dev/dri/card0 file is present, then you have successfully configured 3D graphics. If you get a “no such file or directory” error, then check your /boot/usercfg.txt file, as you probably have an error in it.

Also check that your RTC battery is charging by running:

cat /sys/class/rtc/rtc0/charging_voltage

If you see a value of 0, then you did not enable charging successfully. Check the rtc_bbat_vchg line in your /boot/usercfg.txt file. Note that you need to reboot the Pi for any changes to that file to take effect.

Step 7: Display Startup Messages

When you reboot the Pi, notice it goes directly to a login prompt after booting, and we can’t see the startup messages. This situation is caused by the fact that our initial ramdisk, which is used by Alpine Linux to load kernel drivers before we have the root filesystem mounted, doesn’t have the graphics drivers included. To fix this issue, we need to add the “kms” feature to our initfs. To do this, run:

vi /etc/mkinitfs/mkinitfs.conf

Edit the features line to look like this:

features="base mmc usb ext4 kms"

Now we need to rebuild the initial ramdisk. Save the mkinitfs.conf file, exit Vi, and run the following command:

mkinitfs

Step 8: Edit cmdline.txt

The second thing we need to do in order to display startup messages is to tell the kernel to initialize the first console (called tty1), so that the messages get routed correctly. To do this, run:

vi /boot/cmdline.txt

This file already contains a pretty long line. Move the cursor to the end of the line. Be careful not to change anything on the existing line, but add the following to the end of the line:

console=tty1 brcmfmac.roamoff=1 brcmfmac.feature_disable=0x282000

The console setting will display the startup messages, while the second two parameters will disable some firmware features related to WiFi. These features are currently buggy and serve to reduce WiFi reliability. Be careful when typing! Misspelling something on the kernel command line could cause problems later.

Save the file and exit Vi. Restart the Pi by running:

reboot

You should see the startup messages at boot time.

Submission Guidelines

To prepare your submission photo for this assignment, run the following commands:

hostname
cat /etc/alpine-release
uname -a
ip a s
ls /dev/dri/card0

Check Your Work

Verify the following from the output of the commands you just ran:

  1. Your hostname is in the form username-csci311.coastal.edu, where username is the part of your CCU email address before the @ sign.
  2. The Alpine release is 3.21.
  3. You are running the -tealpi5 kernel.
  4. Your Pi is connected to a network an has an IPv4 address (inet address in the ip a s output).
  5. The /dev/dri/card0 file is present, indicating that 3D graphics support is enabled.

Prepare Your Submission

Use your phone to take a photo of your screen, since you don’t yet have a screenshot tool available on the Pi. Transfer the photo to your computer, and replace the placeholder image in the Milestone Worksheet with your photo. Export the worksheet to PDF format, and upload the PDF to Moodle as the submission for the Milestone 3 assignment activity.

As a reminder, here are the instructions for editing the worksheet in either LibreOffice or Word Online:

Turn Off the Pi

When you’re finished working on the milestone, shut down the Raspberry Pi properly by running the following command:

poweroff

The Pi is shut down correctly when its status light changes from green to red. You may unplug the Pi after it has shut down, and it will start up again the next time you plug it in. Alternatively, you can leave the Pi plugged in. The status light (which should be red at this point) is also the power button on the official Pi case, so pressing it will turn on the Pi if power is connected.

ABET Assessment

Successful completion of this assignment satisfies the following performance indicator: