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:
Machine characteristics include:
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.
If you have a working machine definition from Grbl_ESP32, you can use an automated method. See this FAQ entry.
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 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
[MSG:ERR: Ignored key frodo]
board: 6 Pack
i2so:
bck_pin: gpio.22
data_pin: gpio.21
ws_pin: gpio.17
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.
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.
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
See Troubleshooting Config File Problems.
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.
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.
All config item names will include a suffix that describes the units or type. Examples...
Do not include the units in your value, just the number, string, etc.
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.
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.
To keep the config file consistent and relatively self describing the following naming rules should be followed.