Configuring SSH, UART and WiFi access on Mender-enabled Raspbian images

Introduction

When working with the Raspberry Pi platform and Mender, one of the first steps many users take is to enable some or all of the following:

  • UART
  • SSH
  • Wifi

This can be done on first-boot using either the GUI tools or command-line utilities. This can be tricky because you may rely on these features to access the device and to enable them at runtime will require adding a USB keyboard, mouse and display which many users do not use.

An alternative is to set these features up for headless mode. The instructions from the Raspberry Pi documentation do not work with Mender-enabled images as we have modified the partition layout to support dual-rootfs updates.

Manual Setup

To make these changes manually, do the following:

Step 1

Run mender-convert as normal.

Step 2

Remove the SD Card and reinsert it into your laptop or desktop development system. If your system is configured to automatically mount removable devices then you need to determine which directories have been mounted. With Ubuntu 18.04 they are generally mounted under /mnt/user/blah.

If your OS is not configured to automatically mount removable devices, you will need to mount them manually. Consult your system documentation for more information.

Step 3

Create files on the SD Card to configure the headless mode. Make sure to set the environment variables as appropriate for your system and target wifi network.

Environment variables:

BOOT_MOUNT=/media/user/boot
ROOTFS1_MOUNT=/media/user/rootfs1
ROOTFS2_MOUNT=/media/user/rootfs2
SSID=wifi-ssid-here
 PASSPHRASE='wifi-passphrase-here'
COUNTRY_CODE=us

Code:

echo "enable_uart=1" >> ${BOOT_MOUNT}/config.txt
sudo touch ${ROOTFS1_MOUNT}/boot/ssh
sudo touch ${ROOTFS2_MOUNT}/boot/ssh
cat > ./wpa_supplicant.conf <<EOF 
country=${COUNTRY_CODE}
update_config=1
ctrl_interface=/var/run/wpa_supplicant
EOF
 wpa_passphrase ${SSID} ${PASSPHRASE} | grep -v '#psk' >> ./wpa_supplicant.conf
sudo cp wpa_supplicant.conf ${ROOTFS1_MOUNT}/boot
sudo mv wpa_supplicant.conf ${ROOTFS2_MOUNT}/boot

Integrating with mender-convert

You can also integrate these settings directly into your mender-convert setup using a user_local_modify hook. Create a file in your mender-convert directory named mender_local_config containing the following, making sure to update the variables as needed for your configuration.

function user_local_modify() {
    set +u
    if [ -n "${RASPBERRYPI_BINARIES}" ]; then
        # Setup your configuration here
        SSID=wifi-ssid-here
        PASSPHRASE=wifi-passphrase-here
        COUNTRY_CODE=us
        # End of configuration

        # Enable ssh using Raspbian Headless
        run_and_log_cmd "sudo touch work/boot/ssh"
        run_and_log_cmd "sudo ln -fs /uboot/ssh work/rootfs/boot/ssh"

        # Copy my WPA credentials
        cat > ./wpa_supplicant.conf <<-EOF
            country=${COUNTRY_CODE}
            update_config=1
            ctrl_interface=/var/run/wpa_supplicant
            EOF
        wpa_passphrase ${SSID} ${PASSPHRASE} | grep -v '#psk' >> ./wpa_supplicant.conf
        run_and_log_cmd "sudo mv ./wpa_supplicant.conf work/boot/wpa_supplicant.conf"
        run_and_log_cmd "sudo ln -fs /uboot/wpa_supplicant.conf work/rootfs/boot/wpa_supplicant.conf"

        # Enable other RPI basics in config.txt
        run_and_log_cmd "echo '' | sudo tee -a work/boot/config.txt"
        run_and_log_cmd "echo 'enable_uart=1' | sudo tee -a work/boot/config.txt"
    fi
    set -u
}

Now make sure to add --config mender_local_config to your command line when invoking mender-convert.

Conclusions

Setting up headless mode on your Raspberry Pi devices running the Raspberry Pi OS will make it easy to connect and access the device, even when you do not use a USB keyboard and mouse.