Prepare a Raspberry Pi device

In this tutorial we will prepare a Raspberry Pi with a custom Raspberry Pi OS (previously called Raspbian) image. The only difference from the official Raspberry Pi OS image is that it has been converted to support robust system updates with Mender.

Completing this tutorial normally takes less than one hour.

Prerequisites

To follow this tutorial, you will need the following:

• One of these Raspberry Pi models:
  • Raspberry Pi 3 Model B
  • Raspberry Pi 3 Model B+.
  • Raspberry Pi 4 Model B.
• An 8 GB or larger microSD card.
• A Raspberry Pi universal power supply or a compatible USB cable.
• Internet connectivity for your Raspberry Pi (either Ethernet or WiFi available)

Step 1 - Flash the Raspberry Pi

Download the Raspberry Pi OS image ready for Mender:

• Download link: Raspberry Pi 3 Model B and B+
• Download link: Raspberry Pi 4 Model B

Follow the steps outlined in the Raspberry Pi OS documentation to flash the OS image to the device.

We recommended to use the Raspberry Pi Imager tool, choose "Use custom" and browse to the downloaded Mender Raspberry Pi OS image.

Option #1: Configure your Raspberry Pi in headless mode

You can take advantage of the headless configuration options of Raspberry Pi to enable SSH or to configure the wireless network. This saves you the hassle of connecting a monitor and keyboard after your device has booted, as it will come up with WiFi and SSH already working and you can just SSH into it from your workstation.

First off, insert the SD card you flashed above and find the boot partition inside it. Open a terminal on your workstation and verify that it can be accessed in the default location:

RPI_BOOT="$(awk '/media.*boot(fs)?/ { print $2; }' /proc/mounts)"
[ ! -d "$RPI_BOOT" ] && echo "ERROR: RPI boot directory not found"

RPI_BOOT="$(find /Volumes/ -maxdepth 1 -name boot -or -name bootfs)"
[ ! -d "$RPI_BOOT" ] && echo "ERROR: RPI boot directory not found"

If this outputs nothing you can continue. If you get the ERROR, find out where the SD card's boot partition is accessible and change the RPI_BOOT variable accordingly.

With the path to the boot directory set up, we first configure the default user and password:

USERNAME='' # CHANGE: your desired username
PASSWORD="$(openssl passwd)"

cat << EOF > "$RPI_BOOT"/userconf.txt
${USERNAME}:${PASSWORD}
EOF

We then configure networking. Assuming you have a typical WiFi setup, change the initial three variables and run this code block:

WIFI_SSID='' # CHANGE: your WiFi name
WIFI_PASS='' # CHANGE: your WiFi password
COUNTRY='US' # CHANGE: two-letter country code, see https://en.wikipedia.org/wiki/ISO_3166-1

cat << EOF > "$RPI_BOOT"/wpa_supplicant.conf
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=$COUNTRY

network={
         ssid="$WIFI_SSID"
         psk="$WIFI_PASS"
}
EOF

Finally, enable SSH by creating an empty file:

touch "$RPI_BOOT"/ssh

Last but not least, unmount the boot partition to make all the changes are synced to it safely:

umount "$RPI_BOOT"

Now disconnect the SD card, insert it into your Raspberry Pi and boot it.

If you have a different network setup or encounter any issues, please see the official Raspberry Pi documentation on headless setups.

Option #2: Configure your Raspberry Pi with a keyboard and monitor attached

If you did headless (Option #1 above) skip to Step 2 below.

Boot the Raspberry Pi with the newly flashed SD card. Attach a keyboard and monitor.

Follow the start-up wizard to:

• Select keyboard layout
• Set up your user and password.

Then, log in with your new user and password and do the following steps to set up WiFi:

• Run sudo raspi-config
• Select Localisation Options, then WLAN Country. Select the correct country code.
• Select System Options, then Wireless LAN. Set the SSID and passphrase for the network
• Choose Finish

Check that your Raspberry Pi is connected to the Internet (e.g. ping www.google.com). If this does not work, please see the official Raspberry Pi documentation on network configuration.

Now do the following steps to set up SSH:

• Run sudo raspi-config
• Navigate to Interface Options and Select SSH
• Choose Yes, OK and Finish

If you encounter any issues, see Enable local SSH access in the official Raspberry Pi documentation for more information.

Step 2 - SSH into the Raspberry Pi

Your Raspberry Pi should now be booted, connected to the network and have the SSH daemon running, regardless if you followed the headless approach (Option 1) or connected a keyboard and monitor directly (Option 2).

If you do not know the IP address of your Raspberry Pi device, there are some great resources in the Raspberry Pi OS documentation on different ways of looking this up.

SSH into your device:

ssh <your-login>@<DEVICE-IP-ADDRESS>

You should now see a command prompt similar to the following:

<your-login>@raspberrypi:~ $

Keep this terminal open as we will shortly use it to install the Mender Client.

Step 3 - Login to hosted Mender

Login to hosted Mender. On the main page for the first time new users will get a tutorial in the Mender web GUI.

Go to the Dashboard tab and click on Connect a device.

Step 4 - Connect a device

Select PREPARE AND CONNECT MY RASPBERRY PI.

Step 5 - Choose device type

You need to specify one of the following:

• Raspberry Pi 3
• Raspberry Pi 4

Step 6 - Install the Mender Client on the device

Next we will install the Mender Client on the device and connect it to the Mender server.

In the dialog box from above, click Copy to clipboard to copy the code to install the Mender Client. Now go to the command line on your device, and paste the code e.g. by right-clicking in the terminal and selecting Paste, followed by Enter.

This downloads the Mender Client on the device, configures and starts it.

Step 7 - Accept the device

Once the client has started, the Mender Client will attempt to connect to the server and it will appear in your Pending devices tab in the server. Go ahead and Accept the pending device in the server. After accepting the device, it will appear on the Device groups tab on the left of Pending.

Next step

Proceed to Deploy an application update.