1. 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.

2. 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
Figure 1. Homing Sequences

3. Configuration

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

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.

3.1. 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.

3.2. 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.

3.3. 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.

3.4. 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 joint while homing. Setting this to YES will not ignore limit inputs for other joints. 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 joint while homing. To use only one input for all homing and limits you will have to block the limit signals of the joints not homing in HAL and home one joint at a time.

3.5. 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 joint.n.index-enable from the encoder.n.index-enable.

3.6. 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.

3.7. 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.

3.8. HOME_IS_SHARED

If there is not a separate home switch input for this joint, 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.

3.9. HOME_ABSOLUTE_ENCODER

Use for absolute encoders. When a request is made to home the joint, the current joint position is set to the [JOINT_n]HOME_OFFSET value.

The final move to the [JOINT_n]HOME position is optional according to the HOME_ABSOLUTE_ENCODER setting:

HOME_ABSOLUTE_ENCODER = 0 (Default) joint does not use an absolute encoder
HOME_ABSOLUTE_ENCODER = 1 Absolute encoder, final move to [JOINT_n]HOME
HOME_ABSOLUTE_ENCODER = 2 Absolute encoder, NO final move to [JOINT_n]HOME
Note
A HOME_IS_SHARED setting is silently ignored.
Note
A request to rehome the joint is silently ignored.

3.10. HOME_SEQUENCE

Used to define a multi-joint homing sequence HOME ALL and enforce homing order (e.g., Z may not be homed if X is not yet homed). A joint may be homed after all joints with a lower (absolute value) HOME_SEQUENCE have already been homed and are at the HOME_OFFSET. If two joints have the same HOME_SEQUENCE, they may be homed at the same time. If HOME_SEQUENCE is not specified then this joint will not be homed by the HOME ALL sequence.

The initial HOME_SEQUENCE number may be 0, 1 (or -1). The absolute value of sequence numbers must increment by one — skipping sequence numbers is not supported. If a sequence number is omitted, "Home All" homing will stop upon conmpletion of the last valid sequence number.

Negative HOME_SEQUENCE values indicate that joints in the sequence should synchronize the final move to [JOINT_n]HOME by waiting until all joints in the sequence are ready. If any joint has a negative HOME_SEQUENCE value, then all joints with the same absolute value (positive or negative) of the HOME_SEQUENCE item value will synchronize the final move.

A negative HOME_SEQUENCE also applies to commands to home a single joint. If the HOME_SEQUENCE value is negative, all joints having the same absolute value of that HOME_SEQUENCE will be homed together with a synchronized final move. If the HOME_SEQUENCE value is zero or positive, a command to home the joint will home only the specified joint.

Joint mode jogging of joints having a negative HOME_SEQUENCE is disallowed. In common gantry applications, such jogging can lead to misalignment (racking). Note that conventional jogging in world coordinates is always available once a machine is homed.

Examples for a 3 joint system

Two sequences (0,1), no synchronization

[JOINT_0]HOME_SEQUENCE =  0
[JOINT_1]HOME_SEQUENCE =  1
[JOINT_2]HOME_SEQUENCE =  1

Two sequences, joints 1 and 2 synchronized

[JOINT_0]HOME_SEQUENCE =  0
[JOINT_1]HOME_SEQUENCE = -1
[JOINT_2]HOME_SEQUENCE = -1

With mixed positive and negative values, joints 1 and 2 synchronized

[JOINT_0]HOME_SEQUENCE =  0
[JOINT_1]HOME_SEQUENCE = -1
[JOINT_2]HOME_SEQUENCE =  1

One sequence, no synchronization

[JOINT_0]HOME_SEQUENCE =  0
[JOINT_1]HOME_SEQUENCE =  0
[JOINT_2]HOME_SEQUENCE =  0

One sequence, all joints synchronized

[JOINT_0]HOME_SEQUENCE = -1
[JOINT_1]HOME_SEQUENCE = -1
[JOINT_2]HOME_SEQUENCE = -1

3.11. VOLATILE_HOME

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

3.12. LOCKING_INDEXER

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

3.13. Immediate Homing

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

  1. HOME_SEARCH_VEL = 0

  2. HOME_LATCH_VEL = 0

  3. HOME_USE_INDEX = NO

  4. HOME_SEQUENCE = 0

  5. HOME equals to HOME_OFFSET

3.14. Inhibiting Homing

A hal pin (motion.homing-inhibit) is provided to disallow homing inititiation for both "Home All" and individual joint homing.