How to install Octoprint on an Orange Pi Zero 2

Why ?

Let's say you've bought and built a new 3D printer, and started printing stuff like crazy. Yet, you now find very painful to have to remove the SD card each time, insert in the SD card reader, plug on your computer, open Cura or whatever other slicer you might be using, slice and save on the SD card and put back the SD card again in the printer then select the file to print, each time you want to start a new print.

So, with Octoprint, you'll get:

  1. 3D printer print monitoring (from anywhere, on your smartphone for example)
  2. Send file to print without having to leave your computer
  3. Power on/off the printer remotely
  4. Preview the model to print
  5. Create nice timelapses from your prints.
  6. Optionally, get an alert if the printer starts to print spaghetti

How ?

Octoprint is a HTTP server software that's expected to run on a small computer. Many will install Octoprint on a Raspberry Pi (minimum Raspberry Pi 3 is required here) either manually, or by downloading a prebuild image (called OctoPi). However, this means you'll need to source a Raspberry Pi, a casing, likely the Raspicam also, and this is not cheap. All in all, it'll cost around 50€ for the board + casing and almost the same for the Raspicam here. Also Raspberry Pi model 3 is a bit outdated now.

Instead, I'm explaining here how to get the same features with an Orange Pi Zero 2 which is smaller, faster and cheaper.


You'll need a SBC (single board computer) and, currently, the best deal is the Orange Pi Zero 2. If I were you, I'd choose the 1GB version (even if it's a bit more expensive than the 512MB version). Don't be mistaken by all the other board from Orange Pi (like the Zero, the Zero+, the Zero+2). This one is using an Allwinner H616 CPU that's a 64bits ARM CPU.

View of Orange Pi Zero 2

It costs less than 30€. Right now, it's running Armbian with Debian Buster, but a port to latest version is coming (but not ready yet)

There's also a nice transparent case for it. You'll also need a µSDcard (8GB or 16GB is enough) but you can reuse any card you already have.

If you intend to monitor your 3D printer, you might be interested by buying a webcam too (~20€).

You'll need a USB-C cable to power it (you can reuse any cable here, only the 5V and ground pin is used here, you don't need the more expensive data cable).


Installation process is quite straightforward, provided you already know how to use Linux. If you don't, don't worry, I'll (try to) explain here what we are doing.

Preparing the microSD card

Unlike your computer, this small board does not have any non-volatile memory to boot from. This means that the operating system will have to be written to a SD card and it'll boot and run from this µSD card. You should use a 8GB or bigger card here. The larger the card, the less likely it'll run out of space with software update and card damage due to wear. So a 16GB card is probably 1€ more expensive, but if it saves you 4h for reinstalling everything, it's 1€ well spent.

Once you have the SD card ready, you'll need to download the Armbian image for this board from here, click on Google Drive icon. Then you'll need to uncompress this file with 7-zip (on Windows), 7z (on linux) or The Unarchiver (on MacOS). Once you've uncompressed the archive, you'll get a .img file that you'll need to burn to the SD card. Although it can be done with few low level commands, I recommend to use BalenaEtcher software:

  1. You'll pick the .img file
  2. You'll select the µSD card drive on your computer (check the size is matching with your SD card size, don't select your computer's hard drive here)
  3. Burn the image (wait few minutes to happen)
  4. Eject the card, you're done!

First boot

The first boot is a bit long. You'll need to connect a Ethernet cable from your router to the Opiz2 port, even if you intend to use Wifi later on. Plug the ethernet, plug the USB-C cable and wait until the Ethernet is blinking in green. Once this is done, you'll have to find what IP address was leased to the Opiz2.

There are multiple way to do that (and if you don't know what I'm talking about, try each method below in order until one is working):

  1. Solution 1: Connect on your router's administration webpage and list the clients (or the DHCP leases). You're either looking for the newly obtained lease or the client with name orangepizero2. This will give you the IP address (a sequence of 4 numbers separated by dot, like of the board.
  2. Solution 2: Use nmap tool (or an IP scanner tool). Scan your own network for new devices, with a ping scan. Typically, the nmap command is nmap -sP or nmap -sP You'd get an answer like this:
    Nmap scan report for orangepizero2 (
    Host is up (0.0015s latency).
  3. Solution 3: Open a terminal and get your computer IP address (with ipconfig) and start playing trial and error here. For example, if you have an address of, try pinging and so on until you get an answer. This will return false positives here, so you'll need to check if the answer comes synchronously to the green LED blinking on the Opiz2.

Initial connection to the Opiz2

Ok, now you have the IP address of the board, you'll have to connect to it. You'll need a SSH client for this. On both Linux and MacOS, it's as simple as typing ssh root@ (replacing with the board's IP address here) in a terminal. Under Windows, you'll need to download Putty and follow the GUI here.

The initial root password is orangepi.

Updating the operating system

The first command to run is to fetch the latest version of the operating system via:

Don't type the first $ or # in the command below. $ means that the command must be issued by an unpriviledged user, and # means that the command should be run by the root user

# apt-get update
    Blah blah, very long...
# apt-get upgrade 
    Say yes by typing 'y' and wait.

You might have to run this command pair from time to time to maintain your system fresh.

Preparing users

You don't want to leave a default user and password on a device. You need to customize it to your own here. So we'll remove the orangepi user and create your own and give you permissions to use all peripherals on the system. You must not remove the root user (but you can change the password or empty it).

Replace yourname below by your private name

# adduser yourname
# usermod -a -G sudo yourname
# deluser orangepi
# usermod -a -G video,plugdev,games,users,systemd-journal,netdev,input,ssh,dialout,audio,tty,disk yourname
# passwd
     Type your new root password here twice

Enable WIFI

To enable WIFI, you'll need to perform two operations: join a WIFI network, and set a static IP address so your board is always reachable at the same address (no more guess my IP game anymore):

  1. Run orangepi-config command to set the board's hostname, timezone and scan for WIFI network and join a WIFI network. If this fails, you'll need to exit the software, type sync and reboot the board and try again once it has booted again.
  2. Run nmtui command as root to change the IP address configuration for your WIFI link from dynamic to static IP. If you don't know what address to put here, I'd say that many router don't reserve all address pool for dynamic address, so they are likely using address from 1 to 100 (for the last number) for dynamic address DHCP, so it should be safe to use a 200-ish address or so for your board. You'll need to remember this IP address as it'll be the address to use from now on.
  3. Make sure the WIFI link is working by connecting via ssh from your computer.
  4. Sync and reboot (sync && reboot) and test again. If it works, you can unplug the Ethernet cable, move your board to its final location: close to your printer.

As a side note, if your WIFI connection is unstable (if it's dropping after some time), you'll get the impression the board is hung, but it's not (plugging an Ethernet cable would prove it). This happens because network manager is not able to restart connection by its own (maybe your WIFI access point is not reachable at some point) and give up the re-connection process. In that case, I advice you to create a rule that'll be run on Network Manager's down event, by creating a file in /etc/NetworkManager/dispatcher.d/90-restartwlan containing:


UUID="<copy the connection UUID for your wifi here, run nmcli to find out>"

interface=$1 status=$2
if [ "$CONNECTION_UUID" = "$UUID" ]; then
  case $status in
      echo "$(date +"%F %T") Called with ($*) and connection uuid is: ${CONNECTION_UUID}" >> /var/log/nm-dispatcher.log
      nmcli d connect wlan0

If your connection is dropping because the AP is not visible at time, you should also add a timer that'll reconnect when possible: So add 2 files like this:

$ sudo cat > /lib/systemd/system/wlan.timer << EOF
Description=Check wlan0 connection



$ sudo cat > /lib/systemd/system/wlan.service << EOF
Description=Restart wlan connection

ExecStart=/bin/sh -c '/bin/ip addr show wlan0 | /bin/grep DOWN > /dev/null && /usr/bin/nmcli d disconnect wlan0 && sleep 5 && /usr/bin/nmcli d connect wlan0'


$ sudo systemctl enable wlan.timer
$ sudo systemctl enable wlan.service
$ # Optional
$ sudo systemctl start wlan.service

Installing Octoprint

To install Octoprint, we'll need to create a low privileged user first and give him the minimum rights required to run octoprint and connect to any device (printer/camera/etc). From now on, you don't need to connect to your board via the root user, you should use yourname instead.

So, let's do that:

$ sudo adduser --home /home/pi --disabled-password --disabled-login  pi
$ sudo usermod -a -G tty pi
$ sudo usermod -a -G dialout pi
$ sudo usermod -a -G video pi
$ sudo apt install python3-pip python3-dev python3-setuptools python3-venv git libyaml-dev build-essential ffmpeg
$ sudo -u pi bash

Now you are in a sub-shell for this pi user. We'll install octoprint for him:

  $ mkdir /home/pi/OctoPrint && cd /home/pi/OctoPrint
  $ python3 -m venv venv
  $ source venv/bin/activate
  $ pip install pip --upgrade
  $ pip install octoprint
  $ ~/OctoPrint/venv/bin/octoprint serve

If everything went well, you'll need to connect your computer's browser to http://your.board.ip.address:5000 and follow the setup instructions on this page.

Once it's done, you can stop Octoprint's program in the console by hitting Ctrl + C and then Ctrl + D, you'll be back at your own user shell.

Making sure Octoprint starts on boot

We are now adding a service that'll start Octoprint when your board is booting:

$ wget && sudo mv octoprint.service /etc/systemd/system/octoprint.service
$ sudo systemctl enable octoprint
$ sudo systemctl start octoprint

Make sure you can connect via your browser again, and if it's working you're done!

Additional steps for a better life

If you want to have octoprint superpowers, like restarting itself or stopping the system, then the pi user must be granted some privileges. You don't want to grant complete sudo rights to this user since if a bug or an exploit happens in Octoprint, your system will be at risk. So the better solution here is to grant the pi user only the required sudo commands like this:

# echo "pi ALL = NOPASSWD: /bin/systemctl poweroff,/bin/systemctl reboot,/bin/systemctl restart octoprint" >> /etc/sudoers
# cat /etc/sudoers
# This file MUST be edited with the 'visudo' command as root.
# Please consider adding local content in /etc/sudoers.d/ instead of
# directly modifying this file.
# See the man page for details on how to write a sudoers file.
Defaults        env_reset
Defaults        mail_badpass
Defaults        secure_path="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

# Host alias specification

# User alias specification

# Cmnd alias specification

# User privilege specification
root    ALL=(ALL:ALL) ALL

# Allow members of group sudo to execute any command
%sudo   ALL=(ALL:ALL) ALL

# See sudoers(5) for more information on "#include" directives:
#includedir /etc/sudoers.d

pi ALL = NOPASSWD: /bin/systemctl poweroff,/bin/systemctl reboot,/bin/systemctl restart octoprint

Before logging out from root shell, try that sudo is still working via:

# sudo ls

In case of error, remove the last line I've told you to add (or double check it above) via nano /etc/sudoers but don't log out your root shell until the error is fixed, else you might never be able to log as root again later on

Previous Post Next Post

Sponsored links

In order to pay for infrastructure cost for this blog, I'm listing some affiliated links about the hardware listed above.

Related Posts