– Limiters and shaping

Docs: Limiter

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

Control3 Superseded. The current release is 3.34.

Limiter clamps a signal between a lower and an upper bound. It is the block that sits between a controller and an actuator that cannot take more than a certain torque, and it is the simplest protection in the library.

An adaptive variant is also available. It starts from wherever the signal already is and closes in on the configured bounds only as the signal allows — so switching it on around a signal that is already outside its band does not produce a step. A plain limiter in the same situation clamps at once.

flowchart LR
    i1(["input — signal to clamp"]) --> B["Limiter"]
    i2(["disable"]) --> B
    B --> o1(["output — clamped signal"])
    B --> o2(["isLimiting — per channel"])
    B --> o3(["isEnabled"])

The adaptive variant adds two outputs:

flowchart LR
    i1(["input"]) --> B["AdaptiveLimiter"]
    i2(["disable"]) --> B
    B --> o1(["output"])
    B --> o2(["isLimiting"])
    B --> o3(["isEnabled"])
    B --> o4(["activeLowerLimit — the bound in use now"])
    B --> o5(["activeUpperLimit"])

output = input clamped to [lowerLimit, upperLimit], per channel. There is no time constant, no lag and no filtering — the clamp is exact and instant. Nothing here depends on the task rate.

The limiter ships switched off. enable defaults to false, so a fresh limiter passes everything through. This matters most when a limiter is one block inside a larger one: its bound is not protecting anything until it is enabled.

If you write the limits the wrong way round, the block swaps them for you and you will read back the swapped pair.

Signals

Inputs

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

Outputs

Path	Unit	Description
`output`	signal unit	The clamped signal, one element per channel. Equals `input` exactly while bypassed, and exactly whenever the input is inside the bounds.
`isLimiting`	-	True per channel while `input` is outside the configured bounds. On the adaptive variant this means “the signal wants more than you allowed”, which is not the same as “the output was changed” — see below.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block.
`activeLowerLimit`	signal unit	Adaptive variant only. The bound actually in use this cycle, per channel. It is never tighter than `lowerLimit` and may be looser while the signal is outside.
`activeUpperLimit`	signal unit	Adaptive variant only. The upper equivalent.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	False bypasses the limiter entirely. Set this, or the block does nothing.
`lowerLimit`	signal unit	−1	below `upperLimit`	The lower bound, per channel. Set it to what the consumer can actually accept. If it ends up above `upperLimit` the two are swapped silently.
`upperLimit`	signal unit	+1	above `lowerLimit`	The upper bound, per channel.
`adaptive`	-	true	-	Adaptive variant only. False makes it behave as a plain limiter. A plain limiter cannot be made adaptive at runtime.

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

Setup

Set lowerLimit and upperLimit to what the consumer can accept. The defaults of ±1 are placeholders, not machine values.
Leave enable false and confirm output follows input exactly.
Drive the input past a bound and confirm isLimiting goes true for that channel while output still follows — the flag works while bypassed only in the sense that it stays false; here it will read false, which confirms the bypass.
Set enable true and repeat. output should now stop at the bound and isLimiting should read true.

Step 4 changes what reaches the consumer. If the signal is already outside the band when you enable a plain limiter, the output steps to the bound. Enable it with the signal inside the band, or use the adaptive variant.
Trace every element of input, output and isLimiting. Limits are per channel, so an element with the wrong bound is easy to miss.
On the adaptive variant, watch activeLowerLimit and activeUpperLimit. They should converge onto the configured bounds as the signal moves inside them.

Tuning

There is nothing to tune. The bounds are a machine property, and the only real decision is which variant to use.

Set the bounds from the consumer’s datasheet, not by watching the signal. A limiter tuned to what the signal happens to do is not protecting anything.
Use the plain limiter wherever the bound is a hard safety limit. It clamps immediately and always, which is what a protection limit must do.
Use the adaptive variant wherever the bound shapes a signal rather than protecting the machine, and a step on engagement would be felt. It never introduces a discontinuity, and it tightens toward the configured bounds only as the signal allows.
Do not use the adaptive variant as a safety limit. If the signal never returns inside the band, the active bounds never tighten and nothing is ever clipped.
Watch isLimiting during commissioning. Persistent limiting means either the bound is too tight or something upstream is commanding more than the machine can deliver — and the second is usually the real problem.
Nothing here needs re-checking after a task-rate change.

Read each bound off the height at which its line goes flat.

Symptom	Cause	Action
Nothing is limited and `isLimiting` stays false	`enable` defaults to false	Set `enable` true
`isLimiting` reads true but `output` equals `input`	You are on the adaptive variant, and the active band still admits the signal	Read `activeLowerLimit` and `activeUpperLimit`; use the plain limiter if you need a hard bound
The output stepped when the limiter was enabled	Expected on the plain limiter: it clamps at once	Enable with the signal inside the band, or use the adaptive variant
The adaptive limiter never clips anything	Expected: the active bounds only tighten when the signal comes back inside them	Use the plain limiter for a hard bound
The limits read back swapped	Expected: they were written the wrong way round and the block corrected them	Write the lower bound to `lowerLimit`
The output is pinned at one value	`lowerLimit` and `upperLimit` are equal	Separate them
One channel limits and the others do not	Expected: the bounds are per channel	Check every element of both limit arrays
The output is unbounded inside a larger block	That block’s internal limiter has not been enabled	Enable it in its own sub-tree
A non-numeric value passed straight through	Expected: the clamp does not reject non-numeric values	Fix the source; on the adaptive variant, bypass the block for a cycle to clear its active bounds
The signal is clipped harshly and the machine bumps	A hard clamp is what this block does	Use a soft limiter if you need a rounded approach to the bound

A starting point for bounding an actuator command at ±10 in its own units:

enable     = true
lowerLimit = -10.0
upperLimit = 10.0

Limits and errors

Limit	Set by	What happens	Reported
`lowerLimit` below `upperLimit`	Fixed	If they are inverted the two are swapped in place	Silently; read both back
`output`	`lowerLimit`, `upperLimit` while enabled	Clamped exactly, with no lag. Unbounded while `enable` is false	`isLimiting`, per channel
Limit values	Nothing	Not checked. Any finite pair is accepted, and equal limits pin the output to that value	Not reported
`isLimiting` meaning	Fixed	Reports the input against the configured bounds. On the adaptive variant the output may not have been changed at all	Not reported
Adaptive band	Fixed	The active bounds can only ever be wider than the configured ones, never tighter. They are not reset at start	Published as `activeLowerLimit` / `activeUpperLimit`
Non-numeric input	Nothing	Passes through unchanged. On the adaptive variant it also poisons the active bounds until a bypassed cycle re-derives them	Not reported
Channel count	Machine configuration	Fixed once the controller starts	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: Limiter

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

Control3 Current release

flowchart LR
    i1(["input — signal to clamp"]) --> B["Limiter"]
    i2(["disable"]) --> B
    B --> o1(["output — clamped signal"])
    B --> o2(["isLimiting — per channel"])
    B --> o3(["isEnabled"])

The adaptive variant adds two outputs:

flowchart LR
    i1(["input"]) --> B["AdaptiveLimiter"]
    i2(["disable"]) --> B
    B --> o1(["output"])
    B --> o2(["isLimiting"])
    B --> o3(["isEnabled"])
    B --> o4(["activeLowerLimit — the bound in use now"])
    B --> o5(["activeUpperLimit"])

output = input clamped to [lowerLimit, upperLimit], per channel. There is no time constant, no lag and no filtering — the clamp is exact and instant. Nothing here depends on the task rate.

If you write the limits the wrong way round, the block swaps them for you and you will read back the swapped pair.

Signals

Inputs

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

Outputs

Path	Unit	Description
`output`	signal unit	The clamped signal, one element per channel. Equals `input` exactly while bypassed, and exactly whenever the input is inside the bounds.
`isLimiting`	-	True per channel while `input` is outside the configured bounds. On the adaptive variant this means “the signal wants more than you allowed”, which is not the same as “the output was changed” — see below.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block.
`activeLowerLimit`	signal unit	Adaptive variant only. The bound actually in use this cycle, per channel. It is never tighter than `lowerLimit` and may be looser while the signal is outside.
`activeUpperLimit`	signal unit	Adaptive variant only. The upper equivalent.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	False bypasses the limiter entirely. Set this, or the block does nothing.
`lowerLimit`	signal unit	−1	below `upperLimit`	The lower bound, per channel. Set it to what the consumer can actually accept. If it ends up above `upperLimit` the two are swapped silently.
`upperLimit`	signal unit	+1	above `lowerLimit`	The upper bound, per channel.
`adaptive`	-	true	-	Adaptive variant only. False makes it behave as a plain limiter. A plain limiter cannot be made adaptive at runtime.

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

Setup

Set lowerLimit and upperLimit to what the consumer can accept. The defaults of ±1 are placeholders, not machine values.
Leave enable false and confirm output follows input exactly.
Drive the input past a bound and confirm isLimiting goes true for that channel while output still follows — the flag works while bypassed only in the sense that it stays false; here it will read false, which confirms the bypass.
Set enable true and repeat. output should now stop at the bound and isLimiting should read true.

Step 4 changes what reaches the consumer. If the signal is already outside the band when you enable a plain limiter, the output steps to the bound. Enable it with the signal inside the band, or use the adaptive variant.
Trace every element of input, output and isLimiting. Limits are per channel, so an element with the wrong bound is easy to miss.
On the adaptive variant, watch activeLowerLimit and activeUpperLimit. They should converge onto the configured bounds as the signal moves inside them.

Tuning

There is nothing to tune. The bounds are a machine property, and the only real decision is which variant to use.

Set the bounds from the consumer’s datasheet, not by watching the signal. A limiter tuned to what the signal happens to do is not protecting anything.
Use the plain limiter wherever the bound is a hard safety limit. It clamps immediately and always, which is what a protection limit must do.
Use the adaptive variant wherever the bound shapes a signal rather than protecting the machine, and a step on engagement would be felt. It never introduces a discontinuity, and it tightens toward the configured bounds only as the signal allows.
Do not use the adaptive variant as a safety limit. If the signal never returns inside the band, the active bounds never tighten and nothing is ever clipped.
Watch isLimiting during commissioning. Persistent limiting means either the bound is too tight or something upstream is commanding more than the machine can deliver — and the second is usually the real problem.
Nothing here needs re-checking after a task-rate change.

Read each bound off the height at which its line goes flat.

Symptom	Cause	Action
Nothing is limited and `isLimiting` stays false	`enable` defaults to false	Set `enable` true
`isLimiting` reads true but `output` equals `input`	You are on the adaptive variant, and the active band still admits the signal	Read `activeLowerLimit` and `activeUpperLimit`; use the plain limiter if you need a hard bound
The output stepped when the limiter was enabled	Expected on the plain limiter: it clamps at once	Enable with the signal inside the band, or use the adaptive variant
The adaptive limiter never clips anything	Expected: the active bounds only tighten when the signal comes back inside them	Use the plain limiter for a hard bound
The limits read back swapped	Expected: they were written the wrong way round and the block corrected them	Write the lower bound to `lowerLimit`
The output is pinned at one value	`lowerLimit` and `upperLimit` are equal	Separate them
One channel limits and the others do not	Expected: the bounds are per channel	Check every element of both limit arrays
The output is unbounded inside a larger block	That block’s internal limiter has not been enabled	Enable it in its own sub-tree
A non-numeric value passed straight through	Expected: the clamp does not reject non-numeric values	Fix the source; on the adaptive variant, bypass the block for a cycle to clear its active bounds
The signal is clipped harshly and the machine bumps	A hard clamp is what this block does	Use a soft limiter if you need a rounded approach to the bound

A starting point for bounding an actuator command at ±10 in its own units:

enable     = true
lowerLimit = -10.0
upperLimit = 10.0

Limits and errors

Limit	Set by	What happens	Reported
`lowerLimit` below `upperLimit`	Fixed	If they are inverted the two are swapped in place	Silently; read both back
`output`	`lowerLimit`, `upperLimit` while enabled	Clamped exactly, with no lag. Unbounded while `enable` is false	`isLimiting`, per channel
Limit values	Nothing	Not checked. Any finite pair is accepted, and equal limits pin the output to that value	Not reported
`isLimiting` meaning	Fixed	Reports the input against the configured bounds. On the adaptive variant the output may not have been changed at all	Not reported
Adaptive band	Fixed	The active bounds can only ever be wider than the configured ones, never tighter. They are not reset at start	Published as `activeLowerLimit` / `activeUpperLimit`
Non-numeric input	Nothing	Passes through unchanged. On the adaptive variant it also poisons the active bounds until a bypassed cycle re-derives them	Not reported
Channel count	Machine configuration	Fixed once the controller starts	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.32.1 (340db23).

Docs: SoftLimiter

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

Control3 3.30–3.34

SoftLimiter bounds a signal the way a hard limiter does, but rounds the approach instead of cutting it off. Between the break points the output equals the input exactly; beyond them it curves over and approaches the limit gradually.

It adds no lag and no dynamics — the curve depends only on the current input, so unlike a rate limiter or a filter it costs nothing in responsiveness. The trade is that the limit is never actually reached, only approached.

flowchart LR
    i1(["input — signal to limit"]) --> B["SoftLimiter"]
    i2(["disable"]) --> B
    B --> o1(["output — softly limited signal"])
    B --> o2(["isLimiting — per channel"])
    B --> o3(["isEnabled"])

Between lowerBreakPoint and upperBreakPoint the output is the input, exactly. Beyond a break point it curves toward the matching limit and gets there only at infinity. The fade distance — limit minus break point — is the whole tuning: a wide gap gives a long gentle curve, a narrow one a sharp bend. Set the break point equal to the limit and you get a hard clamp.

This limit is not a guarantee. If the bound must be respected exactly, put a Limiter after this one.

Disabling this block freezes its output rather than passing the input through — see Limits and errors. Unlike most limiters here, it ships enabled.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to limit. One element per channel; the channel count is fixed by the machine configuration.
`disable`	-	-	True stops the block updating. It does not bypass it — `output` freezes at its last value. Use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit	The softly limited signal, one element per channel. Equals `input` exactly between the break points. Frozen at its last value while the block is disabled.
`isLimiting`	-	True per channel while the input is beyond either break point, so the taper is active. It also freezes while disabled.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	Ships on. False freezes the output rather than bypassing.
`lowerLimit`	signal unit	−1.0	below `lowerBreakPoint`	The lower asymptote. The output approaches it and never reaches it. Swapped with `upperLimit` if the two are inverted.
`lowerBreakPoint`	signal unit	−0.9	between `lowerLimit` and `upperBreakPoint`	Where the lower taper begins. Corrected up to `lowerLimit` if set below it.
`upperBreakPoint`	signal unit	+0.9	between `lowerBreakPoint` and `upperLimit`	Where the upper taper begins. Corrected down to `upperLimit` if set above it.
`upperLimit`	signal unit	+1.0	above `upperBreakPoint`	The upper asymptote.

All five are persistent and survive a restart. Every limit and break point is per channel. No parameters exist below this block.

Setup

Set upperLimit and lowerLimit to the values the signal must stay inside. Remember the output only approaches them.
Set the two break points inside those limits. The gap between a break point and its limit is the fade distance — start with about 10% of the range, as the defaults do.
Confirm output equals input exactly while the signal stays between the break points, and that isLimiting reads false.

Step 3 is the check that matters. If the output differs from the input in the middle of the range, a break point is inside your working range and the block is tapering signals you meant to pass untouched.
Drive the signal past a break point and confirm output curves over and isLimiting goes true.
Drive it far past the limit and confirm output gets close to, but never equals, the limit.
Trace every element. All four bounds are per channel.

Tuning

Choose the limits from the consumer, as you would for a hard limiter.
Choose the break points from how much of the range you are willing to distort. Everything between them is untouched; everything outside is compressed.
Widen the fade distance if the bend is harsh, and narrow it if too much of your working range is being compressed. Those two pull against each other, and the gap between them is the whole tuning.
If the machine needs the bound respected exactly, follow this block with a hard limiter set to the same value. The soft taper does the shaping and the hard clamp does the guaranteeing.
To turn a channel into a hard clamp, set its break point equal to its limit. The block handles that case explicitly.
Nothing here needs re-checking after a task-rate change.

Read the fade distance off the gap between where a curve bends and where it flattens.

Symptom	Cause	Action
The output never quite reaches the limit	Expected: the limit is an asymptote, not a bound	Add a hard limiter after this block if the bound must be exact
The output is distorted in the middle of the working range	A break point is inside the range you meant to leave alone	Move the break points outward
The bend at the break point feels harsh	The fade distance is too small	Move the break point further from the limit
Too much of the range is compressed	The fade distance is too large	Move the break point closer to the limit
The output froze and will not follow the input	Expected: disabling this block freezes it rather than bypassing	Set `enable` true and `disable` false
`isLimiting` is stuck true	Same cause — the flag freezes with the output	Re-enable the block
A break point reads back different from what was written	Expected: break points are corrected inside their own limits	Write it inside the limit
The limits read back swapped	Expected: inverted limits are corrected	Write the lower value to `lowerLimit`
Only the upper taper seems to work	The two break points are crossed, and the upper taper is applied last	Keep `lowerBreakPoint` below `upperBreakPoint`
A channel clips hard instead of tapering	Its break point equals its limit	Separate them, or keep it if a hard clamp is what you wanted
Limits were corrected only after the block was enabled	Expected: the correction runs only while the block is running	Enable it, then read the values back
One channel behaves differently from the others	Expected: all four bounds are per channel	Check every element of all four arrays
A non-numeric value passed straight through untapered	Expected: the comparisons that trigger the taper fail for it	Fix the source; the block holds no state and recovers at once

A starting point for shaping a command that must stay inside ±10, tapering over the last 20% of the range:

enable          = true
lowerLimit      = -10.0
lowerBreakPoint = -8.0
upperBreakPoint = 8.0
upperLimit      = 10.0

Limits and errors

Limit	Set by	What happens	Reported
`output` against the limits	The taper	Approached, never reached. This block cannot guarantee a bound — follow it with a hard limiter if you need one	`isLimiting`, per channel
`lowerLimit` below `upperLimit`	Fixed	Inverted limits are swapped in place	Silently; read both back
Break points inside their limits	Fixed	A break point outside its own limit is corrected onto it. The two break points are not ordered against each other — if they cross, only the upper taper applies	Silently; read them back
Parameter correction	While enabled only	The corrections above run only while the block is enabled	Not reported
Disabled behaviour	Fixed	The output freezes at its last value rather than passing the input through, unlike every other limiter here	Not reported
Fade distance zero	Fixed	A break point equal to its limit gives a hard clamp at that value	Not reported
Limit values	Nothing	Not checked beyond the ordering above	Not reported
Non-numeric input	Nothing	Passes through untapered. The block is stateless and recovers immediately	Not reported
Channel count	Machine configuration	Fixed once the controller starts	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: HardLimitVector

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

Control3 3.30–3.34

HardLimitVector limits the length of a vector rather than each of its components. When the vector is too long every component is scaled down by the same factor, so the direction is preserved exactly and only the size changes.

That is why it exists. Clamping a Cartesian velocity component by component turns a diagonal move into a different diagonal — the axis that reaches its bound first stops growing while the others carry on, and the commanded direction rotates. Scaling the whole vector keeps the direction and just slows the move down.

flowchart LR
    i1(["input — the vector's components"]) --> B["HardLimitVector"]
    i2(["disable"]) --> B
    B --> o1(["output — scaled or unchanged vector"])
    B --> o2(["isLimiting"])
    B --> o3(["isEnabled"])

upperLimit is the maximum length of the whole vector, as a single number — not a bound on any one component. While the length is inside the limit the output is the input exactly. Beyond it, every component is multiplied by upperLimit ÷ the actual length.

Every component must share the same unit. The block computes one length across all of them, so a mixed vector — a pose with metres in some elements and radians in others — has a length with no physical meaning. Use one instance per unit group.

There is no lower limit, and there cannot usefully be one: a zero-length vector has no direction to grow in.

The block ships switched off. enable defaults to false.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The vector’s components, one element per channel. All of them must share a unit. The channel count is fixed by the machine configuration.
`disable`	-	-	True bypasses the limiter: every component passes straight through. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit	The vector, scaled down uniformly if it was too long and unchanged otherwise. Its direction always matches `input`. Equals `input` exactly while bypassed.
`isLimiting`	-	True while the vector is being scaled. A single value for the whole vector, not one per channel — the vector is limited as a whole.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	False bypasses the limiter. Set this, or the block does nothing.
`upperLimit`	signal unit	1	0 upward	The maximum vector length, as a single number for the whole vector. 0 collapses the vector to zero. Not checked — a negative value points the output the opposite way.

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

Setup

Confirm every element of input carries the same unit. If they do not, this block cannot limit them together — split them into separate instances.
Set upperLimit to the largest vector length the consumer can accept — for a Cartesian velocity, the maximum tool speed.
Leave enable false and confirm output matches input element for element.
Set enable true. Command a vector well inside the limit and confirm output still matches input exactly and isLimiting reads false.
Command a vector longer than the limit. Confirm isLimiting goes true, and check the ratios between the output components are unchanged from the input’s.

Step 5 is the check that direction is preserved. If the ratios change, something else in the chain is clamping components individually — that is exactly the behaviour this block exists to replace.
Confirm the output’s length equals upperLimit while limiting.

Tuning

There is nothing to tune beyond the one bound.

Set upperLimit from the consumer, not from the signal. For a tool velocity it is the machine’s rated speed; for a force it is what the structure can take.
Watch isLimiting during normal operation. Persistent limiting means something upstream is commanding more than the machine can deliver, and that is usually the real problem.
If individual components also need bounds — a per-axis speed limit as well as a tool speed limit — add a Limiter after this one. Order matters: this block first keeps the direction, and the per-component clamp afterwards catches anything still out of range.
Nothing here needs re-checking after a task-rate change.

Read each limit off the height at which its line goes flat.

Symptom	Cause	Action
Nothing is limited and `isLimiting` stays false	`enable` defaults to false	Set `enable` true
The output points the opposite way from the input	`upperLimit` is negative	Set it positive
The output collapses to zero whenever the input moves	`upperLimit` is 0	Set a positive limit
The direction changes when the limit bites	Not possible in this block — something downstream is clamping components individually	Check what follows this block
The limit bites at a length that makes no sense	The vector mixes units, so its computed length is not physical	Use one instance per unit group
The output stepped when the block was enabled	Expected: the block is memoryless and clamps at once	Enable while the vector is inside the limit
One component is still too large	Expected: this block bounds the whole vector’s length, not any one component	Add a per-component limiter after it
`isLimiting` is a single value, not one per channel	Expected: the vector is limited as a whole	Use a per-component limiter if you need per-channel flags
Limiting is persistent during ordinary motion	The limit is too low, or something upstream is over-commanding	Check the command before raising the limit
A non-numeric component passed straight through	Expected: the length comparison fails and the block copies through	Fix the source; the block holds no state and recovers at once
You need a minimum length as well	Not available — a zero-length vector has no direction to grow in	Handle it upstream

A starting point for bounding a three-axis Cartesian velocity to 0.25 m/s:

enable     = true
upperLimit = 0.25

Limits and errors

Limit	Set by	What happens	Reported
`upperLimit` non-negative	Nothing	Not checked. A negative value scales every component by a negative factor, so the output points the opposite way at the limit’s magnitude	Not reported
`upperLimit` = 0	Fixed	Any non-zero vector is collapsed to zero	`isLimiting` reads true
`output` length	`upperLimit` while enabled	Bounded exactly. Unbounded while `enable` is false	`isLimiting`, one flag for the vector
Individual components	Nothing	Not bounded. A long vector along one axis is scaled, but nothing caps any single component on its own	Not reported
Unit consistency	Nothing	Not checked, and cannot be. A vector mixing units has a length with no physical meaning	Not reported
Lower limit	Not available	There is none, by design: a zero-length vector has no direction to scale toward	Not applicable
Enabling	Fixed	The block is memoryless, so a vector already too long is scaled on the first enabled cycle — a step	Not reported
Non-numeric input	Nothing	Passes through unchanged. The block is stateless and recovers immediately	Not reported
Channel count	Machine configuration	Fixed once the controller starts	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: RateLimiter

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

Control3 3.30–3.34

RateLimiter caps how fast a signal may change. Where a limiter bounds a signal’s value, this bounds its slope: the output follows the input wherever it can, and ramps toward it at no more than rateLimit per second wherever it cannot.

Use it to take a step out of a command — a mode switch, a new setpoint typed in by an operator, a discontinuous reference — without a filter’s lag. Below the rate limit the output is the input exactly. Only when the limit binds does the block do anything at all.

flowchart LR
    i1(["input — signal to slew"]) --> B["RateLimiter"]
    i2(["disable"]) --> B
    B --> o1(["output — rate-limited signal"])
    B --> o2(["isLimiting — per channel"])
    B --> o3(["isEnabled"])

rateLimit is in units per second, so a step of height $H$ takes $H/$rateLimit seconds to follow. The setting keeps its meaning across task rates — unlike the sample-counted blocks, nothing needs rescaling if the task period changes.

Disabling this block lets the signal jump. The output snaps to the input on the same cycle. That is the one thing not to do while the machine is moving — raise rateLimit instead until it no longer binds.

After a controller start the output ramps up from zero, taking input ÷ rateLimit seconds to catch up.

Signals

Inputs

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

Outputs

Path	Unit	Description
`output`	signal unit	The rate-limited signal, one element per channel. Equals `input` exactly whenever the input’s slope is inside the limit, and while bypassed. Starts from zero after every controller start and is not cleared by a stop.
`isLimiting`	-	True per channel on cycles where the output was actually clamped. It is exact — no false positives.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	Ships on. False bypasses the block, letting the signal step.
`rateLimit`	signal unit per second	1.0	0 upward, per channel	The fastest the output may change. Lower is gentler and slower to follow. 0 freezes the output where it is. Not checked — a negative value makes the output run away.

Both are persistent and survive a controller restart. rateLimit is per channel. No parameters exist below this block.

Setup

Work out the fastest change the consumer can accept, in units per second. That is your rateLimit — it is a property of the machine, not of the signal.
Set rateLimit for every channel. The default of 1.0 is a placeholder.
Set enable true and confirm isEnabled reads true.
Step the input and time how long output takes to catch up. It should be the step height divided by rateLimit.
Move the input at a normal working speed and confirm output tracks it exactly, with isLimiting reading false.

Step 5 is the check that the limit is not in your way. If isLimiting is true during normal motion, the limit is shaping every move and not just the steps — raise it until it only bites on the discontinuities.
Trace every element of input, output and isLimiting. Rates are per channel.

Tuning

Set the rate from the machine, not from the signal. It is the slope the consumer downstream can absorb.
Confirm it does not bind during normal motion, per Setup step 5. A rate limiter that is always active has become a slow ramp generator.
Lower it only until steps are absorbed comfortably. Every reduction also delays genuine fast movements.
If you need smoothing as well as slope limiting, add a filter — this block only bounds the slope, and leaves corners at the start and end of every ramp.
If the corners themselves are a problem, you need acceleration limiting, not rate limiting. A PVA limiter bounds the rate of the rate.
Nothing here needs re-checking after a task-rate change. The rate is in units per second and keeps its meaning.

Read the rate off the slope of any ramp.

Symptom	Cause	Action
The output ramps up from zero for a while after every start	Expected: the output starts at zero and slews to the input	Gate the consumer for input ÷ `rateLimit` seconds, or bypass for one cycle to seed it
The output jumped when the block was bypassed	Expected: bypassing assigns the input directly	Raise `rateLimit` until it no longer binds, then bypass
The output froze and will not move	`rateLimit` is 0 for that channel	Set a positive rate
The output runs away in one direction	`rateLimit` is negative	Set it positive, then bypass for one cycle to re-seed the output
`isLimiting` is true during ordinary motion	The rate is too low for normal moves	Raise it, per Tuning step 2
Motion is slower than commanded everywhere	Same cause	Raise the rate
Steps still reach the consumer	`enable` is false, `disable` is true, or the rate is far above the step’s slope	Read `isEnabled`; lower `rateLimit`
The output has sharp corners at the start and end of each ramp	Expected: this block bounds slope only, not acceleration	Use a PVA limiter if the corners matter
A sine wave came out as a triangle	Expected: the rate limit is below the sine’s peak slope	Raise the rate above 2π × frequency × amplitude
One channel slews differently from the others	Expected: `rateLimit` is per channel	Check every element
The behaviour changed after a task-rate change	Not possible — the rate is in units per second	Look elsewhere in the loop
The output stuck at a non-numeric value	A non-numeric input latched into the output, which then poisons every bound	Bypass the block for one cycle to clear it, then fix the source
The block resumed from an old value after a restart	Expected: the output is not cleared by a stop	Bypass for one cycle at start

A starting point for slewing a position command that may move at 0.5 units per second:

enable    = true
rateLimit = 0.5

Limits and errors

Limit	Set by	What happens	Reported
`rateLimit` non-negative	Nothing	Not checked. A negative value makes the output decrease every cycle without bound. Only bypassing the block or a restart clears it	Not reported
`rateLimit` = 0	Fixed	Freezes the output at its current value. This is legitimate and is the way to hold a signal	`isLimiting` reads true
`output` slope	`rateLimit` while enabled	Bounded exactly, with no overshoot and no lag inside the bound	`isLimiting`, per channel
`output` value	Nothing	Unbounded — this block limits slope, not magnitude. Follow it with a limiter if the value needs a bound	Not reported
Disabled behaviour	Fixed	Exact pass-through, so the output steps to the input	Not reported
Output state	Nothing	Not cleared at start or stop. There is no reset input — bypassing for one cycle is the only way to re-seed it	Not reported
Non-numeric input	Nothing	Latches permanently: once the output is non-numeric every bound derived from it is too. Bypass for one cycle to clear	Not reported
Task rate	Independent	`rateLimit` is in units per second and keeps its meaning at any task period	Not applicable
Channel count	Machine configuration	Fixed once the controller starts	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: RateLimiter3D

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

Control3 3.30–3.34

RateLimiter3D caps how fast a point in three dimensions may move. Each cycle it moves the output along a straight line toward the target, by no more than rateLimit per second.

It is the vector form of RateLimiter, and the difference matters. Limiting each axis’s rate separately makes a diagonal move bend — the axis that saturates first falls behind while the others carry on, so the path through space changes and not just its speed. Scaling the whole step keeps the point travelling in a straight line toward where it was told to go.

flowchart LR
    i1(["inputs — target point, three values"]) --> B["RateLimiter3D"]
    B --> o1(["outputs — rate-limited point, three values"])
    B --> o2(["active — true while limiting"])

rateLimit is the maximum speed through space, in units per second, and it applies to the whole vector — a diagonal move is limited to the same speed as a move along one axis. The setting keeps its meaning across task rates. While the target is close enough to reach in one cycle, the output arrives exactly and active reads false.

Both defaults leave the block transparent. enable is false, and rateLimit starts at the largest number a double can hold. You must set both.

This block has no disable input and no isEnabled output, unlike every other limiter here. enable is the only switch, and active tells you it is limiting — not that it is switched on.

After a controller start the output begins at the origin and travels to wherever inputs points. On a position command that is a commanded move from zero — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`inputs`	m, or any shared unit	unbounded	The target point, as three values. All three must share a unit for the speed limit to mean anything. Note the path name is plural.

Outputs

Path	Unit	Description
`outputs`	m, or the input unit	The rate-limited point, three values. It travels toward `inputs` in a straight line at no more than `rateLimit`, and arrives exactly once the remaining distance fits in one cycle. Starts at the origin after every controller start and is not cleared by a stop. Note the plural path name.
`active`	-	True while the step is being scaled — the equivalent of `isLimiting` on the other limiters, under a different name. False while the output is keeping up.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	False passes `inputs` straight to `outputs`, as a step. Set this, or the block does nothing.
`rateLimit`	unit per second	effectively unlimited	0 upward	The maximum speed through space. The default is so large that the block is transparent even when enabled — set a real value. 0 freezes the point. Not checked — a negative value drives the output away from the target.

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

Setup

Confirm all three elements of inputs share a unit — three positions in metres, or three velocities in metres per second. A mixed vector has no meaningful speed.
Set rateLimit to the maximum speed the machine may travel at. The default is not a limit.
Set enable true.
Command a target close to the current point and confirm outputs reaches it in one cycle with active reading false.
Command a distant target and confirm active goes true, outputs moves toward it, and the ratios between the three components of the remaining distance stay constant — that is what a straight path looks like.

Step 5 is the check that the path is straight. If the ratios drift, something downstream is limiting the axes separately, which is exactly what this block exists to replace.
Time the move and divide the distance travelled by it. That should equal rateLimit.
Plan for the first cycle after a start. The output begins at the origin, so with a real rate configured the block will command a straight-line move from zero to the current target. Gate the consumer, or command the machine’s actual position first.

Tuning

Set the rate from the machine, not from the signal — it is the fastest the point may travel.
Confirm it does not bind during ordinary moves. active true all the time means the limit has become the speed governor rather than a safety net.
If you need the corners of the ramp smoothed as well, this block cannot do it: it bounds speed, not acceleration. A PVA limiter bounds the rate of the rate.
If individual axes also need a bound, add a per-axis limiter after this one — this block keeps the direction, and the per-axis clamp catches anything still out of range.
Nothing here needs re-checking after a task-rate change. The rate is in units per second.

Read the speed off the slope of any ramp.

Symptom	Cause	Action
Nothing is limited and `active` stays false	`enable` is false, or `rateLimit` is still at its enormous default	Set both
The machine made a long move immediately after a restart	Expected: the output starts at the origin and travels to the target	Command the machine’s actual position first, or gate the consumer
The output moves away from the target	`rateLimit` is negative	Set it positive, then disable for one cycle to re-seed the output
The output froze	`rateLimit` is 0	Set a positive rate
The path bends instead of running straight	Not possible in this block — something downstream is limiting the axes separately	Check what follows this block
The point jumped when the block was disabled	Expected: disabling assigns the target directly	Raise `rateLimit` until it no longer binds, then disable
`active` is true during ordinary moves	The rate is too low for normal motion	Raise it
The speed limit bites at a value that makes no sense	The three inputs do not share a unit	Use this block only on a vector with one unit
There is no way to override the block at runtime	Expected: there is no `disable` input	Write `enable` false, or raise `rateLimit`
I cannot tell whether the block is switched on	Expected: there is no `isEnabled` output. `active` means limiting, not enabled	Read `enable` back
The path has sharp corners at the start and end	Expected: this block bounds speed only	Use a PVA limiter if the corners matter
The outputs stuck at a non-numeric value	A non-numeric input latched into the output, which then poisons every step	Disable for one cycle to clear it, then fix the source

A starting point for limiting a Cartesian position command to 0.25 m/s:

enable    = true
rateLimit = 0.25

Limits and errors

Limit	Set by	What happens	Reported
`rateLimit` non-negative	Nothing	Not checked. A negative value drives the output away from the target, without bound. Only disabling the block or a restart clears it	Not reported
`rateLimit` = 0	Fixed	Freezes the point where it is	`active` reads true
`rateLimit` default	Fixed	Effectively unlimited, so an enabled but unconfigured block is transparent	Not reported
Speed through space	`rateLimit` while enabled	Bounded exactly, with the direction preserved	`active`
Individual axes	Nothing	Not bounded. This block limits the vector’s speed, not any one axis	Not reported
Position	Nothing	Unbounded — this block limits speed, not travel. Follow it with a limiter if the value needs a bound	Not reported
Startup position	Fixed	The output starts at the origin, not at the current target. There is no reset input	Not reported
Disabled behaviour	Fixed	Exact pass-through, so the point steps to the target	Not reported
Runtime override	Not available	There is no `disable` input and no `isEnabled` output	Not applicable
Non-numeric input	Nothing	Latches permanently — once an output is non-numeric every step derived from it is too. Disable for one cycle to clear	Not reported
Dimensions	Fixed	Always three channels. It cannot be resized	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: PVALimiter

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

Control3 Superseded. The current release is 3.34.

PVALimiter shapes a position command so the motion it produces respects a position range, a velocity limit and an acceleration limit all at once. It outputs a matching position, velocity and acceleration, so whatever follows it gets a consistent set.

Its most useful behaviour is at the position limits. Instead of clamping the position — which arrives as a wall and demands an impossible deceleration — it works out, every cycle, the fastest it could be going and still stop in time, and holds the velocity below that. The axis decelerates into the limit and arrives at zero speed.

flowchart LR
    i1(["input — position reference"]) --> B["PVALimiter"]
    i2(["inputDot — velocity reference"]) --> B
    i3(["inputDDot — acceleration reference"]) --> B
    i4(["disable"]) --> B
    B --> o1(["output — limited position"])
    B --> o2(["outputDot — limited velocity"])
    B --> o3(["outputDDot — limited acceleration"])
    B --> o4(["currentMaxVel — allowed velocity now"])
    B --> o5(["currentMinVel"])
    B --> o6(["pLimActive"])
    B --> o7(["vLimActive"])
    B --> o8(["aLimActive"])
    B --> o9(["state"])
    B --> o10(["inputFilt, inputFiltDot, inputFiltDDot"])
    B --> o11(["isEnabled"])

Approaching a limit, the allowed velocity is $\sqrt{2 \times \text{distance} \times \texttt{maxBrakingAcceleration}}$ — so at 0.1 m from the limit with a braking limit of 10, the axis may travel at 1.4 m/s. omega and beta set how hard the block chases the input: higher omega tracks more tightly, and beta 4 is heavily damped so it does not overshoot.

Keep maxBrakingAcceleration at or below maxAcceleration. The block sizes its approach speed on the braking figure but can only ever deliver the acceleration figure. Setting braking higher promises a stop the block cannot perform, and the axis overshoots the limit.

Every instance logs a warning at startup with default settings. omega ships at infinity, meaning “as fast as possible”, and the block corrects it to what the task rate allows — and says so in the log. It is expected.

Signals

Inputs

Path	Unit	Range	Description
`input`	m or rad	unbounded	The position reference to shape.
`inputDot`	m/s or rad/s	unbounded	The velocity reference. Only used when `enablePVAInputs` is set; ignored otherwise.
`inputDDot`	m/s² or rad/s²	unbounded	The acceleration reference. Same condition.
`disable`	-	-	True bypasses the block: `input` passes straight to `output`. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	m or rad	The limited position. Starts from zero after every controller start and moves to the input under its own limits — a real commanded move if the input is not near zero.
`outputDot`	m/s or rad/s	The limited velocity. It is not updated while the block is bypassed, so it holds a stale value from before.
`outputDDot`	m/s² or rad/s²	The limited acceleration.
`currentMaxVel`	m/s or rad/s	The fastest the block will currently allow, given how close the axis is to the upper limit. The single most useful output for understanding why the axis slowed down.
`currentMinVel`	m/s or rad/s	The same toward the lower limit.
`pLimActive`	-	True while the position envelope is holding the velocity down.
`vLimActive`	-	True while the velocity limit is binding.
`aLimActive`	-	True while the acceleration limit is binding — but it is forced false whenever either of the other two is true, so it under-reports.
`state`	-	The same three flags again, grouped.
`inputFilt`, `inputFiltDot`, `inputFiltDDot`	m, m/s, m/s²	The block’s internal smoothed copy of the input. Only meaningful while `enablePVAInputs` is false.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	False bypasses the block.
`lowerLimit`	m or rad	−1.0	below `upperLimit`	The lowest position the output may reach.
`upperLimit`	m or rad	+1.0	above `lowerLimit`	The highest.
`maxVelocity`	m/s or rad/s	1.0	above 0	Speed limit. Negative values are used as their magnitude.
`maxAcceleration`	m/s² or rad/s²	10.0	above 0	How hard the block may accelerate or decelerate in practice. Used as its magnitude.
`maxBrakingAcceleration`	m/s² or rad/s²	10.0	at most `maxAcceleration`	How hard the block assumes it can brake, when sizing the approach to a position limit. Set it at or below `maxAcceleration` — see Limits and errors.
`omega`	rad/s	infinity	0 up to a task-rate ceiling	Tracking bandwidth. Higher follows the input more tightly. The infinite default means “as fast as the task rate allows” and is corrected at startup with a logged warning.
`beta`	-	4.0	above 0	Tracking damping. 4 is heavily damped and does not overshoot. Lowering it makes the output chase harder and eventually ring.
`enablePLim`	-	true	-	Switches the position envelope and the hard position clamp on. False leaves only the velocity and acceleration limits.
`enablePVAInputs`	-	false	-	False: the block derives velocity and acceleration internally from `input` alone. True: it uses `inputDot` and `inputDDot`. This changes how the block tracks, not just what it reads — decide once and leave it.

All ten are persistent and survive a restart. No parameters exist below this block.

Setup

Set lowerLimit and upperLimit to the axis’s real travel.
Set maxVelocity and maxAcceleration from the machine.
Set maxBrakingAcceleration equal to or below maxAcceleration. Equal is the normal choice.
Leave omega alone. It corrects itself at startup and logs that it did.
Leave beta at 4 and enablePVAInputs false for a first pass.
Set enable true. Command a small move well inside the limits and confirm output follows input closely with all three flags false.
Command a fast move and watch vLimActive and aLimActive go true in turn.
Command a move that runs into a position limit. Watch currentMaxVel fall as the axis approaches, and confirm the axis arrives at the limit with outputDot at zero.

Step 8 drives the axis into its travel limit deliberately. Do it at low speed first, and confirm the deceleration is inside what the machine can take before repeating it at full speed.

Tuning

Set the three machine limits first — position, velocity, acceleration. They are properties of the hardware.
Keep braking at or below acceleration, per Setup step 3. This is the one parameter relationship the block does not check and it is the one that causes overshoot.
Leave omega at its default unless the output visibly lags the input during ordinary moves. It is already as fast as the task rate allows.
Lower beta only if the block is too slow to catch a fast input. Below about 1 it starts to overshoot, which for a limiter is the wrong direction.
Use enablePVAInputs when your source already produces a consistent position, velocity and acceleration — a setpoint generator, say. It lets the block follow without having to infer the derivatives, so it tracks much more closely. Do not switch it at runtime.
Watch currentMaxVel during a limit approach. It is the envelope, and it tells you directly whether maxBrakingAcceleration is set sensibly: a larger value gives a steeper, later deceleration.
If you need jerk limited as well, this block does not do it — use a PVAJ limiter.

Read the allowed speed at any distance off the curve for your braking setting.

Symptom	Cause	Action
A warning about `omega` at every startup	Expected: the default is infinity and the block corrects it	Ignore it, or set a finite `omega`
The axis overshoots its position limit	`maxBrakingAcceleration` is higher than `maxAcceleration`	Set it at or below the acceleration limit
The axis stops well short of the limit and creeps in	`maxBrakingAcceleration` is very low, so the envelope is conservative	Raise it, up to `maxAcceleration`
The axis slows down and nothing seems to be limiting	The position envelope is active — check `pLimActive` and `currentMaxVel`	This is the block working as designed
`aLimActive` never goes true	Expected: it is suppressed whenever the position or velocity limit is also active	Watch all three flags together
The output lags the input during ordinary moves	`omega` too low, or `beta` too high	Leave `omega` alone and try `enablePVAInputs` if your source provides derivatives
The output overshoots the input	`beta` too low	Raise it back toward 4
Tracking changed when `enablePVAInputs` was switched	Expected: it changes how the block tracks, not just what it reads	Choose one mode and keep it
`inputDot` and `inputDDot` seem to be ignored	Expected: they are only read when `enablePVAInputs` is true	Set that parameter
The axis made a move immediately after a restart	Expected: the output starts at zero and travels to the input under its limits	Command the machine’s actual position first, or gate the consumer
The velocity output is wrong just after re-enabling	Expected: `outputDot` is not updated while bypassed and resumes from a stale value	Re-enable at rest
The position stopped at the limit but the velocity output is not zero	The hard backstop clamped the position without zeroing the velocity — the envelope did not do its job	Check `maxBrakingAcceleration` against `maxAcceleration`
Motion is jerky at the start and end of moves	Expected: this block bounds acceleration, not jerk	Use a PVAJ limiter
A non-numeric value latched into the outputs	The block holds state and there is no reset	Bypass the block for one cycle to recover the position; restart to clear the velocity

A starting point for an axis with 1 m of travel, 1 m/s and 10 m/s² on a 1 ms task:

enable                 = true
lowerLimit             = -0.5
upperLimit             = 0.5
maxVelocity            = 1.0
maxAcceleration        = 10.0
maxBrakingAcceleration = 10.0
beta                   = 4.0
enablePLim             = true
enablePVAInputs        = false

Limits and errors

Limit	Set by	What happens	Reported
`maxBrakingAcceleration` at most `maxAcceleration`	Nothing	Not checked. A higher braking figure makes the block approach the limit faster than it can stop, and the axis overshoots	Not reported
`output` position	`lowerLimit`, `upperLimit` while `enablePLim` is set	Bounded two ways: the velocity envelope decelerates the axis in, and a hard clamp catches anything the envelope missed. The clamp does not zero the velocity, so the two outputs can disagree on that cycle	`pLimActive`
`outputDot`	`maxVelocity`, and the position envelope	Bounded by whichever is lower	`vLimActive`, `currentMaxVel`, `currentMinVel`
`outputDDot`	`maxAcceleration`	Clamped	`aLimActive`, but it is suppressed whenever the position or velocity limit is also active
Jerk	Nothing	Not limited. Acceleration can step	Not reported
`omega`	Task rate and `beta`	Corrected to a stable value at startup and on every cycle. The infinite default always triggers this	Logged as a warning each time it corrects
`beta`, `maxVelocity`, `maxAcceleration`, `maxBrakingAcceleration`	Sign forced	Negative values are used as their magnitude	Not reported; read them back
Zero acceleration limits	Fixed	Either at exactly zero forces the allowed velocity to zero, stopping the axis where it stands	`pLimActive`
Block state	Nothing	The output position and velocity are not cleared at start and there is no reset input. Bypassing recovers the position but not the velocity	Not reported
Channel count	Fixed	One axis per instance. Use the plural block for several	Not reported

The block logs a warning whenever it corrects omega or beta — which with the default settings happens once at startup for every instance. Every other failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: PVALimiter

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

Control3 Current release

Deprecated — scheduled for removal. PvajLimiter is the only setpoint limiter that may be used for new work. It bounds the setpoint in jerk as well as position, velocity and acceleration, and its position guarantee holds with no tolerance where this block’s holds to about 1e-9. This block is kept only until the last machine is off it, and will then be deleted.

It is not a drop-in swap. The replacement has no input filter, so omega, beta and enablePVAInputs have no counterpart. Feed it the position setpoint directly and supply the derivatives on its own inputDot and inputDDot leaves, each behind its own switch. See PvajLimiter for the parameter reference.

flowchart LR
    i1(["input — position reference"]) --> B["PVALimiter"]
    i2(["inputDot — velocity reference"]) --> B
    i3(["inputDDot — acceleration reference"]) --> B
    i4(["disable"]) --> B
    B --> o1(["output — limited position"])
    B --> o2(["outputDot — limited velocity"])
    B --> o3(["outputDDot — limited acceleration"])
    B --> o4(["currentMaxVel — allowed velocity now"])
    B --> o5(["currentMinVel"])
    B --> o6(["pLimActive"])
    B --> o7(["vLimActive"])
    B --> o8(["aLimActive"])
    B --> o9(["state"])
    B --> o10(["inputFilt, inputFiltDot, inputFiltDDot"])
    B --> o11(["isEnabled"])

Approaching a limit, the allowed velocity is $\sqrt{2 \times \text{distance} \times \texttt{maxBrakingAcceleration}}$ — so at 0.1 m from the limit with a braking limit of 10, the axis may travel at 1.4 m/s. omega and beta set how hard the block chases the input: higher omega tracks more tightly, and beta 4 is heavily damped so it does not overshoot.

Signals

Inputs

Path	Unit	Range	Description
`input`	m or rad	unbounded	The position reference to shape.
`inputDot`	m/s or rad/s	unbounded	The velocity reference. Only used when `enablePVAInputs` is set; ignored otherwise.
`inputDDot`	m/s² or rad/s²	unbounded	The acceleration reference. Same condition.
`disable`	-	-	True bypasses the block: `input` passes straight to `output`. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	m or rad	The limited position. Starts from zero after every controller start and moves to the input under its own limits — a real commanded move if the input is not near zero.
`outputDot`	m/s or rad/s	The limited velocity. It is not updated while the block is bypassed, so it holds a stale value from before.
`outputDDot`	m/s² or rad/s²	The limited acceleration.
`currentMaxVel`	m/s or rad/s	The fastest the block will currently allow, given how close the axis is to the upper limit. The single most useful output for understanding why the axis slowed down.
`currentMinVel`	m/s or rad/s	The same toward the lower limit.
`pLimActive`	-	True while the position envelope is holding the velocity down.
`vLimActive`	-	True while the velocity limit is binding.
`aLimActive`	-	True while the acceleration limit is binding — but it is forced false whenever either of the other two is true, so it under-reports.
`state`	-	The same three flags again, grouped.
`inputFilt`, `inputFiltDot`, `inputFiltDDot`	m, m/s, m/s²	The block’s internal smoothed copy of the input. Only meaningful while `enablePVAInputs` is false.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	False bypasses the block.
`lowerLimit`	m or rad	−1.0	below `upperLimit`	The lowest position the output may reach.
`upperLimit`	m or rad	+1.0	above `lowerLimit`	The highest.
`maxVelocity`	m/s or rad/s	1.0	above 0	Speed limit. Negative values are used as their magnitude.
`maxAcceleration`	m/s² or rad/s²	10.0	above 0	How hard the block may accelerate or decelerate in practice. Used as its magnitude.
`maxBrakingAcceleration`	m/s² or rad/s²	10.0	at most `maxAcceleration`	How hard the block assumes it can brake, when sizing the approach to a position limit. Set it at or below `maxAcceleration` — see Limits and errors.
`omega`	rad/s	infinity	0 up to a task-rate ceiling	Tracking bandwidth. Higher follows the input more tightly. The infinite default means “as fast as the task rate allows” and is corrected at startup with a logged warning.
`beta`	-	4.0	above 0	Tracking damping. 4 is heavily damped and does not overshoot. Lowering it makes the output chase harder and eventually ring.
`enablePLim`	-	true	-	Switches the position envelope and the hard position clamp on. False leaves only the velocity and acceleration limits.
`enablePVAInputs`	-	false	-	False: the block derives velocity and acceleration internally from `input` alone. True: it uses `inputDot` and `inputDDot`. This changes how the block tracks, not just what it reads — decide once and leave it.

All ten are persistent and survive a restart. No parameters exist below this block.

Setup

Set lowerLimit and upperLimit to the axis’s real travel.
Set maxVelocity and maxAcceleration from the machine.
Set maxBrakingAcceleration equal to or below maxAcceleration. Equal is the normal choice.
Leave omega alone. It corrects itself at startup and logs that it did.
Leave beta at 4 and enablePVAInputs false for a first pass.
Set enable true. Command a small move well inside the limits and confirm output follows input closely with all three flags false.
Command a fast move and watch vLimActive and aLimActive go true in turn.
Command a move that runs into a position limit. Watch currentMaxVel fall as the axis approaches, and confirm the axis arrives at the limit with outputDot at zero.

Step 8 drives the axis into its travel limit deliberately. Do it at low speed first, and confirm the deceleration is inside what the machine can take before repeating it at full speed.

Tuning

Set the three machine limits first — position, velocity, acceleration. They are properties of the hardware.
Keep braking at or below acceleration, per Setup step 3. This is the one parameter relationship the block does not check and it is the one that causes overshoot.
Leave omega at its default unless the output visibly lags the input during ordinary moves. It is already as fast as the task rate allows.
Lower beta only if the block is too slow to catch a fast input. Below about 1 it starts to overshoot, which for a limiter is the wrong direction.
Use enablePVAInputs when your source already produces a consistent position, velocity and acceleration — a setpoint generator, say. It lets the block follow without having to infer the derivatives, so it tracks much more closely. Do not switch it at runtime.
Watch currentMaxVel during a limit approach. It is the envelope, and it tells you directly whether maxBrakingAcceleration is set sensibly: a larger value gives a steeper, later deceleration.
If you need jerk limited as well, this block does not do it — use a PVAJ limiter.

Read the allowed speed at any distance off the curve for your braking setting.

Symptom	Cause	Action
A warning about `omega` at every startup	Expected: the default is infinity and the block corrects it	Ignore it, or set a finite `omega`
The axis overshoots its position limit	`maxBrakingAcceleration` is higher than `maxAcceleration`	Set it at or below the acceleration limit
The axis stops well short of the limit and creeps in	`maxBrakingAcceleration` is very low, so the envelope is conservative	Raise it, up to `maxAcceleration`
The axis slows down and nothing seems to be limiting	The position envelope is active — check `pLimActive` and `currentMaxVel`	This is the block working as designed
`aLimActive` never goes true	Expected: it is suppressed whenever the position or velocity limit is also active	Watch all three flags together
The output lags the input during ordinary moves	`omega` too low, or `beta` too high	Leave `omega` alone and try `enablePVAInputs` if your source provides derivatives
The output overshoots the input	`beta` too low	Raise it back toward 4
Tracking changed when `enablePVAInputs` was switched	Expected: it changes how the block tracks, not just what it reads	Choose one mode and keep it
`inputDot` and `inputDDot` seem to be ignored	Expected: they are only read when `enablePVAInputs` is true	Set that parameter
The axis made a move immediately after a restart	Expected: the output starts at zero and travels to the input under its limits	Command the machine’s actual position first, or gate the consumer
The velocity output is wrong just after re-enabling	Expected: `outputDot` is not updated while bypassed and resumes from a stale value	Re-enable at rest
The position stopped at the limit but the velocity output is not zero	The hard backstop clamped the position without zeroing the velocity — the envelope did not do its job	Check `maxBrakingAcceleration` against `maxAcceleration`
Motion is jerky at the start and end of moves	Expected: this block bounds acceleration, not jerk	Use a PVAJ limiter
A non-numeric value latched into the outputs	The block holds state and there is no reset	Bypass the block for one cycle to recover the position; restart to clear the velocity

A starting point for an axis with 1 m of travel, 1 m/s and 10 m/s² on a 1 ms task:

enable                 = true
lowerLimit             = -0.5
upperLimit             = 0.5
maxVelocity            = 1.0
maxAcceleration        = 10.0
maxBrakingAcceleration = 10.0
beta                   = 4.0
enablePLim             = true
enablePVAInputs        = false

Limits and errors

Limit	Set by	What happens	Reported
`maxBrakingAcceleration` at most `maxAcceleration`	Nothing	Not checked. A higher braking figure makes the block approach the limit faster than it can stop, and the axis overshoots	Not reported
`output` position	`lowerLimit`, `upperLimit` while `enablePLim` is set	Bounded two ways: the velocity envelope decelerates the axis in, and a hard clamp catches anything the envelope missed. The clamp does not zero the velocity, so the two outputs can disagree on that cycle	`pLimActive`
`outputDot`	`maxVelocity`, and the position envelope	Bounded by whichever is lower	`vLimActive`, `currentMaxVel`, `currentMinVel`
`outputDDot`	`maxAcceleration`	Clamped	`aLimActive`, but it is suppressed whenever the position or velocity limit is also active
Jerk	Nothing	Not limited. Acceleration can step	Not reported
`omega`	Task rate and `beta`	Corrected to a stable value at startup and on every cycle. The infinite default always triggers this	Logged as a warning each time it corrects
`beta`, `maxVelocity`, `maxAcceleration`, `maxBrakingAcceleration`	Sign forced	Negative values are used as their magnitude	Not reported; read them back
Zero acceleration limits	Fixed	Either at exactly zero forces the allowed velocity to zero, stopping the axis where it stands	`pLimActive`
Block state	Nothing	The output position and velocity are not cleared at start and there is no reset input. Bypassing recovers the position but not the velocity	Not reported
Channel count	Fixed	One axis per instance. Use the plural block for several	Not reported

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: PVALimiters

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

Control3 Superseded. The current release is 3.34.

PVALimiters is the multi-axis form of PVALimiter. It takes array inputs, runs one independent limiter per channel, and returns array outputs — so a multi-axis machine presents one block instead of several.

Each channel keeps its own limits. Every axis has a complete parameter set in its own sub-tree: its own travel range, speed, acceleration and tracking settings. This block only fans the signals out and gathers them back.

flowchart LR
    i1(["inputs — position references"]) --> B["PVALimiters"]
    i2(["inputsDot — velocity references"]) --> B
    i3(["inputsDDot — acceleration references"]) --> B
    B --> o1(["outputs — limited positions"])
    B --> o2(["outputsDot — limited velocities"])
    B --> o3(["outputsDDot — limited accelerations"])
    B --> o4(["pLimActive"])
    B --> o5(["vLimActive"])
    B --> o6(["aLimActive"])
    B --> o7(["state"])

Each channel behaves exactly as PVALimiter describes, including the square-root velocity envelope that decelerates an axis into its position limit. Read that page for the tuning — everything below is about the wrapper.

The three limiting flags are combined across channels. pLimActive true means some axis is at its position envelope; it does not say which. To find out, read the same flag inside each channel’s own sub-tree.

inputsDDot has no effect. The acceleration array is accepted and ignored — the sub-limiters never receive it. Leave it unlinked.

This block has no enable, no disable and no isEnabled. To bypass one axis, use disable inside that channel’s own sub-tree.

Signals

Inputs

Path	Unit	Range	Description
`inputs`	m or rad	unbounded	Position references, one element per channel. Note the plural path names throughout this block.
`inputsDot`	m/s or rad/s	unbounded	Velocity references. They reach each channel’s limiter, and are used only where that channel has its own `enablePVAInputs` set.
`inputsDDot`	m/s² or rad/s²	-	Accepted and ignored. The acceleration array does not reach the per-channel limiters. Leave it unlinked.

Outputs

Path	Unit	Description
`outputs`	m or rad	The limited positions, one element per channel. Each starts from zero after a controller start and moves to its input under that channel’s limits.
`outputsDot`	m/s or rad/s	The limited velocities.
`outputsDDot`	m/s² or rad/s²	The limited accelerations.
`pLimActive`	-	True while at least one channel is being held back by its position envelope.
`vLimActive`	-	True while at least one channel is at its speed limit.
`aLimActive`	-	True while at least one channel is at its acceleration limit. Like the single-axis block, it is suppressed on any channel where a position or velocity limit is also active, so it under-reports.
`state`	-	The same three flags again, grouped.

Parameters

There are no parameters at this level. Everything is configured per channel, in the sub-trees pvaLimiter01, pvaLimiter02 and so on — one per channel, numbered from 1 and always two digits.

Each of those carries the full set described in pva-limiter.md: lowerLimit, upperLimit, maxVelocity, maxAcceleration, maxBrakingAcceleration, omega, beta, enable, disable, enablePLim and enablePVAInputs, along with that channel’s own outputs and diagnostics.

Setup

Read the length of inputs from the parameter tree and confirm it matches your axis count. It is fixed when the machine is built.
Configure each channel’s sub-tree separately: travel limits, speed and acceleration for that axis. There is no shared setting — an axis you forget keeps the defaults of ±1, 1 m/s and 10 m/s².
Set maxBrakingAcceleration at or below maxAcceleration in every channel. This is the one relationship that silently causes overshoot, per axis.
Link inputs and, if your source produces them, inputsDot. Leave inputsDDot unlinked.
Command a small move on one axis and confirm only that channel’s outputs element responds.

Step 5 is the check that the channels are independent. If moving one axis changes another’s output, the arrays are wired in the wrong order — and every limit you set afterwards will be applied to the wrong axis.
Command a move that runs into a position limit on one axis. Confirm pLimActive goes true here, and that the same flag is true in that channel’s own sub-tree and false in the others.
Expect one startup warning per channel about omega. It is normal — see pva-limiter.md.

Tuning

All the tuning is per channel and is described in pva-limiter.md. What is specific to this block:

Tune one axis at a time, in its own sub-tree, with the others held still. The aggregate flags cannot tell you which axis is limiting.
Keep a written record of which sub-tree is which axis. The numbering starts at 1 and the array indices start at 0, so pvaLimiter01 is element 0.
When the aggregate pLimActive goes true unexpectedly, walk the sub-trees and read each channel’s own pLimActive to find the axis. There is no faster route.
Watch each channel’s currentMaxVel during a limit approach — it is the most informative signal in the block and there is one per axis.
If several axes should move together and stop together, note that this block does not coordinate them: each is limited independently, so a limited axis falls behind and the path through space changes. Coordinate upstream if that matters.

Read each channel’s behaviour the same way; the axes do not interact.

Symptom	Cause	Action
One axis behaves nothing like the others	That channel’s sub-tree was never configured, so it holds the defaults	Configure every channel
Moving one axis changed another’s output	The arrays are wired in the wrong order	Check the link order against the sub-tree numbering
`pLimActive` is true and no axis looks limited	Some axis is — the flag is combined across all of them	Read the same flag inside each channel’s sub-tree
`inputsDDot` seems to have no effect	Expected: it is not forwarded to the per-channel limiters	Leave it unlinked
An axis overshoots its position limit	That channel’s `maxBrakingAcceleration` is above its `maxAcceleration`	Fix it in that channel’s sub-tree
Several axes fall out of step during a coordinated move	Expected: each axis is limited independently and a limited one falls behind	Coordinate the motion upstream
One warning per axis at every startup	Expected: each channel’s limiter corrects its own default `omega`	Ignore, or set a finite `omega` in each sub-tree
I cannot switch the whole block off	Expected: there is no enable at this level	Set `disable` inside each channel’s sub-tree
The axes all made a move after a restart	Expected: each output starts at zero and travels to its input	Command actual positions first, or gate the consumers
The sub-tree numbering does not match my axis numbering	The sub-trees are numbered from 1; array elements from 0	`pvaLimiter01` is element 0

There is no block-level starting point to give — configure each channel from pva-limiter.md’s starting point, with that axis’s own travel, speed and acceleration.

Limits and errors

Limit	Set by	What happens	Reported
Every per-channel limit	Each channel’s own sub-tree	Position, velocity and acceleration are bounded independently per axis, exactly as the single-axis block describes	That channel’s own flags
`inputsDDot`	Not forwarded	Accepted, stored, and never used	Not reported
Aggregate flags	Combined	Each is true when any channel’s is. The channel is not identified	Not reported; read the per-channel flags
Block-level enable	Not available	There is no `enable`, `disable` or `isEnabled` at this level	Not applicable
Coordination between axes	None	Each axis is limited on its own. A limited axis falls behind and a multi-axis path is distorted	Not reported
Channel count	Machine configuration	Fixed once the controller starts. Read the array lengths to discover it	Not reported
Everything else	—	See `pva-limiter.md`, which applies per channel	—

The block itself raises no errors or warnings. Each channel’s limiter logs a warning when it corrects its own omega, which with default settings happens once per channel at startup.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: PVALimiters

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

Control3 Current release

Deprecated — scheduled for removal. PvajLimiter is the only setpoint limiter that may be used for new work, and it is natively multi-channel: one instance limits N axes, with every limit, switch and diagnostic per channel. This wrapper has no counterpart to port — give the replacement the channel count instead. This block is kept only until the last machine is off it, and will then be deleted.

The per-channel migration is the one described on PVALimiter: the replacement has no input filter, so feed it the setpoint directly and supply the derivatives on its own leaves.

flowchart LR
    i1(["inputs — position references"]) --> B["PVALimiters"]
    i2(["inputsDot — velocity references"]) --> B
    i3(["inputsDDot — acceleration references"]) --> B
    B --> o1(["outputs — limited positions"])
    B --> o2(["outputsDot — limited velocities"])
    B --> o3(["outputsDDot — limited accelerations"])
    B --> o4(["pLimActive"])
    B --> o5(["vLimActive"])
    B --> o6(["aLimActive"])
    B --> o7(["state"])

Each channel behaves exactly as PVALimiter describes, including the square-root velocity envelope that decelerates an axis into its position limit. Read that page for the tuning — everything below is about the wrapper.

inputsDDot has no effect. The acceleration array is accepted and ignored — the sub-limiters never receive it. Leave it unlinked.

This block has no enable, no disable and no isEnabled. To bypass one axis, use disable inside that channel’s own sub-tree.

Signals

Inputs

Path	Unit	Range	Description
`inputs`	m or rad	unbounded	Position references, one element per channel. Note the plural path names throughout this block.
`inputsDot`	m/s or rad/s	unbounded	Velocity references. They reach each channel’s limiter, and are used only where that channel has its own `enablePVAInputs` set.
`inputsDDot`	m/s² or rad/s²	-	Accepted and ignored. The acceleration array does not reach the per-channel limiters. Leave it unlinked.

Outputs

Path	Unit	Description
`outputs`	m or rad	The limited positions, one element per channel. Each starts from zero after a controller start and moves to its input under that channel’s limits.
`outputsDot`	m/s or rad/s	The limited velocities.
`outputsDDot`	m/s² or rad/s²	The limited accelerations.
`pLimActive`	-	True while at least one channel is being held back by its position envelope.
`vLimActive`	-	True while at least one channel is at its speed limit.
`aLimActive`	-	True while at least one channel is at its acceleration limit. Like the single-axis block, it is suppressed on any channel where a position or velocity limit is also active, so it under-reports.
`state`	-	The same three flags again, grouped.

Parameters

There are no parameters at this level. Everything is configured per channel, in the sub-trees pvaLimiter01, pvaLimiter02 and so on — one per channel, numbered from 1 and always two digits.

Setup

Read the length of inputs from the parameter tree and confirm it matches your axis count. It is fixed when the machine is built.
Configure each channel’s sub-tree separately: travel limits, speed and acceleration for that axis. There is no shared setting — an axis you forget keeps the defaults of ±1, 1 m/s and 10 m/s².
Set maxBrakingAcceleration at or below maxAcceleration in every channel. This is the one relationship that silently causes overshoot, per axis.
Link inputs and, if your source produces them, inputsDot. Leave inputsDDot unlinked.
Command a small move on one axis and confirm only that channel’s outputs element responds.

Step 5 is the check that the channels are independent. If moving one axis changes another’s output, the arrays are wired in the wrong order — and every limit you set afterwards will be applied to the wrong axis.
Command a move that runs into a position limit on one axis. Confirm pLimActive goes true here, and that the same flag is true in that channel’s own sub-tree and false in the others.
Expect one startup warning per channel about omega. It is normal — see pva-limiter.md.

Tuning

All the tuning is per channel and is described in pva-limiter.md. What is specific to this block:

Tune one axis at a time, in its own sub-tree, with the others held still. The aggregate flags cannot tell you which axis is limiting.
Keep a written record of which sub-tree is which axis. The numbering starts at 1 and the array indices start at 0, so pvaLimiter01 is element 0.
When the aggregate pLimActive goes true unexpectedly, walk the sub-trees and read each channel’s own pLimActive to find the axis. There is no faster route.
Watch each channel’s currentMaxVel during a limit approach — it is the most informative signal in the block and there is one per axis.
If several axes should move together and stop together, note that this block does not coordinate them: each is limited independently, so a limited axis falls behind and the path through space changes. Coordinate upstream if that matters.

Read each channel’s behaviour the same way; the axes do not interact.

Symptom	Cause	Action
One axis behaves nothing like the others	That channel’s sub-tree was never configured, so it holds the defaults	Configure every channel
Moving one axis changed another’s output	The arrays are wired in the wrong order	Check the link order against the sub-tree numbering
`pLimActive` is true and no axis looks limited	Some axis is — the flag is combined across all of them	Read the same flag inside each channel’s sub-tree
`inputsDDot` seems to have no effect	Expected: it is not forwarded to the per-channel limiters	Leave it unlinked
An axis overshoots its position limit	That channel’s `maxBrakingAcceleration` is above its `maxAcceleration`	Fix it in that channel’s sub-tree
Several axes fall out of step during a coordinated move	Expected: each axis is limited independently and a limited one falls behind	Coordinate the motion upstream
One warning per axis at every startup	Expected: each channel’s limiter corrects its own default `omega`	Ignore, or set a finite `omega` in each sub-tree
I cannot switch the whole block off	Expected: there is no enable at this level	Set `disable` inside each channel’s sub-tree
The axes all made a move after a restart	Expected: each output starts at zero and travels to its input	Command actual positions first, or gate the consumers
The sub-tree numbering does not match my axis numbering	The sub-trees are numbered from 1; array elements from 0	`pvaLimiter01` is element 0

There is no block-level starting point to give — configure each channel from pva-limiter.md’s starting point, with that axis’s own travel, speed and acceleration.

Limits and errors

Limit	Set by	What happens	Reported
Every per-channel limit	Each channel’s own sub-tree	Position, velocity and acceleration are bounded independently per axis, exactly as the single-axis block describes	That channel’s own flags
`inputsDDot`	Not forwarded	Accepted, stored, and never used	Not reported
Aggregate flags	Combined	Each is true when any channel’s is. The channel is not identified	Not reported; read the per-channel flags
Block-level enable	Not available	There is no `enable`, `disable` or `isEnabled` at this level	Not applicable
Coordination between axes	None	Each axis is limited on its own. A limited axis falls behind and a multi-axis path is distorted	Not reported
Channel count	Machine configuration	Fixed once the controller starts. Read the array lengths to discover it	Not reported
Everything else	—	See `pva-limiter.md`, which applies per channel	—

The block itself raises no errors or warnings. Each channel’s limiter logs a warning when it corrects its own omega, which with default settings happens once per channel at startup.

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: PvajLimiter

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

Control3 Superseded. The current release is 3.34.

flowchart LR
    i1(["input — raw position setpoint"]) --> B["PvajLimiter"]
    i2(["inputDot — setpoint velocity"]) --> B
    i3(["inputDDot — setpoint acceleration"]) --> B
    i4(["disable"]) --> B
    B --> o1(["output — bounded position"])
    B --> o2(["outputDot — velocity"])
    B --> o3(["outputDDot — acceleration"])
    B --> o4(["outputDDDot — jerk"])
    B --> o5(["isEnabled"])

Each channel also publishes its own status group under Limits01, Limits02 and so on: isLimiting, the four per-limit flags, predictedStop, viable, softEntryActive, warningPositionLimitOvershootPossible, status, the two active position limits, and a debug/ group.

A full stop from velocityLimit needs $V^2/2A_b + V A_b/2J_b$ of travel, with $A_b$ and $J_b$ the braking authority. If twice that does not fit between your position limits, some states inside the box can no longer be stopped in time — the block tells you so through warningPositionLimitOvershootPossible rather than refusing the settings.

Every parameter can be changed while the machine is running, and the change takes effect on the very next cycle. A setting that is nonsense on its own — a non-positive limit, or an inverted box — is refused and reported in status, and the limiter keeps running on the last good set. A bad edit is ignored; it never leaves the setpoint unbounded.

This block bounds the setpoint, not the machine. The axis follows through a servo loop with a following error, so the mechanism will pass the limit by roughly that error. Back your limits off by the certified worst case.

Signals

Inputs

Path	Unit	Range	Description
`input`	m or rad	unbounded	The raw position setpoint. A non-numeric value is treated as a fault upstream and the previous setpoint is held.
`inputDot`	m/s or rad/s	unbounded	The setpoint’s own velocity. Only used where that channel’s `enableInputDot` is set.
`inputDDot`	m/s² or rad/s²	unbounded	The setpoint’s own acceleration. Only used where `enableInputDDot` is set, and only supply it if it is exact — see Tuning.
`disable`	-	-	True passes `input` straight to `output` and slaves the internal state to it, so re-enabling is bumpless. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	m or rad	The bounded position setpoint. Never outside the position limits.
`outputDot`	m/s or rad/s	Its velocity.
`outputDDot`	m/s² or rad/s²	Its acceleration.
`outputDDDot`	m/s³ or rad/s³	Its jerk. While the block is bypassed this is estimated by difference rather than left at zero, so a feedforward consumer does not see it vanish.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Per channel, under Limits01, Limits02, …:

Path	Description
`isLimiting`	Any clamp shaped the output this cycle.
`positionLimitActive`	The setpoint is outside the box, or the stopping test clamped the motion.
`velocityLimitActive`, `accelerationLimitActive`, `jerkLimitActive`	That limit is binding.
`activePositionLowerLimit`, `activePositionUpperLimit`	The bounds actually in force, which differ from the configured ones while soft entry is ratcheting.
`predictedStop`	Where a full brake from the current state would come to rest.
`viable`	False when the current state can no longer be stopped inside the box.
`warningPositionLimitOvershootPossible`	The limit set cannot be guaranteed with the authority in force. Describes the settings, not the current state.
`softEntryActive`	A limit is ratcheted to the state because the state is outside it.
`status`	The result of the last settings check. Non-zero means an edit was refused.
`debug/error`, `debug/errorDot`, `debug/errorDDot`, `debug/targetActive`	Indicative only. These explain what the limiter did. Do not wire them into logic — the signals a supervisor may act on are the ones above.

Parameters

Block level: enable (default true).

Per channel, under Limits01, Limits02, …:

Path	Unit	Default	Range	Effect
`positionLowerLimit`	m or rad	−1.0	below the upper	The box. Never crossed.
`positionUpperLimit`	m or rad	+1.0	above the lower
`velocityLimit`	m/s or rad/s	2.0	above 0	Symmetric.
`accelerationLimit`	m/s² or rad/s²	20.0	above 0	Symmetric.
`jerkLimit`	m/s³ or rad/s³	400.0	above 0	Symmetric. Lower rounds the corners of every move.
`maxAccelerationBraking`	m/s² or rad/s²	0.0	at least `accelerationLimit`	Elevated authority for defending the position limits. 0 means “inherit `accelerationLimit`", and stays 0 so it keeps following it. A value below the normal limit is raised, and the raise is written back.
`maxJerkBraking`	m/s³ or rad/s³	0.0	at least `jerkLimit`	Same rule.
`enableInputDot`	-	false	-	Use `inputDot` instead of differencing `input`.
`enableInputDDot`	-	false	-	Use `inputDDot`. Only set this if the value is exact — see Tuning.
`enablePositionLimit`	-	true	-	False leaves the box effectively unbounded.
`feedforwardGain`	-	1.0	0 – 1	How far ahead the tracking target is placed. 1 is the full lead, 0 turns the feedforward off. Trades overshoot of the commanded amplitude against tracking lag. Corrected silently if out of range.
`enableSoftEntry`	-	true	-	When the state is already outside a limit, ratchet that limit to the state so only motion that makes the violation worse is forbidden.
`defendLimitsHard`	-	false	-	Spend the elevated braking authority in normal operation rather than keeping it as a backstop. Costs a step in commanded acceleration when the reference crosses a limit.
`preventPositionLimitOvershoot`	-	false	-	Size the braking authority automatically so overshoot cannot happen. Read the braking values back afterwards — see Limits and errors.

All are persistent and survive a restart.

Setup

Read how many channels this instance has, and note that the sub-trees are numbered from 1 — Limits01 is array element 0.
Set each channel’s box, velocityLimit, accelerationLimit and jerkLimit from the machine.
Check the stopping arithmetic: $V^2/2A + VA/2J$, doubled, against the width of your box. If it does not fit, warningPositionLimitOvershootPossible will be true — lower velocityLimit until it clears.
Leave the braking values at 0 for now, so they follow the normal limits.
Leave both input switches off and feedforwardGain at 1.
Link input and set enable true. Command a move and confirm output follows, status reads zero, and viable stays true.
Command a move that runs into a position limit. Confirm output stops at the limit exactly and positionLimitActive goes true.

Step 7 drives the axis into its travel limit. The setpoint is guaranteed; the machine is not — it will pass the limit by its following error. Do this at low speed first and back the limits off by that error.
If your motion source publishes its own velocity, set enableInputDot and confirm tracking improves.

Tuning

Set the four limits from the machine first. They are hardware properties.
Lower jerkLimit to smooth the motion, raise it to sharpen it. This is the knob this block has and PVALimiter does not, and it is what removes the corners at the start and end of every move.
Supply the setpoint’s own derivatives if you have them. The improvement is large and measured: on a 0.2 m 1 Hz sine, differencing the input gives 1.9e-2 m of error, inputDot alone gives 1.8e-2 m, and inputDot plus inputDDot gives 8.0e-8 m — five orders of magnitude.
Only set enableInputDDot if the acceleration is exact. An acceleration differenced from an input carrying a millimetre of noise measured 6.5e-2 m — three times worse than leaving it off. If your generator does not produce a true acceleration, leave the switch off.
Lower feedforwardGain toward 0 if the output overshoots the commanded amplitude; raise it toward 1 if the output lags. That is the whole trade.
Reserve the braking authority explicitly — set maxAccelerationBraking and maxJerkBraking above the normal limits — if you will ever retune accelerationLimit on a running axis. See Limits and errors for why.
Use defendLimitsHard only if you want the extra authority spent in normal operation. It costs a step in commanded acceleration at the limit.
Watch warningPositionLimitOvershootPossible after every limits edit. It describes the settings, so it answers “can this configuration ever be guaranteed” — viable answers “can the axis be stopped from where it is right now”.

Read the effect of the jerk limit off how rounded each curve’s corners are.

Symptom	Cause	Action
`status` is non-zero and a limits edit did nothing	The edit was nonsense on its own — a non-positive limit or an inverted box	Read `status`, fix the value; the limiter is still running on the last good set
`warningPositionLimitOvershootPossible` is true	A full stop from `velocityLimit` does not fit in the box twice over	Lower `velocityLimit`, raise the braking authority, or set `preventPositionLimitOvershoot`
`viable` went false	The axis cannot be stopped inside the box from where it is now	Read `predictedStop` to see how far past it will go; this usually follows a limits narrowing under a moving setpoint
The guarantee was lost after tightening `accelerationLimit` mid-move	A setpoint already moving fast near a limit cannot be stopped once the limits are lowered — arithmetic, not a fault	Reserve `maxAccelerationBraking` and `maxJerkBraking` explicitly so they do not follow the normal limits down
Motion is jerky at the start and end of moves	`jerkLimit` too high	Lower it
Moves take too long	`jerkLimit` or `accelerationLimit` too low	Raise them, then re-check step 3 of Setup
Tracking lags the input	`feedforwardGain` too low, or the derivative switches are off	Raise the gain toward 1; supply `inputDot`
The output overshoots the commanded amplitude	`feedforwardGain` too high	Lower it toward 0
Tracking got worse after enabling `enableInputDDot`	The acceleration being supplied is estimated, not exact	Turn the switch off; a differenced acceleration is worse than none
The machine passed the position limit	Expected: the setpoint is guaranteed, not the mechanism	Back the limits off by the servo’s worst-case following error
A step in commanded acceleration when crossing a limit	Expected with `defendLimitsHard` set	Clear it to keep the extra authority as a backstop
`softEntryActive` is true and the axis is moving oddly	The state is outside a limit, so only motion reducing the violation is allowed	Expected during recovery; it clears once the state is back inside
The braking values read back higher than written	Expected: a value below the normal limit is raised, and the raise is written back	Write a value above the normal limit, or leave it at 0 to inherit
A braking value left at 0 stayed 0	Expected and deliberate: 0 means “inherit”, and keeps following the normal limit	Set a number if you want it fixed
The `debug/` values look wrong	They are indicative only and are not part of the contract	Use the top-level status signals instead
A non-numeric setpoint did not disturb the output	Expected: the previous setpoint is held	Fix the source

A starting point for a 1 m axis on a 1 ms task, with the braking authority reserved so limits can be retuned safely:

enable = true
Limits01/positionLowerLimit     = -0.5
Limits01/positionUpperLimit     =  0.5
Limits01/velocityLimit          =  1.0
Limits01/accelerationLimit      = 10.0
Limits01/jerkLimit              = 200.0
Limits01/maxAccelerationBraking = 20.0
Limits01/maxJerkBraking         = 400.0
Limits01/enableInputDot         = false
Limits01/enableInputDDot        = false
Limits01/feedforwardGain        = 1.0
Limits01/enableSoftEntry        = true

Limits and errors

Limit	Set by	What happens	Reported
`output` position	The box	Guaranteed, with no tolerance. The setpoint never leaves the limits	`positionLimitActive`, `activePositionLowerLimit`, `activePositionUpperLimit`
`output` velocity, acceleration, jerk	Their limits	Bounded	The three matching flags
Settings validity	Fixed	A non-positive velocity, acceleration or jerk limit, or an inverted box, is refused; the limiter keeps running on the last valid set	`status`
Achievability	Reported, not refused	A limit set whose stop does not fit in the box is accepted and flagged	`warningPositionLimitOvershootPossible`
Current state	Reported	Whether the axis can still be stopped inside the box from where it is	`viable`, `predictedStop`
Narrowing limits under a moving setpoint	Arithmetic	A setpoint moving fast near a limit cannot be stopped once the limits are lowered. The limiter brakes at everything it is allowed and reports `viable` false throughout. Reserving the braking authority explicitly removes the hazard	`viable`, `predictedStop`
`preventPositionLimitOvershoot`	Automatic sizing	Commands whatever braking authority the arithmetic demands, which may exceed what the drive can deliver. Authority the machine does not have is authority the guarantee does not have	Read `maxAccelerationBraking` and `maxJerkBraking` back and check them against the axis
The mechanism	Not bounded	This block bounds the setpoint. The machine passes the limit by its servo following error	Not reported
Braking authority	Inheritance	0 inherits the normal limit and stays 0; a value below it is raised and written back	Read the values back
Task period	Fixed	Recorded as part of the settings check. A task-rate change re-triggers validation	`status`
Channel count	Machine configuration	Fixed once the controller starts. Sub-trees are numbered from 1	Not reported

The block raises no errors or warnings and logs nothing. Every condition above is published as a signal you can trace or wire into a supervisor.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: PvajLimiter

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

Control3 Superseded. The current release is 3.34.

It replaces PVALimiter for new work. That block tracks with a filter and clamps acceleration; this one plans a trajectory and bounds jerk as well, so motion starts and stops without the corners that shake a machine. It also runs as a velocity limiter driven by inputDot. Even then it brings the axis to rest on a position limit rather than through it.

flowchart LR
    i1(["input — raw position setpoint"]) --> B["PvajLimiter"]
    i2(["inputDot — setpoint velocity"]) --> B
    i3(["inputDDot — setpoint acceleration"]) --> B
    i4(["disable"]) --> B
    B --> o1(["output — bounded position"])
    B --> o2(["outputDot — velocity"])
    B --> o3(["outputDDot — acceleration"])
    B --> o4(["outputDDDot — jerk"])
    B --> o5(["isEnabled"])

A full stop from velocityLimit needs $V^2/2A_b + V A_b/2J_b$ of travel, with $A_b$ and $J_b$ the braking authority. If twice that does not fit between your position limits, some states inside the box can no longer be stopped in time — the block tells you so through warningPositionLimitOvershootPossible rather than refusing the settings.

Signals

Inputs

Path	Unit	Range	Description
`input`	m or rad	unbounded	The raw position setpoint. A non-numeric value is treated as a fault upstream and the previous setpoint is held. Not read at all where that channel’s `enableInput` is false.
`inputDot`	m/s or rad/s	unbounded	The setpoint’s own velocity, used where that channel’s `enableInputDot` is set. Where `enableInput` is false this leaf is the velocity command instead, and is read whatever `enableInputDot` says. A non-numeric command is held, not followed.
`inputDDot`	m/s² or rad/s²	unbounded	The setpoint’s own acceleration. Only used where `enableInputDDot` is set, and only supply it if it is exact — see Tuning. Unused where `enableInput` is false.
`disable`	-	-	True passes `input` straight to `output` and slaves the internal state to it, so re-enabling is bumpless. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	m or rad	The bounded position setpoint. Never outside the position limits. Where `enableInput` is false it is the integral of the velocity actually emitted, and it freezes where it stands while the block is bypassed.
`outputDot`	m/s or rad/s	Its velocity. While bypassed this is `inputDot` where `enableInputDot` is set, and a difference of `input` where it is not.
`outputDDot`	m/s² or rad/s²	Its acceleration. While bypassed this is `inputDDot` where `enableInputDDot` is set, and a difference of `outputDot` where it is not.
`outputDDDot`	m/s³ or rad/s³	Its jerk. While the block is bypassed this is estimated by difference rather than left at zero, so a feedforward consumer does not see it vanish.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Per channel, under Limits01, Limits02, …:

Path	Description
`isLimiting`	Any clamp shaped the output this cycle.
`positionLimitActive`	The setpoint is outside the box, or the stopping test clamped the motion.
`velocityLimitActive`, `accelerationLimitActive`, `jerkLimitActive`	That limit is binding. Where `enableInput` is false, `velocityLimitActive` means `velocityLimit` clipped the command — not that the axis is converging on it.
`activePositionLowerLimit`, `activePositionUpperLimit`	The bounds actually in force, which differ from the configured ones while soft entry is ratcheting.
`predictedStop`	Where a full brake from the current state would come to rest.
`viable`	False when the current state can no longer be stopped inside the box.
`warningPositionLimitOvershootPossible`	The limit set cannot be guaranteed with the authority in force. Describes the settings, not the current state.
`softEntryActive`	A limit is ratcheted to the state because the state is outside it.
`status`	The result of the last settings check. Non-zero means an edit was refused.
`debug/error`, `debug/errorDot`, `debug/errorDDot`, `debug/targetActive`	Indicative only. These explain what the limiter did. Do not wire them into logic — the signals a supervisor may act on are the ones above. Where `enableInput` is false, `debug/error` is always 0 — there is no position to be in error by — and `debug/errorDot` is the tracking error that matters.

Each channel also publishes State01, State02, … as a sibling of its Limits group, not inside it:

Path	Description
`State{NN}/positionUpperLimitActive`, `State{NN}/positionLowerLimitActive`	Which position bound is binding, rather than only that one is.
`State{NN}/velocityUpperLimitActive`, `State{NN}/velocityLowerLimitActive`	The same, one derivative up.
`State{NN}/accelerationUpperLimitActive`, `State{NN}/accelerationLowerLimitActive`	And one more.
`State{NN}/active`	Any of the six is set.

Use this group where a dashboard needs the direction of the limit. The flags under Limits{NN} say that a limit is binding; these say which side.

Parameters

Block level: enable (default true).

Per channel, under Limits01, Limits02, …:

Path	Unit	Default	Range	Effect
`positionLowerLimit`	m or rad	−1.0	below the upper	The box. Never crossed.
`positionUpperLimit`	m or rad	+1.0	above the lower
`velocityLimit`	m/s or rad/s	2.0	above 0	Symmetric.
`accelerationLimit`	m/s² or rad/s²	20.0	above 0	Symmetric.
`jerkLimit`	m/s³ or rad/s³	400.0	above 0	Symmetric. Lower rounds the corners of every move.
`maxAccelerationBraking`	m/s² or rad/s²	0.0	at least `accelerationLimit`	Elevated authority for defending the position limits. 0 means “inherit `accelerationLimit`", and stays 0 so it keeps following it. A value below the normal limit is raised, and the raise is written back.
`maxJerkBraking`	m/s³ or rad/s³	0.0	at least `jerkLimit`	Same rule.
`enableInput`	-	true	-	True tracks `input` as a position setpoint. False ignores `input` and reads `inputDot` as a velocity command — see the mode table below.
`enableInputDot`	-	false	-	Use `inputDot` instead of differencing `input`. No effect where `enableInput` is false.
`enableInputDDot`	-	false	-	Use `inputDDot`. Only set this if the value is exact — see Tuning.
`enablePositionLimit`	-	true	-	False leaves the box effectively unbounded.
`feedforwardGain`	-	1.0	0 – 1	How far ahead the tracking target is placed. 1 is the full lead, 0 turns the feedforward off. Trades overshoot of the commanded amplitude against tracking lag. Corrected silently if out of range.
`enableSoftEntry`	-	true	-	When the state is already outside a limit, ratchet that limit to the state so only motion that makes the violation worse is forbidden.
`defendLimitsHard`	-	false	-	Spend the elevated braking authority in normal operation rather than keeping it as a backstop. Costs a step in commanded acceleration when the reference crosses a limit.
`preventPositionLimitOvershoot`	-	false	-	Size the braking authority automatically so overshoot cannot happen. Read the braking values back afterwards — see Limits and errors.

All are persistent and survive a restart. Each is per channel, so a six-axis instance can run some axes as position limiters and others as velocity limiters. No parameters exist below this block.

enableInput selects which of the two modes a channel runs in:

Value	What the machine does	Parameters that matter
true (default)	Tracks `input` as a position setpoint, bounded in jerk, acceleration, velocity and position.	`enableInputDot`, `enableInputDDot`, `feedforwardGain`, and all four limits
false	Ignores `input` and drives `outputDot` onto the `inputDot` command within the jerk, acceleration and velocity limits. `output` is the integral of what was emitted, and the position limits still stop the axis on the limit.	`velocityLimit`, `accelerationLimit`, `jerkLimit`, `enablePositionLimit`, and the box

Use the false setting for a velocity-driven axis — a vehicle drive, a spindle, a conveyor — where there is no position setpoint. It also removes a hazard: an unconnected input sitting at 0 is otherwise tracked as “go to the origin”.

Setup

Read how many channels this instance has, and note that the sub-trees are numbered from 1 — Limits01 is array element 0.
Set each channel’s box, velocityLimit, accelerationLimit and jerkLimit from the machine.
Check the stopping arithmetic: $V^2/2A + VA/2J$, doubled, against the width of your box. If it does not fit, warningPositionLimitOvershootPossible will be true — lower velocityLimit until it clears.
Leave the braking values at 0 for now, so they follow the normal limits.
Leave both input switches off and feedforwardGain at 1.
Link input and set enable true. Command a move and confirm output follows, status reads zero, and viable stays true.
Command a move that runs into a position limit. Confirm output stops at the limit exactly and positionLimitActive goes true.

Step 7 drives the axis into its travel limit. The setpoint is guaranteed; the machine is not — it will pass the limit by its following error. Do this at low speed first and back the limits off by that error.
If your motion source publishes its own velocity, set enableInputDot and confirm tracking improves.
For a velocity-driven axis, clear enableInput instead. Leave input unlinked, link your velocity command to inputDot, and confirm outputDot follows it while debug/error stays 0.
Command a velocity that runs the axis into a position limit. Confirm output comes to rest on the limit and positionLimitActive goes true, with outputDDot peaking at accelerationLimit rather than at maxAccelerationBraking.

Tuning

Set the four limits from the machine first. They are hardware properties.
Lower jerkLimit to smooth the motion, raise it to sharpen it. This is the knob this block has and PVALimiter does not, and it is what removes the corners at the start and end of every move.
Supply the setpoint’s own derivatives if you have them. The improvement is large and measured: on a 0.2 m 1 Hz sine, differencing the input gives 1.9e-2 m of error, inputDot alone gives 1.8e-2 m, and inputDot plus inputDDot gives 8.0e-8 m — five orders of magnitude.
Only set enableInputDDot if the acceleration is exact. An acceleration differenced from an input carrying a millimetre of noise measured 6.5e-2 m — three times worse than leaving it off. If your generator does not produce a true acceleration, leave the switch off.
Lower feedforwardGain toward 0 if the output overshoots the commanded amplitude; raise it toward 1 if the output lags. That is the whole trade.
Reserve the braking authority explicitly — set maxAccelerationBraking and maxJerkBraking above the normal limits — if you will ever retune accelerationLimit on a running axis. See Limits and errors for why.
Use defendLimitsHard only if you want the extra authority spent in normal operation. It costs a step in commanded acceleration at the limit.
Watch warningPositionLimitOvershootPossible after every limits edit. It describes the settings, so it answers “can this configuration ever be guaranteed” — viable answers “can the axis be stopped from where it is right now”.
In the velocity-driven mode, tune accelerationLimit and jerkLimit only. feedforwardGain and both derivative switches do nothing there. The approach to a position limit decelerates at accelerationLimit, so that number sets how far in front of the limit braking begins.

Read the effect of the jerk limit off how rounded each curve’s corners are.

Symptom	Cause	Action
`status` is non-zero and a limits edit did nothing	The edit was nonsense on its own — a non-positive limit or an inverted box	Read `status`, fix the value; the limiter is still running on the last good set
`warningPositionLimitOvershootPossible` is true	A full stop from `velocityLimit` does not fit in the box twice over	Lower `velocityLimit`, raise the braking authority, or set `preventPositionLimitOvershoot`
`viable` went false	The axis cannot be stopped inside the box from where it is now	Read `predictedStop` to see how far past it will go; this usually follows a limits narrowing under a moving setpoint
The guarantee was lost after tightening `accelerationLimit` mid-move	A setpoint already moving fast near a limit cannot be stopped once the limits are lowered — arithmetic, not a fault	Reserve `maxAccelerationBraking` and `maxJerkBraking` explicitly so they do not follow the normal limits down
Motion is jerky at the start and end of moves	`jerkLimit` too high	Lower it
Moves take too long	`jerkLimit` or `accelerationLimit` too low	Raise them, then re-check step 3 of Setup
Tracking lags the input	`feedforwardGain` too low, or the derivative switches are off	Raise the gain toward 1; supply `inputDot`
The output overshoots the commanded amplitude	`feedforwardGain` too high	Lower it toward 0
Tracking got worse after enabling `enableInputDDot`	The acceleration being supplied is estimated, not exact	Turn the switch off; a differenced acceleration is worse than none
The machine passed the position limit	Expected: the setpoint is guaranteed, not the mechanism	Back the limits off by the servo’s worst-case following error
A step in commanded acceleration when crossing a limit	Expected with `defendLimitsHard` set	Clear it to keep the extra authority as a backstop
`softEntryActive` is true and the axis is moving oddly	The state is outside a limit, so only motion reducing the violation is allowed	Expected during recovery; it clears once the state is back inside
The braking values read back higher than written	Expected: a value below the normal limit is raised, and the raise is written back	Write a value above the normal limit, or leave it at 0 to inherit
A braking value left at 0 stayed 0	Expected and deliberate: 0 means “inherit”, and keeps following the normal limit	Set a number if you want it fixed
The `debug/` values look wrong	They are indicative only and are not part of the contract	Use the top-level status signals instead
A non-numeric setpoint did not disturb the output	Expected: the previous setpoint is held	Fix the source
The axis drives to the origin as soon as the limiter is enabled	`enableInput` is true with `input` unlinked, so the setpoint reads 0	Clear `enableInput` for a velocity-driven axis, or link `input`
`debug/error` reads 0 while the axis is clearly moving	Expected where `enableInput` is false: there is no position setpoint to be in error by	Read `debug/errorDot` instead
`velocityLimitActive` is true at a velocity well below `velocityLimit`	Expected where `enableInput` is false: the flag reports the command being clipped	Read `outputDot` for what the axis is doing
`output` did not move while the block was bypassed, and jumped on re-enable	Expected where `enableInput` is false: `output` freezes while bypassed, so it is not the integral of `outputDot` in that state	Re-enable from a zero command, or accept the step

A starting point for a 1 m axis on a 1 ms task, with the braking authority reserved so limits can be retuned safely:

enable = true
Limits01/positionLowerLimit     = -0.5
Limits01/positionUpperLimit     =  0.5
Limits01/velocityLimit          =  1.0
Limits01/accelerationLimit      = 10.0
Limits01/jerkLimit              = 200.0
Limits01/maxAccelerationBraking = 20.0
Limits01/maxJerkBraking         = 400.0
Limits01/enableInput            = true
Limits01/enableInputDot         = false
Limits01/enableInputDDot        = false
Limits01/feedforwardGain        = 1.0
Limits01/enableSoftEntry        = true

Limits and errors

Limit	Set by	What happens	Reported
`output` position	The box	Guaranteed, with no tolerance. The setpoint never leaves the limits	`positionLimitActive`, `activePositionLowerLimit`, `activePositionUpperLimit`
`output` velocity, acceleration, jerk	Their limits	Bounded	The three matching flags
Settings validity	Fixed	A non-positive velocity, acceleration or jerk limit, or an inverted box, is refused; the limiter keeps running on the last valid set	`status`
Achievability	Reported, not refused	A limit set whose stop does not fit in the box is accepted and flagged	`warningPositionLimitOvershootPossible`
Current state	Reported	Whether the axis can still be stopped inside the box from where it is	`viable`, `predictedStop`
Narrowing limits under a moving setpoint	Arithmetic	A setpoint moving fast near a limit cannot be stopped once the limits are lowered. The limiter brakes at everything it is allowed and reports `viable` false throughout. Reserving the braking authority explicitly removes the hazard	`viable`, `predictedStop`
`preventPositionLimitOvershoot`	Automatic sizing	Commands whatever braking authority the arithmetic demands, which may exceed what the drive can deliver. Authority the machine does not have is authority the guarantee does not have	Read `maxAccelerationBraking` and `maxJerkBraking` back and check them against the axis
`output` position, velocity-driven mode	The box	Still guaranteed. A velocity command that would run the axis past a limit is refused in time and the axis comes to rest on the limit, at `accelerationLimit` and `jerkLimit`	`positionLimitActive`
Commanded velocity	`velocityLimit` and the soft-entry ratchets	Clipped before it is tracked	`velocityLimitActive`
The mechanism	Not bounded	This block bounds the setpoint. The machine passes the limit by its servo following error	Not reported
Braking authority	Inheritance	0 inherits the normal limit and stays 0; a value below it is raised and written back	Read the values back
Task period	Fixed	Recorded as part of the settings check. A task-rate change re-triggers validation	`status`
Channel count	Machine configuration	Fixed once the controller starts. Sub-trees are numbered from 1	Not reported

The block raises no errors or warnings and logs nothing. Every condition above is published as a signal you can trace or wire into a supervisor.

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: PvajLimiter

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

Control3 Current release

PvajLimiter bounds a position setpoint in jerk, acceleration, velocity and position at the same time, and guarantees the position limits are never crossed. The output satisfies positionLowerLimit ≤ output ≤ positionUpperLimit exactly — not to within a margin, because every cycle the block asks “if I apply this jerk, can the setpoint still be brought to rest inside the box?” before it applies it.

flowchart LR
    i1(["input — position setpoint"]) --> B["PvajLimiter"]
    i2(["inputDot — setpoint velocity, or the velocity command"]) --> B
    i3(["inputDDot — setpoint acceleration"]) --> B
    i4(["disable"]) --> B
    p1(["Limits0N/positionLowerLimit, positionUpperLimit"]) --> B
    p2(["Limits0N/velocityLimit, accelerationLimit, jerkLimit"]) --> B
    p3(["Limits0N/maxAccelerationBraking, maxJerkBraking"]) --> B
    p4(["Limits0N/enableInput, enableInputDot, enableInputDDot"]) --> B
    B --> o1(["output — bounded position"])
    B --> o2(["outputDot — velocity"])
    B --> o3(["outputDDot — acceleration"])
    B --> o4(["outputDDDot — jerk applied this cycle"])
    B --> o5(["isEnabled"])
    B --> o6(["Limits0N/isLimiting and the four limit flags"])

It runs in one of two modes, chosen per channel by enableInput:

Mode	`enableInput`	`enableInputDot`	What is commanded	What you read
PVAJ (default)	`1`	optional — `1` only if `inputDot` really carries the setpoint velocity	`input` is a position setpoint	`output`, `outputDot`, `outputDDot`, `outputDDDot`
VAJ	`0`	`1` — it is the switch that says `inputDot` carries a velocity; with it `0` the leaf is not read and the command is zero	`inputDot` is a velocity command; `input` is not read at all	`outputDot`, `outputDDot`, `outputDDDot`

Both modes shape the motion with the same J, A and V limits. §7 and §8 give a complete configuration for each.

enableInputDot means one thing in both modes: the inputDot leaf carries a real velocity, read it. Off, the leaf is never read. In PVAJ mode the block then estimates the setpoint velocity by differencing input; in VAJ mode there is no input to difference, so the command is zero and the axis is brought to rest. The three switches that shape the position tracking lead — enableInputDDot, feedforwardGain and suppressInputDDotEstimation — are optional in PVAJ mode and inert in VAJ mode.

A full stop from velocityLimit needs $V^2/2A_b + V A_b/2J_b$ of travel, with $A_b$ and $J_b$ the braking authority. If twice that does not fit between your position limits, states exist inside the box from which the setpoint can no longer be stopped in time — the block tells you so through warningSettingsMayCausePositionLimitOvershoot rather than refusing the settings.

Every parameter can be changed while the machine is running, and the change takes effect on the very next cycle. Nothing is refused: a value that is not usable as a limit is fixed into one and written back to the leaf, so there is one thing to look at — the limit set — and no status code to cross-check it against (§3).

This block bounds the setpoint, not the machine. The axis follows through a servo loop with a following error, so the mechanism will pass the limit by roughly that error. Back your limits off by the certified worst case.

Everything is per channel: an N-channel instance publishes Limits01..LimitsNN, and a six-axis stage can run channel 1 in PVAJ mode and channel 2 in VAJ mode. Every parameter named below lives under the channel’s folder — for channel 1 of an instance called pvajLimiter, positionUpperLimit is root/Control/pvajLimiter/Limits01/positionUpperLimit. The examples use channel 1.

1. Signals

input, inputDot, inputDDot, output, outputDot, outputDDot and outputDDDot are N-element arrays at the top of the module. enable, disable and isEnabled are single leaves that apply to the whole stage.

Inputs

Node	Type	Description
`input`	`double[N]`	Position setpoint. Ignored entirely while `enableInput` is `0`. A non-finite value is held, not followed.
`inputDot`	`double[N]`	Read only while `enableInputDot` is `1`. In PVAJ mode it is then the setpoint velocity, for the tracking lead; in VAJ mode it is the commanded velocity. With `enableInputDot` `0` the leaf is ignored in both modes.
`inputDDot`	`double[N]`	The setpoint acceleration, used only if `enableInputDDot` says it is real. Unused in VAJ mode.
`disable`	`bool`	Stage-wide. While set, every channel passes its input through and limits nothing.

Outputs

Node	Type	Description
`output`	`double[N]`	Limited position. Never outside the box. Reads zero in VAJ mode unless `suppressPositionOutput` is cleared.
`outputDot`	`double[N]`	Limited velocity.
`outputDDot`	`double[N]`	Limited acceleration.
`outputDDDot`	`double[N]`	The jerk applied this cycle.
`isEnabled`	`bool`	`enable && !disable`. Stage-wide; per-channel enables do not affect it.

Per-channel status, `Limits0N/`

Node	Description
`isLimiting`	One of the four limits clamped the output this cycle. Converging on the setpoint is not limiting.
`positionLimitActive`	The position limiter is shaping this cycle.
`velocityLimitActive`	The velocity limit is binding.
`accelerationLimitActive`	The acceleration limit is binding.
`jerkLimitActive`	The jerk limit is binding.
`softEntryActive`	The state is outside a limit and only motion that makes the violation worse is forbidden (§4). Always false while disabled.
`warningSettingsMayCausePositionLimitOvershoot`	The limit set cannot guarantee the box: a stop from `velocityLimit` does not fit in half of it. Fix the settings (§3).
`warningNotAbleToStopBeforeLimit`	The current state can no longer be stopped inside the box — the guarantee is already lost. Only reachable by seeding a bad state or narrowing the limits under a moving setpoint.

Per-channel diagnostics, `Limits0N/debug/`

Indicative only; nothing here feeds the control law.

Node	Description
`trackingError`	`input - output`. Zero while disabled and in VAJ mode.
`trackingErrorDot`	The setpoint velocity in use minus `outputDot`: `inputDot` where `enableInputDot` is set, the estimate differenced from `input` otherwise (zero in VAJ mode without `enableInputDot`). This is the tracking error in VAJ mode.
`trackingErrorDDot`	The setpoint acceleration in use minus `outputDDot`: `inputDDot` where `enableInputDDot` is set, the estimate otherwise.
`predictedStopPosition`	Where a full brake from the current state would come to rest, as an absolute position. Plot it next to `output` and the limits to see the braking margin.

`State0N/`

The same facts as the flags above, in the shape GainSchedulingPVALimiter published them, so existing dashboards keep resolving. Prefer the Limits0N/ flags in anything new.

Node	Equals
`active`	`isLimiting`
`positionUpperLimitActive`	`positionLimitActive`, while the setpoint is in the upper half of the box
`positionLowerLimitActive`	`positionLimitActive`, while it is in the lower half
`velocityUpperLimitActive`	`velocityLimitActive`, while `outputDot` is positive
`velocityLowerLimitActive`	`velocityLimitActive`, while `outputDot` is negative
`accelerationUpperLimitActive`	`accelerationLimitActive`, while `outputDDot` is positive
`accelerationLowerLimitActive`	`accelerationLimitActive`, while `outputDDot` is negative

There is no jerk counterpart — GainSchedulingPVALimiter had no jerk limit.

2. Parameters

All under Limits0N/, all writable while the loop runs. The names are the same on the tree and in C++.

The limit set

Node	Default	Description
`positionLowerLimit`	`-1.0`	Lower travel limit.
`positionUpperLimit`	`1.0`	Upper travel limit.
`velocityLimit`	`1.0`	Maximum speed, symmetric.
`accelerationLimit`	`10.0`	Maximum acceleration, symmetric.
`jerkLimit`	`100.0`	Maximum jerk, symmetric.
`maxAccelerationBraking`	`0.0`	Elevated acceleration reserved for defending the travel limits. `0` inherits `accelerationLimit`.
`maxJerkBraking`	`0.0`	Elevated jerk for the same purpose. `0` inherits `jerkLimit`.

The block never assumes a unit: whatever input is in, velocityLimit is that per second, accelerationLimit per second squared and jerkLimit per second cubed. Linear or rotary, the arithmetic is the same.

Mode and behaviour switches

Node	Default	Description
`enable`	`1`	This channel’s own enable, ANDed with the stage-wide `enable`/`disable`. Set `0` to hold one axis out while the rest of the stage runs.
`enableInput`	`1`	`1` = PVAJ mode, `0` = VAJ mode.
`suppressPositionOutput`	`1`	In VAJ mode, publish `output` as zero instead of the position the block integrates along the way. No effect in PVAJ mode.
`enablePositionLimit`	`1`	Enforce the travel limits. `0` bypasses them outright — the bounds become infinite and no position action is taken.
`enableInputDot`	`0`	`inputDot` carries a real velocity — read it. PVAJ mode: optional, with it off the block differences `input` instead. VAJ mode: required — with it off there is no velocity input and nothing to difference, so the command is zero.
`enableInputDDot`	`0`	`inputDDot` carries the real setpoint acceleration. Optional, PVAJ mode only, and independent of `enableInputDot`. Do not set it on an unconnected leaf — that declares the acceleration to be exactly zero and the block believes it.
`suppressInputDDotEstimation`	`0`	Take the setpoint acceleration as zero instead of estimating it from the input’s history. Set it for one reason only: a measured input whose noise the estimate would amplify.
`feedforwardGain`	`0.0`	How much of the braking-distance lead the tracking target is shifted by, `0`..`1`. `1` tracks accurately; `0` keeps the setpoint inside the commanded amplitude. Values outside the range are clamped and written back.
`enableSoftEntry`	`1`	On enabling with the setpoint outside a limit, ratchet that limit to the state instead of driving the setpoint back inside at once (§4).
`enableMaxBrakingAtLimits`	`0`	Plan every limit approach with the braking authority, not just recovery: braking starts later and is harder. Does nothing while the braking values inherit the ordinary ones.
`autoAdjustBraking`	`0`	Raise `maxAccelerationBraking` / `maxJerkBraking` automatically until a stop from `velocityLimit` fits inside the box, and write the result back. See the warning in §3.

3. Configuring the limits

Nothing is refused. A value that is not usable as a limit is fixed into one, so there is one thing to look at — the limit set — and no status leaf to cross-check it against:

You write	In force
`velocityLimit` or `accelerationLimit` = `0`, negative, or non-finite	no limit (infinite)
`jerkLimit` = `0`, negative, or non-finite	no jerk limit: `1e9` stands in, because the jerk is the block’s control input and an infinite value is not-a-number in its arithmetic
`maxAccelerationBraking` / `maxJerkBraking` = `0` or below the ordinary limit	inherits or is raised to the ordinary limit, and written back to the leaf
`positionLowerLimit > positionUpperLimit`	swapped
the two position limits equal, or either non-finite	no box at all, even with `enablePositionLimit` set

A small but positive value is taken literally: velocityLimit = 1e-9 is a very slow axis, not a mistake the block can recognise — it will freeze the setpoint. 0 is what means “no limit”.

Edits take effect on the next cycle. Start-up fails only if the task period is unknown.

Check warningSettingsMayCausePositionLimitOvershoot after configuring. It is true when a stop from velocityLimit does not fit in half the box, which means states exist inside the box from which the setpoint could no longer be stopped in time. Three ways out: lower velocityLimit, raise accelerationLimit / jerkLimit, or reserve maxAccelerationBraking / maxJerkBraking explicitly. autoAdjustBraking does the last one for you — but it commands whatever authority the arithmetic demands, which may exceed what the drive can deliver, and authority the machine does not have is authority the guarantee does not have either. Read the two braking leaves back afterwards and check them against the worst-case deliverable figures.

4. Enabling with the setpoint outside a limit (soft entry)

This is about the moment you enable. A disabled block passes input straight through, so if the input sits outside the travel limits when you enable, the limiter starts from a state that is already outside the box. Soft entry, on by default (enableSoftEntry), decides what happens next.

Without it, the limiter treats the box as gospel and drives the setpoint back inside immediately, at the braking authority — the setpoint snaps to the limit whether the input wants that or not.

With it, the violated limit is ratcheted to the state: the box in force is widened just enough to contain where the setpoint already is, so the only motion that remains forbidden is motion that makes the violation worse. Two cases follow, measured on a ±1.0 box with the input parked at 1.5 at the moment of enabling:

The input then	What `output` does
moves further from the limit (`1.5` → `3.5`)	held where it was, at `1.500` — the setpoint does not follow the input further out
moves back toward the limit	follows the input inward, and entered the box as the input did (at `0.944` in the measurement)

The ratchet re-tightens every cycle against the new position, so the setpoint can approach the limit but never retreat from it again. The moment the state is inside, softEntryActive clears and the real box applies in full.

While the state is outside, the velocity and acceleration limits are relaxed to whatever the state already carries, for the same reason: an inherited over-speed is not required to vanish instantly, only not to grow. Nothing about normal operation depends on any of this — every effective value equals the configured one whenever the state is inside the box.

The consequence to plan for: a setpoint outside the box stays outside while the input asks it to. Getting back inside is the caller’s business — command the input back — and the setpoint comes with it. softEntryActive tells you it is happening. Clear enableSoftEntry if you would rather the limiter recover by itself, accepting that the setpoint then moves against the input.

Enabling is not the only way in: resetState() can seed a state outside the box, and narrowing the travel limits underneath a moving setpoint leaves it outside. Soft entry handles all three the same way.

5. Enabling with a noisy input

§4 covered enabling with the setpoint outside the box. This one is about the derivatives it inherits.

While the limiter is disabled — the stage-wide enable cleared, disable set, or the channel’s own enable cleared — input passes straight through to output and the internal state is slaved to it, so enabling is bumpless in position. The derivatives it hands over come from differencing that input: outputDot is the first difference of input unless enableInputDot supplies a real velocity, and the acceleration and jerk are further differences.

On the first enabled cycle the block zeroes the inherited acceleration and jerk, and keeps the inherited velocity. Zeroing the acceleration is essential: differencing multiplies input noise by 1/dt², so noise of 1e-4 on the input at a 1 ms cycle arrives as an acceleration of 100 — ten times a typical accelerationLimit — and unwinding that takes |a| / jerkLimit seconds with the velocity integrating the whole way. Measured at jerkLimit = 100, accelerationLimit = 10, velocityLimit = 1 with that much noise, the output flew 625 away from the input before returning; with the acceleration zeroed the same case peaks at 0.056. The velocity is kept because it is mostly the input’s real velocity, and zeroing it would be a sudden stop when the limiter is enabled under a moving input.

That is why a noisy input still costs you something at enable. The velocity handed over is noise / dt — 0.1 for noise of 1e-4 at a 1 ms cycle — and it is real as far as the limiter is concerned: the setpoint sets off at that speed and then has to be brought back within accelerationLimit and jerkLimit, which moves the position by roughly v²/(2·accelerationLimit) before it settles. On a path, that is a deviation from the path.

So, for a clean hand-over:

Give the limiter a smooth input. Filter a measured setpoint upstream rather than feeding raw encoder or network-quantised values into input.
Better still, supply the velocity. Connect a filtered velocity to inputDot and set enableInputDot: no differencing happens at all, so there is no noise to inherit. Do the same for inputDDot with enableInputDDot if the filter provides it.
Enable while the input is settled where the application allows it. With the input at rest there is no velocity to inherit, noisy or not.
If the input is measured and cannot be filtered, set suppressInputDDotEstimation as well (§2), so the tracking lead does not differentiate that noise a second time.

Disabling is unconditional and immediate: the channel stops limiting that cycle and goes back to passing input through. Note that a disabled block bounds nothing, so a command beyond velocityLimit reaches the limiter unbounded and has to be braked back once it takes over — bring the command inside the envelope before re-enabling if that matters.

6. Tuning the tracking accuracy

The switches below change only how accurately the limited output follows an unconstrained input. None of them can affect the position guarantee — they all live in the tracking proposal, which is clamped into the box before it is applied.

`enableInputDot` / `enableInputDDot`

Measured settled error on a 0.2 amplitude, 1 Hz sine, with suppressInputDDotEstimation set so that each row shows what the two switches alone buy. Left at its default the estimate fills the acceleration in, and the first two rows collapse to the accuracy of the last two:

`enableInputDot`	`enableInputDDot`	Setpoint velocity	Setpoint acceleration	Error
`false`	`false`	first difference of `input`	zero when `suppressInputDDotEstimation` is set, otherwise estimated	1.92e-2
`true`	`false`	`inputDot`	zero when suppressed, otherwise estimated	1.81e-2
`false`	`true`	first difference of `input`, advanced by `a·dt/2`	`inputDDot`	< 1e-6
`true`	`true`	`inputDot`	`inputDDot`	8.0e-8

The last two rows are worth five orders of magnitude because the tracking lead is how far the input travels before it could come to rest — leaving its acceleration out pretends the input is coasting.

The two switches are independent claims about two separate leaves. Each says “this one carries the real value”, and each is honoured on its own: a source that publishes position and acceleration but no velocity is a usable combination (third row), where the differenced velocity is lined up with the supplied acceleration by half a step. enableInputDDot also wins over suppressInputDDotEstimation — an explicit claim is not second-guessed — which is the trap to know about: set it on an unconnected leaf and you have declared the acceleration to be exactly zero. The limiter then believes you and locks the setpoint’s acceleration to zero, which tracks the position perfectly on a moving input while publishing an outputDDot of zero. Leave both off if you only have a position.

It needs an exact value. An acceleration differenced from an input carrying 1e-3 of noise measured 6.53e-2, three times worse than leaving it off. Nothing is estimated here unless the estimate is left on (below), and the switch defaults to off for that reason: turn it on if the value is real, leave it off if it is estimated, unconnected or unknown.

`feedforwardGain`

The feedforward shifts the tracking target ahead by the braking distance at the setpoint’s own speed, cancelling the lag that “always be able to stop on the setpoint” would otherwise cost. feedforwardGain is how much of that lead is applied, and it is the feedforward’s only control: 0 is off, 1 is the full lead. The two ends are far apart, which is what makes the value in between worth tuning. Measured on a 0.5 amplitude sine at jerkLimit = 1745, accelerationLimit = 30, velocityLimit = 3.14, position input only:

gain	0.5 Hz: envelope excess / error / lag	1.0 Hz
0.00 (= off)	−1.4e-5 / 5.4e-2 / 31 ms	−3.7e-4 / 1.67e-1 / 51 ms
0.50	+8.6e-7 / 2.7e-2 / 15 ms	−1.5e-4 / 8.6e-2 / 26 ms
0.75	+1.6e-5 / 1.4e-2 / 8 ms	+4.7e-4 / 4.8e-2 / 14 ms
1.00 (= on)	+4.6e-5 / 2.4e-3 / 0 ms	+2.0e-3 / 2.1e-2 / 5 ms

Monotone and smooth throughout: roughly 7–12 ms of lag and a factor of 2–5 in overshoot per 0.25 of gain.

The landmark worth tuning to is where the envelope excess changes sign — around 0.5 at 0.5 Hz and 0.6–0.7 at 1 Hz here. Just below it the output never exceeds what was commanded while most of the lag reduction is still there. It moves with frequency, so it is an application tune, not a constant.

Prefer the derivatives where you have them. The overshoot exists because the lead is computed as how far the input travels before it could come to rest, which assumes the input is coasting when only input is available. A sine is decelerating into its peak, so the lead is overestimated exactly there. Supplying exact inputDot and inputDDot removes the cause instead of trading against it, and beats any gain below 1: the same measurement gives 1.3e-7 of tracking error, no lag, and zero envelope excess. Reach for the gain when only input is real.

The gain is bounded to [0, 1]. 0 is no lead, 1 is the full lead, and there is nothing useful past it: over-leading was measured — at gain 2, 5.0e-2 excess against 9.0e-2 error; by gain 5 the target is permanently clamped to the position limit, so the setpoint just parks at the box edge and stops following at all. Out-of-range values are clamped, not refused, so a bad config value leaves the limiter running on the nearest usable gain rather than on nothing. The clamp is applied by the setters and again at the top of every cycle — a control.xml or parameter-server write lands straight on the leaf without passing a setter — and the clamped value is written back, so feedforwardGain reads what is in force rather than what was asked for. A non-finite value becomes 0.

No gain can touch the position guarantee — the bound is a convenience, not the safety argument. Verified to gain 100 before the bound existed: the position never left the box by any amount, and the emitted motion gained no oscillation. The lead moves the tracking target only, and the target is clamped into the box before the braking-set test runs.

Gain `0`: the feedforward off

feedforwardGain = 0 is the feedforward switched off outright — no lead is computed and the tracking target is the input itself. It costs a factor of 38 in tracking accuracy and buys exactly one thing: the output then stays inside the commanded amplitude envelope instead of leading it by the lead distance. On a 0.5 amplitude, 0.2 Hz sine, tracking error is 2.5e-2 off against 6.5e-4 at the full lead; envelope excess is −1.2e-6 off against +4.3e-6. That is the only reason the off end exists — for machines where the setpoint must not exceed what was commanded, quite apart from the position limits.

With enableInputDot and enableInputDDot both set the trade-off evaporates: 1.1e-8 of tracking error and −1.1e-12 of envelope excess. Better on both counts, so leave the gain at 1.0 there.

`suppressInputDDotEstimation`: the input’s acceleration, and the reversal transient without it

Set it for one reason only: to suppress noise on the input. By default the acceleration is estimated; setting this takes it as zero instead. The estimate is a second difference, so input noise reaches the lead multiplied by 1/dt² — and above roughly 1e-7 of jitter at a 1 ms cycle, taking the acceleration as zero is the better guess. Everywhere else — any computed input, and any input whose derivatives you supply — leave it clear. If the input is measured and you can filter it, do that and supply inputDot / inputDDot instead: that beats both settings at every noise level.

With only input connected and the acceleration taken as zero, the lead is computed as if the input were coasting. That is exact on a ramp, but it grows as the square root of the distance-to-stop, so its curvature is unbounded where the input’s velocity passes through zero. The setpoint answers with full jerk both ways, and outputDDot shows a spike at every velocity reversal — on a 0.0975 amplitude, 1 rad/s sine at jerkLimit = accelerationLimit = 10 π, the target’s acceleration one millisecond before the reversal reaches 0.127, more than the sine’s own 0.0975. With the gain at 0 the same reversal shows a longer, lower bump instead: the output then has to arrive at every instantaneous input position able to stop there, so it over-brakes into a reversal and re-accelerates only as the input opens a gap again.

By default the limiter supplies the missing acceleration from the input’s own history: the acceleration is the second backward difference of input, and the velocity is the first difference advanced by half a step (a · dt / 2), because a plain backward difference is the velocity at k − ½ and that half-step error is larger than the velocity itself in the last millisecond before a reversal. When enableInputDot is set and enableInputDDot is not, the acceleration is the difference of inputDot instead. Measured on the sine above, gain 1:

derivative source	peak \|aOut − aIn\|	cycles at ±J per five periods	peak error
none	0.179 (184 % of aIn)	118	1.6e-4
backward differences, not aligned	0.056 (58 %)	21	2.5e-6
estimated (the default)	0.000	0	0 (locked)
exact `inputDot` + `inputDDot`	0.000	0	0 (locked)

The zero errors are the rest window locking onto the reference state once the derivatives are known; before it did, the estimator measured 3.0e-7 and exact derivatives 1.6e-9.

It is for computed inputs — a trajectory generator, an interpolated path, a kinematics output — not for measured ones. Differencing amplifies noise by 1/dt and 1/dt²: on a position carrying 1e-8 of noise at a 1 ms cycle the acceleration estimate is already 10 of noise against 0.1 of signal and the jerk sits on its limit most of the time. (From 1e-6 of noise upwards even exact derivatives no longer help at this jerk limit, because the position target itself jitters by e/dt³ ≈ 1000 against jerkLimit = 31 — the limiter is then smoothing a noisy setpoint, and the reversal is not the problem.) For a sensor-driven input, filter first and hand over the filter’s derivatives with enableInputDot / enableInputDDot. Off by default.

It does not change what the limits do at a step or a corner. A block wave is shaped by J, A and V alone and tracks identically with the estimator on or off; a triangle wave tracks identically to the exact-derivative case. Note that the lead itself overshoots a triangle’s corner by the braking distance at the ramp velocity — 0.058 at a ramp velocity of 0.5 with jerkLimit = accelerationLimit = 10 π, on and off the estimator alike and with exact derivatives too — because a lead is a prediction that the input keeps its velocity, and at a non-differentiable corner that prediction is wrong by exactly that distance. Use gain 0 where a setpoint may never exceed what was commanded.

7. Example configuration — PVAJ mode (position)

An axis driven by a trajectory generator that publishes a position only. Accurate tracking wanted, the travel limits guaranteed at an authority the drive can actually deliver. The limit values here are the block’s defaults, so on a fresh instance only the last three rows are edits:

Parameter	Set to	Why
`positionLowerLimit`	`-1.0`	the travel, backed off by the worst-case servo following error (default)
`positionUpperLimit`	`1.0`	" (default)
`velocityLimit`	`1.0`	what the mechanism can deliver (default)
`accelerationLimit`	`10.0`	" (default)
`jerkLimit`	`100.0`	" (default)
`maxAccelerationBraking`	`15.0`	authority reserved for defending the travel, at worst-case deliverable figures — `0.0` by default, which inherits `accelerationLimit`
`maxJerkBraking`	`1500.0`	" — `0.0` by default, which inherits `jerkLimit`
`feedforwardGain`	`1.0`	accurate tracking — `0.0` by default, which is the feedforward off

enableInput and enablePositionLimit are already 1, which is PVAJ mode with the travel enforced, so they need no edit. Everything else can stay at its default too.

Connect input to the generator’s position output. enableInputDot and enableInputDDot are optional: leave them at 0 unless the generator really publishes a velocity and an acceleration on those leaves. With them off the block differences the input for the velocity and estimates the acceleration from its history, which is what keeps the lead accurate through a velocity reversal — so a position-only setpoint needs no extra configuration.

What to expect: output follows input closely and never leaves ±1.0; trackingError is the lag; isLimiting is false while merely converging on a new setpoint and true when J, A, V or the box actually binds; warningSettingsMayCausePositionLimitOvershoot reads false with these numbers — a stop from 1.0 at 15.0 needs 0.038 of travel, against the 1.0 of half-box available.

Two adjustments worth knowing:

feedforwardGain 1 lets the setpoint exceed the commanded amplitude slightly on a curved input. Set it to 0 where that must never happen, at the cost of tracking lag.
If the generator publishes exact derivatives, set enableInputDot and enableInputDDot — that is more accurate still than any estimate.

8. Example configuration — VAJ mode (velocity)

A conveyor driven by a velocity command, with no end stops. Only J, A and V are to be enforced; the position is meaningless and must not be published. The envelope is again left at the block’s defaults, so the three mode switches are the only edits:

Parameter	Set to	Why
`enableInput`	`0`	VAJ mode: `input` is not read at all, `inputDot` is the commanded velocity
`enableInputDot`	`1`	says the `inputDot` leaf carries that velocity — off, the leaf is not read and the command is zero
`enablePositionLimit`	`0`	no travel limits on this axis — and with the position output suppressed there is no published position for a limit to mean anything against
`suppressPositionOutput`	`1`	`output` reads zero rather than a position nobody commanded (default)
`velocityLimit`	`1.0`	the envelope the command is shaped into (default)
`accelerationLimit`	`10.0`	" (default)
`jerkLimit`	`100.0`	" (default)

Everything else can stay at its default.

Connect the velocity command to inputDot. Leave input unconnected — it is not read, and it may hold anything.

enableInputDot must be 1 here. It is the one switch that says the inputDot leaf carries a velocity; with it 0 the leaf is not read in either mode, and in this mode there is no input to estimate a velocity from, so the command is zero and the axis comes to rest. In PVAJ mode the same switch declares that the leaf carries a real setpoint velocity for the tracking lead. enableInputDDot, feedforwardGain and suppressInputDDotEstimation, by contrast, change nothing here: they shape the position tracking lead, which this mode does not have.

What to expect: outputDot is brought onto the command within accelerationLimit and jerkLimit without overshooting it, and is clipped to velocityLimit; outputDot, outputDDot and outputDDDot are a consistent triple; output reads 0; trackingErrorDot is the tracking error to watch. A command beyond velocityLimit is clipped, not refused, and a non-finite command is held rather than followed.

suppressPositionOutput is only about the published leaf — the block keeps integrating the position internally either way, and the trajectory is identical. Clear it if you want to see how far the axis has travelled; with no box in force that number is unbounded and drifts as far as the commanded motion takes it.

With end stops instead, set enablePositionLimit to 1 and give the travel: the box is then defended on the integrated position while the command is still followed in velocity, which is the reason to use this block rather than a rate limiter. Note that suppressing the output does not switch the box off — the two are independent, so with both set the box is enforced on a position output does not show. Clear suppressPositionOutput when you need to see that position, or read it in C++ with getIntegratedPosition().

9. Diagnosing

Symptom	Likely cause
Output frozen after a limit edit	A tiny positive J, A or V taken literally (§3). `0` would have meant no limit.
Output ignores the travel limits	The two position limits are equal, or one is non-finite, which is no box at all (§3).
`warningSettingsMayCausePositionLimitOvershoot` true	A stop from `velocityLimit` does not fit in half the box. §3.
`warningNotAbleToStopBeforeLimit` true	The limits were narrowed under a moving setpoint, or a bad state was seeded. The guarantee is already lost; `debug/predictedStopPosition` says how far past the limit the setpoint will go.
Setpoint sits outside the box and stays there	Soft entry doing its job — `softEntryActive` is true, and the input is still asking for it. §4.
Output lags badly	`feedforwardGain` is `0`, or `enableInputDot` is off on a generator that publishes a real velocity.
`outputDDot` spikes at every velocity reversal of the input	`suppressInputDDotEstimation` is set, so the lead assumes the input coasts. Clear it, or supply `inputDDot`.
`outputDDot` reads zero on a moving axis	`enableInputDDot` is set on an unconnected `inputDDot`, which declares the acceleration to be zero.
`output` reads zero in VAJ mode	`suppressPositionOutput`, by design (§8).
Stops at a limit harsher than `accelerationLimit`	`enableMaxBrakingAtLimits` is set, so approaches are planned at the braking authority.
Deviation from the path just after enabling	A noisy `input`: the velocity inherited from differencing it is real to the limiter, and removing it moves the setpoint. Filter the input, or supply `inputDot`. §5.
Module refuses to start	The task period is unknown at start-up.

Docs: GainSchedulingPVALimiter

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

Control3 Superseded. The current release is 3.34.

GainSchedulingPVALimiter bounds a position reference in position, velocity, acceleration and jerk. It uses a feedback loop whose gain is scheduled: when the trajectory runs into a limit the gain is reduced so the limited setpoint parks smoothly against the limit rather than fighting it, and once every signal is back inside its limits the gain returns to normal over gainReturnTime.

Use PvajLimiter for new work. It replaces this block, and its parameter names were deliberately chosen to match these ones so an existing configuration and dashboard keep working. The important difference is the position limit:

Block	How closely the position limit is held
`PvajLimiter`	Exactly. No tolerance at all
This block	To about 1e-6 — a soft limit, not a guarantee

Those figures come from a test that runs both against the same limit set. If your position limit is a safety boundary rather than a shaping preference, that difference is the reason to migrate.

flowchart LR
    i1(["input — unlimited position reference"]) --> B["GainSchedulingPVALimiter"]
    i2(["inputDot — unlimited velocity"]) --> B
    i3(["inputDDot — unlimited acceleration"]) --> B
    i4(["disable"]) --> B
    B --> o1(["output — limited position"])
    B --> o2(["outputDot — limited velocity"])
    B --> o3(["outputDDot — limited acceleration"])
    B --> o4(["gainOutput — the scheduled gain"])
    B --> o5(["isEnabled"])

Each channel also publishes State01, State02, … with six limit flags and an active flag, plus Limits01/activePositionLowerLimit and activePositionUpperLimit.

The scheduled gain falls toward zero while any limit is active and returns to 1 once everything is inside. gainReturnTime sets that recovery, but the gain is also smoothed, so the actual recovery takes about gainReturnTime ÷ 0.7 — roughly 2.9 s for a setting of 2.

Supply exact derivatives or none. This block’s gain schedule degrades when inputDot and inputDDot are differenced from a noisy input. If your motion source does not produce true derivatives, leave those inputs at zero.

This block cannot be configured from an application in C++ — its limits are reachable only through the parameter tree.

Signals

Inputs

Path	Unit	Range	Description
`input`	m or rad	unbounded	The unlimited position reference. One element per channel.
`inputDot`	m/s or rad/s	unbounded	The unlimited velocity reference, used in the modes that take it.
`inputDDot`	m/s² or rad/s²	unbounded	The unlimited acceleration reference.
`disable`	-	-	True passes `input` straight to `output`. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	m or rad	The limited position. It settles against the limit rather than being clamped to it, so it may sit a fraction outside — see Limits and errors.
`outputDot`	m/s or rad/s	The limited velocity.
`outputDDot`	m/s² or rad/s²	The limited acceleration.
`gainOutput`	-	The scheduled gain, one element per channel. 1 while free, near zero while a limit is active, recovering in between. Watch this to see when the block is limiting and how long it takes to let go.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Per channel, State01, State02, …: positionUpperLimitActive, positionLowerLimitActive, velocityUpperLimitActive, velocityLowerLimitActive, accelerationUpperLimitActive, accelerationLowerLimitActive and active.

Parameters

Block level: enable, and adaptive.

Settings holds the loop tuning:

Field	Unit	Description
`positionGain`	1/s²	Position gain of the feedback loop.
`velocityGain`	1/s	Velocity gain. The two together are really one bandwidth-and-damping choice.
`gainReturnTime`	s	How long the gain takes to recover after the last limit clears. Accepted range 0.1 – 5.0; outside that it is corrected and logged. The real recovery is about this divided by 0.7.
`omega`	rad/s	Cut-off of the input pre-filter.

Limits01, Limits02, … hold each channel’s limits:

Field	Unit	Description
`positionLowerLimit`, `positionUpperLimit`	m or rad	The position band. Soft — see Limits and errors.
`velocityLimit`	m/s or rad/s	Symmetric.
`accelerationLimit`	m/s² or rad/s²	Symmetric.
`jerkLimit`	m/s³ or rad/s³	Symmetric.
`mode`	-	Which inputs are used and whether a pre-limit is applied. See below.

`mode`	What the machine does
0	Position input only, with a pre-limit applied. The recommended value.
1	Position input, no pre-limit. The source records that this mode is not robust — avoid it.
2	Velocity and acceleration inputs are used as well.
3	Position input only.
4	Not used.

All parameters are persistent and survive a restart.

Setup

Consider migrating first. If this is a new installation, use PvajLimiter. The rest of this page is for a machine that already runs this block.
Set each channel’s position band, velocityLimit, accelerationLimit and jerkLimit.
Set mode to 0.
Set gainReturnTime to 2.0 and leave the two gains at whatever your configuration ships with.
Set enable true. Command a move well inside the limits and confirm output tracks input and gainOutput stays at 1.
Command a move that runs into a position limit. Confirm gainOutput falls, the matching State flag goes true, and output settles against the limit.

Step 6 will let the setpoint sit slightly past the limit. That is how this block works — the limit is where the loop settles, not a wall. Leave margin, and if the boundary is a safety limit, migrate to PvajLimiter.
Release the limit and time how long gainOutput takes to return to 1. It will be longer than gainReturnTime.

Tuning

Set the four limits from the machine.
Leave mode at 0. Mode 1 is documented in the source as not robust, and modes 2 and 3 change which inputs matter.
Tune gainReturnTime for how quickly the block should let go after a limit event. Shorter recovers sooner and can re-enter the limit; longer keeps the setpoint soft for a while afterwards. The accepted range is 0.1 to 5.0.
Leave positionGain and velocityGain alone unless tracking is visibly poor. They are a matched pair, and changing one without the other changes the loop’s damping.
Watch gainOutput during commissioning. It is the clearest picture of what this block is doing: a dip means a limit was hit, and the width of the recovery is your gainReturnTime in practice.
Supply inputDot and inputDDot only if they are exact. Differenced derivatives make the gain schedule behave worse than leaving them at zero.

Read the recovery time off how long each curve takes to climb back to 1.

Symptom	Cause	Action
The setpoint sits slightly past a position limit	Expected: this block’s position limit is soft — it settles against the limit rather than clamping	Leave margin, or migrate to `PvajLimiter`
The machine passed the position limit by more than expected	The soft limit plus the servo’s own following error	Back the limits off, and consider migrating
The block behaves worse when the derivative inputs are wired	Those derivatives are differenced rather than exact, and the gain schedule folds	Leave `inputDot` and `inputDDot` at zero unless your source produces true values
Recovery after a limit takes longer than `gainReturnTime`	Expected: the gain is smoothed as well as ramped, so recovery is about that time divided by 0.7	Shorten `gainReturnTime`
`gainReturnTime` reads back different from what was written	It is outside the accepted 0.1 – 5.0 range and was corrected	Write a value in range; the correction is logged
The setpoint keeps re-entering the limit	`gainReturnTime` too short, so the gain recovers before the situation has	Lengthen it
The setpoint stays soft long after the limit cleared	`gainReturnTime` too long	Shorten it
Motion is rough or unstable near a limit	`mode` is 1, which the source records as not robust	Set `mode` to 0
The block cannot be configured from the application	Expected: its limits are reachable only through the parameter tree	Configure it in the configuration package
`gainOutput` never returns to 1	Some limit is still active — check the `State` flags for that channel	Widen the limit, or fix what is commanding past it
The gain schedule resumed mid-recovery after a restart	The gain is not reset at start	Expected; it recovers on its own
I need the position limit guaranteed	This block cannot do that	Use `PvajLimiter`

A starting point for a channel with 1 m of travel:

enable                        = true
Settings/gainReturnTime       = 2.0
Limits01/positionLowerLimit   = -0.5
Limits01/positionUpperLimit   =  0.5
Limits01/velocityLimit        =  0.5
Limits01/accelerationLimit    =  5.0
Limits01/jerkLimit            = 50.0
Limits01/mode                 = 0

These are the block’s own defaults, and they are the limit set the comparison test uses.

Limits and errors

Limit	Set by	What happens	Reported
`output` position	The position band	Soft. The setpoint settles against the limit and may sit about 1e-6 outside it. This is not a guarantee	The `State` position flags
`output` velocity, acceleration	Their limits	Held to about 1e-9	The `State` velocity and acceleration flags
Jerk	`jerkLimit`	Bounded	Not separately reported
`gainReturnTime` within 0.1 – 5.0	Fixed	Corrected to the nearest edge	Logged when corrected
Actual recovery time	Fixed	About `gainReturnTime` divided by 0.7, because the gain is smoothed as well as ramped	Watch `gainOutput`
Derivative inputs	Nothing	Not checked. Differenced derivatives degrade the gain schedule — worse than supplying none	Not reported
Configuration from C++	Not available	The limits are writable only through the parameter tree	Not applicable
The mechanism	Not bounded	This block bounds the setpoint. The machine passes the limit by its servo following error, on top of the soft limit above	Not reported
Gain schedule state	Nothing	Not reset at start; it recovers on its own	`gainOutput`
Channel count	Machine configuration	Fixed once the controller starts. Sub-trees are numbered from 1	Not reported

The block logs when it corrects a setting outside its accepted range. Every other condition above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: GainSchedulingPVALimiter

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

Control3 Current release

Deprecated — scheduled for removal. PvajLimiter is the only setpoint limiter that may be used for new work. This block is kept only until the last machine is off it, and will then be deleted. Plan the migration; do not start a new installation on it.

Its Limits01, Limits02, … leaf names were deliberately chosen to match these ones, so an existing configuration package and dashboard keep applying across the swap. The rest does not carry over. Settings/omega, Settings/positionGain, Settings/velocityGain, Settings/gainReturnTime, velocityFactor, gainOutput and the adaptive group have no counterpart — there is no gain scheduling and no input filter in the replacement. Config entries that set those leaves will not resolve. The important behavioural difference is the position limit:

Block	How closely the position limit is held
`PvajLimiter`	Exactly. No tolerance at all
This block	To about 1e-6 — a soft limit, not a guarantee

Those figures come from a test that runs both against the same limit set. If your position limit is a safety boundary rather than a shaping preference, that difference is the reason to migrate.

flowchart LR
    i1(["input — unlimited position reference"]) --> B["GainSchedulingPVALimiter"]
    i2(["inputDot — unlimited velocity"]) --> B
    i3(["inputDDot — unlimited acceleration"]) --> B
    i4(["disable"]) --> B
    B --> o1(["output — limited position"])
    B --> o2(["outputDot — limited velocity"])
    B --> o3(["outputDDot — limited acceleration"])
    B --> o4(["gainOutput — the scheduled gain"])
    B --> o5(["isEnabled"])

Each channel also publishes State01, State02, … with six limit flags and an active flag, plus Limits01/activePositionLowerLimit and activePositionUpperLimit.

The scheduled gain falls toward zero while any limit is active and returns to 1 once everything is inside. gainReturnTime sets that recovery, but the gain is also smoothed, so the actual recovery takes about gainReturnTime ÷ 0.7 — roughly 2.9 s for a setting of 2.

This block cannot be configured from an application in C++ — its limits are reachable only through the parameter tree.

Signals

Inputs

Path	Unit	Range	Description
`input`	m or rad	unbounded	The unlimited position reference. One element per channel.
`inputDot`	m/s or rad/s	unbounded	The unlimited velocity reference, used in the modes that take it.
`inputDDot`	m/s² or rad/s²	unbounded	The unlimited acceleration reference.
`disable`	-	-	True passes `input` straight to `output`. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	m or rad	The limited position. It settles against the limit rather than being clamped to it, so it may sit a fraction outside — see Limits and errors.
`outputDot`	m/s or rad/s	The limited velocity.
`outputDDot`	m/s² or rad/s²	The limited acceleration.
`gainOutput`	-	The scheduled gain, one element per channel. 1 while free, near zero while a limit is active, recovering in between. Watch this to see when the block is limiting and how long it takes to let go.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Block level: enable, and adaptive.

Settings holds the loop tuning:

Field	Unit	Description
`positionGain`	1/s²	Position gain of the feedback loop.
`velocityGain`	1/s	Velocity gain. The two together are really one bandwidth-and-damping choice.
`gainReturnTime`	s	How long the gain takes to recover after the last limit clears. Accepted range 0.1 – 5.0; outside that it is corrected and logged. The real recovery is about this divided by 0.7.
`omega`	rad/s	Cut-off of the input pre-filter.

Limits01, Limits02, … hold each channel’s limits:

Field	Unit	Description
`positionLowerLimit`, `positionUpperLimit`	m or rad	The position band. Soft — see Limits and errors.
`velocityLimit`	m/s or rad/s	Symmetric.
`accelerationLimit`	m/s² or rad/s²	Symmetric.
`jerkLimit`	m/s³ or rad/s³	Symmetric.
`mode`	-	Which inputs are used and whether a pre-limit is applied. See below.

`mode`	What the machine does
0	Position input only, with a pre-limit applied. The recommended value.
1	Position input, no pre-limit. The source records that this mode is not robust — avoid it.
2	Velocity and acceleration inputs are used as well.
3	Position input only, with the position limit applied as a taper rather than a clamp. See the note below.
4	Not used.

In mode 3 the limit is approached through a taper instead of a clamp. The taper begins one braking distance inside each active position limit:

Break-point offset $= V^2/2A$ [m], with $V$ velocityLimit and $A$ accelerationLimit — the distance an axis at full speed needs to stop at the acceleration limit. It is capped at half the width of the active band, so the two break points can never cross. On a band narrower than twice the braking distance the two meet in the middle and the taper degenerates into a hard limit, which is the correct behaviour for a band shorter than the stop it has to absorb.

Raising velocityLimit or lowering accelerationLimit therefore starts the taper further from the limit and softens the approach over a longer distance.

All parameters are persistent and survive a restart.

Setup

Consider migrating first. If this is a new installation, use PvajLimiter. The rest of this page is for a machine that already runs this block.
Set each channel’s position band, velocityLimit, accelerationLimit and jerkLimit.
Set mode to 0.
Set gainReturnTime to 2.0 and leave the two gains at whatever your configuration ships with.
Set enable true. Command a move well inside the limits and confirm output tracks input and gainOutput stays at 1.
Command a move that runs into a position limit. Confirm gainOutput falls, the matching State flag goes true, and output settles against the limit.

Step 6 will let the setpoint sit slightly past the limit. That is how this block works — the limit is where the loop settles, not a wall. Leave margin, and if the boundary is a safety limit, migrate to PvajLimiter.
Release the limit and time how long gainOutput takes to return to 1. It will be longer than gainReturnTime.

Tuning

Set the four limits from the machine.
Leave mode at 0. Mode 1 is documented in the source as not robust, and modes 2 and 3 change which inputs matter.
Tune gainReturnTime for how quickly the block should let go after a limit event. Shorter recovers sooner and can re-enter the limit; longer keeps the setpoint soft for a while afterwards. The accepted range is 0.1 to 5.0.
Leave positionGain and velocityGain alone unless tracking is visibly poor. They are a matched pair, and changing one without the other changes the loop’s damping.
Watch gainOutput during commissioning. It is the clearest picture of what this block is doing: a dip means a limit was hit, and the width of the recovery is your gainReturnTime in practice.
Supply inputDot and inputDDot only if they are exact. Differenced derivatives make the gain schedule behave worse than leaving them at zero.

Read the recovery time off how long each curve takes to climb back to 1.

Symptom	Cause	Action
The setpoint sits slightly past a position limit	Expected: this block’s position limit is soft — it settles against the limit rather than clamping	Leave margin, or migrate to `PvajLimiter`
The machine passed the position limit by more than expected	The soft limit plus the servo’s own following error	Back the limits off, and consider migrating
The block behaves worse when the derivative inputs are wired	Those derivatives are differenced rather than exact, and the gain schedule folds	Leave `inputDot` and `inputDDot` at zero unless your source produces true values
Recovery after a limit takes longer than `gainReturnTime`	Expected: the gain is smoothed as well as ramped, so recovery is about that time divided by 0.7	Shorten `gainReturnTime`
`gainReturnTime` reads back different from what was written	It is outside the accepted 0.1 – 5.0 range and was corrected	Write a value in range; the correction is logged
The setpoint keeps re-entering the limit	`gainReturnTime` too short, so the gain recovers before the situation has	Lengthen it
The setpoint stays soft long after the limit cleared	`gainReturnTime` too long	Shorten it
In mode 3 the setpoint starts easing off a long way before the limit	Expected: the taper begins one braking distance $V^2/2A$ inside the limit	Lower `velocityLimit` or raise `accelerationLimit` to shorten it
In mode 3 the limit behaves like a hard clamp with no taper at all	Expected: the position band is narrower than twice the braking distance, so the two break points met in the middle	Widen the band, or lower `velocityLimit`
Motion is rough or unstable near a limit	`mode` is 1, which the source records as not robust	Set `mode` to 0
The block cannot be configured from the application	Expected: its limits are reachable only through the parameter tree	Configure it in the configuration package
`gainOutput` never returns to 1	Some limit is still active — check the `State` flags for that channel	Widen the limit, or fix what is commanding past it
The gain schedule resumed mid-recovery after a restart	The gain is not reset at start	Expected; it recovers on its own
I need the position limit guaranteed	This block cannot do that	Use `PvajLimiter`

A starting point for a channel with 1 m of travel:

enable                        = true
Settings/gainReturnTime       = 2.0
Limits01/positionLowerLimit   = -0.5
Limits01/positionUpperLimit   =  0.5
Limits01/velocityLimit        =  0.5
Limits01/accelerationLimit    =  5.0
Limits01/jerkLimit            = 50.0
Limits01/mode                 = 0

These are the block’s own defaults, and they are the limit set the comparison test uses.

Limits and errors

Limit	Set by	What happens	Reported
`output` position	The position band	Soft. The setpoint settles against the limit and may sit about 1e-6 outside it. This is not a guarantee	The `State` position flags
`output` velocity, acceleration	Their limits	Held to about 1e-9	The `State` velocity and acceleration flags
Jerk	`jerkLimit`	Bounded	Not separately reported
`gainReturnTime` within 0.1 – 5.0	Fixed	Corrected to the nearest edge	Logged when corrected
Actual recovery time	Fixed	About `gainReturnTime` divided by 0.7, because the gain is smoothed as well as ramped	Watch `gainOutput`
Derivative inputs	Nothing	Not checked. Differenced derivatives degrade the gain schedule — worse than supplying none	Not reported
Configuration from C++	Not available	The limits are writable only through the parameter tree	Not applicable
The mechanism	Not bounded	This block bounds the setpoint. The machine passes the limit by its servo following error, on top of the soft limit above	Not reported
Gain schedule state	Nothing	Not reset at start; it recovers on its own	`gainOutput`
Channel count	Machine configuration	Fixed once the controller starts. Sub-trees are numbered from 1	Not reported

The block logs when it corrects a setting outside its accepted range. Every other condition above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: SmoothStop

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

Control3 3.30–3.34

SmoothStop brings a moving axis to a controlled standstill on command. When you raise gotoStandstill it takes over from the live motion reference, follows a jerk-limited braking profile down to zero velocity, and holds there. Release the command and it fades back to the live reference.

The stop is bounded three ways at once — by deceleration, by jerk, and by whichever of a time budget or a distance budget runs out first. If the natural profile would exceed a budget, the block computes a shorter one rather than letting the stop overrun.

flowchart LR
    i1(["u — live position reference"]) --> B["SmoothStop"]
    i2(["uDot — live velocity reference"]) --> B
    i3(["uDDot — live acceleration reference"]) --> B
    i4(["gotoStandstill"]) --> B
    i5(["resetStandstill"]) --> B
    B --> o1(["y — position output"])
    B --> o2(["ydot — velocity output"])
    B --> o3(["yddot — acceleration output"])
    B --> o4(["yss — braking profile position"])
    B --> o5(["yssDot — braking profile velocity"])
    B --> o6(["yssDDot — braking profile acceleration"])
    B --> o7(["smoothStopActive — per channel"])
    B --> o8(["isAtStandstill"])
    B --> o9(["standstillSwitchIsOn"])
    B --> o10(["standstillSwitchIsOff"])

Stopping distance from velocity $v$ with deceleration $a$ is roughly $v^2/2a$, and jerk rounds the corners at each end. The stop takes about $v/a + a/j$ seconds. maxStopJerkFactor is the fraction of the stop spent ramping the deceleration, from 0 (a pure trapezoid, sharpest) to 0.5 (a pure triangle, gentlest).

Both limits default to zero, which means “stop instantly”. With smoothStopAcc and smoothStopJerk at 0 the block jumps the output to where the axis was and holds it — a hard stop from a block called SmoothStop. Set both before you use it.

gotoStandstill is a level, not a pulse. Hold it true and the axis stays stopped; release it and the block fades back to the live reference.

Signals

Inputs

Path	Unit	Range	Description
`u`	m or rad	unbounded	The live position reference the axis normally follows. One element per channel.
`uDot`	m/s or rad/s	unbounded	The live velocity reference.
`uDDot`	m/s² or rad/s²	unbounded	The live acceleration reference.
`gotoStandstill`	-	-	Raise it to begin stopping; hold it to stay stopped; release it to fade back to the live reference. A level, and one value for the whole block.
`resetStandstill`	-	-	Makes the changeover between the live reference and the braking profile happen instantly rather than fading. Use it when a fade would itself be a disturbance.

Outputs

Path	Unit	Description
`y`	m or rad	The position to follow — the live reference, the braking profile, or a fade between them. This is what the axis should track.
`ydot`	m/s or rad/s	The matching velocity. Note the lower-case path name, where the input is `uDot`.
`yddot`	m/s² or rad/s²	The matching acceleration.
`yss`	m or rad	The braking profile’s own position, whether or not it is currently selected. Useful for watching a stop that has not been engaged.
`yssDot`	m/s or rad/s	The braking profile’s velocity — watch this to see the stop shape.
`yssDDot`	m/s² or rad/s²	The braking profile’s acceleration.
`smoothStopActive`	-	True per channel while that channel’s braking profile is still running.
`isAtStandstill`	-	True when every channel has finished stopping and is at rest. One value for the whole block.
`standstillSwitchIsOn`	-	The changeover has fully reached the braking profile.
`standstillSwitchIsOff`	-	The changeover has fully reached the live reference.

Parameters

Path	Unit	Default	Range	Effect
`smoothStopAcc`	m/s² or rad/s²	0.0	above 0, per channel	Deceleration limit. 0 means an instant stop. Higher stops sooner and harder. Negative values are used as their magnitude.
`smoothStopJerk`	m/s³ or rad/s³	0.0	above 0, per channel	Jerk limit — how fast the deceleration may build. 0 means an instant stop. Higher gives sharper corners.
`maxStopTime`	s	0.0	at least one task period, per channel	The longest the stop may take. If the natural profile would exceed it, the block computes a harder one that fits. Corrected up to one task period if set lower.
`maxStopDistance`	m or rad	0.0	0 upward, per channel	The furthest the axis may travel while stopping. Same treatment as the time budget.
`maxStopJerkFactor`	-	0.0	0 – 0.5, per channel	Only used when a budget forces a recomputed profile. 0 gives the sharpest stop that fits, 0.5 the gentlest. Corrected silently if out of range.
`startAtStandstill`	-	false	-	When true, the block comes up stopped on the first cycle instead of following the reference.

All six are persistent and survive a restart, and the first five are per channel.

One parameter lives below this block: the changeover’s fade time, in the standstillSwitch sub-tree. See soft-switch.md.

Setup

Set smoothStopAcc and smoothStopJerk first. Both default to zero, which makes the block stop the axis instantly. Start with the deceleration the machine uses for a normal decelerating move, and a jerk about ten times that.
Set maxStopTime and maxStopDistance from the machine’s real safety budget — how long and how far the axis may keep moving after a stop is commanded.
Set maxStopJerkFactor to 0.25 as a starting point. It only matters when a budget forces a shorter profile.
Link u, uDot and uDDot from the motion source, and y, ydot, yddot to whatever follows. Confirm the outputs track the inputs exactly with gotoStandstill false.
With the axis moving slowly, raise gotoStandstill. Watch yssDot come down to zero and isAtStandstill go true.

Step 5 stops a moving machine. Do it at low speed first, with the axis clear, and confirm the distance travelled is inside your budget before trying it at full speed.
Measure the stop: time it, and measure how far the axis travelled. Compare both against maxStopTime and maxStopDistance.
Release gotoStandstill and confirm the outputs fade back to the live reference without a bump.

Tuning

Set the deceleration from the machine — what the mechanics, the drive and the load can take. This is a physical limit, not a preference.
Set the jerk from what the structure tolerates. Lower jerk gives rounder corners and a longer stop; higher jerk stops sooner and shakes more.
Check the resulting stopping distance at full speed: roughly $v^2/2a$ plus a little for the jerk ramps. If it exceeds the budget, either raise the deceleration or accept that the block will override your limits.
Watch yssDot on a trace during a stop. It should fall smoothly to zero with no overshoot and no residual crawl.
If a budget is forcing a recomputed profile, the actual deceleration and jerk used will be higher than what you configured — and the block does not publish them. Infer them from the trace.
Use maxStopJerkFactor to shape those forced stops: lower for the shortest stop that fits, higher for the gentlest.
Set the changeover fade time in the standstillSwitch sub-tree so releasing the stop is smooth. The engagement is instant by design — the profile starts exactly where the axis is, so there is nothing to fade.

Read the deceleration off the slope of the straight section and the jerk off how rounded the corners are.

Symptom	Cause	Action
The axis stops dead instead of smoothly	`smoothStopAcc` or `smoothStopJerk` is 0 — the default	Set both to real values
The stop is harsher than configured	A budget forced a shorter profile	Raise `maxStopTime` or `maxStopDistance`, or accept it
The stop overshoots the distance budget	The budget branch cannot fully compensate when the axis is still accelerating at the moment of the stop	Command the stop from a steady speed where possible, and leave margin
A jolt at the start of the stop	The axis was accelerating when the stop was commanded, and the recomputed profile starts from zero acceleration	Leave margin in the budgets so the natural profile is used
The stop takes longer than expected	Jerk too low, so the corners dominate	Raise `smoothStopJerk`, or lower `maxStopJerkFactor`
The machine shakes during the stop	Jerk too high	Lower `smoothStopJerk`, or raise `maxStopJerkFactor`
`isAtStandstill` never goes true	One channel has not finished — it needs every channel stopped	Check `smoothStopActive` per channel
The axis crawls instead of settling exactly at zero	Not possible — the profile lands on exactly zero by construction	Check what consumes `y`
A bump when the stop is released	The changeover fade is too fast	Lengthen the fade time in the `standstillSwitch` sub-tree
A bump when the stop is engaged	Expected: engagement is instant, but the profile starts where the axis is, so it should be seamless. A bump means `u` and `y` had already diverged	Check the outputs were tracking before the stop
The changeover jumps instead of fading	`resetStandstill` is being held true	Release it
The axis comes up stopped after a restart	Expected: `startAtStandstill` is set	Clear it if the axis should follow the reference immediately
One channel stops differently from the others	Expected: all five limits are per channel	Check every element
I cannot tell what deceleration is actually being used	The block does not publish the limits it computes when a budget binds	Measure the slope of `yssDot` on a trace
A non-numeric value appeared and will not clear	There is no reset input	Restart the controller

A starting point for an axis that decelerates at 2 units/s² and must stop within half a second and a quarter of a unit:

smoothStopAcc     = 2.0
smoothStopJerk    = 20.0
maxStopTime       = 0.5
maxStopDistance   = 0.25
maxStopJerkFactor = 0.25
startAtStandstill = false

This is a starting point, not a final tuning. Work Setup step 6 with your own machine.

Limits and errors

Limit	Set by	What happens	Reported
`smoothStopAcc`, `smoothStopJerk` above 0	Nothing	Not checked, and both default to 0, which makes the stop instant. Negative values are used as their magnitude	Not reported
Stop time	`maxStopTime`	If the natural profile is longer, a harder profile is computed to fit. Corrected up to one task period if set below it	Not reported; the actual limits used are not published
Stop distance	`maxStopDistance`	Same treatment. Corrected up to 0 if set negative	Not reported
`maxStopJerkFactor` within 0 – 0.5	Fixed	Corrected to the nearest edge	Silently; read it back
Starting acceleration	Not handled in the budget branch	When a budget forces a recomputed profile, the axis’s acceleration at the moment of the stop is ignored, so the deceleration begins with a step	Not reported
Actual deceleration and jerk	Not published	When a budget binds, the limits actually used are higher than the configured ones and cannot be read from the parameter tree	Not reported
`y`, `ydot`, `yddot`	Nothing	Unbounded — the block shapes the stop, it does not bound the reference	Not reported
Block state	Nothing	The latched profile and the changeover state are not cleared at start. There is no reset input	Not reported
Non-numeric input	Nothing	Not guarded anywhere	Not reported
Channel count	Machine configuration	Fixed once the controller starts	Not reported

The block raises no errors or warnings. It writes one debug log line per channel at the moment a stop is triggered, recording the position, velocity and acceleration it latched. Every failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Deadzone

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

Control3 3.30–3.34

Deadzone blanks a band around zero and passes everything outside it. Use it to stop a machine reacting to a signal that is close to but not exactly zero — a noisy force reading, a joystick at rest — or to simulate backlash in a mechanism.

Outside the band the output is shifted inward by the band’s width, not passed through unchanged. That keeps the output continuous at the band edge: the signal leaves zero smoothly instead of jumping.

flowchart LR
    i1(["input — signal to blank"]) --> B["Deadzone"]
    B --> o1(["output — blanked and shifted signal"])

Inside ±amplitude the output is 0. Outside it, the output is the input minus amplitude in the direction of travel — so an input of twice the amplitude gives an output of one amplitude, not two. The output is continuous at the band edge and passes through zero without a step.

This block has no enable, no disable and no isEnabled. It is always running. Set amplitude to 0 to pass the signal through untouched, which is the default. It is single channel.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to blank. A single value, not an array.

Outputs

Path	Unit	Description
`output`	signal unit	Zero while the input is inside the band; outside it, the input shifted toward zero by `amplitude`. A single value. It never lags — the output depends only on this cycle’s input.

Parameters

Path	Unit	Default	Range	Effect
`amplitude`	signal unit	0.0	any; used as its magnitude	Half the width of the band. 0 passes the signal through unchanged. A negative value behaves as its positive equivalent. Not checked.

amplitude is persistent and survives a controller restart. No parameters exist below this block.

Setup

Trace input with the machine at rest and note how far it wanders from zero. That wander is what you are blanking.
Set amplitude a little above that. Confirm output sits at exactly zero with the machine at rest.
Move the machine slowly and confirm output leaves zero smoothly, with no jump at the moment it starts moving.

Step 3 is what distinguishes this from a threshold. If the output jumps, you are looking at the wrong block — this one is continuous at the band edge by construction.
Move the machine to a known value well outside the band and check the output. It should read the input minus amplitude, not the input. That offset is normal.

Tuning

Set amplitude from the measurement in Setup step 1, not by feel. It is the noise floor of your signal.
Raise it until the machine stops reacting at rest, and no further. Every increase also shifts the signal outside the band by the same amount.
Check the offset at your normal working amplitude. If the dead zone is a large fraction of the signal you care about, the shift is a real gain error — reduce the dead zone or compensate downstream.
If you need the signal outside the band passed through unshifted, this block cannot do it. Use a comparison and a switch instead.
Nothing here needs re-checking after a task-rate change.

Read the band width off the flat section, and the shift off the horizontal offset of either sloped branch.

Symptom	Cause	Action
The machine still creeps at rest	`amplitude` below the signal’s noise floor	Raise it, per Setup steps 1 and 2
The output is smaller than the input by a constant	Expected: the output is shifted inward by `amplitude`	Compensate downstream, or reduce the dead zone
The output jumps as the signal leaves the band	Not possible — this block is continuous at the band edge	Check you are looking at this block’s output
The output stays at zero no matter what	`amplitude` is larger than the signal ever gets	Lower it
Nothing is blanked at all	Expected: `amplitude` defaults to 0	Set an amplitude
A negative `amplitude` behaved like a positive one	Expected: the magnitude is used	Write a positive value for clarity
The output reads zero when the input is not a number	Expected: a non-numeric input falls inside the band and gives zero	Fix the source — note this block will hide such a value from anything downstream
You cannot switch the block off	Expected: there is no enable	Set `amplitude` to 0, which is an exact pass-through
You need this on several channels	Not possible — this block is single channel	Use one instance per channel
The gain of the signal changed after adding the dead zone	Expected: the shift is a constant offset, which looks like a gain change on a small signal	Size the dead zone against your working range

A starting point for blanking a force reading whose noise floor is about 0.3 N:

amplitude = 0.5

Limits and errors

Limit	Set by	What happens	Reported
`amplitude`	Nothing	Not checked. Any finite value is accepted and used as its magnitude. 0 is an exact pass-through	Not reported
`output`	Nothing	Unbounded — whatever the input carries, less the band width, reaches the output. Limit it downstream if the consumer needs a bound	Not reported
Output continuity	Fixed	Continuous at both band edges by construction. The slope changes there, but the value does not jump	Not applicable
Signal offset	Fixed	Everything outside the band is shifted toward zero by `amplitude`. This is the design, not a fault	Not reported
Non-numeric input	Fixed	Falls inside the band and produces zero, so this block silently hides a non-numeric value from anything downstream	Not reported
Block state	None	The block has no memory. Nothing survives a stop and there is nothing to reset	Not applicable
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: Decay

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

Control3 3.30–3.34

Decay adds an amount to its output on command, holds it, then ramps it linearly back to a resting level. Use it for an event-driven offset that should fade on its own — a nudge after a collision, a kick on a jog command, a temporary allowance that expires. The ramp is straight, not exponential: despite the name, there is no time constant.

The amount accumulates. A second command before the first has finished adds to what is already there and restarts the hold.

flowchart LR
    i1(["input — amount to add"]) --> B["Decay"]
    i2(["set"]) --> B
    i3(["reset"]) --> B
    B --> o1(["output — the decaying value"])
    B --> o2(["decaySlope — fall per cycle"])
    B --> o3(["busy"])

After a set, output jumps by input, holds for decayStartTimeSec, then falls to defaultValue over decayDurationSec and stops. The fall rate is $($ height above defaultValue $) / ($ decayDurationSec $)$ per second, and it is fixed at the moment of the set. Total event length is decayStartTimeSec + decayDurationSec.

This block has no enable, no disable and no isEnabled. It is always running, and while idle it drives output to defaultValue on every cycle — nothing else can hold that path at another value. decayDurationSec must never be 0; see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The amount to add to `output`, one element per channel. It is a magnitude, not a signal — it is read only at the moment of a `set`, and changing it at any other time has no effect.
`set`	-	-	A rising value starts an event: `input` is added to `output`, the hold begins, and `busy` goes true. The block clears this input itself, so it is a one-shot. Do not drive it from a link that writes every cycle — the block would fire continuously.
`reset`	-	-	While true, `output` is forced to `defaultValue` and any event in progress is abandoned as a step, not a ramp. This input is a level, not a pulse — the block does not clear it, so holding it true pins the output.

Outputs

Path	Unit	Description
`output`	signal unit	The decaying value, one element per channel. Equals `defaultValue` whenever no event is in progress, and is rewritten every cycle while idle. Starts at `defaultValue` after every controller start.
`decaySlope`	signal unit per cycle	How much `output` falls each cycle during the ramp, one element per channel. Fixed when the event starts and unchanged for its duration. Use it to confirm the event was set up as you intended.
`busy`	-	True from the moment of a `set` until the ramp has finished. A single value for the whole block, not one per channel. It stays true for `decayStartTimeSec` + `decayDurationSec`.

Parameters

Path	Unit	Default	Range	Effect
`defaultValue`	signal unit	0.0	any	The resting level the output returns to, one element per channel. The output is driven here whenever no event is in progress.
`decayStartTimeSec`	s	0.0	0 upward	How long `output` holds at its full height before the ramp begins. 0 starts the ramp immediately. Not checked — a negative value makes the event never finish.
`decayDurationSec`	s	1.0	must be greater than one task period	How long the ramp takes. Longer is gentler. Not checked, and 0 breaks the block — see Limits and errors.

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

Setup

Set defaultValue to the level the output should rest at — usually 0.
Set decayDurationSec to a real value before anything else.

Never leave decayDurationSec at 0. A zero duration makes output and decaySlope go to a non-numeric value on the first set, and only a reset clears it. Check this before you wire set to anything.
Set decayStartTimeSec to the hold you want, or 0 for none.
Set input to the amount you want added. Confirm output does not move — the amount is only read on a set.
Pulse set true for one cycle. output should jump by input, busy should go true, and decaySlope should read the amount divided by the duration in cycles.
Watch output hold, then fall in a straight line to defaultValue. Time the whole event: it should equal decayStartTimeSec + decayDurationSec.
Confirm busy goes false at the end and output sits exactly on defaultValue.
Trace every element of output. All channels share one schedule, so they must start and finish together.

Tuning

Set the amount first, with input, and confirm the height of the jump on a trace of output. That height is what the consumer downstream has to tolerate.
Set decayStartTimeSec from the process, not from feel: it is how long the offset must stay at full strength to do its job.
Set decayDurationSec from what the machine can absorb. Read decaySlope after a set and check that fall rate against whatever consumes output — a rate that is too steep shows up as a bump downstream.
Work out how often your event source can fire. If it can fire faster than decayStartTimeSec + decayDurationSec, the amounts will stack and there is no upper limit on how high output goes. Either lengthen the gap or bound the value downstream.
Re-check nothing after a task-rate change. Both durations are in seconds, so they hold their meaning — unlike the sample-counted blocks.

Read the fall rate off any curve as its slope during the ramp.

Symptom	Cause	Action
`output` and `decaySlope` went to a non-numeric value on the first `set`	`decayDurationSec` is 0	Set a real duration, then hold `reset` true for a cycle to clear it
`busy` went true and never came back down	A negative `decayStartTimeSec` or `decayDurationSec`	Write non-negative values, then pulse `reset`
`output` climbed higher and higher	Expected: `set` adds to what is already there, and the events are firing faster than they finish	Lengthen the gap between events, or bound `output` downstream
The hold restarted part way through a ramp	Expected: a `set` during an event restarts the hold from the new height	Gate your event source on `busy` being false
`output` will not stay where I write it	Expected: the block drives `output` to `defaultValue` every idle cycle	Use the block’s own `input` and `set`; nothing else can hold this path
Nothing happened when I changed `input`	Expected: `input` is only read at the moment of a `set`	Pulse `set` after setting the amount
The block fires continuously	`set` is driven from a link that writes it every cycle	Drive `set` from a one-shot source; the block clears it itself
The block is stuck at `defaultValue` and ignores `set`	`reset` is being held true	`reset` is a level, not a pulse — write it false
`reset` stopped the event with a jump rather than a fade	Expected: a reset is a step to `defaultValue`	Let the ramp finish, or use a longer duration and reset later
The ramp finished early and snapped the last part	`decayDurationSec` was shortened while the event was running	Change the durations only while `busy` is false
`output` went below `defaultValue` and then came back up	`decayDurationSec` was lengthened while the event was running	Change the durations only while `busy` is false
One channel decayed and the others did not	Not possible — all channels share one schedule	Check the other channels' `input` values; a zero amount gives a zero jump
Channels finished at different levels	Expected: each channel returns to its own `defaultValue`	Set every element of `defaultValue`
The fall is curved, not straight	Not possible — the ramp is always linear	Nothing to change; this block has no exponential mode

A starting point for a 0.5-unit nudge that holds briefly and fades over half a second:

defaultValue      = 0.0
decayStartTimeSec = 0.1
decayDurationSec  = 0.5

Limits and errors

Limit	Set by	What happens	Reported
`decayDurationSec` > one task period	Nothing	Not checked. A value of 0 makes `output` and `decaySlope` non-numeric on the next `set`, and only `reset` clears it. Always set a real duration	Not reported
`decayStartTimeSec` ≥ 0	Nothing	Not checked. A negative value makes the event never finish and `busy` stay true forever. Clear it with `reset`	Not reported
`output`	Nothing	Unbounded, and it accumulates across overlapping events. Bound it downstream if the consumer needs a limit	Not reported
Event schedule	Shared	One schedule for all channels. A `set` starts every channel, and there is no per-channel event	Not reported
Durations after a task-rate change	Task rate	Both are in seconds and keep their meaning, so nothing needs rescaling	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).