OctoPi with OctoDash on RPi 4 with HyperPixel 4.0

Recently I started a new hobby; 3D printing. This is my first blog post about this subject and I intend to create many more. To control my 3d printer, I use a Raspberry Pi 4 with a HyperPixel 4.0 Touch screen and the Raspberry Pi Camera module v2. On the Raspberry Pi, I am using an OctoPi image (Currently v0.18.0 32-bit) with OctoPrint installed. I will also install OctoDash to show some magic on the screen.

Bill of Materials (BOM)

Warning: If you are using a Display with your Raspberry Pi, always make sure that you have a powerful adapter. I would like to suggest the original Raspberry Pi Adapter. This adapter has 3A of power. A phone charger does not have enough power!

3D Printed case

I am currently using the Hyperpixel 4.0 touch and Raspberry Pi 4B case on Thingiverse that I am remixing to have a slot for the Ribbon Cable and an adjustable mount. If you want to use that case, the description on Thingiverse explains how you should print it. I would like suggest to printing it in PETG due to the temperature of the Pi.

The remixed model is now available on Printables / Thingiverse

Required hardware/software

Hardware

Aside from the BOM above, you’ll need some hardware that you probably already have, however, I am adding them here in case you don’t have them.

To flash your SD card for your Raspberry Pi, you’ll need a computer or laptop with a (Micro)SD card slot. The SD card that I bought has an adapter for Micro SD to SD. Depending on your machine, you might need such an adapter to insert the card into your PC.

While not required, an HDMI monitor or TV and USB keyboard are handy during setup. The Raspberry Pi 4b has two Micro-HDMI ports, these ports are quite new and most people will probably not have a cable or an adapter that fits those ports. A 1m cable is added optionally in the BOM above.

Software

To unzip the archive, the default Windows “Extract All” is sufficient, however, I like to use 7-zip (Chocolatey users: “choco install 7zip.install”).

You’ll need to have a tool that can write the OctoPi image to your SD card. I like to use Win32DiskImager to write the image (Chocolatey users: “choco install win32diskimager.install”). During this tutorial, I am going to use that tool. Other tools that you could use are Rufus or balenaEtcher.

One other tool that you need is a good text editor, I like to use Notepad++ (Chocolatey users: “choco install notepadplusplus.install”) or VSCode (Chocolatey users: “choco install vscode”) Please do not use Notepad, Word, Wordpad or any rich text editors. Your editor needs to be able to handle files with Linux line endings.

To connect to your Raspberry Pi, once connected to your network, you’ll need an SSH tool. I like to use PuTTY (Chocolatey users: “choco install putty.install”), it’s a tool that has been around for quite a while. If you like to use another tool, feel free to do so.

Setting up OctoPi

Currently, OctoPi only comes in a 32-bit version. There is a nightly build with 64-bit available but I’ll be using the 32-bit version for now. In theory, OctoPi runs on all Raspberry Pi devices, however, an Raspberry Pi Zero or Zero W is not recommended due to performance reasons. The HyperPixel 4.0 display only works with a Pi 2, 3, or 4. Therefore a Pi 2, 3, or 4 is required.

Download OctoPi

To get started, you should download the latest OctoPi image. Head over to the download page on the OctoPrint website and download their latest release, at the time of writing this is version 0.18.0 32-bit. This file will be 700MB – 800MB in size. Once downloaded, extract the file with 7zip or the Windows extract. Inside the extracted folder you’ll find an .img file. This file is a couple of GBs in size.

Insert your SD card into your computer, a window might pop up showing the contents of your SD card.

Warning: Make sure there isn’t anything on that SD card that you want to save, after this section all data on that card will be gone!

Flashing SD Card

Start Win32 Disk Imager. You will probably get a pop-up that this tool wants to make changes to your device, you’ll need to accept it. Once started, click on the folder icon on the right side of the “Image File” section in the tool and browse to the .img file of OctoPi. If you have done everything correctly, the program should look like this:

The Image filename and the device shown on the right might be different on your machine. Make sure the Device matches the drive letter of the SD card that you inserted. Once all the settings are entered correctly, press Write. A pop-up message should appear asking if you want to overwrite the image. If you are sure you want to use that device, click Yes. Win32 Disk Imager should now start flashing your SD card with the OctoPi image.

Depending on the speed of your SD card, this can take up to a couple of minutes. During the flashing of the SD card, an Explorer window might pop up asking you if you want to format a drive. Do NOT format this drive, this is the Linux partition where OctoPi is installed. If you have formatted this drive, you should flash your SD card again.

When Win32 Disk Imager finishes with a “Write Successful” message, you can click on OK and Exit after that.

Configure WiFi (Optional)

Note: If you intent to connect your Raspberry Pi to your network using an Ethernet cable, you could skip this step. You can connect that cable now.

Just to be sure Windows has detected all changes on your SD card, eject your SD card and put it back in. In some rare cases, files do not show up right after flashing your SD card. This can happen with any tool that you use. Windows may ask you to format a drive again, do NOT do so!

Depending on your Windows configuration, an Explorer window should pop up. In that folder are a couple of TXT files. One of them is “octopi-wpa-supplicant.txt” Open this file in Notepad++ or VSCode.

I am assuming your WiFi network is configured with WPA or WPA2. If you are not sure, check your router configuration.

Inside that file, you’ll find a section that starts with “##WPA/WPA2 secured”. Remove the hashtag (#) before the 4 lines underneath that line and edit the SSID (WiFi network name) and PSK (WiFi network password). Both the SSID and PSK should stay surrounded with double quotes (“)

Almost at the bottom, a line with “country=GB” is shown. Change the letters of the country to match your two country letters. In my case, this would be “NL” Check this list if you are not sure what letters to use.

Once completed, save the file and close the editor.

Connecting the hardware

Warning: Like all hardware, an Raspberry Pi is sensitive to Static electricity. Make sure that you handle the boards correctly by only touching their edges.

Eject the SD card from your computer, if you have not already done so, and slide it into your Raspberry Pi. The connector of your SD card should face the bottom side of the Raspberry Pi.

If you have bought the heat sink kit, apply them now on the chips. Depending on the kit, there might be different heat sinks in there.

Raspberry Pi Camera

The Camera module comes with a short ribbon cable by default. Depending on how you want to set up your camera, this may or may not be enough length. There are different lengths available, I have used a 100cm one.

If you have bought a separate ribbon cable, you should remove the one that came with the Camera device. Lay your Camera module down with the camera facing your desk. Make sure you put the lens on something soft like the bag it came in.

To remove the cable, carefully pull the two black corners on the connector away from the Camera board. It only goes out 3mm or so and remove the ribbon cable by pulling it out. You shouldn’t have to apply any force to remove the cable. Attach one end of the longer ribbon cable to the camera and push the corners back. Make sure the metal connectors of the cable are in the same orientation as you pulled them out before.

On your Raspberry Pi board between the Audio and HDMI ports, there is a similar connector for the Camera. Carefully pull the left and right side of that port and slide the other end of the ribbon cable in there. The metal connectors should face the same side as your SD card is located.

HyperPixel 4.0

Inside the HyperPixel box, there are 4 standoffs, 4 screws, a 40-pin header, and the display.

Place the display on a flat surface, do not remove the protective cover yet. Screw in the standoffs and connect the 40-pin header. Do not apply any excessive force to the display as it might crack. Turn over your Pi, align the 40-pin header on the Pi with the header on the display, and gently push your Pi down. If you do not intend to use the case, use the 4 screws to attach your Pi to your display. Otherwise, follow the documentation of the case.

Configuring your Raspberry Pi

Once all hardware steps are completed, we are ready to power up our Pi. Connect your powerful adapter to your Pi and the socket. The HyperPixel Display will not display any output. This is because we need to install the drivers for the HyperPixel. (Optional) To be able to see any of the outputs, connect the Pi with an HDMI screen.

Most times, you can connect to your OctoPrint instance by using the “octopi.local” hostname. If this is not the case, you can find its IP address in your DHCP server. This is most likely the router in your home. For information on how to access your router and DHCP leases, please have a look at the documentation of your router.3

Tip: Search in the documentation of your router how to give your Pi a static lease, if possible. That way you are sure that your Pi gets the same IP address every time it starts and you can always find it in your network

Connect to the OctoPrint instance on http://octopi.local your newly created Pi and complete the Setup Wizard. I would like to advise you to set up Access Control, Enable the Connectivity Check, Enable Plugin Blacklist Processing, and set up your printer profile.

The instance that comes with the OctoPi image is probably outdated, while still connected to OctoPrint in your browser, open settings () and go to “Update Software”. Click on the “Check for update now” button and “Update all” after that. OctoPrint shows a screen that it’s updating and after it’s finished it automatically restarts the OctoPrint instance. Once OctoPrint is started, press “Refresh Now” to reload the screen.

Connecting to your Pi using SSH

SSH is enabled by default on your OctoPi. To connect to your Pi over SSH, you’ll need an SSH client, like PuTTY. In the Host Name field enter “pi@octopi.local” or change “octopi.local” to the IP of your Pi. This will connect to your Raspberry Pi with the username pi:

Click on Open. An SSH connection to your Pi will be made. If this is the first time you connect to this machine, a PuTTY Security Alert will appear. Click on Yes to continue.

The SSH connection now asks for a password. By default the password for your Pi is “raspberry” without quotes.

Warning: You should always change the password for the pi user. Use the command “passwd” to change your password. Store this password in a safe place, you cannot recover from a lost password.

Updating your Pi

I think it is always a good idea to update your Pi before making any changes. To update your Pi, run the commands below. The first command will ask for your password. This is the password for the Pi user that you just changed, right? Depending on your internet speed, the age of the image, and the speed of your SD card, this might take some time.

sudo apt update
sudo apt upgrade -y
sudo reboot

HyperPixel 4.0 driver installation

The installation of the HyperPixel 4.0 driver is quite simple. It’s well documented on their GitHub page. In this configuration, please follow these steps. In your PuTTY window, paste, by right-clicking in the window, the following command:

sudo apt install arandr i2c-tools xinput
curl -sSL https://get.pimoroni.com/hyperpixel4 | bash 

The first command will ask for your password, enter it. After you have entered the second command, you will be asked to continue, type “y” and press enter. The installation wizard now asks what combo of HyperPixel and Raspberry Pi you have. In my case, this is a Pi 4, and a Rectangular screen. As there are some known issues, I picked option 2 and pressed enter. It asks you to verify again. If it’s correct, type “y” and press enter. Enter your password for the user Pi

After some checks and installation of software, the Pi asks you to reboot. Type “y” again and press enter. Your SSH session will be disconnected, don’t close the window just now, you’ll need it later. You’ll see text scrolling on your screen during reboot if you have done everything correctly. The screen is probably not in the correct orientation, but that’s what we are going to fix next.

HyperPixel 4.0 orientation

Right-click on the title bar of the Putty window and click “Restart Session”. PuTTY will ask for your password again. Type your (changed) password and press enter.

First, we need to set some parameters for the touch screen. Enter the command below:

DISPLAY=":0.0" sudo hyperpixel4-rotate right

In case you have your HDMI connectors at the bottom of your screen, change right to left in the command above. Your screen will rotate, but this is not saved for reboot. We are going to fix that next.

We need to edit the startup configuration of your Pi. I like to use “vi” for that, but it might be a bit hard for people who are just starting with Linux. Therefore I will explain this using the “nano” tool. Execute the command below to open up the configuration file:

sudo nano /boot/config.txt

This command will ask you for your password, type in your password to continue. With the page down button or arrow keys on your keyboard scroll down to the line that starts with “[pi4]”. Add a pound sign (#) before the line that starts with “dtoverlay=vc4-fkms-v3d” Right-blow that line, and add an extra line “display_lcd_rotate=1”. Use 1 when your power and HDMI ports are on top. Change it to 3 when they are at the bottom.

Press “CTRL + O” to save your file. Do not change the filename, press enter to confirm. Press “CTRL + X” to exit nano. type “sudo reboot” to reboot your Pi. Your SSH session will be disconnected again, don’t close the window, you’ll need it later to install OctoDash. The orientation should now be correct. If the orientation is upside-down, change the “display_lcd_rotate” line. When using your Pi horizontally this value should either be 1 or 3.

Automatic login

By default, a Pi starts with a login prompt. In our case, we would like to show OctoDash on the screen and we need to change the default settings for login. Reconnect your SSH session, just like you did before, and execute the command below.

sudo raspi-config

Type your password to continue. A menu should appear. Select option “1. System Options” and press enter. Next, we will select the option “S5. Boot / Auto Login” and press enter. The last option we should select is “B2 Console Autologin” and press enter. Press “Tab” 2 times to go to “<Finish>” and press enter. Press “Enter” again to reboot your Pi.

Installing OctoDash

The next thing that we are going to install is OctoDash. Reconnect your SSH session, just like you did before. To install OctoDash, run the command below.

bash <(wget -qO- https://github.com/UnchartedBull/OctoDash/raw/main/scripts/install.sh)

The command will ask you for your password. Type in your password to continue. It takes a while and it seems to not be doing anything, it just takes a bit of time before output will be shown. This will happen a couple of times during the installation. The script will install a lot of packages to enable a graphic interface on your Pi, depending on the speed of your internet and your SD card, this might take some time.

After the installation of the packages, the installer asks the plugins that you want to install. Depending on the configuration of your printer and the plugins that you would like to use, select the line with your arrow keys and press the “spacebar” to select them. In this example, I have enabled them all. Press “Enter” to confirm. The installer now asks you if you want to start OctoDash during boot. I selected yes and pressed “Enter” Same for the automatic update script and reboot.

Configuring OctoDash

After your Pi is rebooted, you will be greeted by OctoDash. It takes a few seconds to start and you will be taken to a wizard to configure OctoDash.

Make sure you have your OctoPrint window open in your browser. You should be seeing the normal screen. You’ll need this window in a second to approve a connection between OctoDash and OctoPrint.

With your Touch Screen, tap on “next >”. The wizard asks you which OctoPrint instance you want to use. Tap on the OctoPrint instance on the screen. OctoDash wants to connect to OctoPrint, tap on “send request”.

In your OctoPrint instance, click on Allow. The wizard will now continue. By default the printer name is set to Default, you can change this with a USB keyboard or later by editing a file on the Pi (see below), tapping on “next >”. Enter the values that match your printer extruder. Currently, there isn’t a list of known printers. These values can be changed in a later state, tap on “next >” to continue.

Depending on the Plugins you picked during installation, enable or disable the plugins to match the installation. You can disable or enable them later again, tap on “next >” to continue. The wizard now stores your values in the settings file. Tap on “done” to complete the wizard.

If your printer isn’t attached to your screen, OctoDash will go into a sleep mode. OctoDash only works when your printer is connected to your Pi.

OctoDash printer name

If you want to change the name of your printer that is shown in the bottom left of your screen, enter the command below:

nano ~/.config/octodash/config.json

Change the text “Default” in the line ‘”name”: “Default”,’ to match your printer name. Press “CTRL + O” to save your file. Do not change the filename, press enter to confirm. Press “CTRL + X” to exit nano. For the changes to take effect, type “sudo reboot” to reboot your Pi.