OctoPrint and 3D Printer "Host Software"

Untether Your Desktop 3D Printer!

What is OctoPrint? It describes itself as desktop 3D printer "host software" -- a utlity that receives job files (gcode) from your "slicer" (the CAM tool that builds fabrication instructions from your digital model) and then delivers this code to the printer itself, typically via USB. A snappier way to say this: OctoPrint is a "nanny cam" for your printer. ;-)

Sure, setting up host software to run your printer from your desktop or laptop sounds like nothing new. Since the first RepRaps, the MakerBot CupCake CNC, Ultimakers, and Printrbots, there have been apps like ReplicatorG, PrintRun, and Repetier Host that hobbyist and competing printer vendors shared together as what is used to run your printer. (The slick proprietary, vendor-specific utilities came later...)

But guess what, you can run this new breed of host software on a Raspberry Pi, a BeagleBone Black, or other lightweight, affordable embedded Linux system. And these platforms bring with them opportunities to customize with the software and hardware accessories.

Third party host software is coming back into style!

3D Printer Host Software 2.0: Your Software/Hardware Automation Playground

The last few years have seen an explosion of printer tool development -- with open, innovative tools like Cura and MatterControl continuing the tradition of the open platform while machine-specific tools such as MakerBot DesktopFormlabs PreForm, and 3D Systems Cubify hone in on hyper-machine-specific and marketplace-tie-in features. And on the horizon are universal printer platform tools such Autodesk's Spark and direct printer-driver style integration into operating systems and design packages themselves.

The game changed this past year with the newfound popularity for a new type of host software -- lean, clever web/cloud savvy software packages such as OctoPrint, AstroPrint, PrintToPeer, BotQueue, and 3DPrinterOS that can be deployed on affordable embeddable solutions such as a Raspberry Pi or BeagleBone Black, operating from clients as lightweight as webpages and custom mobile apps, bringing to any given printer (if resources exist for interfacing with the firmware!) highend features as:

  • wireless printing
  • remote job start/kill from mobile phones
  • queue management that automatically logs print success data
  • real-time gcode visualization
  • custom automation/event hooks
  • smart and port-hole machine vision
  • automatic timelapse production...
  • and anything else you can dream up that a featherweight Linux system can tackle.

At the heart of this rise in popularity is the open source project OctoPrint, created by software engineer Gina Häußge, and its community-distributed, easy-to-install OctoPi image.

OctoPrint + Adafruit Hardware = <3 <3 <3

Here are a few of the features bundled into OctoPrint out of the gate:

  • Untether your laptop from your printer and put it on a network.
  • Control your printer as if you were sitting right next to it.
  • Monitor your prints from across town, or across the ocean.
  • Free as in beer and speech.
  • Visualize your gcode before you run your job, with realtime gcode simulation.
  • Compatible with a wide range of desktop 3D printers.

Leveraging simple python scripts shared by an active community developers and any number of easy-to-use webtools, 3D printer hobbyists have more opportunities to experiment with adhoc hardware and software tweaks for their (working) 3D printer than ever before! And after you get your feet wet, the RepRap community and custom building your own printer and printer accessories await. ;-)

For this introductory guide, we will start with the easiest way to get into OctoPrint -- downloading a pre-loaded "OctoPi" SD Card image from the project maintained by Guy Sheffer, with source located here. And proceed from there to share resources to help you setup OctoPrint and configure for the desktop 3D printers currently offered at Adafruit!

Prerequisite Guides

Before you continue further, make sure you have some basic experience setting up a Raspberry Pi, including a modest amount of command line comfort.

These steps are intended to be easy to follow for a Pi novice. However, if you get stumped we suggest diving right into the excellent OctoPrint Google Group to find solutions or post your experiences for help from seasoned Linux users / command line jockeys to get you back in the game.

We recommend walking-through the following tutorials below before starting this project. These guides will help you get familiar with the components and get setup and configured with your Raspberry Pi:

Outfitting OctoPrint For A Raspberry Pi

Basic OctoPrint Hardware

A minimalist setup for an OctoPrint embedded host for your printer can be very trim indeed -- just the Pi, a good power supply (or power from the printer power supply), a USB connection to the printer, and a WiFi or ethernet network connection.

But a typical OctoPrint setup designed to take advantage of all the features might include:

Building A Custom OctoPrint Setup

My OctoPrint experimenter rig (above) rolls up a bunch of prototyping elements in one handy package. At the center of it, a quick scaffold of Open Beam mini-extruded beams trapping an Adafruit Pi Dish on top and a Mini Thermal Receipt Printer below. A 7-port USB Hub and all of the cabling is lashed to the sides and interior of the structure, making this a pretty compact experimenter rig -- that can be access, re-routed, reconfigured at a moment's notice!

Adafruit has a wide variety of components, add-ons, breakout boards, sensors, displays, and tools to take your OctoPrint rig even further. Here are a few of the areas to explore!  

Be sure to check out the featured products on the right sidebar for more ideas.

Raspberry Pi Enclosures

The Adafruit Pi Box Plus Enclosure for RasPi Model B+ works well for protecting a Pi strapped to the side of a desktop 3D printer. But after you get going on this project, you are going to want to check out the many customized Raspberry Pi/OctoPrint 3D printable case designs shared online -- or design your own!

A few standout examples such as Octopi WiFi Camera Case for B+ by barney (above) and Printrbot Octoprint Wi-Fi-Pi camera case front for dual extruder by captainserial (below) integrate nice printer-specific mounting with unique features like barneyj's swivel-ready ball-joint for the Pi Camera. Checkout Thingiverse, Youmagine, and other respository sites online for ideas and models ready to be downloaded and printed.

Lightweight RasPi Go-Box

Your embedded systems "Go Box" is a collection of the tools you keep at the ready when you need to roll up your sleeves and work directly with your Raspberry Pi: everything you need to spin up new headless RasPis.

These items are useful to have on-hand when you are setting up your OctoPrint rig for the first time -- or if you are managing a botfarm full of them. After your Pi is setup, you can detach and pack up Go-Box to operate it "headless" (no keyboard, mouse, or display) from another computer.

  • HDMI enabled monitor / screen: Adafruit stocks a table-full of display options, but make sure to pick with high enough resolution for you to debug code and preferences.
  • USB Keyboard or Wireless Keyboard, with mouse.
  • Power supplies + supply-friendly power strip (required), everything you need to run your Pi, display, hub, and potentially a tiny network switch.
  • Backup 8GB SD/microSD cards preloaded with your favorite host software OS image.
  • 4+port Switch + two or more Ethernet cables (optional). Bring your own copper network with you! Adds weight but can help eliminate wifi troubleshooting while you get your Pi and Pi wireless add-ons configured.
  • Ethernet adapter for your laptop. If you are bringing your laptop with you for controlling the headless Pi, make sure you bring an adapter for connecting to an ethernet cable if yours doesn’t have one built-in.

Blinging Out Octoprint

  • NeoPixel Rings and NeoPixel strips: Map colors, individual lights, and brightness to ndicate temperature, print completion, or even test "What color do I print next?" by bathing your build platform in light!
  • Raspberry Pi NoIR: Continue to shoot timelapses and evaluate printer health without rigging up lighting around your printers.
  • Weatherproof Metal On/Off Switch with LED Ring - 16mm: Add a halt button, 
  • or even an automated pause that moves the toolhead away from the part
  • Thermal Printer: print out slicer settings to have handy with the resulting print, or even a receipt for the amount of plastic consumed!

Adding an OEM Display

Depending on where you have setup your printer, you might find it worth the time and expense to setup a dedicated display, keyboard, and mouse attached to your SBC. (We have many displays and resources for this -- check out the HDMI 4 Pi 7" display as a good compromise of small footprint but text-friendly resolution.)

For many users, I recommend that you setup your OctoPrint system as a "headless" system -- ie. a system that you will access and control only via the network using SSH (see our Learn Guide for SSH here) and/or VNC (using a client on your computer to access a network-delivered version of the GUI of your Pi). 

NOTE: If you aren't familiar with SSH, please visit Simon Monk's guide on the Learn System here first.

OctoPi - Ready-Made OctoPrint OS Disk Image

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:

[Hostname].local/

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: 

octopi.local/

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!

Configuring OctoPrint for Lulzbot TAZ

Model: LulzBot TAZ 4 - Open source 3D Printer

ManufacturerAleph Objects

Official Websitehttps://www.lulzbot.com/

Support Websitehttps://www.lulzbot.com/support

Electronics: RAMBo

Firmware: Marlin-based (located here)

Baudrate: 115200

Port: /dev/ttyACM0

  • There are a number of TAZ users running their unit via Octoprint now that TAZ is one of the officially supported options listed in OctoPrint.
  • The RAMBo electronics and Marlin-based firmware are both elements well implemented by OctoPrint.  
  • If you are having difficulty with losing connections in long prints, you may need to adjust the Timeout settings. Read more about OctoPrint's Configuration settings here

Configuring OctoPrint for PrintrBot Simple Metal & Kit

Model:

ManufacturerPrintrbot

Official Websitehttp://printrbot.com/

Support Websitehttp://help.printrbot.com/Answers

OctoPrint-specific ResourcesLong thread on PrintrbotTalk

Electronics: Printrboard with onboard MicroUSB port and MicroSD slot. Built around Atmel AT90USB1286 MCU

Firmware: Ships with Marlin-based Printrbot firmware (subject to change, see manufacturer)

Baudrate: 250000

Port: /dev/ttyAMA0

There is an active community of Printrbot users and staff configuring and using Octoprint with their machines. Printrbot was one of the first to bundle a Raspberry Pi and Pi Camera with a printer-kit --  PrintrBot Go v2 kit -- and have been mentioned an interest in rolling out 3D printing host software (OctoPrint, AstroPrint, etc.) with the other machines in the future.

Printrbot Go series launched with bundled, onboard OctoPrint embedded systems inside.

Printrbot Octoprint Resources

  • Printrbot Talk Forum: community members have an active forum topic with Printrboard-specific updates, tips, and tweaks for the range of Printrbot printers.

Configuring OctoPrint for SeeMeCNC Orion Delta Printer

ModelOrion Delta 3D Printer

ManufacturerSee-Me-CNC

Electronics: RAMBo, USB B port

Firmware: Orion 0.91 Firmware, Repetier-Firmware based (source)

Official Websitehttp://seemecnc.com/

Support Websitehttp://seemecnc.com/pages/support

Baud Rate: 250000, typically. Make sure that you are using the very latest OctoPrint release (that has a PySerial update to permit 250000 baud rate). After you confirm that, you may need to change the onboard setting on the Orion to this rate and push it to the firmware before you attempt to connect. 

Port: /dev/ttyACM0

OctoPrint FAQ and Further Resources

Where can I learn more about configuring OctoPrint for my specific printer model?

One of the core dev challenges for a community project aiming to serve a wide variety of platforms and models is offering configuration resources for each specific printer model.

While developers within the community are working to add tools to the OctoPrint suite to fold back in those vendors that are adopting proprietary electronics/firmware/printer control toolchains (for example, MakerBot .s3g/.x3g and new electronics packages), the project's initial aim was to address the elements in use in popular open hardware desktop 3D printers in use in 2012. And as it happens, this will still get you access to most of the desktop 3D printers on the market today!

What electronics package does your printer use? 

  • A number of the most common options available have already been tested and are listed by firmware, host OS, and printer vendor on the OctoPrint wiki here. (Contribute if you test a new option!)
  • In general, most of the electronic packages in use developed using development boards such as the Arduino MEGA 2560, so the key thing to solve is picking the baudrate to communicate with the electronics. While a baudrate of 250000 is generally the first place to start (because the Arduino boards communicate more stably at this rate), limitations of the SBC host doesn't always permit this default rate. No luck? Drop to "115200" and try again. 
  • It isn't always that easy to find out from the vendor the electronics packages at the heart of a closed desktop 3D printer, even if at the end of the day the boards are slight modifications of generic reprap boards in wide use.
  • A helpful list of those in use by the RepRap community is on the RepRap Wiki here.

What is your printer's firmware package?

  • The most popular 3D printer firmwares from the open source community right now are Marlin, Sprinter, and Smoothie (popular for Deltas!). Octoprint typically works well with these. 
  • A helpful list of those in wide active use today is hosted by the RepRap Wiki here.

Beyond taking advantage of resources in the OctoPrint community for the electronics and firmware determined above, hunt for OctoPrint-specific discussions in community forums for your specific vendor -- you might find just the tweak you need to connect to your printer!

TouchUI Plugin

Plugin Manager

With OctoPrint version 1.20, it introduces a plugin system which allows extending it’s core functionality.

Plugins may be installed through the new and bundled Plugin Manager Plugin available in OctoPrint's settings. This Plugin Manager also allows browsing and easy installation of plugins registered on the official OctoPrint Plugin Repository.

TouchUI Plugin by BillyBlaze

This plugin will turns the OctoPrint layout into a Mobile/TFT friendly layout. With larger buttons and a responsive layout down to the smallest resolution possible. It will mimick pointer events as touch, so you can hook up those touchscreens. It also supports a virtual keyboard.

Read more details and see screenshots by clicking the button below.

Easy Install

To install the plugin, start by clicking on the "Settings" icon in the top right corner, then select the "Plugin Manager" menu item in the left hand sidebar.

Get More Plugins

Click on the large button near the bottom of the pop-up window labled "Get More...", then click into the Search input field and type in "TouchUI". You should see the plugin appear below the text field.

Click on the big blue "Install" button to begin the installation process. It'll take a few minutes and will require you to restart OctoPrint.

Take note that all plugin management functionality is disabled while your printer is printing.

Usage and Settings

You can find the TouchUI settings in a dedicated modal. The mobile interface will automatically start while loading OctoPrint. This will only start if the browser is smaller then 980 pixels in width or if you’re browsing with a touch device. You can turn this off in the Settings modal under TouchUI.

We've tested the Raspberry Pi Epiphany and Chromium browsers with good results.