WindowDetector

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

Outputs

Parameters

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

1. Connect the signal you want to supervise to input.
2. Set the two error levels first, from what the machine cannot tolerate.
3. Set the two warning levels inside them, from what you want to know about early.
4. 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.
5. Set timeWindow — go to Tuning.
6. Confirm noError is true during normal operation and goes false when you deliberately push the signal past an error level.
7. 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

1. 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.
2. Set the error levels outside that, with margin.
3. 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.
4. 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.
5. Re-run and confirm the flags stay clear through the normal cycle.
6. Push the signal past each level in turn and confirm the right flag latches, after roughly timeWindow.
7. If you cannot find a timeWindow that ignores the noise and still catches the fault, filter the input upstream instead of widening the levels.
8. timeWindow is in seconds, so a task-rate change does not move it.

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

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

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