= Homing Configuration

[[cha:homing-configuration]]

== Overview

Homing seems simple enough - just move each joint to a known location,
and set LinuxCNC's internal variables accordingly. However, different
machines have different requirements, and homing is actually quite
complicated.

== Homing Sequence

There are four possible homing sequences defined by the sign of HOME_SEARCH_VEL
and HOME_LATCH_VEL, along with the associated configuration parameters as shown
in the following table. Two basic conditions exist, HOME_SEARCH_VEL and
HOME_LATCH_VEL are the same sign or they are opposite signs. For a more
detailed description of what each configuration parameter does, see the
following section.

.Homing Sequences

image::images/emc2-motion-homing-diag.png[align="center"]

== Configuration

The following determines exactly how the home sequence behaves.
They are defined in an [AXIS] section of the inifile.

[width="80%", options="header", cols="4*^"]
|==========================================================
|Homing Type      |HOME_SEARCH_VEL |HOME_LATCH_VEL    |HOME_USE_INDEX
|Immediate        |0          |0            |NO
|Index-only       |0          |nonzero      |YES
|Switch-only      |nonzero    |nonzero      |NO
|Switch and Index |nonzero    |nonzero      |YES
|==========================================================

[NOTE]
Any other combinations may result in an error.

=== HOME_SEARCH_VEL (((HOME SEARCH VEL)))

This variable has units of machine-units per second.

The default value is zero. A value of zero causes LinuxCNC to assume that
there is no home switch; the search stage of homing is skipped.

If HOME_SEARCH_VEL is non-zero, then LinuxCNC assumes that there is a home
switch. It begins by checking whether the home switch is already
tripped. If tripped it backs off the switch at HOME_SEARCH_VEL. The
direction of the back-off is opposite the sign of HOME_SEARCH_VEL. Then
it searches for the home switch by moving in the direction specified by
the sign of HOME_SEARCH_VEL, at a speed determined by its absolute
value. When the home switch is detected, the joint will stop as fast as
possible, but there will always be some overshoot. The amount of
overshoot depends on the speed. If it is too high, the joint might
overshoot enough to hit a limit switch or crash into the end of travel.
On the other hand, if HOME_SEARCH_VEL is too low, homing can take a
long time.

=== HOME_LATCH_VEL (((HOME LATCH VEL)))

This variable has units of machine-units per second.

Specifies the speed and direction that LinuxCNC uses when it makes its
final accurate determination of the home switch (if present) and index
pulse location (if present). It will usually be slower than the search
velocity to maximize accuracy. If HOME_SEARCH_VEL and HOME_LATCH_VEL
have the same sign, then the latch phase is done while moving in the
same direction as the search phase. (In that case, LinuxCNC first backs off
the switch, before moving towards it again at the latch velocity.) If
HOME_SEARCH_VEL and HOME_LATCH_VEL have opposite signs, the latch phase
is done while moving in the opposite direction from the search phase.
That means LinuxCNC will latch the first pulse after it moves off the
switch. If HOME_SEARCH_VEL is zero (meaning there is no home switch),
and this parameter is nonzero, LinuxCNC goes ahead to the index pulse
search. If HOME_SEARCH_VEL is non-zero and this parameter is zero, it
is an error and the homing operation will fail. The default value is
zero.

=== HOME_FINAL_VEL

This variable has units of machine-units per second.

It specifies the speed that LinuxCNC uses when it makes its move from
HOME_OFFSET to the HOME position. If the HOME_FINAL_VEL is missing from
the ini file, then the maximum joint speed is used to make this move.
The value must be a positive number.

=== HOME_IGNORE_LIMITS (((HOME IGNORE LIMITS)))

Can hold the values YES / NO. The default value for this parameter is NO.
This flag determines whether LinuxCNC will ignore the limit switch input
for this axis while homing. Setting this to YES will not ignore limit inputs
for other axes. If you do not have a separate home switch set this to YES and
case connect the limit switch signal to the home switch input in HAL. LinuxCNC
will ignore the limit switch input for this axis while homing. To use only
one input for all homing and limits you will have to block the limit signals
of the axes not homing in HAL and home one axis at a time.

=== HOME_USE_INDEX (((HOME USE INDEX)))

Specifies whether or not there is an index pulse. If the flag is true
(HOME_USE_INDEX = YES), LinuxCNC will latch on the rising edge of the index
pulse. If false, LinuxCNC will latch on either the rising or falling edge of
the home switch (depending on the signs of HOME_SEARCH_VEL and
HOME_LATCH_VEL). The default value is NO.

[NOTE]
HOME_USE_INDEX requires connections in your hal file to axis.n.index-enable
from the encoder.n.index-enable.

=== HOME_OFFSET (((HOME OFFSET)))

Contains the location of the home switch or index pulse, in joint
coordinates. It can also be treated as the distance between the point
where the switch or index pulse is latched and the zero point of the
joint. After detecting the index pulse, LinuxCNC sets the joint coordinate
of the current point to HOME_OFFSET. The default value is zero.

NOTE: The home switch location, as indicated by the HOME_OFFSET variable,
must be strictly within the soft limits.  That is, `MIN_LIMIT <
HOME_OFFSET < MAX_LIMIT`.

=== HOME (((HOME)))

The position that the joint will go to upon completion of the homing
sequence. After detecting the home switch or home switch then index pulse
(depending on configuation), and setting the coordinate of that point to
HOME_OFFSET, LinuxCNC makes a move to HOME as the final step of the homing
process. The default value is zero. Note that even if this parameter is the
same as HOME_OFFSET, the joint will slightly overshoot the latched position as
it stops. Therefore there will always be a small move at this time (unless
HOME_SEARCH_VEL is zero, and the entire search/latch stage was skipped). This
final move will be made at the joint's maximum velocity unless HOME_FINAL has
been set.

[NOTE]
The distinction between 'HOME_OFFSET' and 'HOME' is that 'HOME_OFFSET' first
establishes the scale location on the machine by applying the 'HOME_OFFSET'
value to the location where home was found, and then 'HOME' says where the
joint should move to on that scale.

=== HOME_IS_SHARED (((HOME IS SHARED)))

If there is not a separate home switch input for this axis, but a
number of momentary switches wired to the same pin, set this value to 1
to prevent homing from starting if one of the shared switches is
already closed. Set this value to 0 to permit homing even if the switch
is already closed.

=== HOME_SEQUENCE (((HOME SEQUENCE)))

Used to define a multi-axis homing sequence HOME ALL and enforce
homing order (e.g., Z may not be homed if X is not yet homed). An axis
may be homed after all axes with a lower HOME_SEQUENCE have already
been homed and are at the HOME_OFFSET. If two axes have the same
HOME_SEQUENCE, they may be homed at the same time. If HOME_SEQUENCE is
-1 or not specified then this joint will not be homed by the HOME ALL
sequence. HOME_SEQUENCE numbers start with 0 and there may be no unused
numbers.

=== VOLATILE_HOME (((VOLATILE HOME)))

If this setting is true, this axis becomes unhomed whenever the
machine transitions into the OFF state. This is appropriate for
any axis that does not maintain position when the axis drive is
off.  Some stepper drives, especially microstep drives, may need
this.

=== LOCKING_INDEXER (((LOCKING INDEXER)))

If this axis is a locking rotary indexer, it will unlock before
homing, and lock afterward.

=== Immediate Homing (((Immediate Homing)))

If an axis does not have home switches or does not have a logical
home position like a rotary axis and you want that axis to home at
the current position when the "Home All" button is pressed in Axis
the following ini entries for that axis are needed.

. HOME_SEARCH_VEL = 0
. HOME_LATCH_VEL = 0
. HOME_USE_INDEX = NO
. HOME_SEQUENCE = 0

