– Setpoints and motion

Docs: SetpointGenerator

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

Control3 3.30–3.34

SetpointGenerator turns a step change in a target into a smooth profiled move. Write a new number to input and the output travels there while respecting velocity, acceleration and jerk limits — and publishes the matching velocity and acceleration as it goes, so a feedforward path can use them.

The move time is computed, not configured. You give it the limits; it works out the fastest move that respects them.

flowchart LR
    i1(["input — the target value"]) --> B["SetpointGenerator"]
    i2(["timeScaleFactor"]) --> B
    i3(["timeScaleFactorDot"]) --> B
    B --> o1(["output — profiled position"])
    B --> o2(["outputDot — velocity"])
    B --> o3(["outputDDot — acceleration"])
    B --> o4(["done"])
    B --> o5(["numTargets — how many are queued"])

timeScaleFactor stretches the profile’s clock while it runs — 0.5 makes the move take twice as long at half the velocity and a quarter of the acceleration. That is what a jog-override wheel needs. timeScaleFactorDot lets the override itself be turned smoothly.

All three limits default to 0, and a generator with a zero limit refuses every target. Nothing moves, an error is logged once, and no output changes to tell you why. Set maxVel, maxAcc and maxJerk before anything else.

An unachievable target is discarded, not clamped. The generator keeps the previous target and carries on. That is the safe failure, but it is silent apart from that one log line.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The target. A change starts a new move; writing the same value again does nothing. If the move cannot be profiled with the current limits, the target is discarded and the previous one kept.
`timeScaleFactor`	-	above 0	Stretches or compresses the profile’s clock while it runs. 1 is normal speed, 0.5 is half speed, 0 freezes the move. Not checked.
`timeScaleFactorDot`	1/s	any	How fast `timeScaleFactor` is itself changing, so an override can be turned without a jolt.

Outputs

Path	Unit	Description
`output`	signal unit	The profiled value on its way to the target.
`outputDot`	signal unit per second	Its velocity — feed this to a feedforward path.
`outputDDot`	signal unit per second²	Its acceleration.
`done`	-	True when the profile has finished. It starts true, so a freshly started generator reports done before it has done anything.
`numTargets`	-	How many targets are queued. Writing a new target while a move is running adds to the queue rather than replacing it.

Parameters

Path	Unit	Default	Range	Effect
`maxVel`	signal unit per second	0.0	above 0	Velocity limit. A zero here makes every target be refused. Negative values are used as their magnitude and written back.
`maxAcc`	signal unit per second²	0.0	above 0	Acceleration limit. Same treatment.
`maxJerk`	signal unit per second³	0.0	above 0	Jerk limit. Only used by the jerk-limited profile, but still needs a value.
`faderType`	-	0	0 or 1	Which profile shape. See the table below.
`delayTime`	s	0.0	0 upward	How long to wait after a new target before the move starts.
`applyTimeScaleToDelay`	-	—	-	Whether `timeScaleFactor` stretches the delay as well as the move.
`maxTargets`	-	10	1 upward	How many targets may be queued at once.

`faderType`	What the machine does	Parameters that matter
0 `QUINTIC`	Position, velocity and acceleration all start and end at zero. The smoothest shape, and the default	`maxVel`, `maxAcc`
1 `JERK_LIMITED`	Reaches the acceleration and velocity limits and holds them, so the move is faster for the same limits, with a slightly harsher start	all three limits

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

Setup

Set maxVel, maxAcc and maxJerk first. They default to 0, and a generator with a zero limit refuses every target you give it.
Leave faderType at 0 for a first pass — the quintic profile is the gentler of the two.
Have your application seed the generator at the machine’s current position before enabling anything downstream, so the first move does not start from zero.
Write a small target to input and watch output travel there. Confirm done goes false at the start and true at the end.

Step 4 moves the machine. The generator will use the full velocity and acceleration you configured, immediately. Start with a small target and limits well below the machine’s capability.
Check outputDot peaks at or below maxVel, and outputDDot at or below maxAcc.
Write a second target while the first move is running and watch numTargets. The moves queue rather than replacing each other.

Tuning

Set the three limits from the machine, not from the move you want. They are what the mechanics can take.
Choose the profile shape from what the machine minds more. Quintic is smoother and slower; jerk-limited reaches the limits and holds them, so it is faster for the same numbers.
Time a move and compare it against what the limits imply. If it is slower than expected, the quintic shape is the reason — switch to jerk-limited.
Use delayTime when several axes should start together after a common trigger.
Use timeScaleFactor for a speed override. Ramp it with timeScaleFactorDot rather than stepping it, or the move’s velocity jumps.
Raise maxTargets if your application streams targets faster than the moves complete. Watch numTargets to see whether the queue is filling.
Nothing here needs re-checking after a task-rate change — but note the block captures the task period once at startup, so if the rate changes while running, restart the controller.

Read how much of the move is spent at constant speed off the straight section in the middle.

Symptom	Cause	Action
Nothing moves and no output changes	A limit is 0 — the default — so every target is refused	Set `maxVel`, `maxAcc` and `maxJerk`
A new target had no effect	Either it was refused, or it is the same value as the last one	Check the limits; the generator only reacts to a change
An error about invalid settings appeared once	The limits cannot produce a valid profile	Fix the limits; the previous target is still in force
`done` reads true before the first move	Expected: it starts true	Wait for it to go false after a target is written
The move is slower than the limits suggest	Expected with the quintic profile, which eases throughout	Set `faderType` to 1
The start of a move is harsher than expected	Expected with the jerk-limited profile, which pushes to its limits	Set `faderType` to 0
The move takes the wrong time after a task-rate change	The block captured the task period at startup	Restart the controller
A limit reads back as a positive number after writing a negative one	Expected: the magnitude is used	Write positive values
The move froze part-way	`timeScaleFactor` is 0	Set it above 0
The velocity jumped when the override was changed	`timeScaleFactor` was stepped	Ramp it, using `timeScaleFactorDot`
Targets are being dropped	The queue is full — check `numTargets` against `maxTargets`	Raise `maxTargets`, or write targets less often
The first move went to the wrong place	The generator was not seeded at the machine’s position	Have the application seed it before enabling
I cannot change the jerk-limited profile’s shape	Those two shape factors are not exposed	Only the two profile types are selectable
I need this on several axes	Not possible — this block is single channel	Use one instance per axis

A starting point for an axis that may move at 0.5 units per second:

maxVel                = 0.5
maxAcc                = 5.0
maxJerk               = 50.0
faderType             = 0
delayTime             = 0.0
maxTargets            = 10

Limits and errors

Limit	Set by	What happens	Reported
`maxVel`, `maxAcc`, `maxJerk` above 0	Nothing	Not checked, and all three default to 0. A zero limit makes every target be refused	Logged once when the settings first become invalid; no output changes
Target achievability	Checked on every change	A target that cannot be profiled is discarded and the previous one kept — the generator keeps running on the last valid profile	Logged once on the transition. No output flag
`output`	The profile	Reaches the target exactly. Velocity and acceleration stay inside their limits	Not reported
Limit signs	Fixed	Negative limits are used as their magnitude and written back	Read the values back
`timeScaleFactor`	Nothing	Not checked. 0 freezes the move and a negative value is not guarded	Not reported
Profile shape factors	Not exposed	The jerk-limited shape’s two factors are fixed and cannot be configured	Not applicable
Task period	Captured at startup	Read once when the controller starts. A task-rate change while running is not picked up and the move takes the wrong time	Not reported
Target queue	`maxTargets`	Targets written while a move is running are queued, up to this depth	`numTargets`
Channel count	Fixed	One channel per instance, always	Not reported

The block logs one error when the limit set first becomes invalid. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: SetpointGenerator4thOrder

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

Control3 3.30–3.34

SetpointGenerator4thOrder generates a motion profile bounded in four derivatives: velocity, acceleration, jerk and snap. Bounding the fourth means jerk itself ramps instead of stepping, which is what a machine with a lightly damped structure needs — a stepped jerk rings it, a ramped one does not.

It moves to a position, or holds a velocity as a jog, and switches between the two while running.

flowchart LR
    i1(["command/start"]) --> B["SetpointGenerator4thOrder"]
    i2(["command/abort"]) --> B
    i3(["command/type"]) --> B
    i4(["command/jogVelocity"]) --> B
    p1(["targetProfile/position, velocity, acceleration, jerk, snap"]) --> B
    B --> o1(["outputProfile/position, velocity, acceleration, jerk, snap"])
    B --> o2(["status/isDone, isAborted"])
    B --> o3(["status/isMovingToPosition, isMovingToVelocity, isAtConstantVelocity"])
    B --> o4(["status/currentSample, currentIndex"])
    B --> o5(["calc/sampleArray, snapArray, numberOfSamples, totalTime"])

The four numbers under targetProfile other than position are bounds, not targets. The generator uses as much of each as it needs and no more, so a short move may never reach any of them.

Two things about this block will catch you out. Read them before using it.

command/start must be held true for the whole move. It is not a pulse. Clearing it mid-move aborts the move as soon as the axis reaches its cruise speed.

command/abort only works in jog mode. To abort a position move, clear command/start. And an abort of either kind only takes effect during a constant-speed phase — requested during acceleration or braking, it waits. This is not an emergency stop.

Signals

Inputs

Path	Unit	Range	Description
`command/start`	-	true or false	Starts a position move, and must stay true until it finishes. The block clears it when the move ends.
`command/abort`	-	true or false	Aborts a jog only. Ignored during a position move. Cleared by the block once acted on.
`command/type`	-	0, 1, 2	0 relative, 1 absolute, 2 velocity (jog). See the table below.
`command/jogVelocity`	axis unit per second	any	The jog target speed. Only read every hundredth cycle, and only while the axis is at constant speed, so a jog change can take that long to act.

Outputs

Path	Unit	Description
`outputProfile/position`	axis unit	The setpoint to follow. Held where it stopped when a move ends.
`outputProfile/velocity`	axis unit per second	Its speed — feed this to a feedforward path.
`outputProfile/acceleration`	axis unit per second²	Its acceleration.
`outputProfile/jerk`	axis unit per second³	Its jerk. Continuous, which is the point of this block.
`outputProfile/snap`	axis unit per second⁴	The driving quantity, which steps between sixteen fixed values.
`status/isDone`	-	The move has finished. Reads false until the first move completes, including straight after a restart.
`status/isAborted`	-	The last move was aborted rather than completed.
`status/isMovingToPosition`	-	A position move is running.
`status/isMovingToVelocity`	-	A jog is running.
`status/isAtConstantVelocity`	-	Acceleration, jerk and snap are all zero. An abort can only act while this is true.
`status/currentSample`	-	How many cycles into the profile the axis is.
`status/currentIndex`	-	Which of the eighteen profile segments is playing, 0 to 17.
`calc/numberOfSamples`	-	How many cycles the whole move will take.
`calc/totalTime`	s	How long it will take. Check this after starting — a very small bound makes it enormous.
`calc/sampleArray`	-	How many cycles each profile segment lasts. Diagnostic. Shows 17 of the 18 segments.
`calc/snapArray`	axis unit per second⁴	The snap value of each segment. Diagnostic. Shows 17 of the 18.

Parameters

Path	Unit	Default	Range	Effect
`targetProfile/position`	axis unit	0.0	unbounded	The target. Absolute or relative depending on `command/type`. In relative mode a value of exactly 0 is refused.
`targetProfile/velocity`	axis unit per second	0.5	above 0	Speed bound. A zero refuses the move.
`targetProfile/acceleration`	axis unit per second²	5	above 0	Acceleration bound. A zero refuses the move.
`targetProfile/jerk`	axis unit per second³	100	above 0	Jerk bound. A zero refuses the move.
`targetProfile/snap`	axis unit per second⁴	1000	above 0	Snap bound — how fast jerk may change. This is the parameter that makes the profile gentle. A zero refuses the move.

All five are persistent and survive a controller restart. Negative values are used as their magnitude. No parameters exist below this block.

`command/type`	What the machine does	What `targetProfile/position` means
0 `RELATIVE`	Moves a given distance from where it is	The distance to travel. Exactly 0 is refused
1 `ABSOLUTE`	Moves to a given position — the default	The position to arrive at
2 `VELOCITY`	Jogs at `command/jogVelocity` until aborted	Not used

Setup

Set the four bounds from what the machine can take. All four have non-zero defaults, so the block will move without being configured — check them before you start it.
Set command/type to 0 for a first move, so the distance is relative to wherever the axis already is.
Set targetProfile/position to a small distance.
Set command/start true and leave it true.

Step 4 moves the machine, immediately and at the bounds you configured. Set them well below the machine’s capability first, and use a distance you can afford to overshoot.
Watch status/isMovingToPosition go true, then status/isDone go true when it arrives. The block clears command/start itself.
Read calc/totalTime and check it against the distance and the speed bound. A much larger number means a bound is far smaller than you meant.
Confirm outputProfile/position ends exactly at the target. It should be exact, not close.

Tuning

Set targetProfile/velocity and targetProfile/acceleration first — they are what the machine’s mechanics allow.
Set targetProfile/jerk to what the drivetrain tolerates. Lower means gentler load reversals.
Set targetProfile/snap last, and use it to trade smoothness against move time. It is the only bound the third-order generators do not have, and the reason to use this block at all.
Run a move and watch outputProfile/jerk. With snap bounded it ramps between levels; the flatter the ramps, the gentler the move.
If the machine rings at a known frequency, lower targetProfile/snap until the ringing stops. Every reduction lengthens the move.
Compare calc/totalTime before and after each change, so you can see what the smoothness cost.
Short moves take longer than the bounds imply. Every profile segment is rounded up to a whole cycle, which matters most when the move is only a few cycles long.

The gentler the curve leaves zero, the less the machine is excited — and the longer the move takes.

Symptom	Cause	Action
The move stopped part-way	`command/start` was cleared, which aborts	Hold `command/start` true for the whole move
`command/abort` did nothing	It only aborts a jog	Clear `command/start` to stop a position move
An abort did not act for a while	Aborts only take effect at constant speed	Expected. Do not use this as an emergency stop
The axis stopped in the wrong place after an abort	An abort plays out the braking half, wherever that ends	Expected. The stopping point is not predictable
Nothing moved and an error was logged	A bound is 0, or a relative move of exactly 0 was requested	Set all four bounds above 0
The same error keeps repeating	The block retries every hundredth cycle	Fix the bound or the move type
The first absolute move went to the wrong place	The block starts from position 0, and cannot be told the machine’s real position from the parameter tree	Use relative moves, or drive the block from an application
`status/isDone` reads false after a restart	Expected: it only becomes true when a move finishes	Run one move
`calc/totalTime` is enormous	A bound is far smaller than intended	Check all four
A short move took much longer than expected	Each segment is rounded up to a whole cycle	Expected. It matters only for very short moves
A jog change took a long time to act	Jog targets are read every hundredth cycle, at constant speed only	Expected
The machine rings during acceleration	`targetProfile/snap` is too high	Lower it
The move is smooth but too slow	A bound is limiting it — read `calc/totalTime`	Raise `snap` first, then `jerk`
`calc/snapArray` shows 17 entries, not 18	Expected: the last segment is not published	The missing entry is always 0
A bound reads back positive after writing a negative one	Expected: the magnitude is used	Write positive values
I need this on several axes	Not possible — this block is single axis	Use one instance per axis

A starting point for an axis that may move at 0.5 units per second:

targetProfile/velocity     = 0.5
targetProfile/acceleration = 5.0
targetProfile/jerk         = 100.0
targetProfile/snap         = 1000.0
command/type               = 1

Limits and errors

Limit	Set by	What happens	Reported
The four bounds	`targetProfile`	Respected exactly. The profile uses as much of each as it needs; a short move reaches none of them	`calc/totalTime` and `calc/numberOfSamples`
A bound of 0	Nothing	The move is refused and the output does not change	Logged, and repeated every hundredth cycle while it persists
A relative move of exactly 0	Checked	Refused as an incorrect move command	Logged, and repeated
Bound signs	Fixed	Negative bounds are used as their magnitude	Read the values back
A very small bound	Nothing	Accepted, and produces an enormous move time	`calc/totalTime`
Arrival	The profile	The move lands exactly on the target, not within a rounding error	`outputProfile/position`
Segment durations	Fixed	Rounded up to whole cycles, so short moves take longer than the bounds imply	`calc/totalTime`
Position move abort	`command/start`	Clearing it aborts, but only once the axis is at constant speed	`status/isAborted`
Jog abort	`command/abort`	Aborts, but only once the axis is at constant speed	`status/isAborted`
Abort stopping point	Nothing	The braking half plays out and the axis stops wherever it ends. Not the target, and not predicted	Not reported
Starting position	Not settable from the tree	An absolute move always starts from 0 unless the block is driven from an application	Not reported
Jog latency	Fixed	A new jog target is read every hundredth cycle, at constant speed only	Not reported
Axis count	Fixed	One axis per instance, always	Not reported

The block logs an error, repeatedly, when a bound is 0 or the move command is not valid. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Interpolator

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

Control3 3.30–3.34

Interpolator fills in the gaps between values that arrive more slowly than the control loop runs. A trajectory point every 10 ms on a 1 ms task leaves nine cycles with nothing new to follow; this block generates those nine, so the controller downstream sees a continuous command instead of a staircase.

It offers two shapes. Straight-line segments are the default and cost one segment of delay. Cubic segments with matched slopes at the joins are smoother — the only interpolation here with no corner at a join — and cost two.

flowchart LR
    i1(["input — the slowly arriving value"]) --> B["Interpolator"]
    i2(["disable"]) --> B
    B --> o1(["output — interpolated value, every cycle"])
    B --> o2(["isEnabled"])

Set sampleFactor to the number of task cycles between arrivals: input every 10 ms on a 1 ms task means 10. Delay is sampleFactor × task period with lookAhead false, and twice that with lookAhead true — 10 ms and 20 ms in that example. With filterSamples at 0 the output passes exactly through every arrived value; above 0 it no longer does, and adds a lag of (filterSamples + 1) × task period on top.

Nothing here detects when a new value actually arrives. The block counts cycles, so sampleFactor must match the arrival rate — see the symptom table. outputFiltered no longer exists; if you are upgrading, see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The slowly arriving value. One element per channel; the channel count is fixed by the machine configuration. The block reads it once per segment, not every cycle.
`disable`	-	-	True bypasses the interpolation: `input` passes straight to `output`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	signal unit	The interpolated value, fresh every cycle, one element per channel. Equals `input` exactly while bypassed. Ramps from zero to the first arrived value over one segment after every controller start. With `filterSamples` at 0 it passes exactly through each arrived value at the end of its segment.
`isEnabled`	-	True when `enable` is true and `disable` is false. A single value for the whole block, not one per channel.

Parameters

Path	Unit	Default	Range	Effect
`sampleFactor`	cycles	1	1 – 1000	Task cycles per arriving value. Must match your input’s arrival rate. Out-of-range values are corrected silently, and 1 makes the block a one-cycle delay.
`filterSamples`	samples	0 (off)	0 – 1000	Extra smoothing applied after interpolation. 0 is off and is the right default. Above 0 it adds a lag of (`filterSamples` + 1) cycles and the output stops passing exactly through the arrived values. Corrected silently if out of range.
`enable`	-	true	-	False bypasses the interpolation: `input` passes through unchanged.
`lookAhead`	-	false	-	False gives straight segments with a corner at each join. True gives cubic segments with matched slopes and no corner, at twice the delay. Change it with the machine at rest.

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

Setup

Measure how often the source updates input, in task cycles. Divide the update period by the task period: a 10 ms source on a 1 ms task is 10.
Link the source into input and confirm on a trace that input moves in steps at the rate you measured.
Set enable false. output equals input sample for sample and isEnabled reads false.
Set sampleFactor to the number from step 1, filterSamples to 0, and lookAhead false. Read both numbers back to confirm they were accepted.
Set enable true. output should now move smoothly every cycle instead of in steps.
Overlay input and output on one trace. output should reach each arrived value exactly at the moment the next one arrives, and never hold flat mid-segment.

Step 6 is the check that sampleFactor matches. A flat stretch at the end of each segment means the value is too low; output still moving in steps means it is too high. Get this right before tuning anything else.
Trace every element of input and output. An element that reads zero while the machine moves is an unwired channel.

Tuning

Get sampleFactor right first, with Setup step 6. Nothing else in this block works until the segment length matches the arrival rate.
Decide whether you need lookAhead. Leave it false unless the corner at each join is visibly reaching the machine — as a tick in the velocity, a bump in the torque, or audible roughness at the update rate.
If you enable lookAhead, re-measure your total delay. It doubles, and whatever loop consumes output pays for it in phase margin.
With lookAhead true, watch a sharp change of direction on a trace. Cubic segments overshoot on a corner — the output will go past the commanded value and come back. If that overshoot is beyond what the machine can accept, use straight segments instead.
Leave filterSamples at 0 unless you have residual noise the interpolation itself cannot handle. It costs lag on top of the interpolation delay and it stops the output passing through the arrived values exactly.
Re-check sampleFactor after any task-rate change. It counts cycles, so the same value is a different segment length in seconds — rescale it by the ratio of the task periods, and re-check that it still matches the arrival rate.

Read the delay off either curve as its horizontal offset from the dashed input.

Symptom	Cause	Action
`output` holds flat at the end of every segment	`sampleFactor` is lower than the actual arrival rate, so each segment finishes early	Raise `sampleFactor` to the measured number of cycles between arrivals
`output` still moves in visible steps	`sampleFactor` is higher than the arrival rate, so segments are cut short	Lower `sampleFactor` to the measured number
`output` drifts in and out of matching the input	The source’s update rate is not constant	Fix the source’s timing; this block cannot follow a varying rate
A tick in velocity or torque at the update rate	Expected with straight segments: the slope jumps at each join	Set `lookAhead` true, and accept twice the delay
`output` overshoots past a commanded value on a sharp turn	Expected with `lookAhead` true: cubic segments overshoot at a corner	Set `lookAhead` false, or bound the output downstream
The delay doubled after switching to `lookAhead`	Expected: cubic segments need the next value before they can start	Budget for it, or go back to straight segments
A glitch when `lookAhead` was changed while running	The block does not clean up its state on a mode change	Change `lookAhead` with the machine at rest
`output` no longer reaches the arrived values exactly	`filterSamples` is above 0	Set `filterSamples` to 0 if the arrived values must be honoured
The loop consuming `output` went soft after raising `filterSamples`	Expected: the extra smoothing adds lag on top of the interpolation delay	Set `filterSamples` back to 0 and fix noise at its source
`output` ramps up from zero for one segment after every start	Expected: the block has no previous value to interpolate from	Gate the consumer off `isEnabled` plus one segment
A large ramp on `output` after re-enabling with straight segments	Expected: the block interpolates from the value it last held to the current input	Re-enable at rest, or use `lookAhead`, whose first segment after a re-enable is deliberately straight and clean
`sampleFactor` or `filterSamples` reads back different from what you wrote	Outside the accepted range	Work within the value you read back
Setting `sampleFactor` to 0 gave 1	Expected: 1 is the minimum, and it makes the block a one-cycle delay	Set the real cycle count
The delay in seconds changed after a task-rate change	Expected: `sampleFactor` counts cycles, not seconds	Rescale it by the ratio of the task periods
Some channels interpolate differently from others	Not possible — all channels share one segment length and one mode	Use a separate instance per channel group
`output` went to a non-numeric value	A non-numeric value reached `input`	Fix the source, then bypass the block for one cycle — that clears its state completely

A starting point for a 10 ms trajectory source on a 1 ms task, with straight segments and no extra smoothing:

sampleFactor  = 10
filterSamples = 0
lookAhead     = false
enable        = true

Limits and errors

Limit	Set by	What happens	Reported
`sampleFactor` within 1 – 1000	Fixed	A value outside the range is replaced by the nearest edge. 1 is a one-cycle delay	Silently; read `sampleFactor` back
`filterSamples` within 0 – 1000	Fixed	A value outside the range is replaced by the nearest edge. 0 switches the extra smoothing off	Silently; read `filterSamples` back
Arrival rate	Nothing	Not checked. The block counts cycles and never looks at whether `input` actually changed, so a mismatch between `sampleFactor` and the real arrival rate is silent — it shows only as the shape of `output`	Not reported
Overshoot with `lookAhead` true	Nothing	Cubic segments overshoot at a corner, and there is no limit on by how much. Bound the output downstream if the machine cannot accept it	Not reported
`output`	Nothing	Unbounded. Limit it downstream if the consumer needs a bound	Not reported
Block state	A bypassed cycle	Bypassing the block clears its state completely. There is no separate reset	Not reported
`outputFiltered`	Removed	This path no longer exists. It was removed in an earlier release and its value was always identical to `output`. A linking file still referencing it will not resolve — point it at `output` instead	Not reported; the link fails to resolve
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

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

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: MotionPlayer

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

Control3 3.30–3.34

MotionPlayer replays recorded motion from files on disk. It reads a folder of profile files at startup, keeps them in memory, and streams one row at a time onto a fifty-wide output. Play, pause, stop and reload are commanded from the tree.

Use it to replay a taught motion, a test sequence or a recorded trajectory.

flowchart LR
    i1(["command"]) --> B["MotionPlayer"]
    i2(["timeScaleFactor"]) --> B
    p1(["profileID"]) --> B
    B --> o1(["output — 50 columns"])
    B --> o2(["state"])
    B --> o3(["error"])
    B --> o4(["activeProfileID"])
    B --> o5(["activeProfileTimestamp"])
    B --> o6(["activeProfileEndTime"])
    B --> o7(["activeProfileEnding"])
    B --> o8(["fractionComplete"])
    B --> o9(["numberOfProfiles"])

The output is never interpolated. It holds each file row until the next one is due, so the output is a staircase whose step size is set entirely by how finely the file was recorded. This is the single most important thing to know about the block.

Two behaviours will surprise you. Both are by design.

Stopping rewinds. Pausing holds. A stopped player drives its output back to the profile’s first row and keeps it there.

When a non-looping profile ends, the output jumps back to the first row, one cycle after it completes. If the file does not end where it starts, that is a step of the whole profile range on your output. Make the file end where it begins, or stop using its output before it finishes.

File format

Files live in a folder chosen when the controller is built, and are read once at startup.

The filename must begin with a number followed by an underscore — 00_home.csv, 12_pick.csv. That number is the profileID.
Lines beginning with # are comments.
A line reading loop = 1 makes the profile repeat; loop = 0, or no such line, plays it once.
Every other line is one row: the first number is the time in seconds, and the rest are the data columns, separated by spaces or tabs.
Times start at zero and must increase down the file. This is not checked — a file whose time column goes backwards will skip rows.
At most 50 data columns. Extra columns are dropped silently, and unused columns read 0.
Avoid blank lines. Each one adds an invisible all-zero row.

Signals

Inputs

Path	Unit	Range	Description
`command`	-	0 to 4	0 none, 1 play, 2 pause, 3 stop, 4 reload. Write the number; the block clears it back to 0 once acted on, so it is a pulse, not a level.
`timeScaleFactor`	-	above 0	Multiplies the playback speed. 1 is normal, 0.5 is half speed. Not checked. 0 freezes playback; a negative value stalls it rather than rewinding; a large value skips rows.

Outputs

Path	Unit	Description
`output`	file unit	The 50 columns of the row being played. Columns your file does not have read 0.
`state`	-	0 stopped, 1 playing, 2 paused, 3 finished, 4 and 5 reloading.
`error`	-	0 none, 1 no profile loaded, 2 the requested id does not exist.
`activeProfileID`	-	The profile actually loaded. -1 means none — check this first when nothing plays.
`activeProfileTimestamp`	s	The file timestamp of the current row, not the elapsed time. It advances in jumps, one per row.
`activeProfileEndTime`	s	The last timestamp in the loaded file — how long the profile runs at normal speed.
`activeProfileEnding`	-	0 the profile plays once, 1 it loops. Read from the file’s `loop =` line.
`fractionComplete`	-	How far through the profile, 0 to 1. Reads 1.0 when no profile is loaded, so read `activeProfileID` alongside it.
`numberOfProfiles`	-	How many files loaded successfully. 0 means the folder was missing, empty, or every file was rejected.

Parameters

Path	Unit	Default	Range	Effect
`profileID`	-	0	0 upward	Which profile to play next. Changing it while a profile is playing does nothing until that profile ends — which is how profiles are sequenced back to back. If no file has this id, `error` reads 2 and `activeProfileID` reads -1.

profileID is persistent and survives a controller restart, so the player comes back with the same profile selected. No parameters exist below this block, and the folder the files are read from is not visible in the tree.

Setup

Put your profile files in the player’s folder, named <number>_<name>.csv.
Start the controller and read numberOfProfiles. It should match the number of files you provided. A 0 here means the folder was not found — nothing else in the tree will tell you that.
Read activeProfileID. It should be 0 at startup, or -1 if no file has id 0.
Read activeProfileEndTime and check it against the last timestamp in your file. A mismatch means the file did not parse as you expected.
Set profileID to the profile you want and confirm activeProfileID follows it and error reads 0.
Write 1 to command to play.

Step 6 moves the machine, immediately and at whatever rate the file was recorded. Confirm the file’s first row matches where the machine already is, or the first output will be a step.
Watch fractionComplete climb to 1 and state go to 0 or 3.

Tuning

Check that the file’s first row matches the machine’s resting position. The player makes no attempt to blend into the profile.
Check that a non-looping file ends where it starts, or arrange for its output to be ignored once fractionComplete reaches 1. Otherwise the snap back to row 0 is a step.
Read activeProfileEndTime and divide it by the number of rows to get the average row interval. That interval is your output’s step size.
If the machine is rough during playback, the file is too sparsely sampled. Re-record it more finely, or filter the output downstream.
Use timeScaleFactor to slow a profile down while commissioning. Halving it halves the speed and doubles the duration.
Sequence profiles by writing the next profileID while the current one is still playing. The switch happens exactly at the end, with no gap.
After changing files on disk, write 4 to command to reload. Wait for state to leave 4 and 5 before playing.

Reloading while a profile is selected is not safe in this version. Stop the player, set profileID to a different value and back again after the reload completes, so the profile is re-resolved.

Read your file’s step size off the height of the treads.

Symptom	Cause	Action
`numberOfProfiles` is 0	The folder is missing, empty, or every file was rejected	Check the controller log — every rejected file is logged by name
A file was not loaded	Its name does not start with a number and an underscore, or another file already claims that id	Rename it. The log message mentions an “id: tag”, which is wrong — it is the filename that carries the id
`activeProfileID` reads -1	No file has the requested `profileID`	Set `profileID` to an id that exists; `error` reads 2
`fractionComplete` reads 1.0 and nothing plays	No profile is loaded	Check `activeProfileID` — 1.0 here means “nothing”, not “finished”
The output stepped at the start of playback	The file’s first row does not match where the machine is	Re-record the file from the resting position
The output stepped at the end of playback	Expected: a finished non-looping profile snaps back to row 0	End the file where it starts, or ignore the output past `fractionComplete` 1
Stopping caused a jump	Expected: stop rewinds to row 0	Use pause, which holds
The output is a visible staircase	The file’s rows are too far apart, and the block never interpolates	Re-record more finely, or filter downstream
The motion is jerky at the loop point	The file’s last row does not match its first	Make them match
Playback froze	`timeScaleFactor` is 0 or negative	Set it above 0
Rows appear to be skipped	`timeScaleFactor` is large, or the file’s time column is not increasing	Check both. Non-monotonic times are not validated
Some columns read 0	The file has fewer than 50 columns	Expected
Columns past the 50th are missing	Only 50 are carried	Split the profile across two players
A `profileID` change had no effect	Expected: it is deferred until the current profile ends	Stop the player first if you need it immediately
The player misbehaved after a reload	Reloading while a profile is selected is not safe in this version	Follow the callout in Tuning step 7
A `command` write disappeared	Expected: the block clears it once acted on	Read `state` to confirm the command took

A starting point:

profileID       = 0
timeScaleFactor = 1.0
command         = 1     (play)

Limits and errors

Limit	Set by	What happens	Reported
Folder	Fixed at build time	Read once at startup. Not visible in the tree. A missing folder is logged and leaves nothing loaded	`numberOfProfiles` reads 0
File names	Fixed	Must be `<number>_<name>.csv`. Others are logged and skipped	Controller log only
Duplicate ids	Checked	The first file wins; the second is logged and skipped	Controller log only
Data columns	50	Extra columns are dropped silently; missing ones read 0	Not reported
Row timestamps	Nothing	Must increase down the file. Not validated — a backwards step makes rows be skipped	Not reported
Blank lines	Nothing	Each one adds an all-zero row	Not reported
Interpolation	Fixed	None. Each row is held until the next is due	Not reported
`timeScaleFactor`	Nothing	Not checked. 0 freezes; negative stalls; large skips rows	Not reported
Profile switch	Deferred	A new `profileID` takes effect only when the current profile ends	`activeProfileID`
End of a non-looping profile	Fixed	The output jumps back to row 0 one cycle after completion	`state`, `fractionComplete`
Stop	Fixed	Rewinds the output to row 0 and holds it there	`state` reads 0
Pause	Fixed	Holds the output where it is	`state` reads 2
Reload	`command` 4	Re-reads the folder on a background thread. Not safe while a profile is selected in this version	`state` reads 4 then 5
Loading time	The files	The player reports reloading and cannot play until parsing finishes	`state`

The block logs every file it loads, skips or fails to parse, at startup and on every reload. Nothing is logged during playback. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Sequencer

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

Control3 3.30–3.34

Sequencer steps through a table of values on a timer. Each output channel has its own row of values and they all advance together, holding each column for the time you give it. Use it for a pattern — a sequence of beeps on a speaker, a blink pattern for an indicator light, a fixed series of setpoints.

flowchart LR
    i1(["input — true runs the sequence"]) --> B["Sequencer"]
    B --> o1(["output — one value per channel"])

While input is true the block advances one element every durations[e] seconds and wraps at the end of the table. While it is false the outputs sit at element 0 and the sequence is reset, so it always restarts from the beginning.

Element 0 is the idle value, not the first step. When the sequence starts it goes straight to element 1. A five-element table plays 1, 2, 3, 4, 0, 1, 2 … — element 0 is what you see at rest and once per loop.

Set the durations before you use it. They default to zero, and a zero-duration element advances every task cycle, so an unconfigured sequencer flickers through its table at the task rate.

This block has no enable, no disable and no isEnabled. input false is the idle state.

Signals

Inputs

Path	Unit	Range	Description
`input`	-	-	True runs the sequence; false parks every channel on element 0 and resets the timer. It is a level, not a trigger — the sequence restarts from the beginning each time it goes true.

Outputs

Path	Unit	Description
`output`	whatever you put in the table	The active element’s value, one per channel. All channels step together.

Parameters

Path	Unit	Default	Range	Effect
`durations`	s	all 0	above 0	How long each element is held, one per element, shared by every channel. A zero or negative duration advances in one task cycle, which is what the defaults do.
`channel_01`, `channel_02`, …	table unit	all 0	any	One row per output channel, one value per element. Element 0 is the idle value.
`ids`	-	all −1	any	The IDs this sequencer answers to, used by `SequenceSelector` to choose between several. Ignored when the block is used on its own.

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

The table’s shape — how many elements and how many channels — is fixed when the machine is built. Read the length of durations and of output to discover it.

Setup

Read the length of durations to find how many elements the table has, and the length of output for the channel count. Both are fixed.
Fill in durations first. Every element needs a positive time, or the sequence will race through it.
Fill each channel_NN row with the values that channel should take at each element. Put the idle value in element 0 — that is what the channel shows while the sequence is not running.
Leave input false and confirm every channel sits at its element 0 value.
Set input true and watch the outputs step. Time one full loop against the sum of your durations.

Step 5 drives whatever is connected to the outputs. If these values command real motion rather than an indicator, check the whole table before you start it — the sequence loops until the input goes false.
Set input false and confirm every channel returns to its element 0 value immediately.

Tuning

There is nothing to tune — the table is the configuration.

Keep every duration positive. A zero means “one task cycle”, which is almost never what you want.
Remember the sequence starts at element 1. If you want a specific value at the moment it starts, put it there, not in element 0.
Put the rest value in element 0. It is what shows at idle and it is also part of the loop, so it acts as a gap at the end of each pass.
All channels share one duration row, so they cannot step at different rates. Use a second sequencer for a second rhythm.
Nothing here needs re-checking after a task-rate change — the durations are in seconds.

Read each element’s dwell off the width of a step.

Symptom	Cause	Action
The outputs flicker rapidly through the table	The durations are zero — the default	Set a positive duration for every element
The first value of the pattern never appears	Expected: the sequence starts at element 1, and element 0 is the idle value	Put the first step in element 1
The outputs sit at one value and never move	`input` is false	Set it true
The sequence restarts from the beginning every time	Expected: `input` is a level, and going false resets it	This is the designed behaviour
One element is much shorter than configured	Its duration is zero or negative	Write a positive value
The channels do not step together	Not possible — they share one timer and one element index	Check what consumes the outputs
The channels need different rhythms	Not possible — one duration row for all of them	Use a second sequencer
The loop takes longer than the sum of the durations	Expected: each element is held for its own listed time, and element 0 is part of the loop	Include element 0’s duration in the total
I cannot tell which element is active	The block does not publish it	Infer it from the output values
The table is too short	Its size is fixed when the machine is built	It needs a configuration change
The sequencer never runs inside a selector	Its `ids` do not match the selector’s input	Check the `ids` array

A starting point for a three-element blink pattern on one channel, half a second per step:

durations  = 0.5, 0.5, 0.5
channel_01 = 0.0, 1.0, 0.0

At rest the channel reads 0. Running, it plays 1.0, then 0.0, then 0.0, and loops.

Limits and errors

Limit	Set by	What happens	Reported
`durations` above 0	Nothing	Not checked. A zero or negative duration advances that element in one task cycle. All zeros — the default — makes the whole table free-run at the task rate	Not reported
Active element	Not published	Which step is running cannot be read from the parameter tree	Not reported
Table shape	Machine configuration	The element count and channel count are fixed when the machine is built. Read the array lengths to discover them	Not reported
`output`	Nothing	Whatever is in the table. Bound it downstream if the consumer needs a limit	Not reported
Timing	Task rate independent	Durations are in seconds and keep their meaning at any task period	Not applicable
Block state	`input` false	Going idle resets the timer and the element. There is no separate reset	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: SequenceSelector

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

Control3 3.30–3.34

SequenceSelector holds several Sequencer patterns and picks between them by ID. Give it a number and whichever sequencer lists that number in its ids drives the output. If none matches, a configured default is emitted.

Use it to map a machine state to an indicator pattern, or an error code to a beep sequence.

flowchart LR
    i1(["input — the ID to select"]) --> B["SequenceSelector"]
    B --> o1(["output — the selected pattern's values"])

Every sequencer runs every cycle. The ones that do not match are held at their element 0 and their timers reset — so a pattern always starts from the beginning when it is selected, never part-way through.

If two sequencers list the same ID, the later one wins and the earlier one runs invisibly. Nothing warns about it.

Sequencer IDs default to −1, so an unconfigured selector driven with −1 matches every sequencer at once. Give each one a real ID.

This block has no enable and no disable. To emit the default, send an ID that no sequencer lists.

Signals

Inputs

Path	Unit	Range	Description
`input`	-	any integer	The ID to select on. Every sequencer is asked whether this number is in its `ids` list.

Outputs

Path	Unit	Description
`output`	whatever the patterns contain	The selected sequencer’s output, one value per channel — or `defaultOutput` when nothing matches.

Parameters

Path	Unit	Default	Range	Effect
`defaultOutput`	pattern unit	all 0	any	What every channel shows when no sequencer matches the input.

defaultOutput is persistent and survives a controller restart.

The patterns live below this block, in sub-trees named Sequencer01, Sequencer02 and so on — one per sequencer, numbered from 1. Each carries its own ids, durations and channel_NN rows. See sequencer.md for how to fill one in.

All sequencers share one shape: the same number of elements, the same number of channels and the same ID-list length, fixed when the machine is built.

Setup

Read how many sequencers this instance has by looking for the SequencerNN sub-trees, and note they are numbered from 1.
Give every sequencer a distinct ID. They default to −1, so an unconfigured set all match the same input and only the last one shows.
Configure each sequencer’s durations and channel_NN rows, per sequencer.md. Remember each pattern starts at its element 1, and element 0 is its rest value.
Set defaultOutput to what the machine should show when nothing is selected — usually the same as the sequencers' element 0.
Send an ID that no sequencer lists and confirm every channel reads defaultOutput.
Send each configured ID in turn and confirm the right pattern runs.

Step 6 is the only check that the IDs are distinct. If two sequencers share an ID you will see the later one and never know the earlier one is also running.

Tuning

There is nothing to tune. The work is assigning IDs and filling in the patterns.

Keep the IDs distinct across sequencers. Nothing checks this and nothing reports a clash.
Choose an ID that means “nothing” and make sure no sequencer lists it. That is how you get the default.
A sequencer may list several IDs, so one pattern can serve several machine states.
Adding an unused sequencer costs the same processing time as a used one — they all run every cycle. Size the instance to what you need.
Nothing here depends on the task rate; the sequencers' own durations are in seconds.

The flat section is the default. Each pattern restarts from its first element whenever its id is selected — see sequencer.md for how a single sequence steps.

Symptom	Cause	Action
Every ID produces the same pattern	The sequencers' `ids` are all at their default of −1, so they all match	Give each a distinct ID
An ID produces the wrong pattern	Two sequencers list it, and the later one wins	Make the IDs distinct
A pattern seems to run but is not visible	It matched, but a later sequencer matched too and overwrote it	Check every `ids` list for duplicates
The output sits at the default for a valid ID	No sequencer lists that ID	Check the `ids` arrays
A pattern starts part-way through	Not possible — non-matching sequencers are reset, so a selected pattern always starts at the beginning	Check what consumes the output
The pattern flickers rapidly	That sequencer’s `durations` are zero	Set positive durations in its sub-tree
The first value of a pattern never appears	Expected: a sequence starts at its element 1	Put the first step in element 1
Switching IDs restarts the new pattern from the beginning	Expected, and deliberate	This is the designed behaviour
I cannot tell which sequencer is selected	The block does not publish it	Compare `input` against each sub-tree’s `ids`
I need more patterns	The count is fixed when the machine is built	It needs a configuration change
I need a longer pattern than the others	All sequencers share one shape	It needs a configuration change

A starting point for three patterns selected by machine state, with state 0 meaning idle:

defaultOutput      = 0.0
Sequencer01/ids    = 1, -1, -1, ...
Sequencer02/ids    = 2, -1, -1, ...
Sequencer03/ids    = 3, -1, -1, ...

Sending 0 gives the default; 1, 2 and 3 give the three patterns. Note the unused ID slots are left at −1, so do not send −1 as a selection.

Limits and errors

Limit	Set by	What happens	Reported
ID uniqueness	Nothing	Not checked. If two sequencers list the same ID, the later one’s output wins and the earlier one runs unseen	Not reported
Unconfigured IDs	Fixed	Sequencer IDs default to −1, so an ID of −1 matches every unconfigured sequencer	Not reported
Selected sequencer	Not published	Which pattern is running cannot be read from the parameter tree	Not reported
No match	`defaultOutput`	Every channel takes the default. This is the only way to select “nothing”	Not reported
Sequencer shape	Machine configuration	Element count, channel count and ID-list length are the same for every sequencer and fixed when the machine is built	Not reported
Processing cost	Fixed	Every sequencer runs every cycle whether selected or not	Not reported
`output`	Nothing	Whatever the patterns contain. Bound it downstream if the consumer needs a limit	Not reported
Block state	None at this level	Each sequencer resets itself as soon as it stops matching	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: Fader

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

Control3 3.30–3.34

Fader moves its output smoothly to whatever value its input holds, over a configured fade time, and publishes the matching velocity and acceleration as it goes.

Write a new number to input and the output travels there. Write another before it arrives and the fade blends into the new target rather than restarting — the output, its velocity and its acceleration all stay continuous.

flowchart LR
    i1(["input"]) --> B["Fader"]
    i2(["timeScaleFactor"]) --> B
    i3(["timeScaleFactorDot"]) --> B
    B --> o1(["output"])
    B --> o2(["outputDot"])
    B --> o3(["outputDDot"])
    B --> o4(["done"])
    B --> o5(["delaying"])
    B --> o6(["numTargets"])

The fade time is what you set. Unlike SetpointGenerator, this block does not work out how fast it may go — it takes exactly fadeTime seconds whatever the distance, so a large jump means a fast move. Size fadeTime from the largest jump you expect.

Targets queue up. Each change to input adds one. When the queue is full the oldest is dropped, and the only sign is that numTargets stops growing. Watch it if your application writes targets quickly.

Four of the parameters below may not exist on your instance. fadeTime, delayTime, jerkFactor and accelerationFactor are hidden when the block that contains this fader controls them itself. If you cannot find them, they are being set for you.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The target. A change queues a new fade; writing the same value again does nothing. Compared exactly, so an input that dithers in its last digit will queue a target every cycle and keep the queue full. Feed it settled values.
`timeScaleFactor`	-	any	Stretches the fade’s clock. 1 is normal, 0.5 is half speed, 0 freezes the fade exactly where it is and nothing is lost — it resumes when you set it back. A negative value is used as its magnitude; the fade does not run backwards.
`timeScaleFactorDot`	1/s	any	How fast `timeScaleFactor` is itself changing. Set this whenever you ramp the scale factor, or the published acceleration will be wrong.

Outputs

Path	Unit	Description
`output`	signal unit	The value on its way to the target.
`outputDot`	signal unit per second	Its velocity — this really is the rate of change of `output`, including across a retarget.
`outputDDot`	signal unit per second²	Its acceleration.
`done`	-	The queue is empty and the output has arrived. Starts true.
`delaying`	-	The newest target is still waiting out its delay and has not started moving.
`numTargets`	-	How many targets are queued. If this stops growing while you keep writing, the oldest are being dropped.

Parameters

Path	Unit	Default	Range	Effect
`faderType`	-	0	0 or 1	Which profile shape. See the table below. Changing it while a fade is running switches that fade’s shape part-way, which produces a kink — change it only when `done` is true.
`maxTargets`	-	10	1 upward	How many targets may be queued. Values below 1 are treated as 1. When the queue is full the oldest target is dropped and its position becomes the new starting point.
`applyTimeScaleToDelay`	-	true	-	Whether `timeScaleFactor` stretches `delayTime` as well as the fade itself.
`fadeTime`	s	1.0	above 0	How long the fade takes, whatever the distance. Negative values are used as their magnitude and written back. A fade shorter than one task period snaps instead.
`delayTime`	s	0.0	0 upward	How long to wait after a new target before moving. Negatives are used as their magnitude.
`jerkFactor`	-	0.333	0 to 0.5	Only used by the jerk-limited shape. The fraction of the profile spent changing acceleration. Values outside the range are clamped and written back.
`accelerationFactor`	-	0.429	0 to 0.5	Only used by the jerk-limited shape. The fraction spent accelerating. Also clamped and written back.

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

`faderType`	What the machine does	Parameters that matter
0 quintic	Position, velocity and acceleration all start and end at zero. The smoothest shape, and the default	`fadeTime`
1 jerk-limited	Reaches its acceleration and velocity plateaus and holds them, so more of the move happens at full speed	`fadeTime`, `jerkFactor`, `accelerationFactor`

Setup

Have your application seed the fader at the machine’s current value before enabling anything downstream, so the first fade does not start from zero.
Set fadeTime from the largest jump you expect and what the machine can take at that distance.
Leave faderType at 0 for a first pass.
Write a small change to input and watch output travel there.

Step 4 moves the machine, over fadeTime seconds regardless of how far it has to go. Start with a small change.
Confirm done goes false at the start and true on arrival.
Write a second target while the first is still moving. output should bend towards the new value with no step in outputDot.
Check numTargets grows and falls back to 0.

Tuning

fadeTime is the only number that matters for most uses. Set it from the biggest jump: the peak velocity is roughly twice the distance divided by the fade time for the quintic shape.
If the fade is smooth but too slow for small jumps and too fast for large ones, this block is the wrong one — SetpointGenerator derives its duration from velocity and acceleration limits instead.
Switch to the jerk-limited shape if you need more of the move spent at full speed. It reaches its plateaus and holds them, so it covers ground faster for the same duration.
With the jerk-limited shape, tune jerkFactor and accelerationFactor together. Both are fractions of the profile and both cap at 0.5. The pairs 0.333 with 0.333, and 0.333 with 0.429, are the two standard settings.
Use delayTime when several faders should start together after a common trigger. Decide whether the delay should stretch with the time scale and set applyTimeScaleToDelay to match.
Use timeScaleFactor for a speed override. Ramp it rather than stepping it, and set timeScaleFactorDot while you do, or outputDDot will be wrong for as long as the ramp lasts.
Raise maxTargets if your application writes targets faster than the fades complete, and watch numTargets to see whether the queue is filling.

The velocity trace has no step where the second target arrives. That continuity is what this block is for.

Symptom	Cause	Action
A large jump moved much faster than a small one	Expected: every fade takes `fadeTime` regardless of distance	Use `SetpointGenerator` if you need a velocity limit
The move was instant	`fadeTime` plus `delayTime` is under one task period	Lengthen `fadeTime`
A kink appeared mid-fade	`faderType` was changed while a fade was running	Change it only when `done` is true
`numTargets` stopped growing while I kept writing	The queue is full and the oldest targets are being dropped	Raise `maxTargets`, or write less often
The output jumped to an unexpected place	An old target was dropped from a full queue, moving the starting point	Same
The output never settles	`input` is dithering, so a new target is queued every cycle	Feed it settled values
Everything became invalid and stayed that way	An input that is not a number queues a target every cycle	Fix the upstream signal
The fade froze part-way	`timeScaleFactor` is 0	Set it above 0. Nothing was lost — it resumes
I set a negative `timeScaleFactor` and it went forwards anyway	Expected: the magnitude is used	This block cannot run backwards
`outputDDot` was wrong while I changed the speed override	`timeScaleFactorDot` was left at 0	Set it while ramping `timeScaleFactor`
`outputDot` disagrees with `output`	It should not — this block carries derivatives correctly	Check what is consuming them
The delay did not scale with the override	`applyTimeScaleToDelay` is false	Set it true
`fadeTime` reads back positive after I wrote a negative	Expected: the magnitude is used	Write positive values
`jerkFactor` reads back as 0.5	Expected: it is capped at 0.5	Use a value in range
The first fade went to the wrong place	The fader was not seeded at the machine’s value	Seed it from your application before enabling
A fade resumed after a restart	The queue is not cleared at startup	Seed the fader after every start
I cannot find `fadeTime` in the tree	The block containing this fader controls it	Set it there instead
I need this on several channels	Not possible — this block is single channel	Use one instance per channel

A starting point:

fadeTime              = 1.0
delayTime             = 0.0
faderType             = 0
maxTargets            = 10
applyTimeScaleToDelay = true

Limits and errors

Limit	Set by	What happens	Reported
Fade duration	`fadeTime`	Exactly that long, whatever the distance. Not derived from any velocity or acceleration limit	`done`
Output velocity	Nothing	Not limited. It is whatever the distance and fade time imply	`outputDot`
Sub-cycle fades	Checked	A `fadeTime` plus `delayTime` under one scaled task period snaps to the target	`done` stays true
`fadeTime`, `delayTime` signs	Checked	Negatives are used as their magnitude and written back	Read the values back
`jerkFactor`, `accelerationFactor`	Checked	Clamped to 0 to 0.5 and written back	Read the values back
`maxTargets`	Checked	Forced to at least 1. When the queue is full the oldest target is dropped and its position becomes the new start	`numTargets`
`timeScaleFactor`	Partly checked	Negatives are negated. 0 freezes the fade with nothing lost	Not reported
`timeScaleFactorDot`	Nothing	Not checked. Leaving it at 0 while ramping the scale makes `outputDDot` wrong	Not reported
`faderType` mid-fade	Nothing	Not guarded. An in-flight fade switches shape and keeps the old shape’s timing, producing a kink	Not reported
Values that are not numbers	Nothing	Not checked. Such an input queues a new target every cycle	`numTargets` sits at its maximum
Startup	Fixed	The queue is not cleared, so a fade in flight resumes after a restart	`done`, `numTargets`
Channel count	Fixed	One channel per instance, always	Not reported

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

Verified against motorcortex-control3 3.30.0 (bc348fd).