Skip to content

Setting Up OctoScreen and Your Display

Jump to bottom
JeffB42 edited this page Mar 27, 2021 · 16 revisions

There are many options for displays that will work with OctoScreen and your Raspberry Pi. If your display is not working properly, I'm not able to provide support, and you should seek out the manufacturer of your display for drivers, configuration settings, and help getting your display working. That being said, here are some tips on getting your system up and running and working with OctoScreen.

Supported Hardware

At this time, only the Raspberry Pi 4 and Raspberry Pi 3B are supported. Other CPUs like the Raspberry Pi Zero and BeagleBone are not supported. They might work, but if you encounter problems, it's up to up you to troubleshoot and work through them.

Supported Distros

Only use OctoScreen with the OctoPi distro. Do not install OctoScreen on a system that already has a GUI shell installed. OctoScreen expects to run on a system where it is the only GUI application running. It might be tempting to have only one Raspberry Pi and use it for all your needs, but you will most likely face issues. Either purchase a Raspberry Pi dedicated to OctoPrint and OctoPi, or purchase an SD card dedicated to OctoPrint and OctoPi.

Known Displays - Pimoroni HyperPixel 4" Capacitive Touch Display

Chris Riley posted an excellent video on how to set up a Pimoroni HyperPixel with OctoScreen. In fact, if you are are running into issues configuring your display but it's not a HyperPixel, it's still worth watching his video, as it has a lot of great advice and tips. This is the display that I regularly use and I recommend it. It works, there are setup instructions that are known to work, it has a capacitive touch display so you can use your finger and don't need a stylus, and I find the 4" 800x480 form factor better than the 3.5" 480x320 screens.

Pimoroni HyperPixel - 4.0" high-Resolution Touchscreen for Raspberry Pi

NOTE: You will need the version of HyperPixel which has capacitive touch, and will need the rectangular version, not the square version.

Known Displays - 3.5" Displays Which Connect via HDMI

OctoScreen is based on Golang, usually this means that is dependency-less, but in this case GTK+3 is used, this means that GTK+3 libraries are required to be installed on the system. Be sure that graphical environment is additionally installed. Required packages can be installed using:

sudo apt-get install libgtk-3-0 xserver-xorg xinit x11-xserver-utils

Also you may need to install video drive, usually no screens found error indicates this. Please find manual here: https://github.com/ssvb/xf86-video-fbturbo/wiki/Installation

Next, the recommended way to install OctoScreen is use the .deb packages from the Releases page. The packages are available for Debian Stretch based distributions such as Raspbian and OctoPi.

For example for a Raspbian Stretch:

wget https://github.com/Z-Bolt/OctoScreen/releases/download/v2.7.0/octoscreen_2.7.0-1_armhf.deb
sudo dpkg -i octoscreen_2.7.0-1_armhf.deb

(NOTE: This document is not kept up to date, and the build listed above might not be the latest release. To install the latest release, see https://github.com/Z-Bolt/OctoScreen/releases)

Known Displays - 3.5" Displays Which Connect via the GPIO Pins

There are many inexpensive 3.5" 480x320 screens available on Amazon. For the most part, it seems they are clones of each other and use the same Waveshare LCD35 drivers. (not confirmed, but many of the 3.5" 480x320 displays on Amazon seem to be the same) This screen has been problematic - it's cheap and popular, but is only 480x320 and OctoScreen requires a minimum display of 548x348... there's a way to scale the screen to a higher resolution (giving the impression it's a larger display) but this can be tricky to set up and get working properly.

@mattglg, @DanielP5433 were VERY helpful in tracking down the issue and coming up with a working set of instructions. I consolidated the instructions and posted the instructions at Installing OctoScreen with a 3.5" 480x320 TFT screen. @Protean-Man also wrote up an install guide and posted his instructions at Octoprint Setup Help

Here is a list of screens that are known to work, though searching on Amazon you will find many that are similar, but under different brand names:

Clone this wiki locally