Homing is the most important part before you start a print. Only when the send coordinates match the real position you can expect your printer to succeed. Unfortunately there are so many printer systems with different requirements that the configuration of the homing process is not trivial. Some printers require a hot extruder or special coordinates to home z. Others use the z-probe for z homing while others have a z min endstop or home to z max. To solve all these different requirements the configuration was written with many options to fullfil all needs.
Note: In this description w eonly describe homing for x, y, z axes. If you also use A, B or C add variable names containing _X with your additional axes names.
Lets start with the basic definitions. You will need a homing order. For homing we loop from 0 to 10 and execute the homing of the axis with that priority. If several axes have same priority, they are executed in the order X, Y, Z, E, A, B, C. The definition looks like this:
/** Axes are homed in order of priority (0..10) if homing direction is not 0. */
#define X_HOME_PRIORITY 0
#define Y_HOME_PRIORITY 1
#define Z_HOME_PRIORITY 2Next is the direction you want to home. Possible values are -1 for homing towards minimum end stop, 1 for homing to maximum end stop and 0 for do not home that axis. Important is that homing always requires an end stop for that direction. Which end stop this is depends the printer type. Deltas can only home in z direction and will ignore homing commands for x and y direction.
The parameter SAFE_HOMING defaults to 1 for enabled. When safe homing is enabled not triggering end stops or not releasing end stops during homing process will cause a fatal error and printer goes into fatal mode ignoring most commands. This prevents moves that can damage your printer when homing does not work, e.g. because main power was not enabled. Should also abort prints on connected host software.
#SAFE_HOMING 1
#define X_HOME_DIR -1
#define Y_HOME_DIR 1
#define Z_HOME_DIR -1For each homing direction you also need to define a homing speed. This can also be changed in eeprom settings later. Use a speed where you can instantly stop without loosing steps.
#define HOMING_FEEDRATE_X 50
#define HOMING_FEEDRATE_Y 50
#define HOMING_FEEDRATE_Z 5
#define ENDSTOP_X_BACK_MOVE 5
#define ENDSTOP_Y_BACK_MOVE 5
#define ENDSTOP_Z_BACK_MOVE 3
#define ENDSTOP_X_RETEST_REDUCTION_FACTOR 3
#define ENDSTOP_Y_RETEST_REDUCTION_FACTOR 3
#define ENDSTOP_Z_RETEST_REDUCTION_FACTOR 3
#define ENDSTOP_X_BACK_ON_HOME 0.5
#define ENDSTOP_Y_BACK_ON_HOME 0.5
#define ENDSTOP_Z_BACK_ON_HOME 20
#define MOVE_X_WHEN_HOMED 0
#define MOVE_Y_WHEN_HOMED 0
#define MOVE_Z_WHEN_HOMED 0
#define ALWAYS_CHECK_ENDSTOPS 1
#define ZHOME_PRE_RAISE 0
#define ZHOME_PRE_RAISE_DISTANCE 10
#define ZHOME_MIN_TEMPERATURE 0
#define ZHOME_HEAT_ALL 0
#define ZHOME_HEAT_HEIGHT 10 // not used any more
#define FIXED_Z_HOME_POSITION 1
#define ZHOME_X_POS 140
#define ZHOME_Y_POS 45
// Height after z homing finishes
#define ZHOME_HEIGHT 0The ...RETEST_REDUCTION_FACTOR settings define the speed for the second test of the end stop. Now that we know we are close we can afford to reduce the speed in favour of higher precision. Just make sure that the ..._BACK_MOVE values move enough away from end stop to set the trigger state to low.
The ..._BACK_ON_HOME values allow to move away from the end stop a bit before the position is stored as home position. There are some reasons you might want that. If you have x min and x max end stop on the same line it would prevent moves if end stop check is enabled after homing. In general it is much better to have one end stop for each directions. An other reason is when you use auto leveling. Assume bed is higher on the right side and x min is 0. For z = 0 you can move to x = 0 but on higher z positions the "real" x position would need to be negative. But that will trigger the end stop and move will stop early (if end stop check is activated) or you simply ram into the end stop. Giving it a bit room will prevent this issue. Note that for z min homing you do not want this different from 0!
..._X_WHEN_HOMED can prevent moves of a not homed axis. To allow moves only after homing set the value to 1. This can reduce possible crashes to a great amount.
Z axis is always a bit special. You might want to prevent scrateches on the bed or your z sensor needs a minimum distance. So with ZHOME_PRE_RAISE you define if and when you want to raise the tool before homing axes. 0 disables it, 1 will raise only if z min end stop is triggered and 2 will always raise.
ZHOME_HEIGHT lets you define the z height after homing. Classically it is 0, but if you want to prevent burns in your bed when you heat up after homing and you forget to raise z, this is a good solution. Some bed coatings like buildtak do not like hot temperatures over a longer time.
The other frequent requirement is to do the z homing at a special (x, y)-position. In that case set FIXED_Z_HOME_POSITION 1 and then the homing will happen at (ZHOME_X_POS, ZHOME_Y_POS).
Last special case for z homing is the extruder temperature. Especially if the nozzle tip acs as part of the sensor it is important that no ooze causes an early trigger. To prevent this you can preheat the active or all nozzles prior to homing z. ZHOME_MIN_TEMPERATURE with a value > 0 activates the feature and sets the minimum temperature. If the temperature is already higher, it will not lower it! ZHOME_HEAT_ALL with 1 makes all tools heat up for homing. This is necessary if all nozzles are at the same height or the height difference is lower then expected ooze thickness.