HomingSwitch

  9 minute read  

HomingSwitch finds a machine’s reference position. It sits in the path of the axis setpoint: normally it passes the nominal setpoint straight through, and when you command a homing run it substitutes a smooth jog of its own, watches up to three trigger signals, and stops when one of them fires.

flowchart LR
    i1(["input — the nominal axis setpoint"]) --> B["HomingSwitch"]
    i2(["triggerSignal1, triggerSignal2, triggerSignal3"]) --> B
    i3(["gotoHoming"]) --> B
    i4(["manualJogPositive, manualJogNegative"]) --> B
    i5(["reset, abort"]) --> B
    i6(["positionReference"]) --> B
    B --> o1(["output — the setpoint to pass downstream"])
    B --> o2(["homingState"])
    B --> o3(["isHomed"])
    B --> o4(["homingInProgress"])
    B --> o5(["doReferenceOutput"])
    B --> o6(["actuatorUnitRatio"])
    B --> s1(["trigger1Detector, trigger2Detector, trigger3Detector"])
    B --> s2(["homingVelocityFader, homingIntegrator, homingSwitch, homingResetOffsetSwitch"])

Four things about this block will catch you out. Read them before commissioning.

There is no timeout. If no trigger ever fires, the axis keeps jogging until it hits something. Nothing stops it and nothing reports a problem. The three trigger detectors are your only protection, so wire and configure them before you set a non-zero homingVelocity.

Lowering gotoHoming does not stop a run. Only the abort input does.

The trigger levels are not on this block. They are the tooLow and tooHigh levels of the three detectors below — trigger1Detector/tooHigh and so on. The warning levels (low, high) are not used as triggers and are yours to use for an approach indication.

The jog directions are fixed. Moving to a trigger always goes positive; moving off one always goes negative. The only way to reverse is a negative homingVelocity, which reverses both.

Signals

Inputs

Path	Unit	Range	Description
input	axis unit	unbounded	The nominal axis setpoint. Passed straight to output when not homing.
triggerSignal1	signal unit	unbounded	First trigger — a switch, a sensor, a torque. Watched by trigger1Detector.
triggerSignal2	signal unit	unbounded	Second trigger. Any of the three firing ends the approach.
triggerSignal3	signal unit	unbounded	Third trigger. Leave unused ones at 0 with their levels wide.
gotoHoming	-	true or false	A rising edge starts a run, and only if isHomed is false. Lowering it does not stop the run.
manualJogPositive	-	true or false	Jog positive. Only has any effect in method 6 — every other method overwrites it.
manualJogNegative	-	true or false	Jog negative. Same restriction.
reset	-	true or false	Clears isHomed and the three detectors, so a new run can start. Cleared for you.
abort	-	true or false	Stops a run. The only way to. Cleared for you.
positionReference	axis unit	unbounded	The position the homing move starts from. Held while not homing.

Outputs

Path	Unit	Description
output	axis unit	The setpoint to send downstream — the nominal input, or the homing move, cross-faded between the two.
homingState	-	1 off, 2 initialise, 3 moving off a trigger, 4 moving to a trigger, 5 referencing, 6 auto-return, 7 done, 8 aborted. Note it starts at 1, not 0.
isHomed	-	The axis has been homed. Blocks another run until you reset.
homingInProgress	-	Jogging, or the pull-back is still fading in.
doReferenceOutput	-	A single-cycle pulse telling your encoder handling to zero the position. Latch it yourself if you need it longer.
actuatorUnitRatio	-	Reads 1.0 always. Nothing in the tree can change it.

Parameters

Path	Unit	Default	Range	Effect
homingMethod	-	1	0 to 6	Which sequence to run. See the table below.
homingVelocity	axis unit per second	0.0	any	The jog speed, applied at full magnitude — there is no proportional jog. At the default of 0 the axis never moves and, in a move-to-trigger method, waits forever. A negative value reverses both jog directions.
pullBackOffset	axis unit	0.0	any	Added to the final setpoint after the trigger fires, faded in, to retract off the switch.
autoReferenceOnHome	-	false	-	Whether doReferenceOutput pulses when the run reaches the referencing step.
homingAutoReturn	-	false	-	Has no effect. The auto-return step is not implemented in this version.

All are persistent and survive a controller restart. The rest of the configuration is in the sub-trees:

Path	Effect
trigger1Detector/tooLow, …/tooHigh	The trigger levels for signal 1. Defaults are -0.05 and 0.05.
trigger1Detector/timeWindow	How long the signal must be past the level before it counts. At the default of 0 a single noisy sample triggers.
trigger2Detector/…, trigger3Detector/…	The same for signals 2 and 3.
homingVelocityFader/fadeTime	How smoothly the jog starts and stops.
homingSwitch/fadeInTime, …/fadeOutTime	How smoothly control passes between the nominal setpoint and the homing move.
homingResetOffsetSwitch/fadeInTime	How smoothly the pull-back offset is applied.

homingMethod	What the machine does
0 bypass	Marks the axis homed without moving. Use to skip homing on an axis that does not need it
1 reference	Zeroes in place, without moving. The default
2 move to trigger	Jogs positive until any trigger fires
3 move off trigger	Jogs negative until all three triggers are clear
4 off then to	Backs off the switch, then approaches it. The usual choice for a repeatable home
5 to then off	Approaches the switch, then backs off it
6 manual jog to trigger	You jog with manualJogPositive and manualJogNegative until a trigger fires

Setup

1. Wire your home switch, or whichever signal marks the reference, to triggerSignal1. Leave the other two at 0.

2. Set the trigger levels before anything else. Trace triggerSignal1 through the switch being made and broken, and set trigger1Detector/tooHigh and …/tooLow so the switch reliably crosses one of them. Set the other two detectors' levels wide so they never fire.

3. Set trigger1Detector/timeWindow to a few milliseconds so contact bounce does not trigger.

4. Verify the trigger works before enabling any motion. With homingVelocity still at 0, operate the switch by hand and watch trigger1Detector/noError go false.

5. Set homingMethod to 2 and homingVelocity to a slow speed — a tenth of what you eventually want.

6. Set homingVelocityFader/fadeTime to a few hundred milliseconds.

7. Raise gotoHoming and watch output move.

   Step 7 drives the axis, and it will not stop on its own. Stand by the abort input, or an external limit. There is no timeout in this block: if the trigger does not fire, the axis jogs until something stops it.

8. Confirm the axis stops when the switch is made, isHomed goes true, and homingState returns to 1.

9. Pulse reset before running again.

Tuning

1. Get the trigger detection right first. Everything else depends on it, and it is the only thing preventing a runaway.
2. Raise homingVelocity in steps, re-testing each time. The faster the approach, the further the axis travels between the switch being made and the jog fading out.
3. Measure that overtravel: home several times and compare the final output. The spread is your homing repeatability.
4. Shorten homingVelocityFader/fadeTime to reduce overtravel, or lower homingVelocity. Lowering the speed usually helps repeatability more.
5. Use method 4 for the best repeatability: backing off the switch first means every run approaches from the same side at the same speed.
6. Set pullBackOffset to retract clear of the switch after homing, so the axis does not sit on it.
7. Set homingSwitch/fadeOutTime so control returns to the nominal setpoint smoothly after the run.
8. Re-check the whole sequence after any change to the axis’s speed limits or task rate.

The distance travelled between the trigger firing and the motion stopping is your overtravel. It scales with both the jog speed and the fade-out time.

Symptom	Cause	Action
The axis jogged until it hit something	No trigger fired and there is no timeout	Verify the trigger detection before enabling motion
The axis never moved	homingVelocity is 0 — the default — or the method is 0 or 1	Set a velocity and a moving method
Nothing happened when I raised gotoHoming	isHomed is already true, or it was already high	Pulse reset, then give a fresh rising edge
Lowering gotoHoming did not stop it	Expected: only abort stops a run	Use abort
The axis homed in the wrong direction	The directions are fixed; only a negative homingVelocity reverses them, and it reverses both phases	Use a negative velocity, or a different method
Homing repeatability is poor	The approach is too fast, or the fade-out too long	Lower homingVelocity first
It triggered before reaching the switch	A detector level is too tight, or timeWindow is 0 and it caught noise	Widen the level, lengthen the window
It triggered on a signal I am not using	An unused trigger signal sits inside its detector’s default levels of ±0.05	Widen the unused detectors' levels
Setting homingAutoReturn did nothing	Expected: the auto-return step is not implemented	Do the return move in your own logic
doReferenceOutput was missed	Expected: it is a single-cycle pulse	Latch it in your own logic
doReferenceOutput never pulsed	autoReferenceOnHome is false	Set it true
actuatorUnitRatio always reads 1	Expected: nothing in the tree can change it	Ignore it
Method 4’s first phase did nothing	Expected: if the axis is already clear of the switch, “move off” completes at once	Nothing
A run resumed after a controller restart	The block does not reset its state at startup	Pulse abort then reset after every start
The axis lurched when the run ended	homingSwitch/fadeOutTime is too short	Lengthen it
The axis lurched when the run started	homingVelocityFader/fadeTime is too short	Lengthen it
Everything triggered at once	A trigger signal is not a valid number, which raises all of that detector’s flags	Fix the upstream signal
I need this on several axes	Not possible — this block is single axis	Use one instance per axis

A starting point for a switch-homed linear axis:

homingMethod                 = 4
homingVelocity               = 0.01
pullBackOffset               = 0.005
autoReferenceOnHome          = true
homingAutoReturn             = false
trigger1Detector/tooHigh     = <set from a trace of the switch>
trigger1Detector/timeWindow  = 0.005
homingVelocityFader/fadeTime = 0.3

Limits and errors

Limit	Set by	What happens	Reported
Homing timeout	None	There is none. A run whose trigger never fires jogs indefinitely	homingInProgress stays true
Trigger levels	The three detectors' tooLow and tooHigh	Any of the three firing ends the approach. The warning levels are not used	trigger1Detector/noError and so on
Trigger debounce	Each detector’s timeWindow	Defaults to 0, so a single sample triggers	Not reported
Jog speed	homingVelocity	Applied at full magnitude, faded in and out	output
Jog direction	Fixed	Move-to-trigger is positive, move-off-trigger negative. Only the velocity’s sign reverses them, and it reverses both	Not reported
Stopping a run	abort only	Lowering gotoHoming does not stop it	homingState
Re-homing	isHomed	Blocked until reset	isHomed
Overtravel	homingVelocity, the fader’s fade time	Not bounded. The axis travels while the jog fades out	output
Auto-return	Fixed	Not implemented. The parameter selects a step that does nothing	homingState passes through 6
actuatorUnitRatio	Not settable from the tree	Reads 1.0 always	Not reported
manualJog inputs	Fixed	Overwritten by every method except 6	Not reported
doReferenceOutput	Fixed	A single-cycle pulse, gated on autoReferenceOnHome	Not reported
Startup	Fixed	No state is reset. A run interrupted by a restart resumes	homingState
Values that are not numbers	Handled below	A bad trigger signal raises all of that detector’s flags, which reads as a trigger and ends the run early	The detector’s flags
Axis count	Fixed	One axis per instance, always	Not reported

This block logs nothing, ever — including when a homing run fails to find its trigger. Every condition above shows as a value on a trace, or not at all.

---

Verified against motorcortex-control3 3.30.0 (bc348fd).