This article is designed to be a basic overview of how to read and configure Unified Firmware to work with your printer. We will discuss the basics of how to read, understand, and use the configuration.h file to set up Unified Firmware for your printer. This article assumes that you have already installed VSCode and PlatformIO.
In order for VSCode to properly open and compile firmware, you must open the proper folder with VSCode. The file called “platformio.ini” is used to determine settings and variables that are required for VSCode to know how to compile properly. Therefore, the folder you open with VSCode must have platformio.ini within it, on the top-level.
To do this, in VSCode go to File > Open Folder and select the “Firmware” folder, then click “Open”.
Go to File > Open Folder…
The file called “configuration.h” contains the settings you’ll need to set up. This configuration file is found in the Marlin folder. Use the file explorer sidebar (on the left-hand side) in VSCode to find and click the “configuration.h” file. This loads the file into a large tab in the main window for editing.
On the left sidebar, open the Marlin folder and click the Configuration.h file. This opens the file in the editor so you can make adjustments.
The main configuration.h file contains options to select a specific printer model and any extra features that you may need for the printer to work properly.
Each setting within the configuration.h file is contained on its own line that begins with “//#define” then the name of the setting. For example, the following line is used to enable the Ender 3 model with a V4.2.2 mainboard installed:
//#define ENDER3_V422_BOARD
In order to enable the settings you want, simply remove the two slashes “//” at the beginning of the line. These slashes indicate that everything else on the line is a “comment” and is not used as valid code, and thus must be removed from each line you wish to use. You MUST leave the pound sign (hashtag) at the beginning of the line, this is important for the code to run properly when compiled. When the example line is properly enabled, it will look like this:
#define ENDER3_V422_BOARD
VSCode will change the text appearance when an option is enabled versus when it is disabled or considered a “comment”. The “commented” options will be shown in green text, as VSCode assumes any line that starts with two slashes (//) is not valid code to run. Code that is shown as “grayed out” or “faded” is also disabled/not used within the current configuration settings. Lines that have been enabled appear as “normal” text, brighter and/or colored differently than the disabled selections by comparison.
The Ender 3 model with the V4.2.2 mainboard shown as enabled, where the other lines are “comments” and go unused
In our example, we do not have the Ender 6 model enabled, so none of its code is used and is thus shown “grayed out”.
We highly encourage you to read through the ENTIRE configuration file before proceeding with modifying the configuration. You may not understand every setting or line right away, and it may look overwhelming or intimidating when reading it for the first time. Stick with it though! The more you familiarize yourself with the features and settings in the configuration file, the easier you’ll find future configuration efforts. Firmware configuration is a vital part of modifying and upgrading any 3D printer, so we encourage all of our users to learn this valuable skill!
Unified Firmware is laid out so that most common settings are available within the top half of the configuration.h file. There are several selections for things such as the printer model, enabling a bed-leveling probe or filament sensor, LCD display settings, EZNeo/Neopixel settings, etc. There is also a “community features” section that has additional features or settings requested by the community for things such as Linear Advance (where available).
Unified Firmware’s configuration file is set up with pre-configured options for each stock printer model. For example, selecting the Ender 3 printer model will set the bed size limits, home offsets, and any “stock” features on the printer automatically. For printers that have a bed-leveling probe or filament sensor installed as stock equipment, these are usually also enabled by default. In other words, simply selecting the printer model (and leaving everything else alone) will assume a 100% stock factory setup on that printer.
Our configuration.h file includes pre-set options for our EZABL bed-leveling probe. One of these options must be enabled in order for the EZABL to function properly on the printer.
Example of the available EZABL mounts and CUSTOM_PROBE option
The options available correspond to the type of MOUNT being used to attach the EZABL sensor to the printer. We have our OEM mounts built into each version of the firmware. When you enable one of these options, the bed-leveling and probing functions are enabled, and the nozzle-to-probe offsets are set up automatically for the selected mount.
This means that when using an EZABL, you simply choose the mount type you’re using and everything else is automatically enabled and configured for you.
CUSTOM_PROBE is used in cases where you are using an aftermarket bed-leveling probe, or using an EZABL with a third-party mount. When using this option, you must also set the nozzle-to-probe offsets manually, as dictated later in the configuration.h file.
Nozzle-to-probe offset section of configuration.h
In addition to the printer model and EZABL settings, Unified Firmware contains settings on a per-printer or per-upgrade basis. These include options for things like using the EZABL in place of a stock ABL probe, switching to a 12864 LCD display where needed, enabling our EZNeo LED strip, and more.
We suggest that you read through ALL of these options to ensure that you enable any features that may be required for your particular printer or setup. Not all printers will have additional options like this, but many do.
These sections contain additional (usually non-vital) settings that tend to be common or universal across all printers, or settings that are specifically requested by community members for products or features we do not officially provide support for.
These include setting a bed-leveling probe’s grid size and outer margin, modifying hot-end and extruder settings and hardware, reversing motor directions, etc.
Some settings may require two lines to be enabled. For example, when adding a new extruder to the printer you may be required to adjust the E-steps setting. In our firmware, you must enable the line to enable the use of the E-steps adjustment setting, then you must also enable the line as well as specify the value you want to use. Both of these lines must be enabled for the value to take effect as seen here:
#define CUSTOM_ESTEPS #define CUSTOM_ESTEPS_VALUE 410
Other settings may also require several lines to enable properly. These include thermistor and maximum temperature settings, custom printer names, home adjust settings, etc. Carefully read the section for the setting you want and ensure that you enable each line as necessary.
If you are having issues locating a certain setting, or if you’re looking for something in particular, VSCode has a “find” search function built in. Go to Edit > Find (or use CTRL+F or ⌘+F) to bring up the search bar, then start typing the first few letters of the setting you’re searching for.
Our Help Center is a great resource for questions about common settings and features, and we’re constantly making improvements and new articles. Check out the following articles as examples:
Unified Firmware’s configuration file is broken into two major sections. The top section contains easy-to-access settings for the most common changes and upgrades, so most users won’t need to look below the nicely-formatted top section.
This warning is where the user-friendly options end.
The bottom section contains machine-specific settings such as bed size, stock features, and the code needed to make the top section’s settings function properly. We do not recommend making adjustments here unless you know exactly what you are doing. These settings can be translated to any Marlin-based firmware, in case you need to recreate our configurations in another firmware version such as stock Marlin.
Modifications made to the bottom section of configuration.h do NOT qualify for technical support. If you make changes to the bottom of the configuration.h file, we cannot help you troubleshoot issues. We’ve already done most of the configuration legwork for you, and you may need to figure out the rest on your own.
Unified Firmware includes two other configuration files, called “configuration_adv.h” and “configuration_backend.h”. These files contain additional code and settings needed for things like EZABL offsets, non-printer-specific settings, and additional code per-printer.
Most users will NOT need to change anything in these files. However, if you are searching for a specific function from Marlin and it does not appear in the main configuration.h file, it may be located in one of these other files. Use the search function in VSCode to find the setting you need to adjust.
We also include Marlin’s stock configuration files along with the firmware package. You can compare and contrast settings within our configuration files to Marlin’s stock files, and create your own custom installation.
Technical support is NOT provided for changes made to these other configuration files. We cannot provide technical support for custom installations or features not included within our main configuration.h file. Modify these files at your own risk, and we suggest that you consider keeping backups of the original files in case of an error.
Unified Firmware itself does NOT include any form of technical support, and does not include any guarantee or warranty. Technical support is provided ONLY for qualifying items purchased from TH3D. Technical support for Unified Firmware can be purchased with our paid firmware or as a standalone service. Contact us for more information!
