¶ Overview
¶ The Problem
FluidNC can run on many different controller boards with different numbers of motor driver sockets/connectors, different numbers and types of inputs for things like limit switches and control buttons, different outputs for controlling spindles, etc. For a given controller board, there are many possible machine variations.
Controller characteristics include:
- How I/O pins are used to control motors, and which are assigned to which motor slots
- Presence of optional features like SD cards, status displays, etc, and how they are connected to the processor
Machine characteristics include:
- What kind of stepper drivers do you have
- How many motors, and which ones drive which axes
- For a given axis, how many steps does it take to move the axis 1 mm
- Which direction of motor rotation corresponds to positive axis motion
- How fast can the machine go before the motor stalls
- Does your machine have limit switches and if so, where are they located on axes, what are their electrical characteristics, and which of the various controller inputs are they connected to
- If your spindle is to be turned on and off or its speed changed by the controller, how is it connected to the controller electrically, and how fast does it go for different values of the control signal
- ... and many others
¶ The Solution
To set up FluidNC for your system, you must create and upload a "config file". A config file a text file that describes the controller and the machine. You create the config file with a text editor, upload it once to the FLASH storage inside the microprocessor module, and then FluidNC reads the config file from FLASH ever time that FluidNC starts.
By default, the name of the config file is config.yaml. It is located in the "localfs" FLASH file system that is part of the microprocessor module. You can use a different name if you wish; if so you must change the setting $Config/Filename to match your chosen name. If you wish you can store multiple config files and switch between them by changing that setting. You must restart the controller if you change the file or filename.
You can edit your config file with any text editor program, for example Notepad++. The preferred extension is ".yaml", because the config file format is a subset of the "Yet Another Markup Language" format. Many text editors recognize that format and provide editing assistance in the form of syntax hightlighting and indentation assistance.
Examples for common machine setups and specific hardware can be found here and here
There are is also an example below.
It is unlikely that any example will exactly match your machine. You should look for examples that correspond to your controller board ("6_pack", "MKS_DLC32", "fysetc", ...), your motor/axis setup ("XYZ", "XYYZ", "XYZA", ...), your driver type ("ext", "stepstick", "2130", ...) and your spindle type ("laser", "relay", "10V", "Huany", ...). Study the files that seem relevant to your situation, understand how their contents correspond to the relevant characteristics, and mix and match sections to describe your specific machine. You will then need to tune things like steps_per_mm. max_rate_mm_per_min, and acceleration_mm_per_sec2 to make your machine move the correct distances without stalling the motors.
¶ Upgrade tool from Grbl_ESP32
If you have a working machine definition from Grbl_ESP32, you can use an automated method. See this FAQ entry.
¶ File Specifications
Our format is a subset of YAML. To keep the firmware simple, only the features we need are used. Many standard YAML features cannot be used.
- Comments must be on their own lines, and are made by starting the line with
#. Comments after a key value pair are not supported. Comments are not read into FluidNC nor will they be output if you do a$Config/Dump ($CD).
# This comment will work
motor0
limit_all_pin: gpio.16:low:pu
motor0 # This comment will cause an error
limit_all_pin: gpio.16:low:pu
- Non-supported keys will be ignored and print an error on startup like
[MSG:ERR: Ignored key frodo] - Trailing whitespace after key values will cause errors.
- Add a blank space after the colon, like
board: 6 Pack - End file with at least one blank line. The last line must have a line end, so have at least one blank line at the end of the file.
- Indentation is critical. All sub items in a section must have the exact same indent level. Use spaces, not tabs.
- Length of the filename including ".yaml" shall not exceed 30 characters.
- Pin declaration: [type].[pin number]:[attribute]
- Type can either be "gpio" or "i2so"
- GPIO: These are native ESP32 pins. There are quite flexible and can be used for most features.
- I2SO: These are on external I2S chips. They are output only and cannot be used for advanced things like PWM. They are only available on controller hardware that implements them, like the 6 Pack. If using I2SO, the control pins must be declared:
i2so: bck_pin: gpio.22 data_pin: gpio.21 ws_pin: gpio.17 - Pin Number is a numeric value for which esp32 gpio pin is used.
- Attribute are optional because each attribute has a default state. Examples of an attribute would be 'high' or 'low'. Note that attributes are preceded with a colon. FluidNC will know the basic input vs. output requirement based on the feature it is assigned to. For example, it knows that GPIO assigned to a limit switch will always be an input. Although attributes are not case sensitive, it is recommended to use lower case for ease of reading.
- Input Pin Attributes
- Active State: Each input feature has an active state. For example, the active state of a switch would be when the switch is pushed. Depending on the switch type and wiring the switch may be connecting a low voltage (ground) or a logic high voltage to the CPU when the switch is pushed. This active state is specified in the configuration with the 'high' or 'low' attribute. For example, limit_all_pin: gpio:14:high would tell FluidNC that when it detects a positive voltage on GPIO pin 14, the switch has been pushed. It will use the default of high if the attribute is not specified. In this example, changing the attribute to low will signal that the switch has been pushed when pin 14 is grounded.
- Pulling Resistor are a valuable feature for input pins. This is done with the 'pu' (pull-up) or 'pd' (pull-down) attribute. Examples: gpio.14:high:pd or gpio.14:low:pu. The default is no pulling resistor. This feature is really handy for eliminating extern circuitry that would otherwise be required to avoid false positives. Without a pull-down or pull-up, it is common to get false activations of the input. This is because the current is so close to zero that it the slightest change will cause it to register as positive or vise versa. A pull-down internally grounds the pin through a resistor, while a pull-up supplies a very small amount of a current through a resistor. This keeps the pin in a default state until an external input overrides this default state.
- Output Pin Attributes
- Active state: Each output feature has an active state. This usually means the feature is on. Depending on your circuitry, a low or high output signal will turn on the feature. You specify this in your configuration with the high or low attribute. Examples: gpio:14:high or gpio.14:low It will is the default of high if it is not specified.
- Input Pin Attributes
- Type can either be "gpio" or "i2so"
¶ Data Types
The detailed descriptions of each config file item will tell you what data type to use. In many cases the values will be limited to a range by the config item. For example: step_per_mm is a Float, but it must be positive. Using an invalid value could result in an error, or the value being constrained to the range.
- Boolean True or False
- Float A number with up to 3 decimal places.
- Integer Do not use a decimal or you will get an error because the parser will think it is a float value. The spec for the item will tell you the valid range.
- String A string of characters. The general maximum length is 255, but specific instances may limit it to a smaller length.
- Pin This is an I/O pin. See more about them here.
- UartData This is used to specify UART mode information, like "8N1"
- Enumeration A list of acceptable values. Example "homing_mode" can be "StealthChop, CoolStep, or StallGuard""
- Speed Map A specially formatted string for setting up spindle speeds. read more
Tip: If you use an editor that highlights yaml syntax, it will highlight the config file keys and values. Some even allow you to collapse sections. When posting in Github issues, Discord posts, and anywhere Markdown is used, you can add yaml after the initial 3 backticks in code blocks to highlight the code.
¶ Uploading
You can upload a config file over WiFi by using the file upload button in the ESP3D tab. It is the green folder icon.
If you upload a file named "config.yaml" into the root folder of the local file system,
FluidNC will use it with no additional setup required. If you want to use a different name, you must also change the $Config/Filename setting to the new name. For example the following command sent through the serial counsel will change the config file name to my_machine.yaml: $Config/Filename=my_machine.yaml
You can also upload using Fluidterm. Press CTRL+U and select the file.
You can view the contents of the file in FLASH with $LocalFS/Show=\<filename\>
You can see all of the files in the local file system with $LocalFS/List
¶ Help with problems
See Troubleshooting Config File Problems.
¶ Live Changes (Tuning)
Many config values can be set when the firmware is running. This is typically done when tuning a machine. For example, if you are trying to determine the best acceleration for an axis, you might try out a few values to see what works best.
Some features cannot be changed when running. They only take effect after a restart. These are features like pin definitions. You must edit the config file to change those.
To view the current value of the setting send $ plus the entire YAML hierarchy for that setting. For example send $/axes/x/steps_per_mm to see that value. You can see any branch of the hierarchy by sending the hierarchy for that section. For example, to see everything about the x axis send $/axes/x.
To change settings you send a $ command that is the entire YAML hierarchy for that setting. For example send $/axes/x/steps_per_mm=80 to change the x axis resolution. The changes only affect the values in volatile memory. You must change the YAML file if you want the changes to be permanent. If you send the $Config/Dump (or $CD) command you can see the complete definition in memory.
The order of the keys in the file are not important as long as the hierarchy is respected. The file will be displayed or saved in the order FluidNC stores it in memory. Therefore, the saved file may not look like the original file you created. Any keys that were ignored will not be saved. Any keys that you omitted, but have defaults will be added to the file.
¶ Saving Live Changes
The $CD command can also save changes to a file. $CD=\<filename\> saves the current config to the file name specified. If you specify a new filename you should change your $Config/Filename to that file.
Be sure there is enough room for the file before saving. The ESP32 does not have a lot of space. It can only hold 2-3 YAML files at a time. Check the free space before saving by showing the contents of the local file system with a $localfs/list command.
¶ Names and Units
All config item names will include a suffix that describes the units or type. Examples...
- step_pin: The value should be a pin
- pulse_us: The value should be in microseconds.
- max_travel_mm The value should be in millimeters.
- r_sense_ohms The value should be in Ohms
- run_amps Run current in amps
Do not include the units in your value, just the number, string, etc.
¶ Default values
Most keys have default values. For pins this is usually NO_PIN. If you are not using a pin like an enable on a spindle, you do not have to specify it in your YAML file. If you do a $CD (config dump) you will see all the keys, even if you did not specify them in your YAML file.
¶ Documentation of each section
- Top level items (no indent)
- stepping:
- axes:
- spi:
- sdcard:
- control:
- coolant:
- probe:
- macros:
- user_outputs:
- spindles
- start:
¶ Example config.yaml
Many more are in the GitHub repo.
name: "ESP32 Dev Controller V4"
board: "ESP32 Dev Controller V4"
stepping:
engine: RMT
idle_ms: 250
dir_delay_us: 1
pulse_us: 2
disable_delay_us: 0
axes:
shared_stepper_disable_pin: gpio.13:low
x:
steps_per_mm: 800
max_rate_mm_per_min: 2000
acceleration_mm_per_sec2: 25
max_travel_mm: 1000
homing:
cycle: 2
mpos_mm: 10
positive_direction: false
motor0:
limit_neg_pin: gpio.17:low:pu
stepstick:
direction_pin: gpio.14
step_pin: gpio.12
motor1:
null_motor:
y:
steps_per_mm: 800
max_rate_mm_per_min: 2000
acceleration_mm_per_sec2: 25
max_travel_mm: 1000
homing:
cycle: 2
mpos_mm: 10
positive_direction: false
motor0:
limit_all_pin: gpio.4:low:pu
stepstick:
direction_pin: gpio.15
step_pin: gpio.26
motor1:
null_motor:
z:
steps_per_mm: 800
max_rate_mm_per_min: 2000
acceleration_mm_per_sec2: 25
max_travel_mm: 1000
homing:
cycle: 1
mpos_mm: 10
positive_direction: true
motor0:
limit_all_pin: gpio.16:low:pu
stepstick:
direction_pin: gpio.33
step_pin: gpio.27
motor1:
null_motor:
spi:
miso_pin: gpio.19
mosi_pin: gpio.23
sck_pin: gpio.18
sdcard:
cs_pin: gpio.5
card_detect_pin: NO_PIN
coolant:
flood_pin: gpio.25:high
mist_pin: gpio.21:low
probe:
pin: gpio.32:low:pu
PWM:
pwm_hz: 5000
output_pin: gpio.2:low
enable_pin: gpio.22
direction_pin: NO_PIN
disable_with_s0: false
s0_with_disable: true
spinup_ms: 0
spindown_ms: 0
tool_num: 0
speed_map: 0=0% 10000=100%
There is also a folder of example configs in the root folder of the repo.
¶ Developer Reference
To keep the config file consistent and relatively self describing the following naming rules should be followed.
- All keywords for pins should have an _pin suffix. Example direction_pin:
- Any keyword that is for a number with a unit should have the unit as the suffix. Example: spinup_ms:
- Use "per" as required, like "_mm_per_min"
- Use 2 for squared, like "_mm_per_sec2"