– Detection and safety

Docs: CollisionDetector

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

CollisionDetector notices when an actuator meets something it was not expecting. It compares the torque the controller asked for against the torque the machine actually developed, and flags a discrepancy that persists.

The trick is that the commanded torque is delayed to match the measurement’s own lag before the two are compared, so the difference stays flat during ordinary motion and the threshold can be tight.

flowchart LR
    i1(["torqueReference"]) --> B["CollisionDetector"]
    i2(["torqueActual"]) --> B
    i3(["reset"]) --> B
    i4(["disable"]) --> B
    p1(["enable"]) --> B
    B --> o1(["torqueError"])
    B --> o2(["isEnabled"])
    B --> s1(["collisionDetector — the detection settings and results"])
    B --> s2(["collisionReferenceFilter — the delay matching"])

The thresholds are not on this block. They live one level down, under collisionDetector. Set collisionDetector/tooHigh and collisionDetector/tooLow to your collision thresholds and collisionDetector/timeWindow to how long the discrepancy must persist.

The detection result is also one level down, at collisionDetector/noError. This block publishes only torqueError — read noError from the sub-tree to know whether a collision was detected.

The block ships disabled. enable defaults to false. Nothing happens until you set it.

Signals

Inputs

Path	Unit	Range	Description
`torqueReference`	torque unit	unbounded	The torque the controller is asking for. Delayed internally before the comparison.
`torqueActual`	torque unit	unbounded	The torque the machine actually developed — from a sensor or the drive.
`reset`	-	true or false	Clears the detection. Passed through to the detector below. The block clears it for you.
`disable`	-	true or false	Suspends detection. The error is still computed and published.

Outputs

Path	Unit	Description
`torqueError`	torque unit	The measured torque minus the delay-matched reference. This is the signal to trace when setting thresholds.
`isEnabled`	-	Detection is running.

The detection flags themselves — isTooLow, isTooHigh, noError — are under collisionDetector.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	Turns detection on. The block does nothing until you set this.

That is the only parameter at this level. Everything that shapes the detection is in the two sub-trees below:

Path	Default	Effect
`collisionDetector/tooHigh`	0.05	The upper collision threshold on `torqueError`.
`collisionDetector/tooLow`	-0.05	The lower collision threshold.
`collisionDetector/high`, `…/low`	0.02, -0.02	Warning levels, if you want an early indication.
`collisionDetector/timeWindow`	0.0	How long the error must exceed a threshold before it is flagged. At 0 a single noisy sample trips it.
`collisionReferenceFilter/enable`	true	The delay matching. Leave this on — turning it off produces false collisions on every move.

All are persistent and survive a controller restart.

Setup

Connect the controller’s torque command to torqueReference and the measured torque to torqueActual. Both must be in the same units — nothing converts between them.
Leave enable false for now.
Run the machine through its normal motion and trace torqueError. It should stay small and flat. If it swings during acceleration, the two signals are not in the same units, or one is scaled differently.
Note the largest excursion of torqueError during normal motion, including the fastest move and the hardest acceleration.
Set collisionDetector/tooHigh and collisionDetector/tooLow outside that, with margin.
Set collisionDetector/timeWindow — go to Tuning.
Set enable true.

Whatever acts on collisionDetector/noError will act the moment it goes false. If that is a stop, confirm the thresholds are wide enough for normal motion before you enable, or the machine will stop on its own first move.
Push against the actuator by hand, gently, and confirm the detection comes up.

Tuning

Trace torqueError for a full working cycle before setting any threshold. The whole design aims to keep this flat; if it is not flat, fix that first.
If torqueError swings during acceleration, the delay matching is not suiting your drive. The internal delay is fixed at about 15 milliseconds at a 1 kHz task rate and is not adjustable. Widen the thresholds, or filter torqueActual upstream so its lag is closer to that.
Set the collision thresholds from the largest normal excursion, with margin — typically twice it.
Set timeWindow longer than the transient you want to ignore and shorter than the time you can afford to keep pushing. Ten to fifty milliseconds is a reasonable range.
Test with a real obstruction, not just by hand. A soft obstruction produces a slower error rise and needs a longer timeWindow to be tolerated, or a lower threshold to be caught.
Set the warning levels inside the collision thresholds if you want an early indication before stopping.
Re-check torqueError after any change to the drive tuning or to the feedforward path — both change the lag this block is matching.

The flat section is what makes a tight threshold possible.

Symptom	Cause	Action
Nothing is ever detected	`enable` defaults to false	Set it true and check `isEnabled`
Nothing is detected even when enabled	The thresholds are on the sub-tree, not here	Set `collisionDetector/tooHigh` and `…/tooLow`
I cannot find the detection result	It is at `collisionDetector/noError`	Read it from the sub-tree
`torqueError` swings during every move	The internal delay does not match your drive’s lag, or the two inputs are scaled differently	Check units first, then widen the thresholds
`torqueError` is huge and grows with speed	The two inputs are in different units	Fix the scaling upstream
False collisions on every move	The delay matching may be off — check `collisionReferenceFilter/enable`	Turn it back on
False collisions on noise	`collisionDetector/timeWindow` is 0	Lengthen it
A real collision was missed	The thresholds are too wide, or `timeWindow` too long	Trace `torqueError` during the collision and set from that
False collisions in torque mode	Detection cannot be suppressed from the tree in this version	Disable the block while in torque mode
A burst of error right after startup	The delay matching needs about 30 cycles to fill	Enable the block a moment after start
The flags will not clear	The detector below latches	Pulse `reset`
Everything is flagged at once	One of the inputs is not a valid number	Fix the upstream signal; this is the detector telling you so
I need this on several axes	Not possible — this block is single channel	Use one instance per axis

A starting point, once you have traced torqueError:

enable                          = true
collisionDetector/tooHigh       =  <twice the largest normal excursion>
collisionDetector/tooLow        = -<the same>
collisionDetector/timeWindow    = 0.02
collisionReferenceFilter/enable = true

Limits and errors

Limit	Set by	What happens	Reported
Detection thresholds	`collisionDetector/tooHigh`, `…/tooLow`	The detector below flags a persistent discrepancy	`collisionDetector/noError`
Debounce	`collisionDetector/timeWindow`	The error must exceed a threshold for this long. At the default of 0 a single sample trips it	Not reported
Delay matching	Fixed	The reference is delayed by about 15 milliseconds at a 1 kHz task rate. Not adjustable, and not matched to any particular drive	Not reported
Delay matching startup	Fixed	Takes about 30 cycles to fill after a start, during which `torqueError` reads high	Not reported
Input units	Nothing	Not checked. The two torque inputs must already be in the same units	`torqueError`
Torque-mode suppression	Not reachable from the tree	The block can suppress detection while the drive is in torque mode, but only when driven from an application	Not reported
Detection output	Fixed	Not published at this level. Read it from the sub-tree	Not applicable
`enable`	Fixed at false	The block ships disabled	`isEnabled`
Values that are not numbers	Handled below	A bad input makes `torqueError` invalid, and the detector below raises every flag — the safe direction	The detector’s flags
Reset	`reset`	Clears the detection below. Cleared for you	Not reported
Channel count	Fixed	One actuator per instance, always	Not reported

This block logs nothing, ever. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: MotionDetector

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

MotionDetector remembers a reference value and raises a flag when the signal drifts further than a threshold from it, in either direction. The flag stays raised until you reset it.

Use it to notice that something which should be standing still has moved — a brake slipping, a load settling, a clamped part creeping.

flowchart LR
    i1(["input"]) --> B["MotionDetector"]
    i2(["activate"]) --> B
    i3(["reset"]) --> B
    i4(["disable"]) --> B
    p1(["threshold"]) --> B
    p2(["enable"]) --> B
    B --> o1(["isTriggered"])
    B --> o2(["isEnabled"])
    B --> o3(["reference"])

Pulse reset whenever you raise activate. Raising activate on its own does not capture a new reference — the detector keeps comparing against whatever reference already holds, which is 0 after a controller start. reset is what captures the current input as the reference. Always send both.

Read reference to see what it is actually comparing against. It is published for exactly this reason, and it is the fastest way to tell whether the reference was captured when you expected.

There is no noise filtering. A single sample past the threshold latches the flag permanently. If your signal is noisy, filter it before this block or use WindowDetector, which has a time window.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal being watched.
`activate`	-	true or false	Detection runs while this is true. A level, not a pulse. On its own it does not capture a reference — see the callout above.
`reset`	-	true or false	Clears the flag and captures the current input as the new reference. The block clears it for you, so it is a pulse. Holding it true holds the detector re-armed.
`disable`	-	true or false	Suspends detection. While disabled the reference tracks the input, so disabling and re-enabling is another way to re-arm cleanly.

Outputs

Path	Unit	Description
`isTriggered`	-	The input has drifted past the threshold. Latches until reset or disabled.
`isEnabled`	-	Detection is permitted.
`reference`	signal unit	The value the input is being compared against. Check this first when the detector behaves unexpectedly.

Parameters

Path	Unit	Default	Range	Effect
`threshold`	signal unit	0.0	above 0	How far the input may drift from `reference` before the flag latches, in either direction. At the default of 0 any change at all triggers. A negative value makes it trigger immediately and permanently, and is not rejected.
`enable`	-	true	-	Turns detection on. When off, the flag is held clear and the reference follows the input.

Both are persistent and survive a controller restart. No parameters exist below this block.

Setup

Connect the signal you want to watch to input.
Set threshold to how much movement you are willing to accept. It defaults to 0, which triggers on anything.
Bring the machine to the state you want to monitor and hold it there.
Raise activate and pulse reset in the same write.
Read reference and confirm it matches the current input. If it reads 0, the reset did not land — send it again.
Confirm isTriggered is false and stays false while the machine is still.
Nudge the machine past the threshold and confirm isTriggered latches.

This block only watches a signal and raises a flag. It does not move anything and cannot be made to — but whatever acts on isTriggered downstream will act the moment it latches.

Tuning

Trace input while the machine is in the state you want to monitor, for as long as you would normally leave it there.
Note the total spread — both the noise and any slow settling that is acceptable.
Set threshold above that spread, with margin. Too tight and you get false trips from noise; too loose and real movement goes unnoticed.
Re-arm and leave it for a realistic dwell. Confirm it does not trip.
If it trips on noise, either widen threshold or filter input upstream. Filtering is usually the better answer — a wide threshold hides real movement, whereas a filter only delays detection.
If you need to ignore short spikes rather than steady noise, WindowDetector with a timeWindow is the better block, at the cost of fixed levels instead of a captured reference.
Nothing here depends on the task rate, so none of this needs re-checking after a rate change.

The flag never falls once raised. That is what makes it useful between polls.

Symptom	Cause	Action
It triggered immediately after activating	`reference` is 0 because `reset` was not sent with `activate`	Read `reference`; pulse `reset`
It triggered immediately even after a reset	`threshold` is 0 — the default — or negative	Set a positive threshold
`reference` reads 0	The reference has never been captured	Pulse `reset`
`reference` is not what I expected	It was captured at a different moment, or while disabled it tracked the input	Pulse `reset` at the moment you want captured
It trips on noise	There is no debounce in this block	Filter the input, or use `WindowDetector`
The flag will not clear	Expected: it latches	Pulse `reset`, or disable and re-enable
The flag cleared on its own	The block was disabled, which clears it	Check `isEnabled`
Real movement was not detected	`threshold` is wider than the movement	Narrow it
Nothing is ever detected	`activate` is false, or `enable` is false, or `disable` is true	Check `isEnabled` and `activate`
A dead sensor was not detected	A signal that is not a number reads as no motion here	Supervise the sensor with `WindowDetector`, which trips on it
The flag survived a restart	It is not cleared at startup, and `reference` returns to 0	Re-arm after every start
I need to watch several signals	Not possible — this block is single channel	Use one instance per signal

A starting point for an axis in metres that should not move:

threshold = 0.002
enable    = true

Limits and errors

Limit	Set by	What happens	Reported
Detection band	`threshold`, `reference`	The flag latches outside `reference` plus or minus `threshold`. Exactly at the edge does not trigger	`isTriggered`
Reference capture	`reset`, and disabling	Only `reset` and being disabled capture a reference. Raising `activate` does not	`reference`
`threshold` sign	Nothing	Not checked. A negative value triggers immediately and permanently	Not reported
`threshold` default	Fixed at 0	Any change at all triggers	Not reported
Debounce	None	A single sample past the threshold latches the flag	Not reported
Values that are not numbers	Nothing	Not checked. The flag is held, so a dead sensor reads as no motion	Not reported
Latching	Fixed	The flag stays raised until reset or disabled	Not reported
Disable	`disable`, `enable`	Detection stops, the flag clears, and the reference tracks the input	`isEnabled`
Startup	Fixed	`reference` starts at 0 and the flag is not cleared	`reference`
Channel count	Fixed	One signal per instance, always	Not reported

This block logs nothing, ever. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: WindowDetector

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

WindowDetector watches one signal against four levels and raises a flag for each. The inner pair — low and high — is a warning band; the outer pair — tooLow and tooHigh — is an error band. A time window stops noise from tripping them.

Use it to supervise a pressure, a temperature, a torque or a following error, and to distinguish “worth knowing about” from “stop now”.

flowchart LR
    i1(["input"]) --> B["WindowDetector"]
    i2(["reset"]) --> B
    i3(["disable"]) --> B
    p1(["tooLow, low, high, tooHigh"]) --> B
    p2(["timeWindow, enable, autoreset, id"]) --> B
    B --> o1(["isTooLow, isLow, isHigh, isTooHigh"])
    B --> o2(["noWarning, noError"])
    B --> o3(["isEnabled"])
    B --> o4(["state"])

The bands are nested, not exclusive. A signal below tooLow is also below low, so isTooLow and isLow are both true. For “warning but not error”, test isLow and not isTooLow yourself.

The flags latch. Once raised they stay raised until you reset, disable, or turn autoreset on. That is what you want for a fault you might otherwise miss between polls.

A signal that is not a number trips all four flags and clears both summaries. This is deliberate: a broken sensor reads as an error rather than as perfectly in range.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to watch. A value that is not a number raises every flag.
`reset`	-	true or false	Clears all four flags and their timers. You do not need to write it back to false — the block notices when you stop writing it and clears it for you.
`disable`	-	true or false	Suspends detection and clears the flags. Re-enabling starts clean.

Outputs

Path	Unit	Description
`isTooLow`	-	The input has been at or below `tooLow` for `timeWindow`. Error level. Latches.
`isLow`	-	At or below `low`. Warning level. Latches. Also true whenever `isTooLow` is.
`isHigh`	-	At or above `high`. Warning level. Latches.
`isTooHigh`	-	At or above `tooHigh`. Error level. Latches. Also raises `isHigh`.
`noWarning`	-	Neither warning flag is raised. Starts true.
`noError`	-	Neither error flag is raised. Starts true. Test this one to decide whether to stop.
`isEnabled`	-	Detection is running.
`state`	-	All of the above as a single signal, plus `id`. Subscribe to this instead of seven separate flags when a supervising task needs the whole picture.

Parameters

Path	Unit	Default	Range	Effect
`tooLow`	signal unit	-0.05	unbounded	Lower error level. Trips at or below.
`low`	signal unit	-0.02	unbounded	Lower warning level.
`high`	signal unit	0.02	unbounded	Upper warning level. Trips at or above.
`tooHigh`	signal unit	0.05	unbounded	Upper error level.
`timeWindow`	s	0.0	0 upward	How long the input must stay out of range before the flag latches. At the default of 0 a single sample trips it, so a noisy signal will chatter. Each band times independently.
`enable`	-	true	-	Turns detection on. When off, the flags are held clear.
`autoreset`	-	false	-	Clears the flags every cycle, so they follow the current condition instead of latching. Useful when a supervising task polls faster than the condition changes.
`id`	-	0	0 upward	A number carried inside `state`, so a task receiving several detectors' states can tell them apart.

All are persistent and survive a controller restart. Nothing checks that the four levels are in order — an inverted pair is accepted and is a legitimate way to disable a band. No parameters exist below this block.

Setup

Connect the signal you want to supervise to input.
Set the two error levels first, from what the machine cannot tolerate.
Set the two warning levels inside them, from what you want to know about early.
Leave timeWindow at 0 and watch the machine run normally. If any flag trips, either a level is too tight or the signal is noisy.
Set timeWindow — go to Tuning.
Confirm noError is true during normal operation and goes false when you deliberately push the signal past an error level.
Pulse reset and confirm all four flags clear.

This block only watches a signal and raises flags. It does not move anything and cannot be made to — but whatever acts on noError downstream will act the moment it goes false.

Tuning

Trace input for a full normal cycle of the machine, including startup. Note the largest excursion that is not a fault — startup spikes are the usual culprit.
Set the error levels outside that, with margin.
Set the warning levels where you want to be told early. There is no rule here; halfway between normal and the error level is a reasonable start.
Set timeWindow longer than the longest spike you want to ignore and shorter than the fastest fault you must catch. For a noisy signal this is usually tens of milliseconds.
Re-run and confirm the flags stay clear through the normal cycle.
Push the signal past each level in turn and confirm the right flag latches, after roughly timeWindow.
If you cannot find a timeWindow that ignores the noise and still catches the fault, filter the input upstream instead of widening the levels.
timeWindow is in seconds, so a task-rate change does not move it.

The time window is what separates a spike from an excursion.

Symptom	Cause	Action
A flag trips on noise	`timeWindow` is 0 or too short	Lengthen it, or filter the input
A flag tripped during startup	A startup spike crossed a level	Lengthen `timeWindow`, or hold `disable` true until the machine is running
`isLow` and `isTooLow` are both true	Expected: the bands are nested	Test `isLow` and not `isTooLow` for warning only
A flag will not clear	Expected: the flags latch	Pulse `reset`, or set `autoreset`
The flags clear on their own	`autoreset` is on	Turn it off if you need latching
I wrote `reset` and it went back to false	Expected: the block clears it once you stop writing	Nothing
Nothing is ever detected	`enable` is false, `disable` is true, or the levels are outside anything the signal reaches	Check `isEnabled` first
The flags cleared when I disabled it	Expected: disabling clears them and re-enabling starts clean	Read them before disabling
Everything trips at once and stays tripped	The input is not a valid number	Fix the upstream signal; this is the block telling you so
A flag trips later than `timeWindow`	Expected: the window is rounded up to a whole number of cycles	Nothing
The flags disagree with the levels I set	The levels may be inverted — nothing checks their order	Read all four back
A flag tripped one cycle after I disabled it	Expected: the check runs once more, and the result is then cleared	Nothing
The timers seem stale right after a restart	The flags clear at startup but the timers do not	Pulse `reset` after starting
I need to watch several signals	Not possible — this block is single channel	Use one instance per signal, each with its own `id`

A starting point for a following error in metres:

tooLow     = -0.05
low        = -0.02
high       =  0.02
tooHigh    =  0.05
timeWindow =  0.02
enable     =  true
autoreset  =  false

Those are also the defaults for the four levels, so an unconfigured detector already watches a symmetric band around zero.

Limits and errors

Limit	Set by	What happens	Reported
Warning band	`low`, `high`	Flags latch at or beyond the level, after `timeWindow`	`isLow`, `isHigh`, `noWarning`
Error band	`tooLow`, `tooHigh`	Same, at the outer levels	`isTooLow`, `isTooHigh`, `noError`
Band nesting	Fixed	The bands overlap by design: an error also raises its warning	Not reported
Level ordering	Nothing	Not checked. Inverted levels are accepted and produce overlapping bands	Not reported
Debounce	`timeWindow`	Each band times independently. The window is rounded up to a whole number of cycles	Not reported
Latching	Fixed, unless `autoreset`	Flags stay raised until reset, disabled, or auto-reset	Not reported
Values that are not numbers	Checked	All four flags are raised and both summaries cleared	The flags themselves
Reset	`reset`	Clears the flags and the timers. Clears itself when you stop writing it	Not reported
Disable	`disable`, `enable`	Detection stops and the flags clear. Re-enabling starts clean	`isEnabled`
Startup	Fixed	The flags clear, the timers do not	Not reported
Channel count	Fixed	One signal per instance, always	Not reported

This block logs nothing, ever. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: AverageValueCheck

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

AverageValueCheck measures the true average of a signal over a fixed duration, on demand, and compares that average against four levels.

Use it for a bounded test rather than continuous supervision: sample a pressure for two seconds after a valve closes, or a torque after a move settles, and decide whether the result is acceptable.

flowchart LR
    i1(["input"]) --> B["AverageValueCheck"]
    i2(["activate"]) --> B
    p1(["duration"]) --> B
    p2(["tooLow, low, high, tooHigh"]) --> B
    B --> o1(["average"])
    B --> o2(["sum"])
    B --> o3(["counter"])
    B --> o4(["busy"])
    B --> o5(["isTooLow, isLow, isHigh, isTooHigh"])

The average is exact, not filtered — every sample over the window carries equal weight. sum and counter are published so you can check the arithmetic yourself.

All four levels default to 0. Until you set them, isHigh and isTooHigh are true for any positive average. Set all four before reading any flag.

The result persists after the measurement ends, which is what makes the block useful — but the flags are also computed before any measurement has run, from an average of zero. Read counter alongside them: a counter of 0 means no measurement has happened.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	Sampled once per cycle while the measurement runs. A value that is not a number spoils the whole measurement and makes all four flags read false — see Limits.
`activate`	-	true or false	A rising edge starts a measurement. Holding it true does not start another. The block does not clear it — lower it yourself, or no further measurement can ever be triggered.

Outputs

Path	Unit	Description
`average`	signal unit	The average so far, and the final result once `busy` falls. Readable while the measurement runs. Holds the last result until the next measurement.
`sum`	signal unit	The running total.
`counter`	-	How many samples have been taken. 0 means no measurement has ever run — check this before trusting the flags.
`busy`	-	The measurement is running. Falls when the duration elapses.
`isTooLow`	-	`average` is below `tooLow`. Does not latch — it always describes the current `average`.
`isLow`	-	Below `low`. Also true whenever `isTooLow` is.
`isHigh`	-	Above `high`.
`isTooHigh`	-	Above `tooHigh`. Also raises `isHigh`.

Parameters

Path	Unit	Default	Range	Effect
`duration`	s	1.0	above 0	How long a measurement runs. The number of samples is the duration divided by the task period, rounded up. A value of 0 or below is not rejected: the measurement ends immediately, `counter` and `sum` read 0, and `average` keeps its previous value.
`tooLow`	signal unit	0.0	unbounded	Lower error level.
`low`	signal unit	0.0	unbounded	Lower warning level.
`high`	signal unit	0.0	unbounded	Upper warning level.
`tooHigh`	signal unit	0.0	unbounded	Upper error level.

All are persistent and survive a controller restart. Nothing checks that the four levels are in order. No parameters exist below this block.

The bands are nested: with the intended ordering, an error also raises its warning. For “warning but not error”, test isLow and not isTooLow.

Setup

Connect the signal you want to measure to input.
Set duration to how long you want to sample for.
Set all four levels. They default to 0, and until you set them the flags are meaningless.
Bring the machine to the state you want to measure.
Raise activate from false to true and confirm busy goes true.
Lower activate again. The block will not clear it for you, and a second measurement needs a fresh rising edge.
Wait for busy to fall, then read average and counter. Confirm counter matches the duration divided by your task period.

This block only measures and compares. It does not move anything and cannot be made to.

Tuning

Set duration from the physics, not from convenience. It must be long enough to average out the noise and short enough that the quantity has not changed by the end.
Trigger a measurement with the machine in a known-good state and record the average. Repeat it a few times to see the spread between runs.
Set the error levels outside that spread, with margin.
Set the warning levels inside them, where you want to be told early.
Trigger with the machine in a known-bad state and confirm the right flags come up.
If the spread between runs is too wide to place levels, lengthen duration — the spread falls roughly with the square root of the sample count.
Watch average while a measurement runs to see how quickly it settles. If it is still moving at the end, duration is too short.
duration is in seconds, so a task-rate change does not move it — but counter will change, because the sample count depends on the rate.

The average is readable while the measurement runs. Only the value once busy falls is the result.

Symptom	Cause	Action
The flags are set and nothing has been measured	The levels default to 0, and the flags describe an average of 0	Check `counter` — 0 means no measurement. Set the four levels
A second measurement never started	`activate` is still true; the trigger is a rising edge	Lower `activate` before raising it again
`counter` reads 0 after triggering	`duration` is 0 or negative	Set it above 0
`average` looks stale and `counter` is 0	Same cause: the measurement ended immediately and left the old result	Set `duration` above 0
`average` is still moving when `busy` falls	`duration` is too short for the signal	Lengthen it
Results vary a lot between runs	The window is too short to average out the noise	Lengthen `duration`
`isLow` and `isTooLow` are both true	Expected: the bands are nested	Test `isLow` and not `isTooLow`
The flags cleared by themselves	Expected: they do not latch, they follow `average`	Use `WindowDetector` if you need latching
All four flags are false and the reading looks wrong	A sample that was not a valid number spoiled the measurement	Fix the upstream signal; check `average`
A measurement carried on after a restart	The block does not clear its state at startup	Trigger a fresh measurement after every start
`counter` changed after a task-rate change	Expected: the sample count depends on the rate, the duration does not	Nothing
I need continuous supervision, not a one-shot test	Wrong block	Use `WindowDetector`
I need a continuously updating average	Wrong block	Use `MovingAverageFilter`
I need to suspend it	Not possible — there is no enable	Leave `activate` low
I need to measure several signals	Not possible — this block is single channel	Use one instance per signal

A starting point for a settled-torque check:

duration = 2.0
tooLow   = -5.0
low      = -2.0
high     =  2.0
tooHigh  =  5.0

Limits and errors

Limit	Set by	What happens	Reported
Measurement window	`duration`	Runs for that long, then stops on its own	`busy`, `counter`
`duration` at 0 or below	Nothing	Not checked. The measurement ends immediately, `counter` and `sum` read 0, and `average` keeps its previous value	`counter` reads 0
Trigger	`activate`	Rising edge only. The block never clears it, so a stuck-true input prevents all further measurements	`busy`
Averaging	Fixed	The exact arithmetic mean, every sample weighted equally	`sum`, `counter`
Level ordering	Nothing	Not checked. The bands are nested by design	Not reported
Level defaults	Fixed at 0	Every flag is meaningful from startup, describing an average of zero	`counter` reads 0
Flag latching	Fixed	The flags do not latch — they always describe the current `average`	Not reported
Values that are not numbers	Nothing	Not checked. One bad sample spoils the whole average, and all four flags then read false — a broken sensor reads as acceptable	`average`
Startup	Fixed	No state is cleared. A measurement interrupted by a restart resumes and keeps accumulating into the same total	`busy`, `counter`
Enable	None	There is no enable, disable or isEnabled	Not applicable
Channel count	Fixed	One signal per instance, always	Not reported

This block logs nothing, ever. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: HomingSwitch

Mon, 01 Jan 0001 00:00:00 +0000

Control3 3.30–3.34

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

Wire your home switch, or whichever signal marks the reference, to triggerSignal1. Leave the other two at 0.
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.
Set trigger1Detector/timeWindow to a few milliseconds so contact bounce does not trigger.
Verify the trigger works before enabling any motion. With homingVelocity still at 0, operate the switch by hand and watch trigger1Detector/noError go false.
Set homingMethod to 2 and homingVelocity to a slow speed — a tenth of what you eventually want.
Set homingVelocityFader/fadeTime to a few hundred milliseconds.
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.
Confirm the axis stops when the switch is made, isHomed goes true, and homingState returns to 1.
Pulse reset before running again.

Tuning

Get the trigger detection right first. Everything else depends on it, and it is the only thing preventing a runaway.
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.
Measure that overtravel: home several times and compare the final output. The spread is your homing repeatability.
Shorten homingVelocityFader/fadeTime to reduce overtravel, or lower homingVelocity. Lowering the speed usually helps repeatability more.
Use method 4 for the best repeatability: backing off the switch first means every run approaches from the same side at the same speed.
Set pullBackOffset to retract clear of the switch after homing, so the axis does not sit on it.
Set homingSwitch/fadeOutTime so control returns to the nominal setpoint smoothly after the run.
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).