– Filters

Docs: LowPass1

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

Control3 3.30–3.34

LowPass1 smooths a noisy signal before a controller consumes it. One cut-off frequency governs every channel, and the channel count is fixed by the machine configuration. It also publishes the rate of change of its own smoothed output, so you never have to differentiate output yourself.

flowchart LR
    i1(["input — signal to smooth"]) --> B["LowPass1"]
    i2(["disable"]) --> B
    B --> o1(["output — smoothed signal"])
    B --> o2(["outputDot — rate of the smoothed signal"])
    B --> o3(["isEnabled"])

$f_c = \omega/2\pi$ — omega 6.283 rad/s is a 1 Hz cut-off. Time constant $\tau = 1/\omega$ [s]: 63% of a step in $\tau$, 90% in $2.3,\tau$, 99% in $4.6,\tau$. At the cut-off: gain 0.71, lag 45°, which is a delay of $0.125/f_c$ [s]. Below the cut-off the delay is $\tau$. That delay is the whole trade of this block.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to smooth. One element per channel; the channel count is fixed by the machine configuration.
`disable`	-	-	True bypasses the filter: `input` passes straight to `output`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit	The smoothed signal, one element per channel. Equals `input` exactly while bypassed. Starts from zero after every controller start, and is not cleared by a stop.
`outputDot`	signal unit per second	The rate of change of `output`, one element per channel. While bypassed this becomes the raw sample-to-sample difference of `input` divided by the task period — see the symptom table.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block, not one per channel.

Parameters

Path	Unit	Default	Range	Effect
`omega`	rad/s	6.283 (1 Hz)	0.1 – 0.628/task period [s]	Cut-off, shared by all channels. Lower removes more noise and adds more delay. Out-of-range values are corrected silently — see Limits and errors.
`enable`	-	true	-	False bypasses the filter: `input` passes through unchanged.

omega and enable are persistent — both survive a controller restart. The inputs and outputs do not; input and disable return to their linked sources and output starts from zero. No parameters exist below this block.

Setup

Link the source signal: …/actuator/actualVelocity → …/velocityFilter/input. input follows the source on a trace.
Set enable false. output equals input sample for sample and isEnabled reads false.
Set omega to 300. Read it back; a lower value means your task rate capped it, and tells you the highest cut-off this task rate allows.
Set enable true. isEnabled reads true and output still tracks input closely, with the noise still visible.
Halve omega in steps, watching the noise and the loop consuming it. Stop one step above where that loop feels soft or hunts.

Step 5 changes what the controller sees. Lower the cut-off with the axis at rest before trying it in motion — the added delay can destabilise a tightly tuned loop.
Trace every element of input and output. An element that reads zero while the machine moves is an unwired channel, not a filtered one.

Tuning

Read the frequency of the ripple you want gone, in Hz, off a trace of input. Set omega to $2\pi$ times that frequency as a starting point, then lower it until the ripple is gone.
Measure the delay you have bought. Step the source and read the time output takes to cross 63% of the step; that time is $\tau$, and the delay below the cut-off equals it.
Keep that delay below a tenth of the response time of the loop consuming output. Above that, the loop pays for the smoothing in stability.
Check the loop in motion, not at rest. Delay costs phase margin only while the axis is moving fast enough to need it.
Re-check omega after any task-rate change. The upper bound scales with the task period, so a slower task can clamp a cut-off that used to be accepted.
If you need the noise gone and the delay, fix the noise at its source — shielding, grounding, or a higher-resolution sensor. No cut-off gives you both.

Read the time constant off any curve as the moment it crosses 0.63.

Symptom	Cause	Action
Noise still present on `output`	Cut-off too high	Halve `omega`, then re-check the loop for softness
Loop went soft, hunts or oscillates after enabling	Delay too high for the loop	Double `omega`; if the noise returns, fix it at the source
Setpoint tracking lags behind the command	The block is in the command path, not the feedback path	Raise `omega`, or move the filter onto the measurement only
`omega` reads back lower than written	Outside the accepted band for this task rate	Raise the task rate or accept the cap
`omega` reads back as 0.1	Written below the fixed lower bound	Write 0.1 or more; a slower filter is not available
`omega` used to be accepted and now clamps	The task period grew, so the upper bound fell	Raise `omega`’s task rate back, or lower `omega`
`output` ramps from zero for a second after every start	Expected: the filter starts from zero	Gate the consumer off `isEnabled` plus a short delay
`output` stays at zero while the signal moves	Channel unwired — an unwired element reads zero	Trace `input` element by element and link every one
`outputDot` shows one large spike the moment the filter is bypassed	Expected: while bypassed, `outputDot` is a raw difference over one task period	Gate any consumer of `outputDot` on `isEnabled`
`output` follows `input` exactly, with no smoothing at all	`enable` is false, or `disable` is true	Read `isEnabled`; it tells you which of the two is holding the bypass
Some channels smooth more than others	Not possible — all channels share one `omega`	Use a separate filter per channel group
`output` went to a non-numeric value and stays there	A non-numeric value reached `input` or `omega`	Fix the source; the block cannot recover its own state, so restart the controller

A conservative starting point for a velocity signal on a 1 ms task, feeding a position loop with a 100 ms response time:

omega  = 60.0
enable = true

This is a starting point, not a final tuning. Work step 1 with a trace of your own signal.

Limits and errors

Limit	Set by	What happens	Reported
`omega` ≥ 0.1 rad/s	Fixed	A slower value is replaced by 0.1 rad/s	Silently; read `omega` back
`omega` ≤ 0.628 / task period [s]	Task rate — 628 rad/s on a 1 ms task, 62.8 rad/s on a 10 ms task	A faster value is replaced by the edge. This is what keeps the filter stable at any setting	Silently; read `omega` back
`output`	Nothing	Unbounded — whatever the input carries reaches the output. Limit it downstream if the consumer needs a bound	Not reported
`outputDot`	Nothing	Unbounded, and largest on the cycle the bypass engages	Not reported
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: LowPass2

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

Control3 3.30–3.34

LowPass2 smooths a noisy signal with a second-order filter: twice the roll-off of a first-order filter, and a damping setting that decides whether the output overshoots. One cut-off and one damping govern every channel. It publishes the whole derivative stack — value, velocity, acceleration and jerk — so a setpoint path can take all four from one block.

flowchart LR
    i1(["input — signal to smooth"]) --> B["LowPass2"]
    i2(["disable"]) --> B
    i3(["vaLimiterDisable"]) --> B
    B --> o1(["output — smoothed signal"])
    B --> o2(["outputDot — velocity of the output"])
    B --> o3(["outputDDot — acceleration of the output"])
    B --> o4(["outputDDDot — jerk of the output"])
    B --> o5(["isEnabled"])
    B --> o6(["vaLimiterIsEnabled"])

$f_c = \omega/2\pi$ — omega 6.283 rad/s is a 1 Hz cut-off. beta is the damping ratio: overshoot is $e^{-\pi\beta/\sqrt{1-\beta^2}}$, so 37% at beta 0.3, 16% at 0.5, and none at 1.0 or above. Ringing frequency is $\omega\sqrt{1-\beta^2}$ [rad/s]. At the cut-off the gain is $1/(2\beta)$ — above 1 for any beta below 0.5, so a low damping amplifies rather than removes. Phase lag at the cut-off is 90°, twice a first-order filter’s, and that lag is the trade.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to smooth. One element per channel; the channel count is fixed by the machine configuration.
`disable`	-	-	True bypasses the filter: `input` passes straight to `output`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.
`vaLimiterDisable`	-	-	True switches the velocity and acceleration limiter off, leaving the filter itself running. Use it for a runtime override; use `vaLimiterEnable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit	The smoothed signal, one element per channel. Equals `input` exactly while bypassed. Starts from zero after every controller start, and is not cleared by a stop.
`outputDot`	signal unit per second	Velocity of `output`. While the filter runs this is integrated, not differenced, so it is as smooth as `output`. While bypassed it becomes a raw difference over one task period.
`outputDDot`	signal unit per second²	Acceleration of `output`, and the quantity the limiter acts on. While bypassed it becomes a raw difference of `outputDot`.
`outputDDDot`	signal unit per second³	Jerk of `output`. Always a raw difference, so it is by far the noisiest output and lags the others by one task period. Treat it as diagnostic, not as a control signal.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block, not one per channel.
`vaLimiterIsEnabled`	-	True when `vaLimiterEnable` is true and `vaLimiterDisable` is false. It does not tell you the limiter is currently cutting, only that it is switched on.

Parameters

Path	Unit	Default	Range	Effect
`omega`	rad/s	6.283 (1 Hz)	0.1 – 0.628/task period [s]	Cut-off, shared by all channels. Lower removes more noise and adds more delay. Out-of-range values are corrected silently — see Limits and errors.
`beta`	-	1.0	0.1 – 10	Damping ratio, shared by all channels. Below 1 the output overshoots and rings; below 0.5 it amplifies at the cut-off. Above 1 it is slower and never overshoots. Out-of-range values are corrected silently.
`vaLimiterMaxAcc`	signal unit per second²	1.0	must be positive	Largest acceleration the limiter allows. Not validated — see Limits and errors. Only has effect while `vaLimiterIsEnabled` is true.
`vaLimiterMaxVel`	signal unit per second	1.0	must be positive	Largest velocity the limiter allows. Where this and `vaLimiterMaxAcc` conflict, the velocity bound wins. Not validated. Only has effect while `vaLimiterIsEnabled` is true.
`enable`	-	true	-	False bypasses the filter: `input` passes through unchanged.
`vaLimiterEnable`	-	false	-	True switches on the velocity and acceleration limiter. Set both bounds to real machine values before you turn this on.

All six parameters are persistent and survive a controller restart. The inputs and outputs do not; output starts from zero. No parameters exist below this block.

Setup

Link the source signal: …/actuator/actualPosition → …/positionFilter/input. input follows the source on a trace.
Set enable false. output equals input sample for sample and isEnabled reads false.
Leave vaLimiterEnable false for the whole of setup. The limiter’s default bounds of 1.0 will throttle any real machine signal.
Set omega to 300 and beta to 1.0. Read omega back; a lower value means your task rate capped it, and tells you the highest cut-off this task rate allows.
Set enable true. isEnabled reads true and output still tracks input closely, with the noise still visible.
Halve omega in steps, watching the noise and the loop consuming it. Stop one step above where that loop feels soft or hunts.

Step 6 changes what the controller sees. A second-order filter costs twice the phase lag of a first-order one at the same cut-off. Lower the cut-off with the axis at rest before trying it in motion.
Trace every element of input and output. An element that reads zero while the machine moves is an unwired channel, not a filtered one.
Only if you want the block to shape motion as well as smooth it: set vaLimiterMaxAcc and vaLimiterMaxVel to your machine’s real bounds, then set vaLimiterEnable true and confirm vaLimiterIsEnabled reads true.

Tuning

Read the frequency of the ripple you want gone, in Hz, off a trace of input. Set omega to $2\pi$ times that frequency, then lower it until the ripple is gone.
Leave beta at 1.0 while you find omega. Damping and cut-off interact, and 1.0 is the setting with no overshoot.
Step the source and measure the overshoot on output. If you want a faster response and can accept overshoot, lower beta toward 0.5. Never go below 0.5 unless you intend a resonant peak — below it the filter amplifies at the cut-off instead of cutting.
Measure the delay you have bought. Step the source and read the time output takes to reach 90% of the step. Keep it below a tenth of the response time of the loop consuming output.
Check the loop in motion, not at rest. Delay costs phase margin only while the axis moves fast enough to need it.
Re-check omega after any task-rate change. The upper bound scales with the task period, so a slower task can clamp a cut-off that used to be accepted.
If you are using outputDDot or outputDDDot, look at them on a trace before you rely on them. Each derivative multiplies the remaining noise, and jerk is differenced rather than filtered.

Read the overshoot off any curve as its highest point above 1.0.

Symptom	Cause	Action
Noise still present on `output`	Cut-off too high	Halve `omega`, then re-check the loop for softness
`output` overshoots the step and rings	`beta` below 1	Raise `beta` toward 1.0; ringing stops entirely at 1.0
Noise at the cut-off got worse after enabling	`beta` below 0.5, so the filter has a resonant peak	Raise `beta` to 1.0
`output` reaches its target far too slowly	`beta` well above 1, or `omega` too low	Lower `beta` toward 1.0 first, then raise `omega`
Loop went soft, hunts or oscillates after enabling	Delay too high — a second-order filter costs twice the lag	Double `omega`, or use a first-order filter instead
`omega` or `beta` reads back different from what you wrote	Outside the accepted band	Read the value back and work within it; the task rate sets `omega`’s upper bound
`omega` used to be accepted and now clamps	The task period grew, so the upper bound fell	Raise the task rate back, or lower `omega`
The axis crawls the moment `vaLimiterEnable` goes true	The limiter’s default bounds are 1.0, not machine values	Set `vaLimiterMaxAcc` and `vaLimiterMaxVel` first, then re-enable
Motion is clipped and you cannot tell whether the limiter did it	Expected: no output reports the limiter cutting	Set `vaLimiterEnable` false and compare; that is the only way to tell
The axis runs away in one direction with the limiter on	A negative or zero value in `vaLimiterMaxAcc`	Write a positive value; negatives are accepted and are unsafe
`output` ramps from zero for a second after every start	Expected: the filter starts from zero	Gate the consumer off `isEnabled` plus a short delay
`output` stays at zero while the signal moves	Channel unwired — an unwired element reads zero	Trace `input` element by element and link every one
One large spike on `outputDot`, `outputDDot` and `outputDDDot` the moment the filter is bypassed	Expected: while bypassed the derivatives are raw differences over one task period	Gate every consumer of the derivative stack on `isEnabled`
A brief ring on `output` after re-enabling the filter	Expected: the filter resumes with the velocity it measured while bypassed	Re-enable while the axis is at rest, or accept a settle of about $1/(\beta\omega)$ seconds
`outputDDDot` is unusably noisy	Expected: jerk is differenced, not filtered	Use it for diagnosis only; filter it downstream if a consumer needs it
Some channels smooth more than others	Not possible — all channels share one `omega` and one `beta`	Use a separate filter per channel group
`output` went to a non-numeric value and stays there	A non-numeric value reached `input`, `omega` or `beta`	Fix the source; the block cannot recover its own state, so restart the controller

A conservative starting point for a position signal on a 1 ms task, feeding a loop with a 100 ms response time, with the limiter off:

omega            = 60.0
beta             = 1.0
vaLimiterEnable  = false

This is a starting point, not a final tuning. Work step 1 with a trace of your own signal.

Limits and errors

Limit	Set by	What happens	Reported
`omega` ≥ 0.1 rad/s	Fixed	A slower value is replaced by 0.1 rad/s	Silently; read `omega` back
`omega` ≤ 0.628 / task period [s]	Task rate — 628 rad/s on a 1 ms task, 62.8 rad/s on a 10 ms task	A faster value is replaced by the edge. This is what keeps the filter stable at any setting	Silently; read `omega` back
`beta` within 0.1 – 10	Fixed	A value outside the band is replaced by the nearest edge	Silently; read `beta` back
`vaLimiterMaxAcc`, `vaLimiterMaxVel`	Nothing	Not checked. Zero and negative values are accepted, and a negative acceleration bound drives the output away in one direction until something else stops it	Not reported
`output`	Nothing while the limiter is off; `vaLimiterMaxVel` and `vaLimiterMaxAcc` shape it while the limiter is on	Unbounded in position either way — the limiter bounds rate, not travel. Limit position downstream if the consumer needs a bound	Not reported
`outputDot`, `outputDDot`, `outputDDDot`	Nothing	Unbounded, and largest on the cycle the bypass engages	Not reported
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: HighPass1

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

Control3 3.30–3.34

HighPass1 removes the slow content of a signal and keeps the fast — sensor drift, a thermal offset, a load cell’s zero error. One cut-off frequency governs every channel, and the channel count is fixed by the machine configuration. Its steady output for a constant input is zero, not the input: this block deletes the part of the signal that does not change.

flowchart LR
    i1(["input — signal to wash out"]) --> B["HighPass1"]
    i2(["disable"]) --> B
    B --> o1(["output — fast content of the input"])
    B --> o2(["isEnabled"])

$f_c = \omega/2\pi$ — omega 6.283 rad/s is a 1 Hz cut-off. Time constant $\tau = 1/\omega$ [s]: a step appears in full, then decays to 37% in $\tau$ and to 1% in $4.6,\tau$. At the cut-off: gain 0.71 and 45° of phase lead. Signals slower than the cut-off are removed; signals faster pass at gain 1. Choosing omega is choosing how slow “slow” means.

This block has no derivative output and no reset input. It also cannot be bypassed without restoring the offset it was removing — see the symptom table.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to wash out. One element per channel; the channel count is fixed by the machine configuration.
`disable`	-	-	True bypasses the filter: `input` passes straight to `output`, offset included. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit	The fast content of `input`, one element per channel. Settles to zero for any constant input. Equals `input` exactly while bypassed. Starts from the full value of `input` after every controller start, then washes out over $\tau$.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block, not one per channel.

Parameters

Path	Unit	Default	Range	Effect
`omega`	rad/s	6.283 (1 Hz)	0.1 – 0.628/task period [s]	Cut-off, shared by all channels. Lower keeps more of the slow content and takes longer to wash a step out. Higher removes more, and starts eating the signal you wanted to keep. Out-of-range values are corrected silently — see Limits and errors.
`enable`	-	true	-	False bypasses the filter: `input` passes through unchanged, offset included.

Both parameters are persistent and survive a controller restart. The inputs and outputs do not. No parameters exist below this block.

Setup

Link the source signal: …/sensor/rawForce → …/forceWashout/input. input follows the source on a trace.
Set enable false. output equals input sample for sample and isEnabled reads false.
Set omega to 300. Read it back; a lower value means your task rate capped it, and tells you the highest cut-off this task rate allows.
Hold the machine still and note the constant value input sits at. That offset is what the block is going to remove.
Set enable true. output starts at the full value of input, then decays toward zero. Time that decay — it reaches 37% of the way at $\tau$.

Step 5 injects the whole offset into whatever consumes output. The filter starts from a clean state, so its first sample is the input in full. Enable it with the machine at rest and the consumer gated off.
Hold the machine still again. output should sit at zero, not at the offset from step 4. If it does not, the cut-off is too low for the drift you have.
Trace every element of input and output. An element that reads zero while the machine moves is an unwired channel, not a washed-out one.

Tuning

Decide the slowest signal you want to keep, in Hz. Set omega to $2\pi$ times that frequency; everything slower than it will be removed.
Measure the drift you want gone. Read how long the offset takes to build on a trace, in seconds; omega must be at least a few times $1/$that.
Check the two against each other. If the drift builds as fast as the signal you want to keep, no cut-off separates them and this block cannot help.
Step the machine and read the decay off output. The time to 37% is $\tau$, and $\tau$ is how long a genuine step survives before the filter eats it.
Confirm the steady state with the machine at rest: output at zero, not at an offset.
Re-check omega after any task-rate change. The upper bound scales with the task period, so a slower task can clamp a cut-off that used to be accepted.

Read the time constant off any curve as the moment it crosses 0.37.

Symptom	Cause	Action
`output` sits at zero while `input` clearly has a value	Expected: a constant input has no fast content, so there is nothing to pass	Confirm with a moving signal; if that also reads zero, the channel is unwired
The offset is still on `output` at rest	Cut-off too low for the drift	Raise `omega`; if the drift is as fast as your signal, this block cannot separate them
A genuine slow movement got deleted	Cut-off too high — the block cannot tell drift from slow signal	Lower `omega`, and accept that some drift stays
`output` jumps to the full input value the moment the filter is enabled	Expected: the block starts from a clean state, so the offset appears once and washes out over $\tau$	Enable at rest, or gate the consumer off `isEnabled` plus a few $\tau$
The same jump every time `disable` is toggled off	Expected: the same reason — the state is cleared while bypassed	Do not toggle the bypass during operation; leave `enable` set and use it as configuration
Bypassing the filter put a large offset back on `output`	Expected: bypass restores the input in full, including the DC the filter was removing	Bypass only when the consumer can accept the raw signal
`output` overshoots the other way after a step	Expected: the block removes the step’s steady part, so the output must return through zero	None; this is what a washout does
`omega` reads back lower than written	Outside the accepted band for this task rate	Raise the task rate or accept the cap
`omega` reads back as 0.1	Written below the fixed lower bound	Write 0.1 or more; a slower washout is not available
`omega` used to be accepted and now clamps	The task period grew, so the upper bound fell	Raise the task rate back, or lower `omega`
You need the rate of the washed-out signal	The block publishes no derivative	Differentiate downstream, or filter first and difference after
Some channels wash out faster than others	Not possible — all channels share one `omega`	Use a separate filter per channel group
`output` went to a non-numeric value and stays there	A non-numeric value reached `input` or `omega`	Fix the source, then bypass the filter for one cycle — that clears its state

A conservative starting point for washing thermal drift off a force signal on a 1 ms task, keeping everything above about 0.5 Hz:

omega  = 3.14
enable = true

This is a starting point, not a final tuning. Work steps 1 to 3 with a trace of your own signal.

Limits and errors

Limit	Set by	What happens	Reported
`omega` ≥ 0.1 rad/s	Fixed	A slower value is replaced by 0.1 rad/s	Silently; read `omega` back
`omega` ≤ 0.628 / task period [s]	Task rate — 628 rad/s on a 1 ms task, 62.8 rad/s on a 10 ms task	A faster value is replaced by the edge. This is what keeps the filter stable at any setting	Silently; read `omega` back
`output`	Nothing	Unbounded — a fast input reaches the output at full size. Limit it downstream if the consumer needs a bound	Not reported
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: HighPass2

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

Control3 3.30–3.34

HighPass2 is the second-order washout filter. Feed it an acceleration and it removes the sustained part — the part a platform cannot reproduce without running out of travel — and returns the transient part, plus the velocity and position that follow from it. The three outputs are three different filters, not three views of one: output keeps the fast content, outputInt keeps only content near the cut-off, and outputIInt keeps the slow content.

flowchart LR
    i1(["input — acceleration to wash out"]) --> B["HighPass2"]
    i2(["disable"]) --> B
    B --> o1(["outputIInt — position, slow content only"])
    B --> o2(["outputInt — velocity, cut-off content only"])
    B --> o3(["output — acceleration, fast content only"])
    B --> o4(["isEnabled"])

$f_c = \omega/2\pi$ — omega 6.283 rad/s is a 1 Hz cut-off. beta is the damping ratio: 1.0 gives one small undershoot, below 1.0 the outputs ring at $\omega\sqrt{1-\beta^2}$ [rad/s]. output settles to zero for any constant input. outputInt peaks at the cut-off with gain $1/(2\beta\omega)$. outputIInt settles to $1/\omega^2$ times a constant input — a factor of 0.025 at the default, so do not expect it to match the input’s magnitude.

Leave this block enabled. Disabling it does not idle it: output drops to zero rather than passing the input through, and outputIInt drifts. It also has no reset input — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	m/s² for a washout, or any signal unit	unbounded	The signal to wash out, normally an acceleration. One element per channel; the channel count is fixed by the machine configuration.
`disable`	-	-	True forces `output` to zero and leaves the other two outputs coasting. It is not a bypass and does not pass `input` through. Use `enable` for the configured intent, and read the note above before using either.

Outputs

Path	Unit	Description
`outputIInt`	m for a washout, or input unit × s²	Position. Keeps the slow content of `input` and settles to $1/\omega^2$ times a constant input. The smoothest of the three. Starts from zero after every controller start, and is never cleared once running.
`outputInt`	m/s for a washout, or input unit × s	Velocity. Keeps only content near the cut-off, and settles to zero for both a constant input and a very fast one. Starts from zero after every controller start.
`output`	m/s² for a washout, or the input unit	Acceleration. Keeps the fast content and settles to zero for a constant input. It is not smoothed — noise on `input` reaches it at full size and undelayed. Zero while `disable` is true or `enable` is false.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block, not one per channel.

Parameters

Path	Unit	Default	Range	Effect
`omega`	rad/s	6.283 (1 Hz)	0.1 – 0.628/task period [s]	Cut-off, shared by all channels. Lower keeps more of the sustained content and washes it out more slowly, so the platform travels further. Higher washes out sooner and the motion feels thinner. Out-of-range values are corrected silently — see Limits and errors.
`beta`	-	1.0	0.1 – 2	Damping ratio, shared by all channels. 1.0 gives one small undershoot and no ringing. Below 1.0 the outputs ring, badly below 0.5. Above 1.0 the washout is slower and gentler. Out-of-range values are corrected silently.
`enable`	-	true	-	False forces `output` to zero. It does not bypass the block. See the note under the diagram.

All three parameters are persistent and survive a controller restart. The inputs and outputs do not; all three outputs start from zero. No parameters exist below this block.

Setup

Link the source signal: …/model/commandedAcceleration → …/washout/input. input follows the source on a trace.
Leave enable true for the whole of setup. There is no useful idle state, and the outputs are already zero before any input arrives.
Set omega to 6.283 and beta to 1.0. Read omega back; a lower value means your task rate capped it.
Decide which output your consumer needs, and wire only that one. A platform position command takes outputIInt; a velocity feedforward takes outputInt; an accelerometer-matching path takes output.
Apply a sustained acceleration on input and hold it. output must return to zero, and outputIInt must settle to a constant, not keep climbing.

Step 5 is the check that the washout works. If outputIInt keeps climbing while input is held constant, stop and fix that before you connect a platform — it will run to its travel limit.
Read the settled value of outputIInt and divide it by the input you applied. It should be close to $1/\omega^2$. This confirms the scaling you have to compensate downstream.
Trace every element of input and each output you use. An element that reads zero while the machine moves is an unwired channel.

Tuning

Measure your consumer’s travel budget first, in metres. That budget, not the feel of the motion, sets the lowest omega you can use.
Apply the largest sustained acceleration your application produces and read the peak of outputIInt. Raise omega until that peak fits the budget with margin.
Leave beta at 1.0 while you find omega. Damping and cut-off interact, and 1.0 is the setting with almost no undershoot.
Step the input and watch output return through zero. The undershoot is the platform being pulled back to centre; it is unavoidable in a washout.
If that return is too abrupt, raise beta toward 2.0. If the motion feels dead, lower beta toward 0.7 — but never below 0.5 unless you intend ringing.
Re-check the travel budget after every beta change. Damping changes the peak excursion as well as its shape.
Re-check omega after any task-rate change. The upper bound scales with the task period, so a slower task can clamp a cut-off that used to be accepted.
Look at output on a trace before relying on it. It is unsmoothed, so it carries whatever noise input carries.

Read the pull-back off any curve as its lowest point below zero.

Symptom	Cause	Action
`outputIInt` is far smaller than the input	Expected: its steady gain is $1/\omega^2$, which is 0.025 at the default cut-off	Scale it downstream; there is no gain parameter in this block
`outputIInt` keeps climbing while `input` is held constant	The block is not running the washout — check `isEnabled` reads true	Set `enable` true and `disable` false; a disabled block coasts instead of washing out
`outputIInt` reached the platform’s travel limit	Cut-off too low for the accelerations you are feeding it	Raise `omega` and re-check step 2 of Tuning
`output` is noisy	Expected: `output` is not smoothed, unlike the two integrals	Filter `input` upstream, or take `outputInt` instead
`output` sits at zero while `input` clearly has a value	Expected for a constant input, since a constant has no fast content. Otherwise `enable` is false	Read `isEnabled`; if it is true, this is normal washout behaviour
All three outputs ring after a step	`beta` below 1	Raise `beta` toward 1.0; ringing stops almost entirely at 1.0
The motion pulls back too hard after a step	Damping too low for the feel you want	Raise `beta` toward 2.0, then re-check the travel budget
The motion feels dead and thin	Cut-off too high — the sustained content is being removed too soon	Lower `omega`, within the travel budget
`omega` or `beta` reads back different from what you wrote	Outside the accepted band	Read the value back and work within it; the task rate sets `omega`’s upper bound
`omega` used to be accepted and now clamps	The task period grew, so the upper bound fell	Raise the task rate back, or lower `omega`
`outputIInt` sits at a large offset and will not return, even with `input` at zero	The block’s state is off-centre and it has no reset	Restart the controller. Nothing in the parameter tree can clear it
`outputIInt` drifted while the block was disabled	Expected: a disabled block holds its velocity and keeps integrating it	Leave the block enabled; restart the controller to clear the drift
Some channels wash out faster than others	Not possible — all channels share one `omega` and one `beta`	Use a separate washout per channel group
An output went to a non-numeric value and stays there	A non-numeric value reached `input`, `omega` or `beta`	Fix the source, then restart the controller. Disabling the block does not clear it

A conservative starting point for a motion-platform washout on a 1 ms task, with a generous travel budget:

omega  = 6.283
beta   = 1.0
enable = true

This is a starting point, not a final tuning. Work steps 1 and 2 with your own travel budget.

Limits and errors

Limit	Set by	What happens	Reported
`omega` ≥ 0.1 rad/s	Fixed	A slower value is replaced by 0.1 rad/s	Silently; read `omega` back
`omega` ≤ 0.628 / task period [s]	Task rate — 628 rad/s on a 1 ms task, 62.8 rad/s on a 10 ms task	A faster value is replaced by the edge. This is what keeps the filter stable at any setting	Silently; read `omega` back
`beta` within 0.1 – 2	Fixed	A value outside the band is replaced by the nearest edge. Note the upper bound is 2, lower than the second-order low-pass filter’s	Silently; read `beta` back
`outputIInt`, `outputInt`, `output`	Nothing	Unbounded. `outputIInt` in particular has no travel limit of its own — bound it downstream before it reaches a platform	Not reported
Block state	Nothing	There is no reset input and no way to clear the outputs in service. Once `outputIInt` is off-centre, only a controller restart returns it to zero	Not reported
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: BandPass1

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

Control3 3.30–3.34

BandPass1 passes a band of frequencies and rejects everything slower and everything faster. The band is set by two independent cut-offs rather than by a centre frequency, so you set its low edge and its high edge separately. Unlike the other filters here, its passband gain is not 1 — the output is scaled by omegaHighPass, so moving the low edge of the band also rescales the output.

flowchart LR
    i1(["input — signal to filter"]) --> B["BandPass1"]
    i2(["disable"]) --> B
    i3(["reset"]) --> B
    B --> o1(["output — content inside the band"])
    B --> o2(["outputDot — rate inside the band"])
    B --> o3(["isEnabled"])

$f = \omega/2\pi$ — omegaHighPass 1 rad/s is a 0.16 Hz low edge, omegaLowPass 10 rad/s a 1.6 Hz high edge. Passband gain is omegaHighPass itself, so the defaults happen to give gain 1. The peak is $-0.8$ dB at the defaults, not 0 dB, because a decade of separation is not wide enough for the two edges to stop interacting. Keep both cut-offs below 0.628/task period [s]; nothing in the block enforces that for you.

A channel whose input is exactly zero is reset to zero and stays there until the input moves off zero. This block also has no automatic stability limit — see Limits and errors before you write either cut-off.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded, but exactly 0.0 triggers a reset	The signal to filter. One element per channel; the channel count is fixed by the machine configuration. This path is treated as configuration rather than as a link target, so it survives a restart with whatever value it last held.
`disable`	-	-	True bypasses the filter: `input` passes straight to `output`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.
`reset`	-	-	A rising value clears `output` and `input` to zero for every channel, once. It clears only part of the filter’s memory, so the output can move again immediately. Ignored while the block is bypassed, and consumed even then.

Outputs

Path	Unit	Description
`output`	signal unit × `omegaHighPass`	The content of `input` inside the band, one element per channel. Equals `input` exactly while bypassed. Starts from zero after every controller start. This path is writable and survives a restart, but the block overwrites it on the next cycle it runs.
`outputDot`	signal unit per second	The rate of the filtered signal. It matches the rate of `output` only while `damping` is 0. It is not updated while the block is bypassed and holds its last value indefinitely.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block, not one per channel.

Parameters

Path	Unit	Default	Range	Effect
`damping`	-	0.0	0 – 0.9 in practice	Slows the high edge of the band. 0 leaves it at `omegaLowPass`; 0.5 halves it. At 1.0 the output freezes and above 1.0 it runs away — see Limits and errors. Prefer lowering `omegaLowPass` instead.
`omegaHighPass`	rad/s	1.0 (0.16 Hz)	0.1 – 0.628/task period [s]	Low edge of the band, and the filter’s gain. Raising it rejects more slow content and multiplies the output by the same factor. Not checked — a value above the range diverges.
`omegaLowPass`	rad/s	10.0 (1.6 Hz)	0.1 – 0.628/task period [s]	High edge of the band. Lowering it rejects more fast content. Keep it at least a decade above `omegaHighPass`, or the band’s peak drops well below its nominal gain. Not checked — a value above the range diverges.
`enable`	-	true	-	False bypasses the filter: `input` passes through unchanged.

All four parameters are persistent and survive a controller restart, and so do input, output and outputDot. No parameters exist below this block.

Setup

Link the source signal into input and confirm on a trace that input follows the source. If your source can sit at exactly zero, read the note under the diagram first.
Set enable false. output equals input sample for sample and isEnabled reads false.
Compute your task rate’s ceiling: 0.628 divided by the task period in seconds. That is 628 on a 1 ms task. Neither cut-off may exceed it.
Set omegaHighPass to the low edge you want and omegaLowPass to the high edge, both below the ceiling from step 3 and at least a decade apart. Leave damping at 0.

Step 4 has no safety net. A cut-off above the ceiling makes the output grow without bound instead of being rejected. Check both values against step 3 before you set enable true.
Set enable true. isEnabled reads true and output responds to movement in the band.
Feed a slow movement and confirm output stays near zero. Feed a fast movement and confirm the same. Feed one in the band and confirm output responds.
Divide output by input for an in-band signal. The ratio should be close to omegaHighPass. That factor is what you compensate for downstream.
Trace every element of input and output. An element that reads zero while the machine moves is either unwired or being reset by an exact-zero input.

Tuning

Read the frequency you want to keep off a trace of input, in Hz. Set omegaHighPass to $2\pi$ times about a third of it, and omegaLowPass to $2\pi$ times about three times it.
Check both against the ceiling from Setup step 3 every time you change either.
Widen the band until the signal you want passes at full size. Narrow it until the content you want rejected is gone. Those two pull against each other, and the gap between them is the whole tuning.
Measure the passband gain after every omegaHighPass change. The gain moves with it, so a wider band is also a quieter one.
Leave damping at 0. It duplicates omegaLowPass — only the product of the two matters — and it has no safe upper limit. Change omegaLowPass instead.
Re-check both cut-offs after any task-rate change. The ceiling scales with the task period, and a value that was safe on a fast task can diverge on a slow one.

Read the passband gain off any curve as its highest point, and the band edges as where it falls 3 dB below that.

Symptom	Cause	Action
`output` is a constant multiple of what you expected	Expected: the passband gain is `omegaHighPass`, not 1	Scale downstream, or set `omegaHighPass` to 1 and set the low edge with `omegaLowPass` alone
The passband gain changed after you retuned the low edge	Expected: gain and low edge are the same parameter	Recompensate downstream after every `omegaHighPass` change
`output` grew without bound until something tripped	A cut-off above 0.628/task period, or `damping` above 1	Bring both cut-offs under the ceiling and `damping` to 0, then restart the controller
`output` froze at a value and `outputDot` still reads non-zero	`damping` is exactly 1	Set `damping` to 0
A channel sits at zero and will not move	Its `input` is exactly 0.0, which resets that channel every cycle	Confirm on a trace that `input` is non-zero; an unwired channel reads exactly zero
A channel dropped to zero mid-motion and recovered	Its `input` landed on exactly 0.0 for a cycle	Expected with quantised or integer-derived signals; add a tiny offset upstream if it recurs
The peak is several dB below the gain you calculated	The two cut-offs are too close together	Separate them by at least a decade
`output` does not respond to the movement you care about	The band excludes it	Widen the band and re-check with step 3 of Tuning
Slow drift is still on `output`	Low edge too low	Raise `omegaHighPass`, and recompensate the gain
Noise is still on `output`	High edge too high	Lower `omegaLowPass`
`outputDot` is frozen while the filter is bypassed	Expected: it is not written on the bypass path	Gate any consumer of `outputDot` on `isEnabled`
`outputDot` does not match the slope of `output`	`damping` is not 0	Set `damping` to 0, or differentiate `output` downstream instead
`reset` did nothing	The block was bypassed at the time, and the reset was consumed	Enable the block first, then reset
`output` moved again immediately after a reset	Expected: a reset clears only part of the filter’s memory	Bypass the block for one cycle to clear it fully
A large step on `output` after re-enabling	Expected: the slow-content memory is cleared while bypassed, so the input’s offset appears once and washes out	Re-enable at rest, or gate the consumer off `isEnabled`
`output` and `outputDot` came back after a restart with old values	Expected: both are stored as configuration	Ignore them until the block has run one cycle
Some channels filter differently from others	Not possible — all channels share one band and one `damping`	Use a separate filter per channel group

A conservative starting point for isolating a 0.5 Hz oscillation on a 1 ms task, with the gain left at 1:

omegaHighPass = 1.0
omegaLowPass  = 10.0
damping       = 0.0
enable        = true

This is a starting point, not a final tuning. Work step 1 with a trace of your own signal.

Limits and errors

Limit	Set by	What happens	Reported
`omegaHighPass`, `omegaLowPass`	Nothing	Not checked. Both must stay under 0.628/task period [s] — 628 rad/s on a 1 ms task. Above that the output grows without bound instead of filtering, and only a controller restart clears it	Not reported
`damping`	Nothing	Not checked. At 1.0 the output freezes; above 1.0 it grows without bound. Keep it at 0	Not reported
`input` exactly 0.0	Fixed	That channel’s `output` and `input` are set to zero for that cycle, every cycle the condition holds	Not reported; visible as a channel stuck at zero
`output`, `outputDot`	Nothing	Unbounded. Limit downstream if the consumer needs a bound	Not reported
Block state	`reset`, or a bypassed cycle	`reset` clears part of the memory; a bypassed cycle clears the rest. There is no single action that clears all of it	Not reported
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: FIRFilter

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

Control3 3.30–3.34

FIRFilter filters a signal with a weighted sum of its last few samples. It has no feedback, which makes it unconditionally stable: no coefficient set you can write will make it run away. That is the reason to choose it over a coefficient-driven filter with feedback, and the trade is cost — matching the same roll-off takes many more taps. It is single channel: one instance filters one signal.

flowchart LR
    i1(["input — signal to filter"]) --> B["FIRFilter"]
    i2(["disable"]) --> B
    B --> o1(["output — filtered signal"])
    B --> o2(["isEnabled"])

The filter computes $y[k] = h_0,u[k] + h_1,u[k-1] + \dots + h_N,u[k-N]$, with $h$ = coefficients. DC gain is the sum of the coefficients, so an averaging filter needs $1/M$ in each of its $M$ taps. A symmetric coefficient set delays the signal by exactly half the tap count, with perfectly linear phase. A step settles completely after one tap count and never overshoots for non-negative coefficients. The coefficients are defined in samples, not seconds, so the same set on a different task rate is a different filter.

The tap count is fixed when the machine is built and cannot be changed at runtime. This block also has no reset — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to filter. A single value, not an array.
`disable`	-	-	True bypasses the filter: `input` passes straight to `output`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit × the DC gain	The filtered signal, a single value. Equals `input` exactly while bypassed. Starts from zero after every controller start and reaches its true value after one tap count of samples.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block.

Parameters

Path	Unit	Default	Range	Effect
`coefficients`	-	1 in the first tap, 0 in the rest	any	The taps, most recent sample first. All of them are always used — writing zeros into the tail is the only way to shorten the filter, and it does not make it cheaper. Check the DC gain after every change.
`enable`	-	true	-	False bypasses the filter: `input` passes through unchanged.

Both parameters are persistent and survive a controller restart, which is how a filter design ships with a machine. No parameters exist below this block.

Setup

Design your filter against your task period. A 1 ms task is 1000 samples per second, so a six-tap filter spans 6 ms.
Read the length of the coefficients array from the parameter tree. That is your tap count, and it is fixed when the machine is built.
Link the source signal into input and confirm on a trace that input follows the source.
Set enable false. output equals input sample for sample and isEnabled reads false.
Write the whole coefficients array, including any trailing zeros. A short write leaves the old values in the tail, and they keep filtering.

Step 5 must cover every tap. A leftover coefficient in the tail is the most common misconfiguration of this block, and it shows up as a filter that behaves almost right.
Set enable true and confirm isEnabled reads true.
Feed a constant into input and read output. Divide the two: the ratio must equal the sum of your coefficients.
Step the input and count the samples until output stops moving. It must be exactly the tap count; anything longer means a coefficient is in a tap you did not intend.

Tuning

There is nothing to tune here in the usual sense. The work is choosing the coefficients and verifying them on the machine.

Fix the task period before you design anything. Every coefficient depends on it. If the task rate changes later, redesign the whole set — no parameter in this block rescales for you.
For plain noise reduction, start with an equal-weight average: $1/M$ in each of $M$ taps. It is the simplest set that works and its DC gain is exactly 1.
For less ripple at the cost of a slightly wider response, taper the weights toward the ends — triangular weights are the usual next step.
Keep the coefficients symmetric if two filtered signals have to stay in step with each other. Symmetry is what buys exactly linear phase.
Measure the delay you have bought: half the tap count, in samples, for a symmetric set. Keep it below a tenth of the response time of the loop consuming output.
Verify the DC gain by summing the coefficients. It should be 1 for a filter that is not meant to change the signal’s size.
Re-verify after any task-rate change, starting from step 1.

Read the settling time off any curve as the sample it first reaches 1.

Symptom	Cause	Action
`output` is a constant multiple of what you expected	The coefficients do not sum to 1	Divide every coefficient by their sum
The filter behaves almost right but not quite	A leftover coefficient in the tail of the array	Write the whole array including trailing zeros, then re-check step 8 of Setup
`output` settles more slowly than the tap count	A non-zero coefficient sits in a tap you did not intend	Write zeros over the whole array, then write your set
Writing zeros into the tail did not make the block cheaper	Expected: every tap is computed regardless of its value	Size the instance to the requirement when the machine is built
The filter behaves nothing like the design	The design assumed a different sample rate	Redesign at the controller’s actual task period
The filter changed behaviour after a task-rate change	Expected: the coefficients are defined in samples, not seconds	Redesign the whole set for the new rate
Two filtered signals drifted out of step	The coefficient sets are not both symmetric, or not the same length	Use symmetric sets of equal length on both
A short glitch on `output` for a few samples after re-enabling	Expected: the filter still holds the samples from before the bypass	Wait one tap count, or gate the consumer off `isEnabled` plus that long
`output` ramps up from zero for a few samples after every start	Expected: the filter memory starts empty	Gate the consumer off `isEnabled` plus one tap count
You cannot flush the filter’s memory	There is no reset in this block	Bypass and re-enable, then wait one tap count
`output` went to a non-numeric value	A non-numeric value reached `input` or a coefficient	Fix the source; the value clears itself after one tap count
You need more taps than the instance has	The tap count is fixed when the machine is built	It cannot be changed at runtime; it needs a configuration change
You need to filter several axes	Not possible — this block is single channel	Use one instance per axis

A five-tap equal-weight average in a six-tap instance, which smooths without changing the signal’s size:

coefficients = 0.2, 0.2, 0.2, 0.2, 0.2, 0.0
enable       = true

A pass-through, which is also what the block ships with:

coefficients = 1.0, 0.0, 0.0, 0.0, 0.0, 0.0

Limits and errors

Limit	Set by	What happens	Reported
Filter stability	Guaranteed	The block has no feedback, so no coefficient set can make it diverge. This is why you would choose it	Not applicable
DC gain	Nothing	Not normalised and not checked. Whatever the coefficients sum to is the gain you get	Not reported
Tap count	Machine configuration	Fixed when the machine is built. A longer coefficient write has its tail dropped; a shorter one leaves the old tail in place and keeps using it	Not reported
Filter memory	Nothing	There is no reset input. Bypassing the block and re-enabling it is the only way to flush it, and it takes one tap count to clear	Not reported
`output`	Nothing	Unbounded. Limit it downstream if the consumer needs a bound	Not reported
Channel count	Fixed	One channel per instance, always	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: IIRFilter

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

Control3 Superseded. The current release is 3.34.

IIRFilter runs any discrete filter you can express as a numerator and a denominator coefficient set — notch, Butterworth, Chebyshev, lead-lag. Where the named filters give you a cut-off, this one gives you the coefficients themselves, so a filter design drops straight into configuration with no code change. It is single channel: one instance filters one signal.

flowchart LR
    i1(["input — signal to filter"]) --> B["IIRFilter"]
    i2(["disable"]) --> B
    B --> o1(["output — filtered signal"])
    B --> o2(["isEnabled"])

The filter computes $a_0,y[k] = b_0,u[k] + b_1,u[k-1] + \dots - a_1,y[k-1]- a_2,y[k-2] - \dots$, with $b$ = num and $a$ = den. DC gain is the sum of num divided by the sum of den — check it after every coefficient change, because nothing normalises it for you. The coefficients are defined in samples, not seconds, so the same set on a different task rate is a different filter.

This block is bypassed to zero, not to the input. While it is disabled, output reads zero and input reads zero too. Stability is yours to guarantee — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to filter. A single value, not an array. The block writes zero here on every cycle it is disabled, so a trace of `input` reads zero while the filter is off.
`disable`	-	-	True stops the filter and forces `output` to zero. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit × the DC gain	The filtered signal, a single value. Zero — not the input while disabled, while `order` is 0, and while `den[0]` is 0. Starts from zero after every controller start and plays out the filter’s full transient.
`isEnabled`	-	True when `enable` is true and `disable` is false. It does not tell you the filter is actually running: a zero `order` or a zero `den[0]` stops it while this still reads true.

Parameters

Path	Unit	Default	Range	Effect
`order`	-	1	0 – the array length minus 1	How many coefficients are used. A value above the ceiling is corrected silently. 0 stops the filter and outputs zero — it is not a constant gain.
`num`	-	1, 0, 0, 0, 0	any	Numerator coefficients $b_0 … b_N$, most recent sample first. Set these together with `den`, then check the DC gain.
`den`	-	1, 0, 0, 0, 0	any, but `den[0]` must not be 0	Denominator coefficients $a_0 … a_N$. `den[0]` divides every output sample, so `den[0]` = 0 stops the filter and outputs zero.
`enable`	-	true	-	False stops the filter and forces `output` to zero.

All four parameters are persistent and survive a controller restart, which is how a filter design ships with a machine. No parameters exist below this block.

Setup

Design your filter against your task period, in whatever tool you use, and export the coefficients. A 1 ms task is 1000 samples per second.
Link the source signal into input and confirm on a trace that input follows the source while the block is enabled.
Set enable false. output reads zero and so does input. This is normal for this block and is not a broken link.
Write order first, then num, then den. Read order back — a lower value means you exceeded the array length.
Check the array length by writing order to a large number and reading it back. The value you get is the highest order this instance supports; it is fixed when the machine is built.
Set enable true and confirm isEnabled reads true.
Feed a constant into input and read output. Divide the two: the ratio must match the sum of num divided by the sum of den.

Step 7 is the check that catches an unnormalised coefficient set. A set that is right up to a scale factor gives a correctly-shaped filter with the wrong gain, and every loop downstream of it is then mistuned.
Step the input and watch output. If it grows instead of settling, your denominator has an unstable root — set enable false immediately.

Tuning

There is nothing to tune here in the usual sense. The work is designing the coefficients and verifying them on the machine.

Fix the task period before you design anything. Every coefficient depends on it. If the task rate changes later, redesign the whole set — no parameter in this block rescales for you.
Design in your own tool, then verify the DC gain by hand: the sum of num divided by the sum of den should be 1 for a filter that is not meant to change the signal’s size.
Confirm stability before you enable it. Every root of the denominator polynomial must lie inside the unit circle. The block does not check this and will happily run a filter that diverges.
Step the input and read the settling time and any overshoot off output. Compare them against what your design predicted; a mismatch usually means the sample rate assumed in the design tool was wrong.
Keep the order as low as the requirement allows. A high-order set with coefficients spanning many orders of magnitude loses precision, and a narrow notch is the usual culprit.
Re-verify after any task-rate change, starting from step 1.

Read the settling time off any curve as the point it stops moving toward 1.

Symptom	Cause	Action
`output` grew without bound until something tripped	A denominator root outside the unit circle	Set `enable` false, redesign the coefficients, and re-check step 3 of Tuning
`output` is a constant multiple of what you expected	The coefficient set is not normalised	Rescale `num` so the sums divide to 1, or rescale in your design tool
`output` reads zero and `isEnabled` reads true	`order` is 0, or `den[0]` is 0	Write a non-zero `den[0]` and an `order` of at least 1
`input` reads zero on a trace while the filter is off	Expected: the block zeroes its own input while disabled	Enable the block before you judge the link
`output` reads zero as soon as you disabled the filter	Expected: this block bypasses to zero, not to the input	Use a switch block downstream if you need the raw signal while bypassed
`order` reads back lower than written	Above the array length for this instance	Work within the value you read back; the length is fixed when the machine is built
The coefficients went to zero after you set the order	Setting the order clears the coefficient arrays	Always write `order` first, then `num` and `den`
The filter behaves nothing like the design	The design assumed a different sample rate	Redesign at the controller’s actual task period
The filter changed behaviour after a task-rate change	Expected: the coefficients are defined in samples, not seconds	Redesign the whole set for the new rate
A high-order coefficient still has an effect after you shortened the set	The unused tail of `num` or `den` was left in place	Write zeros over the whole array, then write the new set
`output` plays out a large transient every time the filter is enabled	Expected: the filter memory starts from zero, so the full transient runs	Enable at rest, or gate the consumer off `isEnabled` plus the settling time
`output` went to a non-numeric value and stays there	A non-numeric value reached `input` or a coefficient	Disable the block for one cycle — that clears the filter memory — then fix the source
You need to filter several axes	Not possible — this block is single channel	Use one instance per axis

A pass-through starting point, which is also what the block ships with:

order = 1
num   = 1, 0
den   = 1, 0

A 2nd-order Butterworth low-pass at 10 Hz for a 1 ms task only:

order = 2
num   = 0.0009447, 0.0018894, 0.0009447
den   = 1, -1.9111971, 0.9149758

Limits and errors

Limit	Set by	What happens	Reported
Filter stability	Nothing	Not checked. A denominator with a root outside the unit circle diverges, and the block runs it. Only a controller restart or disabling the block clears the state	Not reported
`den[0]` ≠ 0	Fixed	A zero `den[0]` stops the filter and `output` reads zero	Not reported; `isEnabled` still reads true
`order` ≤ array length − 1	Machine configuration	A larger value is replaced by the ceiling	Silently; read `order` back
DC gain	Nothing	Not normalised and not checked. Whatever the coefficients imply is what you get	Not reported
`output`	Nothing	Unbounded. Limit it downstream if the consumer needs a bound	Not reported
Channel count	Fixed	One channel per instance, always	Not reported
Array length	Machine configuration	Fixed when the machine is built and not readable directly — discover it with Setup step 5	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: IIRFilter

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

Control3 Current release

flowchart LR
    i1(["input — signal to filter"]) --> B["IIRFilter"]
    i2(["disable"]) --> B
    B --> o1(["output — filtered signal"])
    B --> o2(["isEnabled"])

The filter computes $a_0,y[k] = b_0,u[k] + b_1,u[k-1] + \dots - a_1,y[k-1]- a_2,y[k-2] - \dots$, with $b$ = num and $a$ = den. DC gain is the sum of num divided by the sum of den — check it after every coefficient change, because nothing normalises it for you. The coefficients are defined in samples, not seconds, so the same set on a different task rate is a different filter.

This block is bypassed to zero, not to the input. While it is disabled, output reads zero and input reads zero too. Stability is yours to guarantee — see Limits and errors.

Do not put this block in a setpoint path unguarded. Because a stopped filter outputs zero rather than its input, disable, order = 0 or den[0] = 0 on a position, velocity or torque target is a command to zero. An application in C++ can guard the path with IIRFilter::getIsFiltering(), which is false in exactly those three cases, and substitute the unfiltered signal — this is what ActuatorControlLoop does for its four target filters, so those four are safe to disable at runtime.

The coefficient arrays hold 7 entries by default, so orders up to 6 — two notches plus a lowpass. An instance can be built with a different ceiling; read it back rather than assuming (see Setup, step 5).

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to filter. A single value, not an array. The block writes zero here on every cycle it is disabled, so a trace of `input` reads zero while the filter is off.
`disable`	-	-	True stops the filter and forces `output` to zero. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit × the DC gain	The filtered signal, a single value. Zero — not the input while disabled, while `order` is 0, and while `den[0]` is 0. Starts from zero after every controller start and plays out the filter’s full transient.
`isEnabled`	-	True when `enable` is true and `disable` is false. It does not tell you the filter is actually running: a zero `order` or a zero `den[0]` stops it while this still reads true.

Parameters

Path	Unit	Default	Range	Effect
`order`	-	1	0 – the array length minus 1	How many coefficients are used. A value above the ceiling is corrected silently. 0 stops the filter and outputs zero — it is not a constant gain.
`num`	-	1, 0, 0, 0, 0, 0, 0	any	Numerator coefficients $b_0 … b_N$, most recent sample first. Set these together with `den`, then check the DC gain.
`den`	-	1, 0, 0, 0, 0, 0, 0	any, but `den[0]` must not be 0	Denominator coefficients $a_0 … a_N$. `den[0]` divides every output sample, so `den[0]` = 0 stops the filter and outputs zero.
`enable`	-	true	-	False stops the filter and forces `output` to zero.

All four parameters are persistent and survive a controller restart, which is how a filter design ships with a machine. No parameters exist below this block.

Setup

Design your filter against your task period, in whatever tool you use, and export the coefficients. A 1 ms task is 1000 samples per second.
Link the source signal into input and confirm on a trace that input follows the source while the block is enabled.
Set enable false. output reads zero and so does input. This is normal for this block and is not a broken link.
Write order first, then num, then den. Read order back — a lower value means you exceeded the array length.
Check the array length by writing order to a large number and reading it back. The value you get is the highest order this instance supports; it is fixed when the machine is built.
Set enable true and confirm isEnabled reads true.
Feed a constant into input and read output. Divide the two: the ratio must match the sum of num divided by the sum of den.

Step 7 is the check that catches an unnormalised coefficient set. A set that is right up to a scale factor gives a correctly-shaped filter with the wrong gain, and every loop downstream of it is then mistuned.
Step the input and watch output. If it grows instead of settling, your denominator has an unstable root — set enable false immediately.

Tuning

There is nothing to tune here in the usual sense. The work is designing the coefficients and verifying them on the machine.

Fix the task period before you design anything. Every coefficient depends on it. If the task rate changes later, redesign the whole set — no parameter in this block rescales for you.
Design in your own tool, then verify the DC gain by hand: the sum of num divided by the sum of den should be 1 for a filter that is not meant to change the signal’s size.
Confirm stability before you enable it. Every root of the denominator polynomial must lie inside the unit circle. The block does not check this and will happily run a filter that diverges.
Step the input and read the settling time and any overshoot off output. Compare them against what your design predicted; a mismatch usually means the sample rate assumed in the design tool was wrong.
Keep the order as low as the requirement allows. A high-order set with coefficients spanning many orders of magnitude loses precision, and a narrow notch is the usual culprit.
Re-verify after any task-rate change, starting from step 1.

Read the settling time off any curve as the point it stops moving toward 1.

Symptom	Cause	Action
`output` grew without bound until something tripped	A denominator root outside the unit circle	Set `enable` false, redesign the coefficients, and re-check step 3 of Tuning
`output` is a constant multiple of what you expected	The coefficient set is not normalised	Rescale `num` so the sums divide to 1, or rescale in your design tool
`output` reads zero and `isEnabled` reads true	`order` is 0, or `den[0]` is 0	Write a non-zero `den[0]` and an `order` of at least 1
`input` reads zero on a trace while the filter is off	Expected: the block zeroes its own input while disabled	Enable the block before you judge the link
`output` reads zero as soon as you disabled the filter	Expected: this block bypasses to zero, not to the input	Use a switch block downstream if you need the raw signal while bypassed
`order` reads back lower than written	Above the array length for this instance	Work within the value you read back; the length is fixed when the machine is built
The coefficients went to zero after you set the order	Setting the order clears the coefficient arrays	Always write `order` first, then `num` and `den`
The filter behaves nothing like the design	The design assumed a different sample rate	Redesign at the controller’s actual task period
The filter changed behaviour after a task-rate change	Expected: the coefficients are defined in samples, not seconds	Redesign the whole set for the new rate
A high-order coefficient still has an effect after you shortened the set	The unused tail of `num` or `den` was left in place	Write zeros over the whole array, then write the new set
`output` plays out a large transient every time the filter is enabled	Expected: the filter memory starts from zero, so the full transient runs	Enable at rest, or gate the consumer off `isEnabled` plus the settling time
`output` went to a non-numeric value and stays there	A non-numeric value reached `input` or a coefficient	Disable the block for one cycle — that clears the filter memory — then fix the source
You need to filter several axes	Not possible — this block is single channel	Use one instance per axis

A pass-through starting point, which is also what the block ships with:

order = 1
num   = 1, 0
den   = 1, 0

A 2nd-order Butterworth low-pass at 10 Hz for a 1 ms task only:

order = 2
num   = 0.0009447, 0.0018894, 0.0009447
den   = 1, -1.9111971, 0.9149758

Limits and errors

Limit	Set by	What happens	Reported
Filter stability	Nothing	Not checked. A denominator with a root outside the unit circle diverges, and the block runs it. Only a controller restart or disabling the block clears the state	Not reported
`den[0]` ≠ 0	Fixed	A zero `den[0]` stops the filter and `output` reads zero	Not reported; `isEnabled` still reads true
`order` ≤ array length − 1	Machine configuration	A larger value is replaced by the ceiling	Silently; read `order` back
DC gain	Nothing	Not normalised and not checked. Whatever the coefficients imply is what you get	Not reported
`output`	Nothing	Unbounded. Limit it downstream if the consumer needs a bound	Not reported
Channel count	Fixed	One channel per instance, always	Not reported
Array length	Machine configuration	Fixed when the machine is built and not readable directly — discover it with Setup step 5	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: MovingAverageFilter

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

Control3 3.30–3.34

MovingAverageFilter smooths a noisy signal by averaging it over time, tuned by a sample count rather than by a frequency. It is the filter to use when you think in samples: “average this over a hundred readings”. Its memory cost is the same at any sample count, so a very long average is as cheap as a short one.

It averages by weighted decay, not over a fixed window: older samples fade out rather than dropping out. So output approaches a step gradually and does not finish after numberOfSamples cycles — it reaches 63% at that point and 90% at a little over twice it.

flowchart LR
    i1(["input — signal to smooth"]) --> B["MovingAverageFilter"]
    i2(["reset"]) --> B
    i3(["disable"]) --> B
    B --> o1(["output — smoothed signal"])
    B --> o2(["isEnabled"])

Time constant $\tau = (N+1) \times$ task period [s], with $N$ = numberOfSamples. At the default 100 on a 1 ms task that is 0.101 s, a cut-off of 1.58 Hz: 63% of a step in 0.1 s, 90% in 0.23 s. Phase lag at the cut-off is 45°, and that lag is the whole trade. Note the time constant scales with the task period, so the same sample count is a different filter in seconds on a different task rate.

For the first numberOfSamples cycles after a start or a reset the filter converges faster than the numbers above, because it is averaging everything it has seen rather than decaying. That is deliberate and useful.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to smooth. One element per channel; the channel count is fixed by the machine configuration.
`reset`	-	-	A rising value sets `output` to `input` immediately and restarts the fast-converging phase. It affects every channel at once, and it works whether the block is enabled or not. Use it after a large step you do not want the filter to average across.
`disable`	-	-	True bypasses the filter: `input` passes straight to `output`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit	The smoothed signal, one element per channel. Equals `input` exactly while bypassed. After a controller start its first value is half of `input`, then it converges — gate the consumer if that matters.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block, not one per channel.

Parameters

Path	Unit	Default	Range	Effect
`numberOfSamples`	samples	100	0 upward; no upper limit	How heavily to average, shared by all channels. Higher removes more noise and adds more delay, at no extra cost in memory or computation. 0 is a pass-through. Any value is safe — this filter cannot be made unstable.
`enable`	-	true	-	False bypasses the filter: `input` passes through unchanged.

Both parameters are persistent and survive a controller restart. The inputs and outputs do not. No parameters exist below this block.

Setup

Link the source signal: …/sensor/rawPressure → …/pressureFilter/input. input follows the source on a trace.
Set enable false. output equals input sample for sample and isEnabled reads false.
Set numberOfSamples to 10. Any value is accepted, so there is nothing to read back and check.
Set enable true. isEnabled reads true and output tracks input closely, with the noise still visible.
Raise numberOfSamples in steps of roughly double, watching the noise and the loop consuming output. Stop one step below where that loop feels soft or hunts.

Step 5 changes what the controller sees. Each doubling of the sample count doubles the delay. Raise it with the axis at rest before trying it in motion — the added delay can destabilise a tightly tuned loop.
Step the input and time how long output takes to reach 63% of the step. It should be about numberOfSamples plus one task periods.
Trace every element of input and output. An element that reads zero while the machine moves is an unwired channel, not a filtered one.

Tuning

Read the ripple you want gone off a trace of input, and count its period in task cycles. Set numberOfSamples to at least a few times that count.
Measure the delay you have bought: numberOfSamples plus one task periods is the time constant, and the delay below the cut-off equals it.
Keep that delay below a tenth of the response time of the loop consuming output. Above that, the loop pays for the smoothing in stability.
Double numberOfSamples to halve the noise. It is a cheap knob — there is no memory or computation penalty for a large value — so the only cost is delay.
Check the loop in motion, not at rest. Delay costs phase margin only while the axis is moving fast enough to need it.
Re-check the sample count after any task-rate change. The count stays the same in samples but the delay in seconds moves with the task period.
If you need a filter with a hard cut at a known frequency — to kill a mains harmonic, say — this block cannot do it. A finite-impulse-response filter with equal taps can.

Read the time constant off any curve as the moment it crosses 0.63.

Symptom	Cause	Action
Noise still present on `output`	Sample count too low	Double `numberOfSamples`, then re-check the loop for softness
Loop went soft, hunts or oscillates after enabling	Delay too high for the loop	Halve `numberOfSamples`; if the noise returns, fix it at the source
`output` had not finished settling after `numberOfSamples` cycles	Expected: the filter decays rather than using a fixed window, so it reaches 63% at that point	Wait about 2.3 times the sample count for 90%
Setpoint tracking lags behind the command	The block is in the command path, not the feedback path	Lower `numberOfSamples`, or move the filter onto the measurement only
The filter converged quickly just after start, then got sluggish	Expected: it averages everything it has seen for the first `numberOfSamples` cycles, then switches to steady decay	Use `reset` to get the fast phase back deliberately
`output` was half the input on the first cycle after a start	Expected behaviour of the first sample	Gate the consumer off a short delay after start
`output` averaged across a step you wanted it to follow	The filter has no way to know the step was intentional	Pulse `reset` at the moment of the step
Resetting one channel restarted the averaging on all of them	Expected: the sample count is shared across channels	Use a separate filter per channel if they need independent resets
Changing `numberOfSamples` had no immediate effect	Expected: the filter is still in its fast-converging phase, where the count does not yet apply	Pulse `reset`, or wait for the count to be reached
`output` follows `input` exactly, with no smoothing at all	`numberOfSamples` is 0, or `enable` is false, or `disable` is true	Read `isEnabled` and `numberOfSamples`; 0 is a pass-through
The delay changed after a task-rate change	Expected: the time constant is the sample count times the task period	Rescale `numberOfSamples` by the ratio of the task periods
You need a hard cut at a specific frequency	This filter has no such thing — it is a gentle first-order roll-off	Use a finite-impulse-response filter with equal taps
Some channels smooth more than others	Not possible — all channels share one sample count	Use a separate filter per channel group
`output` went to a non-numeric value	A non-numeric value reached `input`	Fix the source, then pulse `reset` — that clears the filter completely

A conservative starting point for a pressure signal on a 1 ms task, feeding a loop with a 100 ms response time:

numberOfSamples = 50
enable          = true

This is a starting point, not a final tuning. Work step 1 with a trace of your own signal.

Limits and errors

Limit	Set by	What happens	Reported
`numberOfSamples`	Nothing	Not checked, and it does not need to be — no value can make this filter unstable. 0 is a pass-through	Not reported
Filter stability	Guaranteed	Stable at every sample count and every task rate. Unlike the frequency-tuned filters, there is no task-rate ceiling to respect	Not applicable
`output`	Nothing	Unbounded — whatever the input carries reaches the output. Limit it downstream if the consumer needs a bound	Not reported
Filter memory	`reset`, or a bypassed cycle	Both set `output` to `input` and clear the filter completely. There is always a way out of a bad state	Not reported
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

The block raises no errors or warnings and logs nothing. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).