homing: bound the homing moves, return from a failed latch move

docs/src/config/ini-config.adoc

@@ -1206,6 +1206,14 @@ These parameters are Homing related, for a better explanation read the <<cha:hom
   Velocity in machine units per second from home latch position to home position.
   If left at 0 or not included in the joint rapid velocity is used.
   Must be a positive number.
+* `HOME_SEARCH_DIST = 0.0` - (real)
+  Farthest the home search move may travel in machine units without finding the switch.
+  Past it the joint stops and the homing fails.
+  Zero (the default) leaves the move bounded only by twice the joint's travel.
+* `HOME_LATCH_DIST = 0.0` - (real)
+  Farthest the back-off, latch and index search moves may each travel in machine units without result.
+  Past it the joint moves back to where that move began and the homing fails.
+  Zero (the default) leaves those moves bounded only by twice the joint's travel.
 * `HOME_USE_INDEX = NO` - (bool)
   If the encoder used for this joint has an index pulse, and the motion card has provision for this signal you may set it to yes.
   When it is yes, it will affect the kind of home pattern used.

docs/src/config/ini-homing.adoc

@@ -160,6 +160,30 @@ 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_SEARCH_DIST
+
+(((HOME SEARCH DIST)))
+This variable has units of machine-units.
+
+The farthest the search move may travel without finding the home switch.
+When the switch is not seen within this distance the joint stops there and the homing is aborted with an error; the next attempt searches on from that point.
+The default value is zero: the search move is bounded only by twice the joint's travel, so a dead switch takes the joint to its limit switch, or into the end of its travel when the limit switch is shared with the home switch and ignored.
+On a continuous rotary joint, whose soft limits are set far apart, this is the only thing that stops a search with a dead switch: set it to a little over one revolution.
+
+=== HOME_LATCH_DIST
+
+(((HOME LATCH DIST)))
+This variable has units of machine-units.
+
+The farthest any of the moves made next to the home switch may travel: the back-off move that waits for the switch to clear, the latch move that finds the switch again, and the index pulse search.
+When the move ends without result the joint moves back to where that move began, at the speed of that move, and the homing is aborted with an error.
+The default value is zero: these moves are bounded only by twice the joint's travel.
+A switch stuck on sends the back-off move away from the switch for the whole travel; a switch that fails after its first trip sends the latch move the same way at latch speed.
+A value of a few times the distance the joint overshoots when the switch trips (HOME_SEARCH_VEL squared over twice the joint acceleration) plus the width of the switch's active zone bounds both.
+With HOME_USE_INDEX the value must also cover one revolution of the encoder.
+
+When a joint of a synchronized sequence (negative HOME_SEQUENCE) runs out of this distance, every joint of that sequence stops and each one moves back to where its own current move began, so the joints end where they were when the move started.
+
 === HOME_IGNORE_LIMITS
 
 (((HOME IGNORE LIMITS)))

src/emc/ini/inijoint.cc

@@ -48,6 +48,8 @@ static void inline print_dbg_config(const std::string &s)
 // [JOINT_n]HOME_OFFSET <real>                 Home switch/index pulse location
 // [JOINT_n]HOME_SEARCH_VEL <real>             Homing speed, search phase
 // [JOINT_n]HOME_LATCH_VEL <real>              Homing speed, latch phase
+// [JOINT_n]HOME_SEARCH_DIST <real>            Bound on the search move, 0 = unbounded
+// [JOINT_n]HOME_LATCH_DIST <real>             Bound on the back-off, latch and index moves, 0 = unbounded
 // [JOINT_n]HOME_FINAL_VEL <real>              Speed to move from HOME_OFFSET to HOME location (at the end of homing)
 // [JOINT_n]HOME_IS_SHARED <bool>              The home switch input is shared between joints
 // [JOINT_n]HOME_USE_INDEX <bool>              Use index pulse when homing
@@ -129,6 +131,8 @@ static int loadJoint(int joint, const IniFile &ini)
     double search_vel  = ini.findRealV("HOME_SEARCH_VEL", jointSection, 0.0);
     double latch_vel   = ini.findRealV("HOME_LATCH_VEL", jointSection, 0.0);
     double final_vel   = ini.findRealV("HOME_FINAL_VEL", jointSection, -1.0);
+    double search_dist = ini.findRealV("HOME_SEARCH_DIST", jointSection, 0.0);
+    double latch_dist  = ini.findRealV("HOME_LATCH_DIST", jointSection, 0.0);
     bool is_shared     = ini.findBoolV("HOME_IS_SHARED", jointSection, false);
     bool use_index     = ini.findBoolV("HOME_USE_INDEX", jointSection, false);
     bool encoder_reset = ini.findBoolV("HOME_INDEX_NO_ENCODER_RESET", jointSection, false);
@@ -144,6 +148,7 @@ static int loadJoint(int joint, const IniFile &ini)
 
     if (0 != emcJointSetHomingParams(joint, home, offset,
                                      final_vel, search_vel, latch_vel,
+                                     search_dist, latch_dist,
                                      use_index,
                                      encoder_reset,
                                      ignore_limits,

src/emc/motion/command.c

@@ -716,6 +716,8 @@ void emcmotCommandHandler_locked(void *arg, long servo_period)
 	                            emcmotCommand->home_final_vel,
 	                            emcmotCommand->search_vel,
 	                            emcmotCommand->latch_vel,
+	                            emcmotCommand->search_dist,
+	                            emcmotCommand->latch_dist,
 	                            emcmotCommand->flags,
 	                            emcmotCommand->home_sequence,
 	                            emcmotCommand->volatile_home