Since quite a few people on the Ultimaker forums have wanted to build their own copies of the Marlin 3D printer firmware lately, I thought I would document the process that I have used to build it.
I should start by saying that I’m mostly a Mac guy, but I did also set up a Windows 7 virtual machine, and tested the basic steps there, as well. Beyond the basics, though, Windows users are on their own…
Overview of the process
All that you need to build you own Marlin are the Arduino tools, the Marlin source files, and some way to upload the completed firmware to the Ultimaker. While I believe that it is possible to use the full arduino GUI user interface to manage, build and install the firmware, I prefer to work from the command line to perform that actual build step, and use Eclipse to actually manage and edit the source files. This suits my workflow as I’m actively developing and fixing bugs in Marlin. However, if you are simply wanting to build a custom firmware with only a minimum of configuration changes, then you don’t need to go to that level of complexity – the basic command-line ‘make’ command is enough to quickly build a hex file that you can upload to your printer.
Download and install the tools
I have found that I get good results with the older ’00’ series Arduino tools, and I’m not clear exactly how well the Marlin source files will work with newer versions of the tools. Since the older version of the tools is still available, it’s the one I’d recommend you to get, unless you have a good reason not to.
Start by downloading the Arduino 0023 toolkit from the links on this page: http://arduino.cc/en/Main/Software
The Mac version will give you a disk image file which you will need to open, and then drag the Arduino application into your /Applications folder. The Windows version downloads a zipped directory of files – which you can open and drag wherever you choose. My examples below assume that you dragged it to the root of your C: drive – so that you have a folder called e.g., C:\arduino-0023.
Now you need to get a copy of Marlin to build…
Which version of Marlin to use?
The source files for Marlin are available online from the github site. Github is a powerful – but potentially confusing – change tracking and management system based on the ‘git’ tool. It allows anyone to take their own copy of an open source project – known as a ‘fork’ – and make changes to it (such as bug-fixes, or adding new features) and then still be able to merge those changes back into the original version relatively easily. You can download all of the files in any of these forks to your own computer, and use as the basis to build your own copy of the firmware.
There are many forks of Marlin, but two primary ones that you probably want to consider working from when you go to build your own:
- https://github.com/Ultimaker/Marlin – this is the Official Ultimaker fork of Marlin, and the one that is used for the official builds of the firmware that are released by UM (e.g., bundled into Cura). It is the version that I recommend Ultimaker owners use, unless they have a good reason to use another one, since the default configuration settings are more Ultimaker-friendly, and the code base has been well-tested with Ultimakers.
- https://github.com/ErikZalm/Marlin – this is the definitive Master version of Marlin, but by default the settings may not be as Ultimaker-friendly as with the above version. The code in this version is sometimes a week or two ahead of the Ultimaker version, but only with features that aren’t relevant to the Ultimaker. So if you aren’t an Ultimaker user, or have some very non-standard hardware, then this might be the version for you instead. However, it will probably require slightly more knowledge to make sure that the configuration is sane for your particular hardware.
There are two other forks of Marlin that you may see mentioned on the UM forums, and which it is good to be aware of, although these are probably even less good choices unless you are specifically looking for a feature that you know is only in one or other of these:
- https://github.com/daid/Marlin – Daid is the developer of Cura, the keeper of the Ultimaker fork of Marlin, and one of the maintainers of the ErikZalm fork as well. This is his personal fork of Marlin. In the past, it was the version used for his web-based Marlin builder tool. However, as of the time that I’m writing this (late April 2013) the builder tool is currently broken. As such, this fork may be less interesting to DIY Marlin builders than it once was.
- https://github.com/illuminarti/Marlin – this is my personal fork. I generally keep it very close to the Ultimaker fork, with the addition of bug fixes that often get incorporated into the Ultimaker fork within a few days. If I’ve posted about some new fix I’ve written, and you’ve just got to get it asap, then this is the version to download.
Github and the git system are quite complicated, and beyond the scope of this post – but here are a few pointers that might be helpful. Firstly, the list of files on the main page of a github fork aren’t terribly informative or useful. If you want to see what has changed recently in the fork, then switch instead to the ‘Commits’ tab:
Note also the ‘Tags’ link to the extreme right of the ‘Commits’ tab heading. That takes you to a list of all the tagged commits – point-in-time snapshots of the files in the fork. This is particularly relevant for the Ultimaker fork, as Daid is now tagging each major release of Marlin with the corresponding Cura version number – e.g., ‘13.03’. If tag entry offers a link to download a zipped archive file so that you can then retrieve exactly the same source code that was used to build a given version of Marlin that came with Cura – and build your own equivalent version but with custom settings.
The ‘Network’ tab is designed to show how the various forks relate to one another, and how code feeds back and forth between them – but I find it rather hard to use, as not enough information is presented about each change. Therefore if you really want to understand how the changes fit together, and see which fixes and enhancements are in which forks, you really need to go the extra mile and use a desktop git client such as SourceTree that is better able to show the full history tree. That is definitely beyond our scope here, but here’s an example of the sort of output that source tree shows. Notice how the colored lines on the left show the history of how different forks diverged and recombined as changes were made in one or other fork, and then merged together:
The newest changes are at the top – in this case, the ErikZalm version has the most recent change. The current state of the Ultimaker fork is marked in pink towards the bottom of the list – when this was snapped, it was about a dozen changes (and just over two weeks) behind the ErikZalm version.
Download and Customize Marlin
Having decided which fork you are going to work from (or even which tag within a branch), you then need to download the zip of that version of the code – which you can do from the tags screen as indicated above, or from the main page of the fork:
Download the zip file, and unzip it if your browser doesn’t automatically do that, and then move resulting directory to wherever you want to keep it. On a Mac, you can keep it somewhere in your home directory if you want – on Windows you can also put it wherever you wish, but the simplest approach – and the one that I assume in what follows, is that you put the source code directory in the root of your C: drive, as C:\Marlin alongside the Arduino tools directory.
Setting things up to build
We are going to use the command line tool ‘make’ to build the hex file that we will upload to the printer. This is configured using a ‘Makefile’ which is a text file containing a list of settings and commands that decide what tools get used to build which parts of the program.
In order for everything to work, we need to edit the Makefile to ensure that it knows where to find everything. The Arduino tools that we downloaded earlier contain all the necessary tools – we just need to tell make where they are – and confirm which hardware we are compiling for so it can include the correct library files to match the hardware.
The Marlin project file that you downloaded includes and inner ‘Marlin’ directory, and in that are all the source code files for Marlin, and the Makefile itself. We need to edit the latter starting around line 40. On a Mac, the following changes should work to tell make that it can find the necessary files inside of the Arduino application itself (Mac applications are really a special type of folder that is usually treated as a single object):
- Set the HARDWARE_MOTHERBOARD to 7 (for Ultimaker – for other printers, see the list in Configuration.h)
- Set the ARDUINO_INSTALL_DIR to /Applications/Arduino.app/Contents/Resources/Java
- Set the ARDUINO_VERSION to 23
- Set the AVR_TOOLS_PATH to /Applications/Arduino.app/Contents/Resources/Java/hardware/tools/avr/bin/
On Windows, things are even simpler – if you put both downloads in the same folder (e.g., the root of your C: drive) then you can probably leave the two entries that deal with directories at their default values, and just set the motherboard and arduino version entries. (If not, then at least change the Arduino install directory entry to point at the arduino-0023 directory that you installed earlier).
When you are done, the relevant part of your Makefile should look like this for a Mac:
Whereas, on Windows, the file should look more like this:
Choosing the right path
Finally, your system needs to know where to find the tools such as make, so that it knows what to do when you type make.
On a Mac, this is not needed if you already have make installed. Type ‘which make’ in the terminal to see if the system already finds a copy of it somewhere – if it replies with a path then you don’t need to edit your path, and can skip this section. If not, you can open a terminal window and type:
Alternatively you can use a text editor such as nano to edit the .bash_profile file in your home directory and add that line to it (and then close and re-open Terminal.app) so that you don’t have to set that up each time.
On Windows, you need to edit the ‘Path’ environment variable in Computer -> Properties -> Advanced System Settings -> Environment Variables to add the following to the end of what is already there (these are the paths to the two folders we downloaded earlier, separated by a semicolon. Adjust these two paths if you didn’t put the two downloaded folders in the root of your C: drive)…
Then log out of Windows and back in, to be sure the changes are picked up.
Be careful what you wish for
Having got everything set up to build, you now need to edit the configuration.h and configuration-adv.h files to choose the right options for your particular printer. That will be the subject of another post – but for now, at least make sure that you set the correct baudrate and motherboard, and if you have an UltiController, you will want to enable both the EEPROM_SETTINGS and ULTIMAKERCONTROLLER options.
Make it so
Now, you’re ready to make your Marlin hex file. On a mac, open Terminal app, and cd to the inner Marlin folder where the Makefile lives. Using Windows, you can use Windows Explorer to navigate to the outer source code folder, and then Shift-Right-Click on the inner Marlin folder, and select ‘Open command window here’.
On either platform, you then just need to type…
… and the various source files should be compiled, and a hex file assembled. All of the built files get put into a folder called ‘applet’ by default. It lives in the same inner Marlin folder as all the source files. The only file in the applet folder that you need to worry about is Marlin.hex. That is the one that you need to install onto your printer, using e.g., the custom firmware installation option in Cura.
The end result should look similar to this:
(Hint: If you have errors complaining about building wiring.o, check for extra spaces at end of arduino_install_dir or avr_tools_path lines in the Makefile.)
And that’s it. The hex file can be uploaded to the printer and tested. If you want to start over, or just clean up all the files that ‘make’ built, you can type ‘make clean’ to remove the applet directory.
That’s the basic process of building Marlin yourself using ‘make’ . In another post I’ll talk about how to get Marlin to play nicely with a fancier editing and development tool – Eclipse – as that makes life a lot easier if you are hacking on Marlin a lot.