FluidNC Config File Overview - Longus/FluidNC GitHub Wiki

FluidNC is configured (adapted to a particular machine) at run-time by reading a config file from the local (ESP32 flash) file system. The config file is a text file that contains a hierarchical description of which machine features are present, the assignment of controller pins to those features, and other parameters that affect the machine behavior.

Note: There are still a few items in config.h file and require a recompile. These are rarely changed things and we are working incorporate as many as practical into the config file.

The name of the config file is given by the setting $Config/Filename. Its default value is "config.yaml", but you can change it to another name. You must restart the controller if you change the file or filename.

Our format is subset of YAML. To keep the firmware simple, only the features we need are used. Many standard YAML features cannot be used.

• Comments using # after a key value pair are not supported.
• Any key in a section that is not supported will be ignored and will print an error on startup like [MSG:ERR: Ignored key frodo]
• Do not have any trailing whitespace after key values like blanks.
• The last line must have a line end, so have at least one blank line at the end of the file.
• The indentation is critical. All sub items in a section must have the exact same indent level.
• The length of the filename including ".yaml" shall not exceed 30 characters.

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. All when posting in Github issues, Discord posts, wiki pages 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 change the $Config/Filename setting to the new name. Example: $Config/Filename=my_machine.yaml

PlatformIO can upload files to the ESP32. Run pio run -t uploadfs from a PlatformIO terminal. That will transfer all file from the FluidNC/data folder to the root folder of the ESP32. Note: This will erase the files on the local file system of the ESP32 and replace them with the FluidNC/data folder.

See this Wiki page.

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= 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 with a $localfs/list command.

All units of length are in mm. All feed rates are in mm/min. All durations will be specified at the end of the keyword name (example: the units for key delay_ms: are milliseconds) . For integer numbers you should not include a decimal point. For floating point values, you must include a decimal point.

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.

• Top level items (no indent)
• stepping:
• axes:
  • Motor
• spi:
• sdcard:
• control:
• coolant:
• probe:
• macros:
• user_outputs:
• spindles
• start:

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.

1. All keywords for pins should have an _pin suffix. Example direction_pin:
2. Any keyword that is for a number with a unit should have the unit as the suffix. Example: spinup_ms:
   1. Use "per" as required, like "_mm_per_min"
   2. Use 2 for squared, like "_mm_per_sec2"