Supplies

The list of parts you’ll need to put together a Raspberry Pi cluster — sometimes known as a "bramble" — can be short, or it can be quite long, depending on what size and type of cluster you intend to build. So it’s important to think about what you want the cluster to do before you start ordering the parts to put it together. The list above is what we used for our eight-Pi cluster, but your requirements might well be different.

What you will need is a full bramble of Raspberry Pi computers, and if you’re intending to power them over PoE as we are, you’ll need a corresponding number of Raspberry Pi PoE+ HAT boards and an appropriate PoE+ switch. Beyond that, however, you’ll need a micro SD card, some Ethernet cables, a USB to Ethernet adapter, a USB to SATA adapter cable along with an appropriately sized SSD drive, and some sort of case to put all the components into after you’ve bought them. The case can either be a custom-designed "cluster case" or, perhaps, something rack-mountable depending on what you’re thinking of doing with the cluster after you’ve built it.

There is however a lot of leeway in choosing your components, depending on exactly what you’re setting up your cluster to do. For instance, depending on the sorts of jobs you’re anticipating running across the cluster, you might be able to get away with using cheaper 2GB or 1GB boards rather than the 4GB model I used. Alternatively, having a local disk present on each node might be important, so you might need to think about attaching a disk to each board to provide local storage.

However, perhaps the biggest choice when you’re thinking about building a cluster is how you’re going to power the nodes. We used PoE for this cluster, which involved adding a PoE+ HAT board to each node and purchasing a more expensive switch capable of powering our Raspberry Pi boards: for larger clusters, this is probably the best approach. For smaller clusters, you could instead think about powering the nodes from a USB hub, or for the smallest clusters — perhaps four nodes or fewer — powering each node directly from an individual power supply.

Connect over wireless

We configured the head node to know about our local wireless network during setup, so we should just be able to ssh directly into the head node using the name we gave it during setup:

$ ssh <username>@pi-cluster.local

<username>@pi-cluster.local's password:
$

If we take a look at the network configuration by typing nmcli,

$ nmcli
wlan0: connected to preconfigured
        "Broadcom BCM43438 combo and Bluetooth Low Energy"
        wifi (brcmfmac), DC:A6:32:6A:16:91, hw, mtu 1500
        inet4 10.3.194.40/22
        route4 10.3.192.0/22 metric 600
        route4 default via 10.3.194.1 metric 600
        inet6 2001:4d4e:300:c2:1fd1:9c44:f362:3805/64
        inet6 fe80::a725:b6cc:ce19:3caf/64
        route6 fe80::/64 metric 1024
        route6 2001:4d4e:300:c2::/64 metric 600
        route6 default via fe80::dccc:45ff:fe78:a3cc metric 600

lo: connected (externally) to lo
        "lo"
        loopback (unknown), 00:00:00:00:00:00, sw, mtu 65536
        inet4 127.0.0.1/8
        inet6 ::1/128

eth0: disconnected
        "eth0"
        1 connection available
        ethernet (bcmgenet), DC:A6:32:6A:16:90, hw, mtu 1500

DNS configuration:
        servers: 10.3.31.1
        domains: pitowers.org
        interface: eth1

        servers: fe80::8498:d3ff:fe31:8eac
        interface: eth1

        servers: 10.3.194.1
        domains: pitowers.org
        interface: wlan0

        servers: fe80::dccc:45ff:fe78:a3cc
        interface: wlan0

$

you can see that wlan0 is connected to our local network with a 10.3.\* address, while eth0 which we’ve plugged into our switch is disconnected. We’ll resolve this later in the project by turning our head node into a DHCP server that will assign an IP address to each of the compute nodes, as well as to our smart switch.

Add a second Ethernet connection

We’ve been able to reach our head node over the network because we configured our wireless interface wlan0 when we set up our SD card. However, it would be good to hardwire our cluster to the network rather than rely on wireless, because we might want to transfer large files back and forth, and wired interfaces are a lot more stable. To do that we’re going to need an additional Ethernet connection, so I’m going to add a USB 3-to-Gigabit Ethernet adaptor to the head node. We’ll leave the onboard Ethernet socket (eth0) connected to our PoE switch to serve as the internal connection to the cluster, while we use the second Ethernet connection (eth1) to talk to the outside world.

In most cases eth1 will be activated automatically by Network Manager, and pick up an IP address from our LAN’s DHCP server. After plugging in our adaptor we should see something like this,

eth1: connected to Wired connection 2
        "Realtek RTL8153"
        ethernet (r8152), 00:E0:4C:68:1D:DA, hw, mtu 1500
        ip4 default, ip6 default
        inet4 10.3.31.194/24
        route4 10.3.31.0/24 metric 100
        route4 default via 10.3.31.1 metric 100
        inet6 2001:4d4e:300:1f:6f2a:f4b1:65a8:b420/64
        inet6 fe80::7a88:6d47:4554:bd80/64
        route6 fe80::/64 metric 1024
        route6 2001:4d4e:300:1f::/64 metric 100
        route6 default via fe80::8498:d3ff:fe31:8eac metric 100

added to the results of typing nmcli on the command line.

We’ll leave eth0, the onboard Ethernet socket, connected to the Ethernet switch to serve as the internal connection to the cluster. Internally we’ll allocate 192.168.50.*/24 addresses to the cluster, with our head node having the IP address 192.168.50.1.

$ sudo nmcli con mod "Wired connection 1" ipv4.addresses 192.168.50.1/24 ipv4.method manual
$ sudo nmcli con down "Wired connection 1"
$ sudo nmcli con up "Wired connection 1"

Then, if everything has gone to plan, you should see something like this:

$ nmcli
eth1: connected to Wired connection 2
        "Realtek RTL8153"
        ethernet (r8152), 00:E0:4C:68:1D:DA, hw, mtu 1500
        ip4 default, ip6 default
        inet4 10.3.31.194/24
        route4 10.3.31.0/24 metric 100
        route4 default via 10.3.31.1 metric 100
        inet6 2001:4d4e:300:1f:6f2a:f4b1:65a8:b420/64
        inet6 fe80::7a88:6d47:4554:bd80/64
        route6 fe80::/64 metric 1024
        route6 2001:4d4e:300:1f::/64 metric 100
        route6 default via fe80::8498:d3ff:fe31:8eac metric 100

wlan0: connected to preconfigured
        "Broadcom BCM43438 combo and Bluetooth Low Energy"
        wifi (brcmfmac), DC:A6:32:6A:16:91, hw, mtu 1500
        inet4 10.3.194.40/22
        route4 10.3.192.0/22 metric 600
        route4 default via 10.3.194.1 metric 600
        inet6 2001:4d4e:300:c2:1fd1:9c44:f362:3805/64
        inet6 fe80::a725:b6cc:ce19:3caf/64
        route6 fe80::/64 metric 1024
        route6 2001:4d4e:300:c2::/64 metric 600
        route6 default via fe80::dccc:45ff:fe78:a3cc metric 600

eth0: connected to Wired connection 1
        "eth0"
        ethernet (bcmgenet), DC:A6:32:6A:16:90, hw, mtu 1500
        inet4 192.168.50.1/24
        route4 192.168.50.0/24 metric 101
        inet6 fe80::a5a8:6819:ddc6:6b2f/64
        route6 fe80::/64 metric 1024

lo: connected (externally) to lo
        "lo"
        loopback (unknown), 00:00:00:00:00:00, sw, mtu 65536
        inet4 127.0.0.1/8
        inet6 ::1/128

DNS configuration:
        servers: 10.3.31.1
        domains: pitowers.org
        interface: eth1

        servers: fe80::8498:d3ff:fe31:8eac
        interface: eth1

        servers: 10.3.194.1
        domains: pitowers.org
        interface: wlan0

        servers: fe80::dccc:45ff:fe78:a3cc
        interface: wlan0

$

Configure the DHCP server

Now we have a "second" Gigabit Ethernet connection out to the world via eth1, and our onboard Ethernet is configured with a static IP address, it’s time to make our Raspberry Pi into a DHCP server for our cluster on eth0. Start by installing the DHCP server itself:

$ sudo apt install isc-dhcp-server

and then edit the /etc/dhcp/dhcpd.conf file as follows:

ddns-update-style none;
authoritative;
log-facility local7;

# No service will be given on this subnet
subnet 10.3.31.0 netmask 255.255.255.0 {
}

# The internal cluster network
group {
   option broadcast-address 192.168.50.255;
   option routers 192.168.50.1;
   default-lease-time 600;
   max-lease-time 7200;
   option domain-name "cluster";
   option domain-name-servers 8.8.8.8, 8.8.4.4;
   subnet 192.168.50.0 netmask 255.255.255.0 {
      range 192.168.50.20 192.168.50.250;

      # Head Node
      host cluster {
         hardware ethernet dc:a6:32:6a:16:90;
         fixed-address 192.168.50.1;
      }

   }
}

Then edit the /etc/default/isc-dhcp-server file to reflect our new server setup:

DHCPDv4_CONF=/etc/dhcp/dhcpd.conf
DHCPDv4_PID=/var/run/dhcpd.pid
INTERFACESv4="eth0"

as well as the /etc/hosts file:

127.0.0.1	localhost
::1		localhost ip6-localhost ip6-loopback
ff02::1		ip6-allnodes
ff02::2		ip6-allrouters

127.0.1.1	cluster

192.168.50.1	cluster

and then you can reboot the head node to start the DHCP service.

We’ve set things up so that known hosts that aren’t known are allocated an IP address starting from 192.168.50.20. Once we know the MAC addresses of our compute nodes we can add them to the /etc/dhcp/dhcpd.conf file so they grab static IP addresses going forward rather than getting a random one as they come up. Logging back into your head node after the reboot if you have a managed switch for your cluster, like the NETGEAR switch I’m using which will grab an IP address of its own, you can check your DHCP service is working:

$ dhcp-lease-list
Reading leases from /var/lib/dhcp/dhcpd.leases
MAC                IP              hostname       valid until         manufacturer
==================================================================================
80:cc:9c:94:53:35  192.168.50.20   GS308EPP       2021-12-06 14:19:52 NETGEAR
$

Otherwise, you’ll have to wait until you add your first node as unmanaged switches won’t request their own address. However, if you do have a managed switch, you might well want to give it a static IP address inside the cluster by adding one to the /etc/dhcp/dhcpd.conf and /etc/hosts files in a similar fashion to the head node. I went with switch as the hostname:

192.168.50.1	cluster
192.168.50.254	switch

and 192.168.50.254 as the allocated IP address:

subnet 192.168.50.0 netmask 255.255.255.0 {
   range 192.168.50.20 192.168.50.250;

   # Head Node
   host cluster {
      hardware ethernet dc:a6:32:6a:16:90;
      fixed-address 192.168.50.1;
   }

   # NETGEAR Switch
   host switch {
      hardware ethernet 80:cc:9c:94:53:35;
      fixed-address 192.168.50.254;
   }
}

Add an external disk

To network boot our compute nodes, we’re going to need a bit more space. You could do this by plugging a flash stick into one of the USB ports on the head node, but I’m going to use a USB 3 to SATA Adaptor Cable to attach a 1TB SSD that I had on the shelf in the lab to give the cluster plenty of space for data. Plugging the disk into one of the USB 3 sockets on the head node I’m going to format it with a GUID partition table, and a creat single ext4 partition on the disk.

$ sudo parted -s /dev/sda mklabel gpt
$ sudo parted --a optimal /dev/sda mkpart primary ext4 0% 100%
$ sudo mkfs -t ext4 /dev/sda1
mke2fs 1.46.2 (28-Feb-2021)
Creating filesystem with 244175218 4k blocks and 61046784 inodes
Filesystem UUID: 1a312035-ffdb-4c2b-9149-c975461de8f2
Superblock backups stored on blocks:
	32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632, 2654208,
	4096000, 7962624, 11239424, 20480000, 23887872, 71663616, 78675968,
	102400000, 214990848

Allocating group tables: done
Writing inode tables: done
Creating journal (262144 blocks): done
Writing superblocks and filesystem accounting information: done
$

We can then mount the disk manually to check everything is okay:

$ sudo mkdir /mnt/usb
$ sudo mount /dev/sda1 /mnt/usb
$ sudo systemctl daemon-reload

and then make sure it will automatically mount on boot by adding the following to the /etc/fstab file:

/dev/sda1 /mnt/usb auto defaults,user 0 1

You should ensure that you can mount the disk manually before rebooting, as adding it as an entry in the /etc/fstab file might cause the Raspberry Pi to hang during boot if the disk isn’t available.

Make the disk available to the cluster

We’re going to want to make the disk available across the cluster. You’ll need to install the NFS server software:

$ sudo apt install nfs-kernel-server

Create a mount point which we can share:

$ sudo mkdir /mnt/usb/scratch
$ sudo chown pi:pi /mnt/usb/scratch
$ sudo ln -s /mnt/usb/scratch /scratch

Then, edit the /etc/exports file to add a list of IP addresses from which you want to be able to mount your disk:

/mnt/usb/scratch 192.168.50.0/24(rw,sync)

Here we’re exporting it to 192.168.50.0/24 which is shorthand for "all the IP addresses between 192.168.50.0 and `192.168.50.254`".

After doing this you should enable, and then start, both the rpcbind and nfs-server services:

$ sudo systemctl enable rpcbind.service
$ sudo systemctl start rpcbind.service
$ sudo systemctl enable nfs-server.service
$ sudo systemctl start nfs-server.service

Finally, reboot:

$ sudo reboot

Enable network boot

The easiest way to proceed is to use the Raspberry Pi Imager software to burn a second SD card with Raspberry Pi OS Lite (64-bit). There isn’t any need to specially configure this installation before booting the board as we did for the head node, except to enable SSH.

Next, boot the board attached to the cluster switch:

The board should come up and be visible on the cluster subnet after it gets given an IP address by the head node’s DHCP server, and we can look at the cluster network from the head node using dhcp-lease-list:

$ dhcp-lease-list
Reading leases from /var/lib/dhcp/dhcpd.leases
MAC                IP              hostname       valid until         manufacturer
===============================================================================================
dc:a6:32:6a:16:87  192.168.50.21   raspberrypi    2021-12-07 11:54:29 Raspberry Pi Ltd
$

We can now go ahead and SSH into the new board and enable network booting using raspi-config from the command line:

$ ssh pi@192.168.50.21
$ sudo raspi-config

Choose Advanced Options > Boot Order > Network Boot. You’ll then need to reboot the device for the change to the boot order to be programmed into the bootloader EEPROM.

If you get an error when trying to enable network boot complaining that "No EEPROM bin file found" then you need to update the firmware on your Raspberry Pi before proceeding. Run the following commands:

$ sudo apt install rpi-eeprom
$ sudo rpi-eeprom-update -d -a
$ sudo reboot

Then, after the node comes back up from its reboot, try to set up network boot once again.

Once the Raspberry Pi has rebooted, check that the boot order using vcgencmd:

$ vcgencmd bootloader_config
BOOT_UART=0
WAKE_ON_GPIO=1
POWER_OFF_ON_HALT=0


[all]
BOOT_ORDER=0xf21
$

You should now see that BOOT_ORDER is 0xf21 which indicates that the Raspberry Pi will try to boot from an SD card first followed by the network. Before proceeding any further, we need to take a note of both the Ethernet MAC address and serial number of the Raspberry Pi.

$ ethtool -P eth0
Permanent address: dc:a6:32:6a:16:87
$ grep Serial /proc/cpuinfo | cut -d ' ' -f 2 | cut -c 9-16
6a5ef8b0
$

Afterwards, you can shut down the board, at least for now, and remove the SD card.

$ sudo apt install tftpd-hpa
$ sudo apt install kpartx
$ sudo mkdir /mnt/usb/tftpboot
$ sudo chown tftp:tftp /mnt/usb/tftpboot

TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/mnt/usb/tftpboot"
TFTP_ADDRESS=":69"
TFTP_OPTIONS="--secure --create"

$ sudo systemctl restart tftpd-hpa

$ sudo su
# mkdir /tmp/image
# cd /tmp/image
# wget -O raspios_lite_latest.img.xz https://downloads.raspberrypi.com/raspios_lite_arm64_latest
# xz -d raspios_lite_latest.img.xz
# kpartx -a -v *.img
# mkdir bootmnt
# mkdir rootmnt
# mount /dev/mapper/loop0p1 bootmnt/
# mount /dev/mapper/loop0p2 rootmnt/
# mkdir -p /mnt/usb/rpi1
# mkdir -p /mnt/usb/tftpboot/6a5ef8b0
# cp -a rootmnt/* /mnt/usb/rpi1
# cp -a bootmnt/* /mnt/usb/rpi1/boot/firmware

# touch /mnt/usb/rpi1/boot/firmware/ssh
# echo pi:$(echo 'raspberry' | openssl passwd -6 -stdin) > /mnt/usb/rpi1/boot/firmware/userconf.txt
# sed -i /UUID/d /mnt/usb/rpi1/etc/fstab
# echo "192.168.50.1:/mnt/usb/tftpboot/6a5ef8b0 /boot/firmware nfs defaults,vers=3 0 0" >> /mnt/usb/rpi1/etc/fstab
# echo "console=serial0,115200 console=tty root=/dev/nfs nfsroot=192.168.50.1:/mnt/usb/rpi1,vers=3 rw ip=dhcp rootwait" > /mnt/usb/rpi1/boot/firmware/cmdline.txt

# echo "/mnt/usb/rpi1 192.168.50.0/24(rw,sync,no_subtree_check,no_root_squash)" >> /etc/exports

# systemctl restart rpcbind
# systemctl restart nfs-server
# umount bootmnt/
# umount rootmnt/
# cd /tmp; rm -rf image
# exit
$

ddns-update-style none;
authoritative;
log-facility local7;
option option-43 code 43 = text;
option option-66 code 66 = text;

# No service will be given on this subnet
subnet 10.3.31.0 netmask 255.255.255.0 {
}

# The internal cluster network
group {
   option broadcast-address 192.168.50.255;
   option routers 192.168.50.1;
   default-lease-time 600;
   max-lease-time 7200;
   option domain-name "cluster";
   option domain-name-servers 8.8.8.8, 8.8.4.4;
   subnet 192.168.50.0 netmask 255.255.255.0 {
      range 192.168.50.20 192.168.50.250;

      # Head Node
      host cluster {
         hardware ethernet dc:a6:32:6a:16:90;
         fixed-address 192.168.50.1;
      }

      # NETGEAR Switch
      host switch {
         hardware ethernet 80:cc:9c:94:53:35;
         fixed-address 192.168.50.254;
      }

      host rpi1 {
         option root-path "/mnt/usb/tftpboot/";
         hardware ethernet dc:a6:32:6a:16:87;
         option option-43 "Raspberry Pi Boot";
         option option-66 "192.168.50.1";
         next-server 192.168.50.1;
         fixed-address 192.168.50.11;
         option host-name "rpi1";
      }

   }
}

$ sudo reboot

Network boot our node

Make sure you’ve removed the SD card from the compute node, and plug the Raspberry Pi back into your switch. If you’ve got a spare monitor handy it might be a good idea to plug it into the HDMI port so you can watch the diagnostics screen as the node boots.

If all goes to plan the board should boot up without incident. Although there are a few things we will need to tidy up, you should now be able to SSH directly into the compute node.

$ ssh pi@192.168.50.11

pi@192.168.50.11's password:
$

If you were watching the boot messages on a monitor, or if you check in the logs, you can see that our image didn’t come up entirely cleanly. If you log back into the compute node you can make sure that doesn’t happen in future by turning off the feature where the Raspberry Pi tries to resize its filesystem on the first boot, and also by uninstalling the swap daemon.

$ sudo systemctl disable resize2fs_once.service
$ sudo systemctl disable sshswitch.service
$ sudo apt remove dphys-swapfile

Next, we should change the hostname from the default raspberrypi to rpi1 using the raspi-config command-line tool:

$ sudo raspi-config

Select System Options > Hostname to change the hostname of the compute node, and select "Yes" to reboot.

Finally, we can make things slightly easier on ourselves, so that we don’t have to use the IP address of our compute and head nodes every time, by adding our current and future compute nodes to the /etc/hosts file on both our head and compute nodes:

127.0.0.1	localhost
::1		localhost ip6-localhost ip6-loopback
ff02::1		ip6-allnodes
ff02::2		ip6-allrouters

127.0.1.1	cluster

192.168.50.1	cluster
192.168.50.254	switch

192.168.50.11	rpi1
192.168.50.12	rpi2
192.168.50.13	rpi3
192.168.50.14	rpi4
192.168.50.15	rpi5
192.168.50.16	rpi6
192.168.50.17	rpi7

Mount the scratch disk

Normally if we were mounting a network disk we’d make use autofs rather than adding it as an entry directly into the /etc/fstab file. However here, with our entire root filesystem mounted via the network, that seems like unnecessary effort. After it reboots log back into your compute node, add a mount point:

$ sudo mkdir /scratch
$ sudo chown pi:pi scratch

Edit the /etc/fstab file there to add the scratch disk:

192.168.50.1:/mnt/usb/scratch /scratch nfs defaults 0 0

Then, reboot the compute node:

$ sudo reboot

Secure shell without a password

It’s going to get pretty tiresome secure-shelling between the cluster head node and the compute nodes and having to type your password each time. So let’s enable secure shell without a password by generating a public/private key pair. On the compute node you should edit the /etc/ssh/sshd_config file to enable public key login:

PubkeyAuthentication yes
PasswordAuthentication yes
PermitEmptyPasswords no

and then restart the sshd server:

$ sudo systemctl restart ssh

Then going back to the head node we need to generate our public/private key pair and distribute the public key to the compute node. Use a blank passphrase when asked.

$ ssh-keygen -t rsa -b 4096 -C "pi@cluster"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/pi/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/pi/.ssh/id_rsa
Your public key has been saved in /home/pi/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:XdaHog/sAf1QbFiZj7sS9kkFhCJU9tLN0yt8OvZ52gA pi@cluster
The key's randomart image is:
+---
[RSA 4096]----+
|     ...o  *+o   |
|      ...+o+*o . |
|       .o.=.B++ .|
|         = B.ooo |
|        S * Eoo  |
|         .o+o=   |
|         ..+=o.  |
|          ..+o +.|
|           .  +o.|
+----
[SHA256]-----+
$ ssh-copy-id -i /home/pi/.ssh/id_rsa.pub pi@rpi1
/usr/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/home/pi/.ssh/id_rsa.pub"
/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
pi@rpi1's password:

Number of key(s) added: 1

Now try logging into the machine, with:   "ssh 'pi@rpi1'"
and check to make sure that only the key(s) you wanted were added.
$

Afterwards, you should be able to login to the compute node without having to type your password.

Access to the outside world

One thing our compute node doesn’t have right now is access to the LAN. Right now the compute node can only see the head node and eventually, once we add them, the rest of the compute nodes. But we can fix that! On the head node go and edit the /etc/sysctl.conf file by uncommenting the following line:

net.ipv4.ip_forward=1

After activating forwarding we’ll need to configure iptables:

$ sudo apt install iptables
$ sudo iptables -t nat -A POSTROUTING -o eth1 -j MASQUERADE
$ sudo iptables -A FORWARD -i eth1 -o eth0 -m state --state RELATED,ESTABLISHED -j ACCEPT
$ sudo iptables -A FORWARD -i eth0 -o eth1 -j ACCEPT
$ sudo sh -c "iptables-save > /etc/iptables.ipv4.nat"

and then add a line — just above the exit 0 line — in the /etc/rc.local file a line to load the tables on boot:

_IP=$(hostname -I) || true
if
[ "$_IP" ]; then
  printf "My IP address is %s\n" "$_IP"
fi

iptables-restore < /etc/iptables.ipv4.nat

exit 0

and reboot:

$ sudo reboot

Add a remote shutdown service

While parallel-ssh is a great tool to allow you to deploy software and do other tasks across your cluster, sometimes you just want to shut the cluster down cleanly with a single command. There are a bunch of ways you can approach this, the simplest is just to write a shell script to login to each of the compute nodes and shut them down before shutting down the head node itself. Alternatively, you could deploy something like the rshutdown service, editing the command appropriately.

Choose the right Raspberry Pi

The faster your Raspberry Pi, the better performance you’ll get. For this tutorial, we’ll be using a Raspberry Pi 4 2GB.

It’s a good idea to choose a Raspberry Pi with a built-in Wi-Fi module, because you’ll need two Wi-Fi devices to host your own hotel Wi-Fi hotspot: one to connect to the hotel network, and one to broadcast a network to your other devices.

Choose the right USB Wi-Fi adapter

Most USB Wi-Fi adapters with Linux driver support should suffice.

For this tutorial, we used a 802.11 b/g/n 2.4GHz adapter built around the MediaTek MT7601U chipset.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the user name you chose in Imager:

$ ssh <username>@pi-hotspot.local

$ ssh <username>@pi-hotspot.local
The authenticity of host 'pi-hotspot.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-hotspot.local' (ED25519) to the list of known hosts.

<username>@pi-hotspot.local's password:
Linux pi-hotspot 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Oct 24 09:41:00 2023
<username>@pi-hotspot:~ $

When asked for your password, use the password you created in Raspberry Pi Imager.

Find your USB Wi-Fi adapter

First, we need to find the USB adapter. Run the following command to identify Wi-Fi devices with the Network Manager CLI:

$ nmcli device

You should see output similar to the following:

DEVICE         TYPE      STATE                   CONNECTION
wlan1          wifi      connected               Example Wi-Fi
lo             loopback  connected (externally)  lo
wlan0          wifi      disconnected            --
p2p-dev-wlan0  wifi-p2p  disconnected            --
eth0           ethernet  unavailable             --

In the above output, the USB Wi-Fi module, wlan1, is connected to a Wi-Fi network named "Example Wi-Fi". The built-in Wi-Fi device, wlan0, is not currently in use, so the state currently reads "disconnected".

If your Raspberry Pi has a built-in Wi-Fi module, it should show up by default as wlan0. The first Wi-Fi module you connect should show up as wlan1, and subsequent adapters will display as wlan2, wlan3, and so on. Depending on your specific configuration, your Raspberry Pi might connect to your network using either the USB adapter or the built-in Wi-Fi module.

Create hotspot network

Next, we’ll use the built-in Wi-Fi module to broadcast a hotspot network. Run the following command to create a hotspot, replacing the <hotspot name> and <hotspot password> placeholders with a hotspot name and password of your choice:

$ sudo nmcli device wifi hotspot ssid <hotspot name> password <hotspot password> ifname wlan0

After creating the hotspot network, your hotspot should automatically become active.

Next, connect to the hotspot Wi-Fi network from your usual computer. Look for a network with an SSID matching the hotspot name you chose in the previous step. Use the password you also provided in that step to authenticate.

Then, connect to your Raspberry Pi using SSH:

$ ssh <username>@pi-hotspot.local

And run the following command to view your current connections:

$ nmcli connection

You should see output similar to the following:

NAME       UUID                                  TYPE      DEVICE
Hotspot    69d77a03-1cd1-4ec7-bd78-2eb6cd5f1386  wifi      wlan0
lo         f0209dd9-8416-40a0-971d-860d3ff3501b  loopback  lo
Ethernet   4c8098c7-9f7d-4e3e-a27a-70d54235ec9a  ethernet  --
Example 1  f0c4fbcc-ac88-4791-98c2-e75685c70e9f  wifi      --
Example 2  9c6098a7-ac88-40a0-5ac2-b75695c70e9e  wifi      --

The connection named Hotspot represents your new hotspot network. The Example 1 and Example 2 connections above represent saved Wi-Fi connections which are inactive.

Configure hotspot network

Let’s configure your hotspot network to automatically broadcast whenever your Raspberry Pi boots. When your Raspberry Pi boots, it starts whichever connection has autoconnect enabled with the highest priority. To ensure that your hotspot always starts on boot, we’ll enable autoconnect for the hotspot and configure a priority higher than any other connection.

Re-run the nmcli connection command above and copy the UUID for your hotspot network from the table. Then, run the following command to view connection properties for your hotspot network, replacing the <hotspot UUID> placeholder with the UUID for your hotspot:

$ nmcli connection show <hotspot UUID>

The output will contain a lot of properties that describe your hotspot network. But we’re only interested in the following two properties for now:

connection.autoconnect:                 no
connection.autoconnect-priority:        0

Run the following command to change the priority and autoconnect properties for your hotspot, replacing the <hotspot UUID> placeholder with the UUID for your hotspot that you copied to your clipboard before:

$ sudo nmcli connection modify <hotspot UUID> connection.autoconnect yes connection.autoconnect-priority 100

If your command executed successfully, we should see the following new values for those properties when we re-run nmcli connection show <hotspot UUID>:

connection.autoconnect:                 yes
connection.autoconnect-priority:        100

Configure connection portal

Next, let’s configure a portal website that allows you to easily connect your Raspberry Pi to a hotel Wi-Fi network from a browser.

Install the following tools:

$ sudo apt install python3-flask

Then, run the following command to make a directory where we can create our portal, called wifi-portal:

$ mkdir ~/wifi-portal

Then, navigate into the portal directory:

$ cd ~/wifi-portal

Open app.py in the portal directory, which contains the logic for the portal website:

$ sudo nano app.py

Copy and paste the following code into app.py:

from flask import Flask,request
import subprocess

app = Flask(__name__)

wifi_device = "wlan1"

@app.route('/')
def index():
    result = subprocess.check_output(["nmcli", "--colors", "no", "-m", "multiline", "--get-value", "SSID", "dev", "wifi", "list", "ifname", wifi_device])
    ssids_list = result.decode().split('\n')
    dropdowndisplay = f"""
        <!DOCTYPE html>
        <html>
        <head>
            <title>Wifi Control</title>
        </head>
        <body>
            <h1>Wifi Control</h1>
            <form action="/submit" method="post">
                <label for="ssid">Choose a WiFi network:</label>
                <select name="ssid" id="ssid">
        """
    for ssid in ssids_list:
        only_ssid = ssid.removeprefix("SSID:")
        if len(only_ssid) > 0:
            dropdowndisplay += f"""
                    <option value="{only_ssid}">{only_ssid}</option>
            """
    dropdowndisplay += f"""
                </select>
                <p/>
                <label for="password">Password: <input type="password" name="password"/></label>
                <p/>
                <input type="submit" value="Connect">
            </form>
        </body>
        </html>
        """
    return dropdowndisplay


@app.route('/submit',methods=['POST'])
def submit():
    if request.method == 'POST':
        print(*list(request.form.keys()), sep = ", ")
        ssid = request.form['ssid']
        password = request.form['password']
        connection_command = ["nmcli", "--colors", "no", "device", "wifi", "connect", ssid, "ifname", wifi_device]
        if len(password) > 0:
          connection_command.append("password")
          connection_command.append(password)
        result = subprocess.run(connection_command, capture_output=True)
        if result.stderr:
            return "Error: failed to connect to wifi network: <i>%s</i>" % result.stderr.decode()
        elif result.stdout:
            return "Success: <i>%s</i>" % result.stdout.decode()
        return "Error: failed to connect."


if __name__ == '__main__':
    app.run(debug=True, host='0.0.0.0', port=80)

Press Ctrl+X, then Y, and finally Enter to save the edited file with nano.

Next, let’s configure your Raspberry Pi to automatically run the Wi-Fi portal after boot. Run the following command to open your cron tab, a Linux scheduling tool:

$ crontab -e

Enter 1 to use the nano text editor to edit your cron schedule. Then, add the following line to the file, replacing the <username> placeholder with your Raspberry Pi admin account username:

@reboot sudo python3 /home/<username>/wifi-portal/app.py

Press Ctrl+X, then Y, and finally Enter to save the edited file with nano.

And enter the following command to reboot your Raspberry Pi:

$ sudo reboot

You’re now ready to connect to any hotel Wi-Fi network!

Choose a Raspberry Pi

You can use any Raspberry Pi model for this. We recommend Zero 2 W if you can’t decide which model to use.

Assign your Raspberry Pi a static IP address

IP addresses are unique numeric codes that allow you to directly interact with devices on your network. For instance, many routers automatically assign themselves the first address in the IP block they are using, such as 192.168.1.1. Most networks use Dynamic Host Configuration Protocol (DHCP) to assign IP addresses to devices automatically. These IP addresses are known as dynamic IP addresses, because they can change at any time.

To run a Pi-hole on your network, we recommend assigning your Pi-hole a static IP address. A static IP address never changes. This allows devices on your network always to find the Pi-hole at the same address.

To start, run the following command on your Raspberry Pi:

$ hostname -I

You should see output similar to the following:

$ 192.168.1.24

This value is the current (dynamic) IP address of your Raspberry Pi on the network.

To assign a static IP address, you also need the MAC address of your Raspberry Pi. A device’s MAC address is a hardware identifier that your router uses to uniquely identify it. Run the following command to find the MAC address of your Raspberry Pi:

$ nmcli -f GENERAL.HWADDR device show wlan0

You should see output similar to the following:

GENERAL.HWADDR:                         A8:42:EA:58:E0:1C

The value on the right is the MAC address of your Raspberry Pi. Now that we know your Raspberry Pi’s MAC address and IP address, we can configure your router so it always associates the Raspberry Pi’s MAC address with its current IP address. Effectively, we’re turning the current dynamic address into a static one using the MAC address. In your router’s admin interface, configure a static IP address for your Raspberry Pi. There are several ways to accomplish this, depending on your router:

Set Pi-hole as your network’s default DNS server

Once you’ve assigned your Raspberry Pi a static IP address, you can configure individual devices to use Pi-hole as a DNS server in their network settings. But this process is tedious, and some devices don’t provide an easily accessible DNS server setting. However, there is an easier way: most routers automatically suggest a DNS server for devices connected to your network. All you have to do is change the suggested server in your router’s settings, and your entire network should start using your Pi-hole for DNS.

Look for a setting called DNS in your router’s admin interface. You may be able to find the setting in a section called "Internet", "DHCP", "Internet Connection", or "DDNS".

Enter your Pi-hole’s IP address in the DNS (or similarly named) field.

If your router provides multiple custom DNS fields, add your Pi-hole address in each field.

Choose the right Raspberry Pi

For this tutorial, we’ll use a Raspberry Pi Zero 2 W. Since this model supports USB On-The-Go (OTG), we can use one cable for both power and data.

Choose the right camera

For this tutorial, we’ll use a Raspberry Pi Camera Module 3.

You’ll also need a cable to connect your camera with your Raspberry Pi. For all Raspberry Pi Zero models, we recommend the Raspberry Pi Camera Cable.

Choose the right case

A Raspberry Pi case with a camera mount keeps your webcam safe from everyday wear and tear.

You could 3D print these Raspberry Pi Zero 2 W case files. This case requires a combination of M2 and M2.5 nylon hex spacers for assembly.

There are also many third-party Raspberry Pi cases available on the market, and some include a camera mount.

Since you’ll connect the entire setup to your computer as a webcam, you should also consider a laptop mount or tripod to make it easier to set up your webcam.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-webcam.local

The first time you do this, confirm that you want to connect. When asked, use the password you created in Raspberry Pi Imager:

$ ssh <username>@pi-webcam.local
The authenticity of host 'pi-webcam.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-webcam.local' (ED25519) to the list of known hosts.

<username>@pi-webcam.local's password:
Linux pi-webcam 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Thu Oct 26 09:41:00 2023
<username>@pi-webcam:~ $

Now that you’ve connected to your Raspberry Pi, run two commands to make sure that all of your packages are up to date:

$ sudo apt update
$ sudo apt full-upgrade

Once the package update commands finish running, reboot your Raspberry Pi to allow all changes to take effect:

$ sudo reboot

Running this command will disconnect you from the Raspberry Pi SSH session. Wait a few seconds for your Raspberry Pi to reboot, and enter the ssh connection command again to reconnect to your device.

Choose the right Raspberry Pi

Version two of the raspberry-noaa software was developed and tested with a Raspberry Pi 4; we can’t guarantee compatibility with older Raspberry Pi models. For this tutorial, we’ll use a Raspberry Pi 4 Model B.

Tools required for the antenna build:

3D printed parts

Download this tutorial’s .stl files for free from printables.com/model/549255-weather-satellite-receiving-station-antenna.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-weather.local

The first time you do this, confirm that you want to connect. When asked, use the password you created in Raspberry Pi Imager:

$ ssh <username>@pi-weather.local
The authenticity of host 'pi-weather.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-weather.local' (ED25519) to the list of known hosts.

<username>@pi-weather.local's password:
Linux pi-weather 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Fri Oct 27 09:41:00 2023
<username>@pi-weather:~ $

Now that you’ve connected to your Raspberry Pi, run two commands to make sure that all of your packages are up to date:

$ sudo apt update
$ sudo apt full-upgrade

Once the package update commands finish running, reboot your Raspberry Pi to allow all changes to take effect:

$ sudo reboot

Running this command will disconnect you from the Raspberry Pi SSH session. Wait a few seconds for your Raspberry Pi to reboot, and enter the ssh connection command again to reconnect to your device.

Configure Raspberry NOAA V2

First, configure your antenna location.

You can obtain your latitude and longitude coordinates from LatLong.net, either by searching for a place name or by navigating your way around the interactive map. Find your coordinates to four decimal places (for example, 52.2048, 0.1304 is close enough to get you to a cracking pub in Cambridge).

Your altitude can be found using whataltitude.com. Replace 0.0 with your altitude in metres.

Change the default values in the configuration file to match your location:

# base station configurations
#   latitude: south values are negative
#   longitude: west values are negative
latitude: 52.2048
longitude: 0.1304
altitude: 42.0

Next, configure your time zone.

You can use Wikipedia to find your UTC offset.

Change the default values in the configuration file to match your time zone:

# time zone offset from UTC (for example, '-5' for US Eastern)
timezone_offset: -5

Next, update the rest of the locale settings.

Visit php.net/manual/en/timezones.php, click on the link for your region, and find your nearest time zone in the list.

Choose a preferred language from the options provided by Raspberry NOAA V2.

Change the default time zone and language values to match your time zone and preferred language:

# locale settings for timezone and language
#   timezone: see https://www.php.net/manual/en/timezones.php
#   lang_setting: see the 'webpanel/App/Lang' folder for available
#* * * *  languages (2-letter filename - e.g. ar, bg, de, en, es, nl)
timezone: America/New_York
lang_setting: en

Finally, update the web server name setting.

We chose pi-weather as our hostname, so we should update the web server name value to match that hostname:

web_server_name: pi-weather.local
enable_non_tls: false
web_port: 80
enable_tls: true
web_tls_port: 443
cert_valid_days: 365
lock_admin_page: false
admin_username: 'admin'
admin_password: 'admin'
web_passes_date_format: 'd/m/Y'
web_datetime_format: 'd/m/Y H:i:s'

You can also change the date format settings to match your preferred style: the above example formats dates in the UK style. To save your changes, press CTRL+X, then Y, then Enter to save your changes to the configuration file.

Now we can install and automatically start the Raspberry NOAA V2:

$ ./install_and_upgrade.sh

This command could take a few minutes to run.

Choose the right Raspberry Pi

This project will work on any Raspberry Pi Model 3 or newer. For this tutorial, we’ll use a Raspberry Pi 3 Model A+.

Choose the right ADS-B receiver

For the USB ADS-B receiver you can buy any RTL2832/R820T2-based USB dongle that’s available to you locally or from your favourite online retailer. Prices usually start around $20. This tutorial uses NESDR Mini (TV28T v2) USB RTL-SDR, DVB-T & ADS-B Receiver Set.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-flighttracker.local

The first time you do this, confirm that you want to connect. When asked, use the password you created in Raspberry Pi Imager:

$ ssh <username>@pi-flighttracker.local
The authenticity of host 'pi-flighttracker.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-flighttracker.local' (ED25519) to the list of known hosts.

<username>@pi-flighttracker.local's password:
Linux pi-flighttracker 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Thu Oct 26 09:41:00 2023
<username>@pi-flighttracker:~ $

Now that you’ve connected to your Raspberry Pi, run two commands to make sure that all of your packages are up to date:

$ sudo apt update
$ sudo apt full-upgrade

Once the package update commands finish running, reboot your Raspberry Pi to allow all changes to take effect:

$ sudo reboot

Running this command will disconnect you from the Raspberry Pi SSH session. Wait a few seconds for your Raspberry Pi to reboot, and enter the ssh connection command again to reconnect to your device.

Choose a Raspberry Pi

This project can run on any Raspberry Pi computer. For this tutorial, we’ll be using a Raspberry Pi Zero 2 W, which has plenty of power to display train times on a monitor.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-traintimes.local

The first time you do this, confirm that you want to connect. When asked, use the password you created in Raspberry Pi Imager:

$ ssh <username>@pi-traintimes.local
The authenticity of host 'pi-traintimes.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-traintimes.local' (ED25519) to the list of known hosts.

<username>@pi-traintimes.local's password:
Linux pi-traintimes 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Oct 24 09:41:00 2023
<username>@pi-traintimes:~ $

Now that you’ve connected to your Raspberry Pi, run two commands to make sure that all of your packages are up to date:

$ sudo apt update
$ sudo apt full-upgrade

Once the package update commands finish running, reboot your Raspberry Pi to allow all changes to take effect:

$ sudo reboot

Running this command will disconnect you from the Raspberry Pi SSH session. Wait a few seconds for your Raspberry Pi to reboot, and enter the ssh connection command again to reconnect to your device.

Find your local train station

All UK train stations have a unique code. You can find the code for your nearest (or favourite ) station at the National Rail website. For this tutorial we’ll use CBG: Cambridge station.

To find the code for your station, see Wikipedia’s list of UK rail stations. Then, open a web browser on any device and enter the following URL, replacing the CBG at the end with the code for your station:

http://realtime.nationalrail.co.uk/ldbcis/departures.aspx?u=039B1CD1-14D4-4CB9-83B1-A84CC3AEDF83&crs=CBG

You should now see the real-time departure board for your station. Notice that your browser has added a query parameter, H, at the end of the URL. Look for &H=, followed by a number. This scales the page based on your monitor’s resolution.

Make a note of the H query parameter value — you’ll use it later on to scale the display for your Raspberry Pi’s monitor.

Configure kiosk mode

To make a usable display of train times, we need to configure our Raspberry Pi to start up the train times web page in kiosk mode. Kiosk mode hides the browser chrome to display just the web page on your display. We also need to disable the screensaver and DPMS (Display Power Management Signalling) so the train times display doesn’t turn off on its own without interaction.

Next, we need to write the contents of .config/wayfire.ini. Run the following command to use the nano text editor to make changes to the file:

$ sudo nano .config/wayfire.ini

Take a look at the section titled [autostart]. At the moment, it reads like this:

[autostart]
panel = wfrespawn wf-panel-pi
background = wfrespawn pcmanfm --desktop --profile LXDE-pi
xdg-autostart = lxsession-xdg-autostart

Let’s append a few lines to this section to automatically start kiosk mode whenever your Raspberry Pi powers on:

chromium = chromium-browser "https://realtime.nationalrail.co.uk/ldbcis/departures.aspx?u=039B1CD1-14D4-4CB9-83B1-A84CC3AEDF83&crs=CBG&H=1440" --kiosk --noerrdialogs --disable-infobars --no-first-run --ozone-platform=wayland --enable-features=OverlayScrollbar --start-maximized
screensaver = false
dpms = false

Add to the file directly below the existing contents of the [autostart] section. Remember to update the CBG station code to your own station code, and to include the H query parameter value you noted before! When you finish, you should end up with the following:

[autostart]
panel = wfrespawn wf-panel-pi
background = wfrespawn pcmanfm --desktop --profile LXDE-pi
xdg-autostart = lxsession-xdg-autostart
chromium = chromium-browser "https://realtime.nationalrail.co.uk/ldbcis/departures.aspx?u=039B1CD1-14D4-4CB9-83B1-A84CC3AEDF83&crs=CBG&H=1440" --kiosk --noerrdialogs --disable-infobars --no-first-run --ozone-platform=wayland --enable-features=OverlayScrollbar --start-maximized
screensaver = false
dpms = false

Press Ctrl+X, then Y, and finally Enter to save the edited file with nano. Next, reboot your Raspberry Pi:

$ sudo reboot

Now, check the monitor attached to your Raspberry Pi. It should display the train information in full screen mode. Now you’re ready to set your train timetable up wherever it can make your life easier — by your front door, at your desk at work, or possibly at your local train station.

Tools required

Choose the right Raspberry Pi

This project works with all models of Raspberry Pi, but in order to maintain the intended slim look of our mirror we will use a Raspberry Pi 3 Model A+. If you decide to use a Raspberry Pi 4, you’ll need slightly larger M3 20mm standoffs to accommodate the larger board.

Choose the right power supply

This project will require two power supplies: one for your Raspberry Pi, plus a USB-C power supply for the display itself. You can also use a single power supply that splits to provide both micro USB and USB-C connectors such as this one. If you choose this option, ensure that your power supply can provide sufficient power to both devices.

Choose the right HDMI cable

The 90-degree angle in your HDMI cable should lie flat against the monitor when connected, as demonstrated in the photo below:

Choose the right display

The higher the contrast between light and dark, the better your smart mirror will look. When reviewing specifications for a suitable display, pay particular attention to its brightness, which you’ll find specified in units that might be unfamiliar to you: nits and cd/m². Cd/m² (candelas per square metre) is a unit that derives from a very old brightness metric based on whale oil candles. Nit derives from the Latin word "nitere", "to shine". Conveniently, 1 nit is equal to 1 cd/m².

Look for a bright display: no less than 300 nits (or cd/m²).

Connect to your Raspberry Pi via SSH

Open a terminal session on your usual computer and run the following to access your Raspberry Pi via SSH, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-mirror.local

The first time you do this, confirm that you want to connect. When asked, use the password you created in Raspberry Pi Imager:

$ ssh <username>@pi-mirror.local
The authenticity of host 'pi-mirror.local (2a00:23c8:3880:d801:34e0:2052:bc72:dd67)' can't be established.
ED25519 key fingerprint is SHA256:NjLggsBZzj6N99rABupQCwyhjNnGpeMT6T9jaoRShu8.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-mirror.local' (ED25519) to the list of known hosts.

<username>@pi-mirror.local's password:
Linux pi-mirror 5.15.32-v7l+ #1538 SMP Thu Mar 31 19:39:41 BST 2022 armv7l

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Thu Oct 26 09:41:00 2023
<username>@pi-mirror:~ $

Now that you’ve connected to your Raspberry Pi, run two commands to make sure that all of your packages are up to date:

$ sudo apt update
$ sudo apt full-upgrade

Once the package update commands finish running, reboot your Raspberry Pi to allow all changes to take effect:

$ sudo reboot

Running this command will disconnect you from the Raspberry Pi SSH session. Wait a few seconds for your Raspberry Pi to reboot, and enter the ssh connection command again to reconnect to your device.

Disassemble your display

First, prepare your display. Separate it from the housing into component parts. The display we’ve used for this tutorial is fairly generic and is often branded with different names. It comes apart with relative ease and is made up of only a metal front display bezel, a metal rear housing, a driver board, a control board, and two speakers. We need to remove the metal front display bezel which is held in place only by a small amount of glue:

With a prying tool, prise the screen away from the bezel and pull the frame away from the screen. You may find it useful to heat the frame gently with a hairdryer in order to loosen the glue holding it in place:

As soon as you have enough space to get between the bezel and the screen, gently pull the bezel away until it is completely separated. You may need to use the hairdryer again to heat the frame to help the process along:

Once you have removed the frame, fold back the screen gently to reveal the contents of the rear housing. You’ll see two circuit boards: a larger driver board and a smaller controller board. Be sure not to pull out any of the wires and flexes connecting everything; take particular care when handling the screen, as it will be connected to the driver board by a delicate ribbon cable. Again, it’s just glue holding the driver and control boards in place. They can be removed from the housing by heating and prying as we did earlier for the front display bezel:

Detach the two flat speakers from the housing by removing two small Phillips head screws from each one. Finally, remove any pieces of tape that are holding cables in place. Set aside your display ready to install into your smart mirror later in the tutorial.

Prepare to assemble your smart mirror

Let’s take a moment to review the final assembly before we begin some of the construction steps. As the illustration above shows from left to right, there are:

The nylon nuts, bolts, and spacers hold all of these pieces together to form our smart mirror. The design of this smart mirror does not require any sawing or cutting of acrylic pieces, or even any frame-making skills whatsoever. To assemble the mirror:

The following sections walk you through these steps in greater detail.

Drill the mounting holes

We need to make eight mounting holes in perfectly matching locations through the A3-sized acrylic and card pieces. The easiest way to do this is to drill through all three pieces at the same time into a suitable flat surface, such as a piece of engineered wood, using a general-purpose drill bit (any drill bit other than a masonry bit should work). Prepare the clear acrylic piece, black card, and two-way mirror for drilling by holding them together in alignment. Drill eight 3mm holes exactly 15mm in from the edges of the pieces, at each of the four corners and at the midway points down each of the sides, as shown in the diagram below:

If you have a 3D printer, you can print our alignment jigs to simplify things. You can also measure with a ruler and mark out where holes should be drilled. In order to avoid unnecessary scratches, we recommend keeping the protective covering on your acrylic pieces throughout the entire process:

Mount the display to the card

The display you are using is very unlikely to be exactly A3 in size, so we will give it a black border. This prevents light from passing through the back of the two-way mirror around the display and spoiling the overall effect. Measure your display area. With a craft knife and a metal ruler, cut out an area 1-2mm smaller than your measurements in the center of your A3 black card:

Mount the electronic parts to the display

Cover the back of the display with a single layer of 50mm duct tape. This serves two purposes: firstly providing a protective isolation layer between the printed circuit boards and the display, and secondly improving the appearance of the mirror.

Add pieces of VHB double-sided heavy-duty foam tape to the backs of the driver, control, and Raspberry Pi boards, as well as to the two speakers. Attach each of these to the back of the display such that their ports are still accessible from the edge.

Next, attach the display to your black card border using duct tape:

Flip everything over to get a preview of the seamless display effect:

Final hardware assembly

Connect display control board and and your Raspberry Pi with the mini HDMI to HDMI cable.

Connect the power cables (or single split power cable) for the display and Raspberry Pi.

Now we can now assemble the smart mirror using nuts, bolts, and spacers.

For each of the eight holes:

Set the display orientation

Connect with SSH, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-mirror.local

By default, your desktop will display in landscape orientation. If this is your preference, move on to the installation of Magic Mirror². To use your mirror in portrait orientation, we can turn the desktop by editing .config/wayfire.inh. Use the following command to open this file in your preferred text editor, in our case nano:

$ sudo nano .config/wayfire.ini

Add the following lines to the end of the file so it reads as follows:

[output]
transform=90

Press Ctrl+X, then Y, and finally Enter to save the edited file with nano.

Reboot the Raspberry Pi to activate your changes:

$ sudo reboot

When your device reboots, the desktop should display in portrait mode. Connect over SSH again to continue.

Install the Magic Mirror² software

First, we’ll install Node.js, the open source server environment program used as the basis for this smart mirror project. Run the following two commands to install Node.js:

$ curl -sL https://deb.nodesource.com/setup_18.x | sudo -E bash -
$ sudo apt install -y nodejs

Next, install a package manager for JavaScript. Run the following command to install Node Package Manager, the default for Node.js:

$ sudo apt install npm

Run the following commands to download the Magic Mirror repository, enter the directory, and install Magic Mirror:

$ git clone https://github.com/MichMich/MagicMirror
$ cd MagicMirror
$ npm run install-mm

Copy over the sample configuration file to use it as a template for our display:

$ cp config/config.js.sample config/config.js

Finally, start the application with the following command:

$ npm run start

Wait a minute or so, and you should see the default Magic Mirror display. It should look like this:

The Magic Mirror software will now display a sample mirror based on the configuration file we copied over a couple of steps earlier. This file specifies what, when, and how to display information on your screen. The default configuration displays a number of modules, including time, date, weather, US holidays, a news feed, and a compliments module. You can adjust, add, and remove modules to your liking.

Since the amazing Michael Teeuw created the original magic mirror, a community of enthusiasts has created hundreds of modules. One lets you know when your local refuse collector is coming. Another keeps you up-to-date on the newest online cat videos. If you can’t find one you like, write your own! The great thing about a project like this is that you can personalise it to suit your specific requirements.

Automatically start your Magic Mirror using PM2

We need to finish one more step before we can customise our mirror. Magic Mirror currently starts and stops manually from the command line over SSH. We’ll add an autostart program that also gives you a few extra features you might find useful.

Before we begin, stop Magic Mirror by pressing Ctrl+C.

PM2 is a process manager for Node.js applications like Magic Mirror. With PM2, we can start, stop, maintain, and interact with Magic Mirror. Install PM2 with the following command:

$ sudo npm install -g pm2

To use PM2, we’ll have to start it after every boot. Luckily, there’s built-in help for this. Execute the following command to set up autostart for PM2:

$ pm2 startup

After a short introduction, this should output a command that will automatically start PM2 after boot.

Copy and run the command provided by the response.

Next, create a small bash script that starts Magic Mirror:

$ sudo nano ~/mm.sh

Type or paste the following code into it:

cd ./MagicMirror
DISPLAY=:0 npm start

Press Ctrl+X, then Y, and finally Enter to save the edited file with nano.

Enter the following command to make the file executable:

$ sudo chmod +x ~/mm.sh

Now, use PM2 to run your new bash script that start the Magic Mirror application with the following command:

$ pm2 start mm.sh

The mirror will display exactly as it did before, but PM2 controls the process now.

PM2 autostarts programs it controls from saved state.

Run the following command to save PM2’s current state:

$ pm2 save

If your Raspberry Pi loses power, PM2 will autostart when your Raspberry Pi is powered up again. PM2 will restore the most recently saved state. And the smart mirror will automatically start working.

The Magic Mirror configuration file

Since the config.js file is where some of the magic happens, let’s take a closer look at it:

$ sudo nano MagicMirror/config/config.js

The file is written in JavaScript.

Press CTRL+X to exit nano without making any changes. Whenever you make a successful change to your config.js file, type the following to make a backup:

$ sudo cp MagicMirror/config/config.js MagicMirror/config/config.jsBACKUP

Since we’ve given the backup file the made-up filename extension .jsBACKUP, the system will ignore it. But if you make a change to config.js that causes an error and you’re unable to fix it, you can replace your broken config.js file with your functional config.jsBACKUP file with the following command:

$ sudo cp MagicMirror/config/config.jsBACKUP MagicMirror/config/config.js

These backups can help you keep track of changes to your smart mirror configuration over time. Consider adding a number or a date after "BACKUP" in the commands above to keep multiple backup files as you tweak your configuration over time.

Backups are especially handy when you see this dreaded error screen:

Configure an existing module

Edit your config.js file to modify one of the modules that appear on our mirror.

The last module in the file is the news feed module, which pulls news from an RSS feed — a way of distributing content updates from a website in a concise format.

Open your configuration file in nano:

$ sudo nano ~/MagicMirror/config/config.js

For this tutorial, we’ll add two feeds: one for Raspberry Pi Tutorials, and one that provides news local to Pi Towers. Once we’ve done that, the bottom of our file will look like this:

    {
      module: "newsfeed",
      position: "bottom_bar",
      config: {
        feeds: [
          {
            title: "Raspberry Pi Tutorials",
            url: "/tutorials/feed"
          },
          {
            title: "Cambridge Independent News",
            url: "https://www.cambridgeindependent.co.uk/_api/rss/cambridge_independent_news_feed.xml"
          }
        ],
        showSourceTitle: true,
        showPublishDate: true,
        broadcastNewsFeeds: true,
        broadcastNewsUpdates: true
      }
    },
  ]
};

/*************** DO NOT EDIT THE LINE BELOW ***************/
if (typeof module !== "undefined") {module.exports = config;}

Once you are happy with the changes you’ve made to the file, press CTRL+X, then Y, then Enter. Then, type the restart command for the Magic Mirror application to see the result:

$ pm2 restart mm

Remove modules

Edit your config.js file to remove one of the modules that appear on our mirror.

We’ll remove the weather module, which appears in the top right corner of our screen. It’s made up of two small modules, one for the current weather and one for a forecast. Here at Cambridge UK it’s always sunny, so we don’t need this weather forecast.

Open your configuration file in nano:

$ sudo nano ~/MagicMirror/config/config.js

Delete this entire section from the config file, removing everything from the first open curly bracket to the last closing curly bracket and comma:

{
  module: "weather",
  position: "top_right",
  config: {
    weatherProvider: "openweathermap",
    type: "current",
    location: "New York",
    locationID: "5128581", //ID from http://bulk.openweathermap.org/sample/city.list.json.gz; unzip the gz file and find your c>
    apiKey: "YOUR_OPENWEATHER_API_KEY"
  }
},
{
  module: "weather",
  position: "top_right",
  header: "Weather Forecast",
  config: {
    weatherProvider: "openweathermap",
    type: "forecast",
    location: "New York",
    locationID: "5128581", //ID from http://bulk.openweathermap.org/sample/city.list.json.gz; unzip the gz file and find your c>
    apiKey: "YOUR_OPENWEATHER_API_KEY"
  }
},

Once you are happy with the changes you’ve made to the file, press CTRL+X, then Y, then Enter. Then, type the restart command for the Magic Mirror application to see the result:

$ pm2 restart mm

Add new modules

Adding a new module involves two steps:

There are plenty of modules to choose from, but we’re going with one that will display an image of our choice where the weather modules used to be. This particular module is called MMM-EasyPix and was made by Mykle.

To begin, download MMM-EasyPix into the modules folder:

$ cd ~/MagicMirror/modules/
$ git clone https://github.com/mykle1/MMM-EasyPix

Next, modify config.js to use the module.

Open your configuration file in nano:

$ sudo nano ~/MagicMirror/config/config.js

Paste the following sample MMM-EasyPix configuration into the list of modules:

{
  module: "MMM-EasyPix",
  position: "top_right",
  config: {
    picName: "grid.jpg",     // Enter the picture file name.
    maxWidth: "100%",        // Size picture precisely. Retains aspect ratio.
  }
},

The code above calls the MMM-EasyPix module and assigns the following parameters:

Once you are happy with the changes you’ve made to the file, press CTRL+X, then Y, then Enter. Then, type the restart command for the Magic Mirror application to see the result:

$ pm2 restart mm

You should now see a new image on the display:

Let’s replace that image with the Raspberry Pi logo.

Fetch the image from the internet:

curl https://upload.wikimedia.org/wikipedia/en/c/cb/Raspberry_Pi_Logo.svg -o ~/MagicMirror/modules/MMM-EasyPix/pix/logo.svg

Finally, edit the config.js file again to change grid.jpg to our logo.svg image file.

Open your configuration file in nano:

$ sudo nano ~/MagicMirror/config/config.js

Paste the following sample MMM-EasyPix configuration into the list of modules:

{
  module: "MMM-EasyPix",
  position: "top_right",
  config: {
    picName: "logo.svg",     // Enter the picture file name.
    maxWidth: "100%",        // Size picture precisely. Retains aspect ratio.
  }
},

Once you are happy with the changes you’ve made to the file, press CTRL+X, then Y, then Enter. Then, type the restart command for the Magic Mirror application to see the result:

$ pm2 restart mm

Congratulations! You’re ready to go off on your own to build the best smart mirror you can imagine.

Choose a Raspberry Pi

OctoPrint supports older Raspberry Pi devices, but this tutorial uses a 2GB Raspberry Pi 4 Model B for a faster, smoother experience.

Add a camera (optional)

To keep an eye on your models as they print, add a Raspberry Pi camera or a USB webcam.

To do this:

Here, you can click the Test button to make sure your camera works properly and make any necessary changes, such as altering aspect ratio and rotation.

You can also enable time-lapse recordings of your prints and save them to your Raspberry Pi.

You can view your camera settings under Control on the main OctoPrint dashboard.

Choose the right Raspberry Pi

Although RetroPie will work on any Raspberry Pi, even the $5 Raspberry Pi Zero, we recommend using one with as much RAM as possible. More RAM means a smoother gaming experience. For this tutorial, we’ll be using an 8GB Raspberry Pi 4.

Raspberry Pi 400 is also a great choice, especially if some of your favourites use the keyboard as a controller.

Plug in your gaming controller

We’re using a generic USB gaming controller, but you can also use a variety of wired console controllers such as those made for Xbox and PlayStation. If you plan on using a wireless gaming controller that doesn’t have its own dongle, be prepared to troubleshoot some connection issues.

Configure your gaming controller

RetroPie should now begin its initial start up process. When prompted, follow the on-screen instructions to configure your controller. When complete, press your newly assigned A button to exit the setup.

Format your USB flash drive using your usual computer

You’ll need to format your USB flash drive to FAT32 or exFAT before you use it to move your games to your Raspberry Pi. You can format it on macOS using the Disk Utility application, or on Windows by right-clicking on the flash drive then selecting Format.

Build your folders

Next, create a new folder on your USB flash drive and name it retropie. Eject the flash drive from your usual computer and plug it into your Raspberry Pi. RetroPie will now create folders on the USB flash drive for you. This should only take a few minutes. You’ll know it’s complete when the LED on your Raspberry Pi stops blinking.

Download ROMS

Game files are called ROMs. You can download them from a variety of online sources. There are a few copyright restrictions surrounding ROMs; always check that the website you’re using does not supply pirated content. Websites like itch.io provide some brilliant homebrew ROMs, and you can also find some official SEGA ROMs on Steam.

Transfer your ROMs to RetroPie

Remove the USB flash drive from your Raspberry Pi and plug it back into your usual computer. You’ll now see a vast array of folders on the drive, named after all your favourite consoles, in /retropie/roms. It’s now time to drop your ROMs into their respective folders and eject the USB flash drive again.

Plug the USB flash drive back into your Raspberry Pi once more and wait for the LED to stop blinking. The transfer time depends on how many ROMs you’re transferring, so don’t worry if it takes a while. We recommend using this time to make yourself a nice cup of tea.

Eject the USB flash drive, then restart your Raspberry Pi by selecting Start on your controller, followed by Quit, and then RestartEmulationStation.

Once your Raspberry Pi restarts, you’ll find all your games uploaded and ready to play.

You can repeat the download and transfer process to add more ROMs to your Raspberry Pi at any time without losing your existing games.

Happy playing!

Choose the right Raspberry Pi and accessories

This tutorial uses a Raspberry Pi 3. We do not recommend using a Raspberry Pi Zero for this project.

Choose a capture card

If you plan to watch content from streaming sites such as Netflix and Disney+, you’ll need a capture card that supports HDCP. Choose a capture card that matches your display resolution: for instance, if your TV has a resolution of 4K (or you might soon upgrade to a 4K tv), you’ll want a 4K capture card.

Choose an LED strip

The size of your monitor dictates the length of LED strip you need to purchase. To determine the length, measure all the edges of your monitor and add them together. For example, our 47" TV measures 106cm along the top and bottom, and 62cm either side. So we’ll need at least 336cm of NeoPixels. As strips are usually sold in metres, we ordered 4m and cut off the excess.

Choose a power supply

The more LEDs you have, the more power you will need. To get an approximate measure of the output you’ll need to run your LED strip, use the following equation:

0.06 x LED quantity = output current

Our project uses 150 LEDs, so we’ll need approximately 9A power. As 9A isn’t a standard output current for off-the-shelf power supplies, and because we also need to power our Raspberry Pi, we’re using a 5V 10A barrel jack power supply for our setup.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-ambient.local

$ ssh <username>@pi-ambient.local
The authenticity of host 'pi-ambient.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-ambient.local' (ED25519) to the list of known hosts.

<username>@pi-ambient.local's password:
Linux pi-ambient 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Oct 24 09:41:00 2023
<username>@pi-ambient:~ $

When asked for your password, use the password you created in Raspberry Pi Imager.

Power your LED strip

Your LED strip should arrive pre-wired with three wires: live, ground, and data. Ideally, they’ll be pre-installed into a connector, with additional live and ground wires, which we’ll be using to power the strip.

These two wires will likely be red and white, or red and black. Red is live, and white/black is ground. If required, strip them to expose 0.5cm of wire

Next cut the USB-A end from your microUSB/USB-C cable. Depending on the type of cable, you’ll find either two or three wires inside. Again, these represent live and ground and, in some cases, data. As with the LED strip, strip 0.5cm of the live wire (usually red), and the ground wire (usually white or black)

Insert the live wire from the LED strip and microUSB/USB-C lead into the + hole of your female barrel jack connector and tighten them in place. Our connector uses a small screw to secure the wires. Next, insert the ground wire from the LED strip and microUSB/USB-C lead into the + hole of the connector and again tighten them into place

Connect your LED strip to your Raspberry Pi

We’re going to use the GPIO pins of the Raspberry Pi to connect to the data wire of the LED strip. By default, HyperHDR is configured to connect to GPIO 18 and, though you can change this in the dashboard settings later, there’s no reason not to use GPIO 18.

You may also wish to connect a second wire between the ground wire of your LED strip and one of the GPIO ground pins to prevent your lights from flickering. For some setups, we’ve found this isn’t necessary, and for some it is. Better safe than sorry.

Attach the LED strip to your TV

Next, you need to line the rear edge of your monitor with the LED strip. Try to get them as close to the edge as you can without making them visible from the front. When approaching corners, you can either:

Folding is the easiest option, but remember to account for any 'hidden' LEDs later when we set up HyperHDR.

For ease, attach your LED in a clockwise direction when facing the monitor. If you attach them anti-clockwise, remember to select Reverse direction in the LED layout menu of HyperHDR later on in the process.

Connect your input device

1. Connect the USB port of your capture card to a USB port of your Raspberry Pi using a USB-to-USB cable.

2. Connect the capture card’s HDMI OUT port to your monitor using an HDMI-to-HDMI lead.

3. Lastly, connect your input device (games console, DVD Player, TV receiver) to the capture card’s HDMI INPUT port using the second HDMI to HDMI lead.

Multiple input devices (optional)

If you have more than one device you wish to input into your TV, you can use an HDMI hub. Plug all your devices into the hub and connect the hub’s HDMI OUT port to the HDMI IN port of the capture card.

Once everything is plugged in, connect your power supply to the barrel jack connector. Your setup is now complete. We recommend tidying up your wires and securing everything to the back of your TV or into a ventilated container.

LED hardware

Our first step is to tell HyperHDR what type of LEDs we have, and how many there are. Select LED hardware in the side menu. This should open up the LED controller menu.

There are many different types of LED controllers on the market. We’re using a ws2812B LED strip, as it’s a good balance between functionality and cost. So we’ll select "ws281x" from the Controller type dropdown menu.

Once you’ve selected your controller type, you need to enter the number of LEDs on your strip in both the Hardware LED count and Maximum LED count boxes. Confirm your jumper wire is connected to GPIO 18 and that 18 is selected in the GPIO number box, then click Save settings.

Next, select LED layout at the top of the page.

Here, we need to tell HyperHDR where our LEDs are. Enter the number of LEDs for the top, bottom, and sides of your monitor into the appropriate boxes. You’ll also want to move the input indicator to the correct position. Ours is located at the bottom of our television.

Ideally, you’ll have attached your LEDs in a clockwise direction. If not, now is the time to select Reverse direction.

Click Save layout.

Video capturing

Image processing

Select Image processing from the side menu. Scroll down and activate Blackbar detection and Save settings.

RGB order wizard

Lastly, we’re going to make sure HyperHDR is aware of the RGB order of your LED strip. Select Advanced from the side menu, followed by Misc and RGB order wizard. Here, you’ll need to tell HyperHDR whether the colours on the screen match the colours of your LEDs:

Finish up

After following the steps of this tutorial, you should see your LED lights reacting to the video content on your television. If you don’t, go back and double-check the steps to ensure you followed them correctly.

Chances are, you’ll need to tweak the settings to get the best experience from your LEDs. We needed to move the input location a few LEDs in the LED layout section to match our lights to the images on the screen. For those of you with a taste for colour theory, HyperHDR offers a variety of more advanced options. To access them, select Advanced from the side menu, followed by Misc and Settings level. Here, you can select Expert to access all HyperHDR features in the dashboard.

3D-printed parts

Four 3D-printed pieces are required to house all the component parts: the back, main body, Pico stand, and front. We will glue them together to form the complete assembly. You can download the 3D print files for free at printables.com. Print them using any FDM (Fused Deposition Modelling) 3D printer with a build area of 70mm² or larger. We recommend you use a material that is easy to print with, such as PLA or PETG filament.

Cutting and preparing the acrylic discs

For this project, you will need two acrylic discs 3mm thick and 70mm in diameter, one of which will require a hole approximately 5mm in diameter for wiring. If you have access to a laser cutter, making these is straightforward. Otherwise, it might be time to dig out your old pencil case and find a pair of compasses.

Using a jigsaw, cut out a 70mm circle and neaten up the edges with sandpaper or a file. The final discs don’t need to be absolutely flawless, since the subsequent steps will cover any minor imperfections. One disc should be drilled with a 5mm hole in the centre to allow wiring to pass through later:

Mark a 70mm circle on your flexible adhesive mirror tile and another on your one-way mirror self-adhesive film. To make them perfectly round, cut them out using scissors. Ensure that you remove all the protective layers from your acrylic discs and then peel the adhesive backing from your mirror sheets in turn. Attach the circle of mirror tile sheet to the disc with the hole, which will be used to mount your Pico, and the circle of one-way mirror film to the other disc.

Wire and solder the electronics

The Arc Reactor base contains the rechargeable battery, on/off switch, and USB-C charging board, all of which you need to glue into place inside the 3D-printed cutouts. At this stage, you need to do some cutting of wires, stripping and soldering. Use the photograph below as a reference to ensure that:

You can solder the positive wire from the switch to either of the two outer switch terminals:

Next, solder three wires directly to the back of your Pico. The wires should be long enough to complete the wiring circuit later in the assembly process: about 20cm. To provide power to your Pico:

Solder a third wire, shown here in blue, to the pin marked GP28. Our MicroPython script uses this pin to communicate with the LEDs:

LED strips usually come pre-wired, but their joints are often bulky, so we will make our own wiring loom. Using a pair of scissors, remove any pre-existing wiring and cut a strip of 31 LEDs. Be sure to cut along the line between LEDs:

The strip is also marked with arrows to show the correct current direction, + symbols for the positive wire, 0 for the data wire, and G for the negative or ground wire. When cutting, be sure to snip down the middle of each solder pad. If you’re not careful, it could be tricky to solder the wires to the pads.

Solder three more wires, also approximately 20cm in length, as shown in the photo above: red for positive, blue for data, and black for ground. You may find it more convenient to solder from the rear of the strip.

Choose the right Raspberry Pi

The faster your Raspberry Pi, the faster your data will save to your external storage. For this tutorial, we’ll be using a Raspberry Pi 4 8GB.

Choose the right storage

Unless you’re very frugal with file sizes, an SD card probably isn’t large enough for NAS.

So in this tutorial, we’ll use a portable USB solid state drive (SSD). You could also use a USB flash drive or a USB hard disk drive (HDD). We recommend clearing your drive of data, as you may need to format it.

To maintain a consistent power supply to your external hard drives, it is best to use a powered USB hub to connect your storage to your Raspberry Pi.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-nas.local

$ ssh <username>@pi-nas.local
The authenticity of host 'pi-nas.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/
[fingerprint])? yes
Warning: Permanently added 'pi-nas.local' (ED25519) to the list of known hosts.

<username>@pi-nas.local's password:
Linux pi-nas 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Oct 24 09:41:00 2023
<username>@pi-nas:~ $

When asked for your password, use the password you created in Raspberry Pi Imager.

Find your drive

First, we need to find the identifiers for the drives we want to format. To see the storage devices currently connected to your system, run the following command:

$ lsblk

You should see output similar to the following:

NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda           8:0    0   1.8T  0 disk
mmcblk0     179:0    0 238.8G  0 disk
├─mmcblk0p1 179:1    0   256M  0 part /boot
└─mmcblk0p2 179:2    0 238.5G  0 part /

This command describes storage devices connected to your Raspberry Pi. The mmcblk0 device is your microSD card. The first USB storage device you connect should show up as Storage Device A, or sda for short. If you connect additional USB storage devices, you’ll see them as Storage Device B (sdb), C (sdc), etc.

Partition drive

Next, partition your drive so Raspberry Pi OS recognizes it as a single storage device:

$ sudo fdisk /dev/sda

When prompted:

Use the default option for all other prompts.

Format drive

Now that the drive has been partitioned, we need to format it so Raspberry Pi OS can read and write data. The following command formats your drive into the ext4 file system:

$ sudo mkfs.ext4 /dev/sda1

Mount drive

Next, mount the drive to make it available to the file system on your Raspberry Pi:

$ sudo mount /dev/sda1

And ensure that the drive is mounted after each boot:

$ sudo nano /etc/fstab

Add the following line at the end of the file:

/dev/sda1 /mnt/sda1/ ext4 defaults,noatime 0 1

Press Ctrl+X, then Y, and finally Enter to save the edited file with nano.

Create a shared folder

Run the following command to create a shared folder on your drive:

$ sudo mkdir /mnt/sda1/shared

Run the following command to grant read, write, and execute permissions to the folder to all users on your Raspberry Pi:

$ sudo chmod -R 777 /mnt/sda1/shared

Choose the right Raspberry Pi

Kiosk mode relies on you running a graphical web browser, and this in turn requires a Raspberry Pi 3 or newer with at least 1 GB of RAM (as both Chromium and Firefox will refuse to run on anything older). This tutorial also assumes that you’re using a Raspberry Pi with built-in Wi-Fi®, but it should be easy to adapt these instructions for wired Ethernet.

Connect via SSH

Open a terminal session on your usual computer. To access your Raspberry Pi via SSH, run the following command, replacing <username> with the username you chose in Imager:

$ ssh <username>@pi-kiosk.local
The authenticity of host 'pi-kiosk.local (fd81:b8a1:261d:1:acd4:610c:b069:ac16)' can't be established.
ED25519 key fingerprint is SHA256:s6aWAEe8xrbPmJzhctei7/gEQitO9mj2ilXigelBm04.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'pi-kiosk.local' (ED25519) to the list of known hosts.

<username>@pi-kiosk.local's password:
Linux pi-kiosk 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Oct 24 09:41:00 2023
<username>@pi-kiosk:~ $

When asked for your password, use the password you created in Raspberry Pi Imager.

As the kiosk will be left unattended and/or displayed in a public place, it’s always a good idea to make sure that your software is up to date.

Run this command to refresh the list of available updates:

$ sudo apt update

Then run this command to install those updates:

$ sudo apt -y full-upgrade

Hide USB ports

As this project currently stands, simply plugging a keyboard and mouse into the USB ports on your Raspberry Pi would give an attacker full control. To defend against this, the Raspberry Pi should be placed in a physically secure case to make the ports inaccessible.

Set up SSH using keys rather than a password

Until now, you have connected to your Raspberry Pi with SSH using a password. We can provide an extra layer of security by using pre-generated private-public ED25519 keys and removing the ability to log in with a username and password altogether. With key-based authentication, you’ll keep a private key on your usual computer and a public key on your Raspberry Pi. This variant of authentication is much harder to crack than a username and password. To create ED25519 keys (which are more secure than the older RSA keys), open a terminal on your usual computer and run the following:

$ ssh-keygen -t ed25519

Accepting the defaults when prompted will create a private key and a public key. The location of these saved files is also given:

$ ssh-keygen
Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/<username>/.ssh/id_ed25519):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/<username>/.ssh/id_ed25519
Your public key has been saved in /Users/<username>/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:u3Ry3y8g3tEo4TChzzjmebihkWqonbhVj7qiq3BsjMk <username>@<hostname>.local
The key's randomart image is:
+--[ED25519 256]--+
|                 |
|        .        |
|       . .       |
|      . o .      |
|    .  +S+ . o   |
|.= . ++ o.+ + .  |
|+E* +oo++.o+ o   |
|+*.+ o+o.=.....  |
|@=*.. .o.   . .o.|
+----[SHA256]-----+
$

The id_ed25519 file is your private key; do not share it. The id_ed25519.pub file is your public key. To use key-based authentication, transfer the public key to your Raspberry Pi.

Run the following command on your usual computer to print your public key to your terminal:

$ cat ~/.ssh/id_ed25519.pub

Copy the output of the command into your clipboard. Now, let’s move the public key onto your Raspberry Pi.

Connect to your Raspberry Pi over SSH:

$ ssh <username>@pi-kiosk.local

Then, create a folder called .ssh in your home directory:

$ mkdir ~/.ssh

Next, open a text editor for a new file named authorized_keys in the .ssh folder:

$ nano ~/.ssh/authorized_keys

Paste the contents of id_ed25519.pub from your usual computer into this file. Press Ctrl+X, then Y, and finally Enter to save the file with nano. Finally, disconnect from your Raspberry Pi:

$ exit

Now try reconnecting, from your usual computer, to your Raspberry Pi via SSH again:

$ ssh <username>@pi-kiosk.local

If everything works as expected, you will no longer be prompted to enter a password. We can now disable password access completely by editing the /etc/ssh/sshd_config file:

$ sudo nano /etc/ssh/sshd_config

Find the line that reads #PasswordAuthentication yes. Uncomment it by removing the #, then change yes to no, so that it looks like this:

# To disable tunneled clear text passwords, change to no here!
PasswordAuthentication no
#PermitEmptyPasswords no

Press Ctrl+X, then Y, and finally Enter to save the file with nano. Reboot your Raspberry Pi:

$ sudo reboot

Now your Raspberry Pi is hardened against attacks over SSH.

SD card read-only mode

Unplugging your Raspberry Pi to shut it down can eventually result in system file corruption. Any operating system stored on an SD card may eventually fail if used for long periods of time. To reduce these risks, you can set your SD card to read-only. Open the raspi-config tool with the following command:

$ sudo raspi-config

Navigate through the menu system as follows:

This whole process may take a few minutes to complete.