What is Marlin?
Marlin is an open source firmware for the RepRap family of replicating rapid prototypers — popularly known as “3D printers.” It was derived from Sprinter and grbl, and became a standalone open source project on August 12, 2011 with its Github release. Marlin is licensed under the GPLv3 and is free for all applications.
From the start Marlin was built by and for RepRap enthusiasts to be a straightforward, reliable, and adaptable printer driver that “just works.” As a testament to its quality, Marlin is used by several respected commercial 3D printers. Ultimaker, Printrbot, AlephObjects (Lulzbot), and Prusa Research are just a few of the vendors who ship a variant of Marlin. Marlin is also capable of driving CNC’s and laser engravers.
One key to Marlin’s popularity is that it runs on inexpensive 8-bit Atmel AVR micro-controllers - Marlin 2.x has added support for 32-bit boards. These chips are at the center of the popular open source Arduino/Genuino platform. The reference platforms for Marlin is an Arduino Mega2560 with RAMPS 1.4 and Re-Arm with Ramps 1.4.
As a community product, Marlin aims to be adaptable to as many boards and configurations as possible. We want it to be configurable, customizable, extensible, and economical for hobbyists and vendors alike. A Marlin build can be very small, for use on a headless printer with only modest hardware. Features are enabled as-needed to adapt Marlin to added components.
- Full-featured G-code with over 150 commands
- Complete G-code movement suite, including lines, arcs, and Bézier curves
- Smart motion system with lookahead, interrupt-based movement, linear acceleration
- Support for Cartesian, Delta, SCARA, and Core/H-Bot kinematics
- Closed-loop PID heater control with auto-tuning, thermal protection, safety cutoff
- Support for up to 5 extruders plus a heated printbed
- LCD Controller UI with more than 30 language translations
- Host-based and SD Card printing with autostart
- Bed Leveling Compensation — with or without a bed probe
- Linear Advance for pressure-based extrusion
- Support for Volumetric extrusion
- Support for mixing and multi-extruders (Cyclops, Chimera, Diamond)
- Support for Filament Runout/Width Sensors
- Print Job Timer and Print Counter
How Marlin Works
Marlin Firmware runs on the 3D printer’s main board, managing all the real-time activities of the machine. It coordinates the heaters, steppers, sensors, lights, LCD display, buttons, and everything else involved in the 3D printing process.
Marlin implements an additive manufacturing process called Fused Deposition Modeling (FDM) — aka Fused Filament Fabrication (FFF). In this process a motor pushes plastic filament through a hot nozzle that melts and extrudes the material while the nozzle is moved under computer control. After several minutes (or many hours) of laying down thin layers of plastic, the result is a physical object.
The control-language for Marlin is a derivative of G-code. G-code commands tell a machine to do simple things like “set heater 1 to 180°,” or “move to XY at speed F.” To print a model with Marlin, it must be converted to G-code using a program called a “slicer.” Since every printer is different, you won’t find G-code files for download; you’ll need to slice them yourself.
As Marlin receives movement commands it adds them to a movement queue to be executed in the order received. The “stepper interrupt” processes the queue, converting linear movements into precisely-timed electronic pulses to the stepper motors. Even at modest speeds Marlin needs to generate thousands of stepper pulses every second. (e.g., 80 steps-per-mm * 50mm/s = 4000 steps-per-second!) Since CPU speed limits how fast the machine can move, we’re always looking for new ways to optimize the stepper interrupt!
Heaters and sensors are managed in a second interrupt that executes at much slower speed, while the main loop handles command processing, updating the display, and controller events. For safety reasons, Marlin will actually reboot if the CPU gets too overloaded to read the sensors.
While Marlin only prints G-code, most slicers only slice STL files.
Whatever you use for your CAD toolchain, as long you can export a solid model, a slicer can “slice” it into G-code, and Marlin firmware will do its best to print the final result.
Before Marlin can dream of printing, first you’ll need a 3D model. You can either download models or make your own with one of many free CAD programs, such as FreeCAD, OpenSCAD, Tinkercad, Autodesk Fusion 360, SketchUp, etc.
A high degree of knowledge is needed to model complex objects like a T-Rex Skull, but other objects can be quite simple to model. To get ideas and test things out, explore sites like Thingiverse and YouMagine and print things for fun.
Slicers prepare a solid 3D model by dividing it up into thin slices (layers). In the process it generates the G-code that tells the printer in minute detail how to reproduce the model. There are many slicers to choose from, including:
- PrusaSlicer (formerly Slic3r Prusa Edition) The new Kid on the block based on Slic3r.
- Simplify3D is a commercial offering.
Marlin can be controlled entirely from a host or in standalone mode from an SD Card. Even without an LCD controller, a standalone SD print can still be initiated from a host, so your computer can be untethered from the printer.
Host software is available for several platforms, including desktop systems, Raspberry Pi, and Android tablets. Any device with a USB port and serial terminal can technically act as a host, but you’ll have a better printing experience using host software specifically designed for 3D printers. Current selections include:
- Pronterface is an open source host by Kliment.
- Repetier Host is a closed-source host by Repetier Software.
- OctoPrint is an open source host for Raspberry Pi by Gina Häußge.
- Cura is an open source host by Ultimaker. (WARNING: You can no longer manual select com port and speed, your printer needs to be auto detected by Cura)
- Simplify3D includes both a host and slicer.
Many 3D printers ship with a customized version of Repetier or Cura. While this helps to associate the printer brand with a companion piece of software, these versions are usually obsolete and receive few upgrades. We recommend you download the latest generic version of your preferred host software instead.
To install Marlin on your printer you’ll first need to Download Marlin, then edit your Configuration files, and finally use an IDE to Compile the Marlin project into a binary form and Upload it to your board. The build process can seem daunting at first, but after you do it a few times you’ll be a pro.
Marlin only needs to be re-flashed when fixed settings are changed in the configuration files. Many settings are only defaults and can be changed (and saved to EEPROM) with G-codes. See each option’s description in the configuration files to find out which G-codes apply.
Start by downloading the Marlin source code. There are a few codebases to choose from.
|Download 2.0.x||Current release|
|Download 1.1.x||Previous release|
|Download 1.0.x||Older release|
|Download bugfix-1.1.x||“Nightly” build. Proceed with Caution!|
|Download bugfix-2.0.x||“Nightly” build. Proceed with Caution!|
|Download dev-2.1.x||“Nightly” build. Proceed with Caution!|
Marlin 2.0 and up include 32-bit ARM support. PlatformIO is not required for AVR boards.
Build and Install:
Marlin installation procedure can vary depending on which version of Marlin you want to install and which board you’re installing onto. Once your Marlin build environment is set up installing updates can be a one-click operation.
|1.1.x or 2.x||8-bit AVR||Install Marlin with Arduino IDE|
|1.1.9 or 2.x||8-bit AVR, 32-bit ARM||Install Marlin with PlatformIO|
|2.0||LPC1768 (Re-Arm)||Install Marlin on Re-ARM|
Graphical LCD Artifacts:
After a new install of Marlin your graphical LCD shows glitches or is blank. This is caused by bad timing in the LCD data transmission.
Define custom delays. Add the following lines to
Configuration.h as your starting-point and adjust values upward until the display works reliably. You should keep testing to find the lowest values that produce a reliable display because the LCD update steals time from the main loop.
#define ST7920_DELAY_1 DELAY_NS(200) // After CLK LOW #define ST7920_DELAY_2 DELAY_NS(400) // After DAT #define ST7920_DELAY_3 DELAY_NS(200) // After CLK HIGH
- For AVR boards open
#pragma GCC optimize (3)to reduce code optimization.
- Add 4.7k pullup resistors to the SPI lines if they are not commonly used for SPI.
BLOCK_BUFFER_SIZE to see if the problem goes away.
No LCD / SD on ReARM?
As seen in this Chris’s Basement video, the RRD display doesn’t always work on first install. It didn’t even light up. A custom adapter is needed with the ReARM. See this issue, and this issue, and this page.
At 115K baud use 167 latency, 192 USB block request. As one goes up the other goes down.
This is a hardware issue due to the connected beeper pin being HIGH when the board is first powered. Marlin turns off the BEEPER pin as soon as it possibly can. A new bootloader for your board might fix the issue in the future.
An under-powered PSU combined with heaters and high speed moves can lead to a frozen board. No kill, no watchdog, heaters stuck on. See #17202. To test for this:
- To test for this, enable the bed and extruder heaters and print at high speed to see if a hard freeze occurs. Try disabling heaters and/or slower printing to see if the problem goes away.
- Read the input voltage from PSU with a meter during fast moves. If you see a drop too far below your expected voltage (e.g., 12V or 24V) this indicates a problem.
After flashing a new version of Marlin, the existing EEPROM contents may no longer conform to the updated EEPROM layout. As a result, you may see an error like one of these:
Error:EEPROM datasize error.
EEPROM CRC mismatch - (stored) 4235 != 6244 (calculated)!
- If using Octoprint, turn off the option to disconnect on “Error” messages before proceeding.
M500and then reboot the machine. This procedure will initialize the EEPROM to your configured “factory” settings.
- If you still see checksum or data-size errors, add the following option to your
Configuration.h, flash, and reboot.
This option makes Marlin check the EEPROM data during
M500(write) and report mismatched fields. Please report these errors to the Marlin project, because a mismatched field may indicate a bug in the code.
- You can also enable the
EEPROM_AUTO_INIToption to automatically reset the EEPROM when the data structure changes or the data gets corrupted.
Sanity Check Errors
SanityCheck.h files exist to check the validity of settings and make sure obsolete settings get updated for the newest Marlin. Be sure to read and follow all directions provided by these checks.
Build Too Large
A Marlin build can range in size from under 60K to over 200K with a generous complement of features enabled. All features try to use as little SRAM as possible, but some have a higher SRAM cost. As a guide and starting-point, be sure to use the example configuration included with Marlin that best matches your specific machine model.
Since Marlin 1.1 “Delta Height” is defined as the distance between Z Home Position and the Z-MIN trigger point (so it remains constant). The Z Probe Offset is added to that distance in order to go to the height of the first printed layer and as such is independent from Delta Height. (Printers without a probe have no Z Probe Offset. Instead, the Z-MIN trigger-point comes from the paper test height, aka Z0.)
Trinamic Stepper Drivers
These tips are collected from various reports we have received. See Trinamic troubleshooting for additional guidance.
- Some SilentStepSticks with variable 3-5V logic voltage (VIO) might get damaged if only powered over USB.
- SPI conflict with the SD card? Solutions vary.
- E Stepper won’t move when using Linear Advance with TMC drivers?
- “I ended up using the drivers in legacy mode and setting them to SpreadCycle using the OTP (One Time Programmer). Unfortunately trying to set individual drivers to SpreadCycle via UART by enabling HybridThreshhold and setting the threshold to 0 for the respective axes did not work.” See #11825.
- Loud / grinding TMC2208? Increase the current to ~1500mA and lower the Hybrid Threshold.
- Unreliable printing, shifting layers? Make sure the ‘rsense’ value is configured according to recommendations. See #9368.
- TMC2208 uses SoftwareSerial, and this conflicts with Endstop Interrupts. Disable Endstop Interrupts to proceed.
- Should I use
SOFTWARE_DRIVER_ENABLE? Not unless required by the hardware. See #13326.
Babystep Double-click ignored
- Increase the
False Endstop Triggering
- Enable and set
ENDSTOP_NOISE_THRESHOLDto filter the endstop signals.
BLTouch Pin Drop / Blinking
- Servo voltage / signals may be unstable due to heater signal lines being too close to servo traces.
- Solution: Disconnect the servo signal line after the print starts.
More can be found here:
Troubleshooting a complex piece of software with a minimal interface can sometimes be challenging, even for the most experienced 3D printing enthusiast. Please use our Troubleshooting Guide for tips on some common problems.