The setup of the limit switches in FluidNC is very flexible. This allows it to be both feature rich and allows for very low input pin count. It supports basic axes as well as ganged axes with squaring. Some key are under the homing: group for the axis and some are under the motor<0 or 1>: group.

An IO pin can only be used once. You can use parallel or series wiring for multiple switches, but you can never assign the input to more than one item in your config file.

Note: For a deeper explanation of machine space setup, see this page.

These key are for the axis. Even if an axis more than one motor, it still homes towards one end and at a specific speed.

• cycle:

  • Type: Integer
  • Range: -1 to 6
  • Default: -1
  • Interactions: multi-axis homing cannot be used with CoreXY, because 2 motors are used for each axis move.
  • Details: A setting of 1 or greater enables the axis for homing with $H. Anything lower than 1 will be an inactive cycle and no homing will occur for that axis.
    Homing cycles allow you to home axes sequentially or group a few axes into a single cycle for multi-axis homing. Assign the same number to multiple axes to home them in the same cycle.
    Typically you would put the Z axis on cycle: 1 and the other axes on higher cycles.

• allow_single_axis:

  • Type: Boolean
  • Default: true
  • Details: Allows single axis homing for the axis (example: $HX to home the X axis).
    Set to false if you do not have limits switches, or to block the command. You might want to block it because a single axis home unlocks the machine even though other axes may not be homed. Soft limits are only accurate on homed axes and will not protect a machine that has not homed all axes.

• positive_direction:

  • Type: Boolean
  • Default: true
  • Details: Controls the direction in which the axis moves when homing. true will home in the positive direction, where positive means moving towards a higher position value.

• mpos_mm:

  • Type: Float
  • Range: ✪
  • Default: 0.000
  • Details: Sets the machine position after homing and limit switch pulloff in millimeters. If you want the machine position to be zero at the limit switch, set this to zero. Keep in mind the homing direction and the pulloff_mm: values when you choose this number.

• seek_mm_per_min:

  • Type: Float
  • Range: greater than 0.000, workable values are generally 200.000 — 800.000
  • Default: 200.000
  • Details: Usually a faster rate to do the initial seeking of the limit switch.

• seek_scaler:

  • Type: Float
  • Range: ✪, workable value is slightly higher than 1
  • Default: 1.100
  • Details: Sets how far the machine will move to try to find the limit switch. It is multiplied by the max_travel_mm: of the axis. For example, where seek_scaler: is 1.100, and max_travel_mm: is 500.000, the controller will give up after moving 550.000 mm.

• feed_mm_per_min:

  • Type: Float
  • Range: ✪, workable values are generally 50.000 — 100.000
  • Default: 50.000
  • Details: Usually a slower rate when in close proximity to the limit switch, to do the pulloff and second touch.

• feed_scaler:

  • Type: Float
  • Range: ✪, workable value is slightly higher than 1
  • Default: 1.100
  • Details: Sets how far the machine will move to try to find the limit switch in the slower feed phase of homing. It is multiplied by the pulloff_mm: of the axis. For example, where feed_scaler: is 1.100, and pulloff_mm: is 3.000, the controller will give up after moving 3.300 mm.

• settle_ms:

  • Type: 32-bit Unsigned Integer
  • Range: ✪, workable values are generally 250 — 500
  • Default: 250
  • Details: Sets the amount of time (in milliseconds) the machine will pause between moves to allow the machine to settle.

homing:
      cycle: 2
      allow_single_axis: true
      positive_direction: false
      mpos_mm: 150.000
      feed_mm_per_min: 100.000
      seek_mm_per_min: 200.000
      settle_ms: 500
      seek_scaler: 1.100
      feed_scaler: 1.100

These affect the specific motor doing the homing. It allows you to define different values for a 2 motor axes.

• limit_neg_pin: This is the pin used for the limit switch in the negative direction of travel
• limit_pos_pin: This is the pin used for the limit switch in the positive direction of travel
• limit_all_pin: Use this if you are using one switch input for more than one switch. The drawback to using switches at both ends on one input, is if a switch is activated before homing. It does not know which one, so it cannot pull off. You must do it manually.
• hard_limits: This is used to apply hard limits to to all the switches on this motor. Hard limits force an alarm mode, with all motion stopped when a limit switch is touched. It is a rapid uncontrolled stop that will lose position. You should rehome the machine after a hard limit alarm.
• pulloff_mm: This sets how far the motor will back off of the switch after touching. If you have a 2 motor axis and your switches are not accurately aligned, you can give each axis a slightly different value.

motor0:
      limit_neg_pin: NO_PIN
      limit_pos_pin: NO_PIN
      limit_all_pin: gpio.33:pu
      hard_limits: true
      pulloff_mm:1.000

These control whether you can move the axis past its endpoints. You can use none, either or both of these features.

Hard limits use switches to stop the motion when you get to an end. It only works if you have switches at the both ends. If it hits a switch motion is immediately stopped, an alarm is given and accurate position is lost. You must rehome. Since they are controlled by switches this is defined at the same level as the switches. Hard limits alarms will not occur during homing.

Soft limits are determined by the range of motion. If you send a command that would send it beyond the range it blocks that command. It does a safe stop and position is not lost. It requires that you home the machine before using them, so the machine accurately knows where it is. The soft limit range of each axis is shown in the startup messages. These values are in machine coordinates, not work coordinates. Most gcode uses work coordinates. If you are getting unexpected soft limit errors, check your work offsets.

[MSG:INFO: Axis X (0.000,300.000)]

If you specify a limit_all_pin:, you cannot specify a limit_neg_pin: or a limit_pos_pin:.

You can view the real time switch status in a test mode by sending the $limits command. The status of the switches will be displayed on the serial console. Activate switches and you should see it in the reporting. It uses lower case for motor0 and upper case for motor1. If you have an limit_all_pin: switch, the same switch should report for a positive and negative end. Send ! to exit this mode and return to normal control mode. It can take a few seconds to react to the ! character and stop.

It will look like this:

$limits
Homing Axes: xyz
Limit  Axes: xyz
  PosLimitPins NegLimitPins
: x            x
: x     X

Here is one with explanations added:

$limits                       (The command to start the reporting)
Homing Axes: xyz              (Your config file has a homing section for motors x,y, & z)
Limit  Axes: xyz              (Axes x,y, & z have limit switch pins defined in the config file)
  PosLimitPins NegLimitPins   (A header for the reporting below it)
: x            x              (motor0 has a positive x and negative x switch active. Could be an all switch)
: x     X                     (motor0 and motor1 [upper case] have positive switches active)
:                             (No switches active)
!                             (The command to stop the recording)

Axis squaring uses 2 homing switches to make sure the axis is squared during homing. It requires 2 motors and a separate switch input for each side. If it sees this in the config file, squaring will be used. This allows us to use a stress free method. This means no side will move without the other if it does not have to. If your axis starts out square, it will never be pulled out of square (stressed) during the squaring.

The above method assumes your switches are mounted squarely. That is definitely the ideal setup. If this is not the case, you can use pulloff_mm: settings in the config file to compensate for this. This is the amount the motor reverses after touching the switch. By using different values for each motor, you can compensate for misaligned switches.

• One switch on the homed direction side

x:
  motor0:
    limit_neg_pin: gpio:2

• Separate inputs for the positive and negative ends

x:
  motor0:
    limit_neg_pin: gpio:2
    limit_pos_pin: gpio:2

• 2 independent switches on the homed end of each side

x:
  motor0:
      limit_neg: gpio:2
  motor1:
      limit_neg: gpio:3

• 4 independent switches

x:
  motor0:
      limit_neg_pin: gpio:2
      limit_pos_pin: gpio:3
  motor1:
      limit_neg_pin: gpio:4
      limit_pos_pin: gpio:5

• One side with an all switch and the other with pos, neg or both

x:
  motor0:
      limit_all_pin: gpio:2
  motor1:
      limit_neg_pin: gpio:4
      limit_pos_pin: gpio:5

This configuration is not allowed in FluidNC. We use a stress free squaring method that requires separate switch inputs for each axis. With stress free squaring, if the axis starts out square, homing will never move it out of square.

If you get strange behavior, you might need pull up or pull down resistors. External ones in the 3k-10k range work well. You can also apply ESP32 ones to many pins in firmware with the :pu or :pd pin attribute. It is a good practice to put these in your config file even if you have external ones, so people reading your file will know.