OctoPi - Easiest Option to Explore OctoPrint!

The easiest way to setup your RasPi for OctoPrint is to download the pre-loaded SD Card image from the GitHub repo maintained by Guy Sheffer, with source located here. (Latest  image can be found here.)

This first step -- getting the image on the SD card -- can be a tricky challenge for those not comfortable on the command line or Linux systems. If this describes you, I suggestion that you grab one of the helper utilities from the Embedded Linux Wiki page to make it a lot easier and safer to produce the card we will use to activate your system.

There are a range of methods to get the image onto your SD card, depending on your operating system. For the purposes of this Guide, I set things up on my MacBook Pro with OS 10.8.5 with a built in SD card slot, using PiFiller. And there have been reports of ApplePi-Baker (test SUDO and non-SUDO versions) working on Mavericks and Yosemite as well.

For other OSes, please take advantage of the well-maintained "RPi Easy SD Card Setup" wiki page.


Raspberry Pi Software Configuration Tool

When you boot up your OctoPi OS for the first time, you will see the raspi-config tool, just like you might if booting Raspbian or other RasPi OSes for the first time. Here are my suggestions for what settings to tweak:

  • (1) Expand Filesystem
  • (2) Change User Password. Your Pi is a mighty tool that will have the power to command a 3D printer, among other tricks. Keep it safe!
  • (5) Enable Camera. If you have a camera attached, activate your Pi Camera here. (Recommended configuration!)
  • (8) Advanced Options. If you live in a world with many printers and Octopi rigs, change the network name for each octopi to keep yourself sane.

Note that if you are using a WiFi adapter instead of an ethernet connection, you may want to change (3) Enable Boot to Desktop/Scratch option to boot once into the GUI so that you can configure the wifi elements there using quick GUI wireless management tools. I always prefer to leave this on default and boot to command line -- and enter startx should I want to bring up the GUI to use the Wifi-Config tool.

First Boot Command Line Tasks

After you run the raspi-config tool and boot to the command line for the first time, you will watch as a long stream of updates are posted to the terminal for everything from the final stages of setting up to the booting of the Octoprint server elements. The great advantage of OctoPi is that as with development OSes like Adafruit's Occidentalis disk image, a number of helpful tools, processes, and services have been activated that you would otherwise need to spend another 45min tuning and configuring. 

Your tasks are as follows:

  • Check the tail end of the terminal posts to see if the Camera Module is working -- if you have patched it in correctly. If everything is not right, the system will keep trying. (Well, as long as you enabled the camera in raspi-config.) Maybe it is just me, but I depend on checking this occasionally to make sure I seated the flex cable properly!)
  • sudo ifconfig. One of the various ways to check to locate the IP address of your Pi. If you are connected via ethernet, check next to eth0. If you have a wifi module attached, check next to wlan0. While most of the block might be meaningless to you, locating the inet address with the IP for either option is handy, as is noticing whether it is listed as UP or DOWN.
  • sudo apt-get update && sudo apt-get upgrade - [optional] Update the database of available software packages and then update any packages to newer versions. OctoPi lags a bit behind OctoPrint and Raspbian, so this can be handy to pull in fixes otherwise difficult to troubleshoot. In the case of my testing, some handy tools for working with Repetier Firmware and the release of PySerial updates to allow the RasPi to connect more successfully at 250000 baud were solved more easily by updating these 

A few handy commands to have at your disposal:

  • raspi-config - will re-run the Raspberry Pi Configuration Utility.
  • startx - will bring up the GUI if you have a display attached.
  • sudo shutdown -h now - Shut your system down now with a halt so that it doesn't reboot. Handy for unplugging and moving your rig.
  • sudo reboot - Similar, but reboots instead!

SSH Accessing Your OctoPi From Your Network

While there isn't much that you'll need to do here now that you can't do via the OctoPrint web-based UI, I recommend attempting to SSH into your Pi from your other machine first -- to make sure your network access is all set and that you can send the commands to shutdown or reboot your pi easily if anything behaves strangely.

So open up a terminal tool and type the follow.

ssh pi@[hostname]

For "hostname" you can use either the IP address (that we learned in the previous step using "sudo ifconfig") or the hostname of your Pi (which is "octopi" by default).

If you aren't familiar with SSH, please visit Simon Monk's guide on the Learn System here first to get a head start. 

So thankfully there isn't that much you need to be doing on the command line until you make further use of this connection for running updates of your Pi's software or operating system -- or you have a custom project you want to deploy. But knowing that this works -- or that the IP address works but the hostname you have for the Pi does not, makes the next step easier.


One handy trick if you, like me, continue to experiment with setting up separate OSes on a Pi that continues to show up with the same IP address -- you can kill the RSA assigned ssh key from your host computer by typing: "ssh-keygen -R [hostname]". (You can use the IP address itself -- that was just rejected! -- as the hostname.)

Activating OctoPrint for the First Time

Hooray! If you have made it this far, you are ready to jump in and connect to your OctoPrint server via the web interface. From here on out, you will mostly be connecting to your Raspberry Pi Octoprint rig via a web browser on the same network as your printer, or via SSH on a command line interface. 

To reach Octoprint, you type into the address bar for a browser like Safari, Chrome, or Firefox the following:


As with the SSH setup above, you can either use the direct IP address for the machine, or the hostname that you set in the Raspberry Pi Configuration Utility (defaults as "octopi" unless you change it).

So for most first time users, the entry you will use is: 


And the first thing that will appear when the OctoPrint UI comes up is the window above requesting that you enter a username and password for Access Control. Unless you think the idea of 3D printed SPAM and takeovers is something you'd like experience instead of just read about, I highly suggest you create a username and password, and keep your printer host safe!

After setting up Access Control, you will see.....

OctoPrint Web Browser Interface

The basic interface of OctoPrint is very straight forward -- and as you tweak the few settings you need to match your machine, you will find that you will tend to only need a few elements of the UI to accomplish most of what you need!

  • CONNECTION. You set the Serial Port and Baud Rate for your machine here, and then hit "Connect" or "Disconnect" as needed. Once you have this set, you'll probably want to click the top bar to minimalize this block.
  • STATE. Reports back both Machine state and print-progress information in one handy window. This is one of the most useful features of OctoPrint, and you will likely leave this open whenever you are operating your printer.
  • FILES. Here is where you upload, add to the print queue, and trash gcode files for printing. You can also drag gcode anywhere into the OctoPrint window if you don't want to click on "Upload" and "Upload to SD" card buttons. 
  • PRIMARY OCTOPRINT WINDOW. This pane is divided into a number of different "modes" that are ways to use and access your OctoPrint.
    • TEMPERATURE. Monitor current and target temperatures. Activate/deactivate heating for toolheads, beds, and set offsets as needed.
    • CONTROL. One of my favorite windows. Output from Webcam displayed on top, and access to machine controls (movement, toolhead, fans) below, much like you might see in other host software. As an added bonus, you might be repositioning the toolhead, checking for jams or halts -- from elsewhere on the network, or even elsewhere in the world.
    • GCODE VIEWER. Doubles as a tool to analyze the GCode print job files you are about to run, and shifts into live gcode feedback mode during printing.
    • TERMINAL. Grants you terminal access to your serial connection to your machine. Useful to read to see reports when things aren't working. There is a command box for sending GCodes, MCodes etc that are used for specific configuration needs for your machine, receive feedback from a custom sensor, or even change the color of LEDs.
    • TIMELAPSE. Activate preset timelapse tools (either via time or triggered by z-movement) or come up with your own timelapse script. A handy way to keep a record of what happens for every print, whether you are monitoring the print itself closely or not!

 There are lot of bells and whistles here that you will want to explore in the future. For now, head on to the printer configuration pages that follow to select the connection information so that you can connect to your machine and give printing gcode files a go!

This guide was first published on Nov 06, 2014. It was last updated on Nov 18, 2015.

This page (OctoPi - Ready-Made OctoPrint OS Disk Image) was last updated on Nov 05, 2014.

Text editor powered by tinymce.