Configuring with INI
On Configuration
Over Marlin’s lifetime we’ve considered many alternatives to the current
system of two configuration header files, but there have always been trade-
offs, especially in terms of maintaining hundreds of examples. Marlin also
maintains support for Arduino IDE and small build sizes, and that requires us
to use C++ headers at some level.
All the concepts we’ve explored that include splitting up configs (e.g., by
feature or by category) have fallen short; however, maintainers of multiple
builds have always been free to come up with their own tools and methods.
Marlin configurations include #if blocks to group dependent options,
although this is not strictly necessary. This is done partly to make the build
more efficient, but we also want to capture the dependencies between
options so scripts and tools can (mostly) derive them directly from the
Configurations.
On Migration
It can be tricky to migrate from older versions of Marlin as settings change.
Marlin checks for old settings and tells you what to change during the build,
but the final result is never fully up to date. Wouldn’t it be nice if Marlin
would automatically migrate old settings to a new configuration for you?
We’re currently working on tools to improve the situation, with the goal to
build a schema and a database of configurations across all Marlin versions so
we can generate complete configuration headers, perform migrations, and
even generate searchable documentation for this website. That is a big
project unto itself, so feel free to get involved on Discord!
Meta Configuration
Since Marlin now supports PlatformIO we can do custom pre-processing as
part of the build. PlatformIO loves INI files, which are very simple and
commonly used for 3D printer firmware configuration. So, we now include a
config.ini configuration file that can do a lot of useful tricks.
config.ini
Note that the behavior of this feature is likely to change as we continue to
experiment and find new ways to use it, so consult the codebase for the
most up to date information.
Overview
The default config.ini for Marlin 2.1.2.4 looks something like this:
# Marlin Firmware
# config.ini - Options to apply before the build
[config:base]
ini_use_config = none
# Load all config: sections in this file
;ini_use_config = all
# Load config file relative to Marlin/
;ini_use_config = another.ini
# Download configurations from GitHub
;ini_use_config = example/Creality/Ender-5 Plus @ bugfix-
2.1.x
# Download configurations from your server
;ini_use_config = https://me.myserver.com/path/to/configs
# Evaluate config:base and do a config dump
;ini_use_config = base
;config_export =2
[config:minimal]
motherboard = BOARD_RAMPS_14_EFB
serial_port =0
; ...
[config:basic]
bed_overshoot = 10
busy_while_heating = on
; ...
[config:advanced]
arc_support = on
auto_report_temperatures = on
; ... and many more!
At the start of a build / upload PlatformIO runs the script
buildroot/share/PlatformIO/scripts/configuration.py to process the config.ini
file at the very start of the build process so that the configuration headers
are prepared in advance of any other scripts. This allows you to start with
any set of configuration files and just apply the changes that apply to your
current needs. Thus the .ini file will be very small compared to the full set of
configurations.
The config.ini file follows regular conventions. Names in braces are used to
start a section. (We use section names beginning with config: to avoid
conflicts with any other INI files in the project that may already be loaded by
PlatformIO.) Lines that include an equals sign are option/value pairs, with
everything after the equals sign taken literally. The names of options are
case-insensitive, so we stick to lowercase.
Base INI Options
The section named config:base is always processed first. Any options within
any section that start with ini_ only apply to config.ini processing itself and
won’t be used to modify configurations.
At this time the only special option is ini_use_config, with these possible
values:
Value Description
none Ignore this file and continue the build.
all Apply all sections in this file to the configurations.
base Just apply config:base (i.e., not all or none).
myname Apply everything in the section config:myname.
another.ini Apply another.ini completely (then more of config:base). Files can
be nested.
fast @ better.ini Apply just the config:fast section of better.ini (and
config:base).
path/to/example @ branch Download from the Configurations repo, with
optional branch.
http... Download files from a custom URL.
Values can also be combined in any order, separated by commas. For
example:
Exporting config.ini
Marlin can generate a config.ini file as part of any build. Set the
CONFIG_EXPORT option to 2. This will export a file with sections named
config:basic and config:advanced that only includes enabled options.
Suggested Uses
Any automated build system that currently uses Configuration.h and
Configuration_adv.h files could switch to INI files, which should be easier to
maintain and apply and compare changes going forward. The INI system is
meant to allow for you to create a base configuration section for a particular
machine and then apply just the differences in additional sections.
A migration system based on INI will save time and effort, as it only needs to
export an INI from the previous Marlin version and generate a new INI file
with the known changes applied. The advantage here is that modified
configurations can still be migrated, no matter how rearranged and
reorganized they might be.
