– Switching and routing

Docs: ChannelSelector

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

Control3 3.30–3.34

ChannelSelector stores a set of values and fades its output between them as the selection changes. Pick a channel by number, or by raising its enable flag.

Use it to switch a gain, a speed limit or a mode setpoint between preset values without stepping the machine.

It switches between stored numbers, not between live signals. The values live in channelValue, a persistent parameter array you configure. To blend two live signals, use SimpleSwitch instead.

flowchart LR
    i1(["channelEnable"]) --> B["ChannelSelector"]
    i2(["timeScaleFactor"]) --> B
    p1(["channelValue"]) --> B
    p2(["useChannelNumberSelection"]) --> B
    p3(["channelNumberSelection"]) --> B
    p4(["defaultChannel"]) --> B
    B --> o1(["output"])
    B --> o2(["activeChannel"])
    B --> o3(["faderValue"])
    B --> o4(["channelPriority"])

channelPriority does nothing. It is published, and it is filled in with a value per channel at startup, but the block never reads it. When you select by enable flags, the highest-numbered enabled channel wins — put the channel that should take precedence last.

Changing the selection mid-fade is safe. The block always fades from wherever the output currently is, so a change part-way through picks up cleanly with no step.

Signals

Inputs

Path	Unit	Range	Description
`channelEnable`	-	true or false per channel	Which channels are available. The highest-numbered enabled channel is the one selected. Ignored when `useChannelNumberSelection` is true. Every flag is cleared at startup, so your application must rewrite them after each restart.
`timeScaleFactor`	-	above 0	Speeds up or slows down the fade while it runs. 0 freezes it. Reset to 1 every time the controller starts. A negative value leaves the output stuck.

Outputs

Path	Unit	Description
`output`	signal unit	The single blended value. One output, whatever the channel count.
`activeChannel`	-	Which channel the output is heading for, counting from 0.
`faderValue`	-	How far through the fade, 0 at the departure value and 1 on arrival. The straight-line fraction even when the shape is cosine.
`channelPriority`	-	Published but not used by anything. See the callout above.

Parameters

Path	Unit	Default	Range	Effect
`channelValue`	signal unit	zeros	unbounded	The stored value for each channel. This is what the output fades to. Writable at run time.
`useChannelNumberSelection`	-	false	-	When true, the selection comes from `channelNumberSelection` and `channelEnable` is ignored.
`channelNumberSelection`	-	0	0 to one below the channel count	Which channel to select, when the mode above is true. A value equal to the channel count is wrongly accepted and reads past the end of the value list — the output then becomes meaningless. Stay within range.
`defaultChannel`	-	0	0 to one below the channel count	Which channel is enabled at startup. Not range-checked — a value outside the channel count corrupts memory before the first cycle. Set it carefully.
`fadeTime`	s	5.0	one task period to 10	How long the output takes to reach a newly selected value. Above 10 is silently reduced to 10, with a warning in the log.
`fadeType`	-	0	0 or 1	0 straight line, 1 cosine. Both take the same time.

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

Setup

Decide how many channels you need. The channel count is fixed when the controller is built and defaults to 2.
Write the value for each channel into channelValue.
Set defaultChannel to the channel that should be active at startup. Check it is within the channel count — this one is not validated.
Set fadeTime. Start with a second or two.
Choose a selection mode:
- By number — set useChannelNumberSelection true and write channelNumberSelection. Simpler, and the mode that is fully validated.
- By flags — leave it false and raise channelEnable per channel, remembering the highest-numbered enabled channel wins.
Start the controller and confirm activeChannel matches what you asked for and output settles on that channel’s value.

The output is not stable until one fade time after startup. The block always starts a fade at start, even when the destination is the value it is already on. Do not act on output until faderValue reaches 1.
Change the selection and watch output travel to the new value.

Tuning

Trace channelValue and output together. The gap between the current and next value is the size of the change the fade will produce.
Set fadeTime from that gap and what the machine downstream can take.
Use the cosine shape unless you need the shortest transit — it has the same duration but no rate step at either end.
Watch activeChannel to confirm the selection is what you intended. With flag selection this is where a wrong assumption about priority shows up.
If you need to pause a change part-way, set timeScaleFactor to 0. The blend freezes exactly where it is and resumes when you set it back.
Change the selection mid-fade freely — the block re-departs from wherever the output is.
fadeTime is in seconds, so a task-rate change does not move it. But timeScaleFactor returns to 1 after every restart.

The fade always starts from the output, never from the previous channel’s value.

Symptom	Cause	Action
The wrong channel was selected	With flag selection the highest-numbered enabled channel wins, not the highest priority	Reorder your channels, or select by number
Setting `channelPriority` changed nothing	Expected: the block does not read it	Use channel order, or select by number
The output is nonsense and stays that way	`channelNumberSelection` equals the channel count, which reads past the end of the value list	Use 0 to one below the count
The controller misbehaved from startup	`defaultChannel` is outside the channel count, which is not validated	Set it within range
The output moved right after startup	Expected: the block always fades once at start	Wait for `faderValue` to reach 1
The enable flags were cleared after a restart	Expected: all flags are cleared at startup	Rewrite them from your application
The fade is shorter than I asked for	A time above 10 is reduced to 10	Check the log; 10 seconds is the maximum
A log warning mentions fade time, but I changed the channel number	The range check reuses the fade-time message	Check `channelNumberSelection` too
The fade is slower or faster than the time I set	`timeScaleFactor` is not 1	Set it to 1
`timeScaleFactor` reverted after a restart	Expected: it is forced to 1 at startup	Set it from your application after start
The fade froze part-way	`timeScaleFactor` is 0	Set it above 0
The output stuck and never arrives	`timeScaleFactor` is negative, which is not rejected	Write a positive value
A rate step at the start or end of a fade	The straight-line shape does that	Set `fadeType` to 1
A signal scaled by `faderValue` does not match	Expected: `faderValue` is the straight-line fraction	Apply the same cosine yourself
I need to blend two live signals	This block switches stored values only	Use `SimpleSwitch`
I need more channels	The count is fixed when the controller is built	Rebuild, or use a second instance

A starting point for a three-channel speed preset:

channelValue              = [0.1, 0.5, 1.0]
useChannelNumberSelection = true
channelNumberSelection    = 0
defaultChannel            = 0
fadeTime                  = 1.0
fadeType                  = 1

Limits and errors

Limit	Set by	What happens	Reported
Selection by flags	`channelEnable`	The highest-numbered enabled channel wins. Priority is not consulted	`activeChannel`
`channelPriority`	Fixed	Published and never read. Setting it has no effect	Not applicable
`channelNumberSelection`	Partly checked	Clamped, but one too high — a value equal to the channel count is accepted and reads past the end of the value list	Logged, with the wrong message text
`defaultChannel`	Nothing	Not checked at all. A value outside the channel count writes outside the enable array at startup	Not reported
Fade duration	`fadeTime`	The output reaches the selected value in that time, divided by `timeScaleFactor`	`faderValue`
Fade time range	Fixed at one task period to 10 s	Out-of-range values are clamped and written back	Logged as a warning, once per write
Departure point	Fixed	Every fade starts from the current output, so a mid-fade change is continuous	Not reported
`timeScaleFactor`	Nothing	Not checked. 0 freezes; negative leaves the output stuck short of the target	Not reported
`timeScaleFactor` persistence	Fixed	Forced to 1 at every controller start	Not reported
Startup	Fixed	Every enable flag is cleared, the default channel is enabled, and one fade always runs	`faderValue`
Values that are not numbers	Nothing	Not caught by the range checks	Not reported
Output count	Fixed	One output, whatever the channel count	Not reported
Channel count	Fixed at build time	Cannot be changed from the tree	Not reported

The block logs a warning when the fade time or the channel number is written out of range — both using the fade-time wording. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: ConfigurationSelector

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

Control3 3.30–3.34

ConfigurationSelector holds up to five matrices of the same size and publishes whichever one you select. All five can be edited while the controller runs, so a gain set, a transformation or a model’s coefficients can be changed and switched without rebuilding.

Set the matrix size to 1×1 and it becomes a five-way switch between single numbers.

flowchart LR
    p0(["configurationIndex"]) --> B["ConfigurationSelector"]
    p1(["configuration0"]) --> B
    p2(["configuration1"]) --> B
    p3(["configuration2"]) --> B
    p4(["configuration3"]) --> B
    p5(["configuration4"]) --> B
    B --> o1(["output"])

The switch is instantaneous. The output steps to the new matrix on the same cycle the index changes — there is no fade. That is usually what you want for a set of coefficients, because a blend of two validated configurations is a third one nobody validated. If the block downstream cannot take a step, smooth it there.

Matrices are stored one column at a time, not one row at a time. For a 3×3, tree elements 0, 1, 2 are the first column, not the first row. Fill them in that order or you will get the transpose of the matrix you meant. This catches nearly everyone once.

An index above 4 silently selects configuration0. Nothing reports that your request was rejected, so check output matches what you expected.

Signals

Outputs

Path	Unit	Description
`output`	depends on use	The selected matrix, published one column at a time. Updated every cycle, so an edit to the active configuration appears on the next one.

This block has no inputs. The selection and all five matrices are parameters, so everything about it is configured rather than driven.

Parameters

Path	Unit	Default	Range	Effect
`configurationIndex`	-	0	0 to 4	Which configuration appears on the output. Anything above 4 silently selects `configuration0`. Persistent, so the controller comes back up on whichever configuration it was left on.
`configuration0`	depends on use	zeros	unbounded	The matrix selected at index 0. Column-major — see the callout above.
`configuration1`	depends on use	zeros	unbounded	The matrix selected at index 1.
`configuration2`	depends on use	zeros	unbounded	The matrix selected at index 2.
`configuration3`	depends on use	zeros	unbounded	The matrix selected at index 3.
`configuration4`	depends on use	zeros	unbounded	The matrix selected at index 4.

All are persistent and survive a controller restart. All five configurations exist whether or not you use them, and each is the full matrix size, so an unused configuration still occupies its place in the tree. No parameters exist below this block.

The matrix size is fixed when the controller is built and cannot be changed from the tree.

Setup

Work out the storage order for your matrix size before you write anything. For a 3×3, the nine values run down the first column, then the second, then the third.
Write your first matrix into configuration0 in that order.
Read output back and confirm it matches. If it looks like the transpose of what you typed, you filled it row by row — refill it column by column.
Fill the other configurations you need. Leave the rest at zero.
Set configurationIndex and confirm output changes to the matching matrix.
Confirm the index survives a controller restart, and that the output comes back on the right configuration.

Whatever consumes output will act on the new values immediately when you change the index — there is no fade. If that is a controller gain, the machine’s behaviour changes on that cycle.

Tuning

There is nothing to tune in this block itself. The tuning lives in the matrices you put in it and in whatever consumes them.
Use it to hold alternative tunings side by side: a cautious set in configuration0, a production set in configuration1, a diagnostic set in configuration2.
Keep configuration0 as your safe fallback. It is what you get when the index is out of range, so it is the one that must always be sane.
Edit a configuration while the controller runs and the change reaches output on the next cycle — including the one currently selected. Editing the active configuration changes the machine’s behaviour immediately, one element at a time as you type them. Edit an inactive one and switch to it instead.
Verify each configuration by selecting it and reading output back, rather than trusting what you wrote.
Nothing here depends on the task rate, so none of this needs re-checking after a rate change.

The step is the point. Smooth it downstream if you need it smoothed.

Symptom	Cause	Action
The matrix came back transposed	It was filled row by row; storage is column by column	Refill it column by column
The output does not match any configuration I set	The index is above 4, so `configuration0` is selected	Use 0 to 4
Changing the index did nothing	The two configurations hold the same values, or the index is out of range both times	Read `output` back to see which is active
The machine’s behaviour changed while I was typing values	Expected: edits to the active configuration reach the output immediately	Edit an inactive configuration, then switch
The machine stepped when I changed the index	Expected: this block does not fade	Smooth it in the block downstream
The output was zeros at startup	The selected configuration is still all zeros	Fill it
A configuration I never use is cluttering the tree	Expected: all five always exist	Leave them at zero
The index reverted to something I did not set	It is persistent — it came back from the saved configuration	Set and save it deliberately
I need more than five	Not possible — five is fixed when the controller is built	Use a second instance
I need a different matrix size	Fixed when the controller is built	Rebuild
I need to fade between two configurations	Not possible here, and usually not wise	Put a switch downstream of this block

A starting point for a 3×3 used to hold two gain sets:

configuration0 = <the cautious set, column by column>
configuration1 = <the production set, column by column>
configurationIndex = 0

Limits and errors

Limit	Set by	What happens	Reported
`configurationIndex`	Checked	Anything above 4 selects `configuration0`. The block never reads outside its configurations	Not reported — the fallback is silent
Storage order	Fixed	Every matrix, including `output`, is laid out one column at a time	Not reported
Switching	Fixed	Instantaneous. The output steps on the same cycle the index changes	Not reported
Configuration edits	The tree	Reach `output` on the next cycle, including for the currently selected configuration	Not reported
Configuration count	Fixed at five	Cannot be extended from the tree	Not reported
Matrix size	Fixed at build time	All five configurations and the output share one size	Not reported
Values that are not numbers	Nothing	Not checked. A bad value in the selected configuration is copied to the output	Not reported
Startup	Fixed	The output is set from the saved index before the first cycle runs, so it is never briefly zero	Not reported
Values	Nothing	No range checking of any kind. The matrices mean whatever the block downstream makes of them	Not reported

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

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: SimpleSwitch

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

Control3 3.30–3.34

SimpleSwitch cross-fades between two sets of signals. A boolean picks which set you want and the output travels there over a configured time, in a straight line or along a smooth cosine.

Use it to hand a machine over between two sources — two setpoint generators, two controllers, manual and automatic — without a step at the changeover.

flowchart LR
    i1(["input1 — selected when toggle is false"]) --> B["SimpleSwitch"]
    i2(["input2 — selected when toggle is true"]) --> B
    i3(["toggle"]) --> B
    i4(["doInstantToggle"]) --> B
    B --> o1(["output"])
    B --> o2(["isOn"])
    B --> o3(["isOff"])
    B --> o4(["faderValue"])

Fading in and fading out are configured separately — their own times and their own shapes. A switch can ease in gently over two seconds and drop back in a tenth of one.

The fade is on the mixing fraction, not on the signals. If input1 and input2 are both moving, the output is a blend of two moving signals, and its rate of change during the fade is not bounded by anything you set here. Use SoftSwitch when the output’s velocity and acceleration must stay within limits.

Signals

Inputs

Path	Unit	Range	Description
`input1`	signal unit	unbounded	The set selected when `toggle` is false. This is where the block starts.
`input2`	signal unit	unbounded	The set selected when `toggle` is true.
`toggle`	-	true or false	Which input the output should travel to. A level, not a pulse — hold it. Flipping it back mid-fade reverses the fade from wherever it had got to.
`doInstantToggle`	-	true or false	While true, the output snaps to the selected input every cycle with no fade. Also a level: leave it true and the switch never fades again.

Outputs

Path	Unit	Description
`output`	signal unit	The blend. Same number of channels as the inputs.
`isOn`	-	The fade to `input2` has completed. Goes true a few cycles before `faderValue` actually reaches 1.
`isOff`	-	The fade to `input1` has completed. Starts true.
`faderValue`	-	How far through the fade, 0 at `input1` and 1 at `input2`. This is the straight-line fraction even when the fade shape is cosine, so scaling another signal by it will not match this switch’s own shape.

Parameters

Path	Unit	Default	Range	Effect
`fadeInTime`	s	5.0	one task period to 10	How long it takes to travel to `input2`. Values above 10 are silently reduced to 10, with a warning in the log.
`fadeOutTime`	s	5.0	one task period to 10	How long it takes to travel back to `input1`. Same ceiling.
`fadeInType`	-	0	0 or 1	The shape of the fade to `input2`. 0 straight line, 1 cosine.
`fadeOutType`	-	0	0 or 1	The shape of the fade back to `input1`.
`timeScaleFactor`	-	1.0	0 upward	Speeds up or slows down the fade while it runs. 0 freezes the switch mid-fade, which is a useful way to hold a handover. Reset to 1 every time the controller starts, so a saved value is not kept.

All are persistent and survive a controller restart, except that timeScaleFactor is forced back to 1 at startup. No parameters exist below this block.

`fadeInType` / `fadeOutType`	What the machine does	When to use it
0 straight line	The output moves at a constant rate, then stops dead	Fast handovers, or when the signals are already smooth
1 cosine	The output eases away from one input and eases into the other	Anywhere a step in rate would be felt. Same duration as the straight line — only the shape changes

Setup

Connect the two signal sets to input1 and input2. They must have the same number of channels.
Leave toggle false. Confirm output matches input1 and isOff is true.
Set fadeInTime and fadeOutTime. Start slow — a second or two.
Set both shapes to 1 unless you have a reason not to. The cosine costs nothing and removes the rate step at each end.
Set toggle true and watch output travel to input2.

Step 5 hands the machine over to whatever input2 is carrying. If the two inputs differ, the machine moves the difference over the fade time. Check what input2 is holding before you flip the toggle.
Confirm isOn goes true and output matches input2.
Set toggle back to false and confirm it travels back over fadeOutTime.

Tuning

Trace both inputs together before switching. The size of the gap between them is the size of the motion the fade will produce.
Set the fade time from that gap and what the machine can take: the average rate is the gap divided by the fade time.
Use the cosine shape unless you need the shortest possible transit. It has the same duration but no rate step at either end, so the peak rate is higher in the middle and zero at both ends.
Fade out is usually the more urgent direction. It is normal to set fadeOutTime much shorter than fadeInTime.
Watch faderValue to see the fade progress. Remember it is the straight-line fraction, so with the cosine shape the output will lag it early and lead it late.
If a handover must be able to pause, use timeScaleFactor. Setting it to 0 freezes the blend exactly where it is.
Fade times are in seconds, so a task-rate change does not move them — but the lower bound of one task period does change.

Both shapes arrive together. Only the way they get there differs.

Symptom	Cause	Action
The machine moved when I flipped the toggle	Expected: the two inputs held different values	Match them before switching, or lengthen the fade
The output stepped instead of fading	`doInstantToggle` is true	Set it false — it is a level, not a pulse
The fade is shorter than I asked for	`fadeInTime` above 10 is reduced to 10	Check the log; 10 seconds is the maximum
The fade time reads back as 10	Same cause	Split the handover, or fade a scaling signal instead
The fade time reads back as a tiny number	A value below one task period was raised to it	Write a longer time
The fade is slower or faster than the time I set	`timeScaleFactor` is not 1	Set it to 1
`timeScaleFactor` reverted after a restart	Expected: it is forced to 1 at startup	Set it from your application after start
The fade froze part-way	`timeScaleFactor` is 0	Set it above 0
The switch stuck at one end and will not come back	`timeScaleFactor` is negative, which is not rejected	Write a positive value
A rate step at the start or end of the fade	The straight-line shape does that	Set the type to 1
The output jerked mid-fade	One of the inputs moved during the fade — the block does not limit that	Use `SoftSwitch` if the output’s rate must stay bounded
I reversed the toggle mid-fade and it went back from where it was	Expected, and usually what you want	Nothing
`isOn` went true slightly early	Expected: the completion test has a small tolerance	Watch `faderValue` for the exact end
A signal scaled by `faderValue` does not match the fade	Expected: `faderValue` is the straight-line fraction, not the shaped one	Apply the same cosine yourself
The output is all zeros	An input is not connected — unconnected inputs read 0	Check both
Everything became invalid and stayed that way	A fade time that is not a number is not caught by the range check	Rewrite the fade times

A starting point for a handover between two setpoint sources:

fadeInTime      = 2.0
fadeOutTime     = 0.5
fadeInType      = 1
fadeOutType     = 1
timeScaleFactor = 1.0

Limits and errors

Limit	Set by	What happens	Reported
Fade duration	`fadeInTime`, `fadeOutTime`	The blend reaches the far end in exactly that time, divided by `timeScaleFactor`	`faderValue`, `isOn`, `isOff`
Fade time range	Fixed at one task period to 10 s	Out-of-range values are clamped and written back	Logged as a warning, once per write
Output rate during a fade	Nothing	Not limited. The output’s rate is the gap between the inputs divided by the fade time, plus whatever the inputs are doing themselves	Not reported
`timeScaleFactor`	Nothing	Not checked. 0 freezes the fade; a negative value runs it backwards until it sticks at an end	Not reported
`timeScaleFactor` persistence	Fixed	Forced to 1 at every controller start, discarding a saved value	Not reported
Fade shape	`fadeInType`, `fadeOutType`	Independent per direction. Both take the same time	Not reported
`faderValue`	Fixed	Always the unshaped fraction, whatever the shape in use	Not applicable
`doInstantToggle`	The input	A level. While true, every cycle snaps to the selected input	`faderValue` reads 0 or 1
Values that are not numbers	Nothing	Not caught by the range check. A bad fade time makes the output invalid permanently	Not reported
Startup state	Fixed	The output starts on `input1` and `isOff` starts true	`isOff`
Channel count	Fixed at build time	Both inputs and the output share one channel count	Not reported

The block logs a warning when a fade time is written outside its range. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: SimpleSwitch3D

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

Control3 3.30–3.34

SimpleSwitch3D cross-fades between two sets of signals and their first and second derivatives. A boolean picks which set you want and all three levels travel there together over a configured time.

Use it where a feedforward path downstream needs position, velocity and acceleration together, and the source of all three has to change.

The 3D in the name means three derivative levels, not three axes. The channel count is set when the controller is built and defaults to one, the same as SimpleSwitch.

flowchart LR
    i1(["input1, input1Dot, input1DDot"]) --> B["SimpleSwitch3D"]
    i2(["input2, input2Dot, input2DDot"]) --> B
    i3(["toggle"]) --> B
    i4(["doInstantToggle"]) --> B
    B --> o1(["output, outputDot, outputDDot"])
    B --> o2(["isOn"])
    B --> o3(["isOff"])
    B --> o4(["faderValue"])

During a fade, outputDot is not the rate of change of output. All three levels are blended with the same fraction, which leaves out the part of the derivative that comes from the blend itself moving. The error is zero before and after the fade, largest in the middle, and grows with the gap between the two sources. The figure under Tuning shows the size of it.

Do not feed outputDot to anything that must agree with output during a handover. Differentiate output yourself, or keep the two sources close together while you switch.

Fading in and fading out are configured separately — their own times and their own shapes.

Signals

Inputs

Path	Unit	Range	Description
`input1`	signal unit	unbounded	The value selected when `toggle` is false. This is where the block starts.
`input1Dot`	signal unit per second	unbounded	Its rate of change. You supply this — the block does not compute it.
`input1DDot`	signal unit per second²	unbounded	Its acceleration. Also supplied by you.
`input2`	signal unit	unbounded	The value selected when `toggle` is true.
`input2Dot`	signal unit per second	unbounded	Its rate of change.
`input2DDot`	signal unit per second²	unbounded	Its acceleration.
`toggle`	-	true or false	Which input set the output should travel to. A level, not a pulse. Flipping it back mid-fade reverses from wherever it had got to.
`doInstantToggle`	-	true or false	While true, all three outputs snap to the selected set every cycle with no fade. Also a level.

Nothing checks that the derivative inputs really are the derivatives of the value inputs. If you wire them inconsistently you get a consistent blend of inconsistent data.

Outputs

Path	Unit	Description
`output`	signal unit	The blended value.
`outputDot`	signal unit per second	The blended rate. Not the rate of change of `output` during a fade — see the callout above.
`outputDDot`	signal unit per second²	The blended acceleration. Same caveat, larger.
`isOn`	-	The fade to `input2` has completed. Goes true a few cycles early.
`isOff`	-	The fade to `input1` has completed. Starts true.
`faderValue`	-	How far through the fade, 0 to 1. The straight-line fraction even when the shape is cosine.

Parameters

Path	Unit	Default	Range	Effect
`fadeInTime`	s	5.0	one task period to 10	How long it takes to travel to `input2`. Values above 10 are silently reduced to 10, with a warning in the log.
`fadeOutTime`	s	5.0	one task period to 10	How long it takes to travel back. Same ceiling.
`fadeInType`	-	0	0 or 1	Shape of the fade to `input2`. 0 straight line, 1 cosine.
`fadeOutType`	-	0	0 or 1	Shape of the fade back to `input1`.
`timeScaleFactor`	-	1.0	0 upward	Speeds up or slows down the fade while it runs. 0 freezes it. Reset to 1 every time the controller starts.

All are persistent and survive a controller restart, except that timeScaleFactor is forced back to 1 at startup. No parameters exist below this block.

`fadeInType` / `fadeOutType`	What the machine does	Effect on the derivative error
0 straight line	Constant blend rate, stopping dead at each end	The error is constant through the fade and steps at both ends
1 cosine	The blend eases away from one set and into the other	The error is zero at both ends and peaks in the middle. Larger at its peak than the straight line, but smooth

Setup

Connect both sets of three signals. All six must have the same number of channels.
Leave toggle false. Confirm output matches input1 and isOff is true.
Set fadeInTime and fadeOutTime. Start with a second or two.
Set both shapes to 1 unless you need the shortest transit.
Bring the two sources close together before switching — this both reduces the motion and reduces the derivative error to nearly nothing.
Set toggle true and watch all three outputs travel to the input2 set.

Step 6 hands the machine over to whatever input2 is carrying, and the derivative outputs will be wrong for the duration of the fade. If anything downstream acts on outputDot, check the size of the gap first.
Confirm isOn goes true and the outputs match the input2 set.

Tuning

Trace both value inputs together before switching. The gap between them drives both the motion and the derivative error.
Close that gap before switching wherever you can. A handover between two sources that already agree is nearly free.
Set the fade time from the gap and what the machine can take.
Lengthen the fade to reduce the derivative error: the error is proportional to the gap divided by the fade time, so doubling the time halves it.
Use the cosine shape for a smooth blend, the straight line if you would rather the error be constant and predictable than smooth.
Watch faderValue for the fade progress. With the cosine shape the outputs lag it early and lead it late.
Fade times are in seconds, so a task-rate change does not move them.

With both sources standing still the whole of outputDot is missing. In general the shortfall is the gap between the sources times the blend’s own rate.

Symptom	Cause	Action
A feedforward path fought the machine during a handover	`outputDot` did not match `output` during the fade	Differentiate `output` yourself, or close the gap before switching
`outputDot` read zero while `output` was moving	Expected: both sources were still, so the whole derivative is the blend’s own motion, which is not published	See the callout at the top
The derivative error is worse than I expected	The gap is large or the fade is short	Close the gap, or lengthen the fade
`outputDDot` is further out than `outputDot`	Expected: the second derivative is missing two terms, not one	Same actions
The machine moved when I flipped the toggle	Expected: the two value inputs held different values	Match them first, or lengthen the fade
The outputs stepped instead of fading	`doInstantToggle` is true	Set it false — it is a level, not a pulse
The fade is shorter than I asked for	A time above 10 is reduced to 10	Check the log; 10 seconds is the maximum
The fade time reads back as a tiny number	A value below one task period was raised to it	Write a longer time
The fade is slower or faster than the time I set	`timeScaleFactor` is not 1	Set it to 1
`timeScaleFactor` reverted after a restart	Expected: it is forced to 1 at startup	Set it from your application after start
The fade froze part-way	`timeScaleFactor` is 0	Set it above 0
The switch stuck at one end	`timeScaleFactor` is negative, which is not rejected	Write a positive value
The switch never fades at all	The task period read as zero at startup, which is not guarded here	Restart the controller
A rate step at the start or end	The straight-line shape does that	Set the type to 1
`isOn` went true slightly early	Expected: the completion test has a small tolerance	Watch `faderValue`
A signal scaled by `faderValue` does not match	Expected: it is the straight-line fraction	Apply the same cosine yourself
The derivative outputs never made sense	The derivative inputs may not be the derivatives of the value inputs	Nothing checks this — verify upstream
Everything became invalid and stayed that way	A fade time that is not a number is not caught	Rewrite the fade times

A starting point for a handover between two profile sources:

fadeInTime      = 2.0
fadeOutTime     = 0.5
fadeInType      = 1
fadeOutType     = 1
timeScaleFactor = 1.0

Limits and errors

Limit	Set by	What happens	Reported
Derivative consistency	Nothing	`outputDot` and `outputDDot` do not match `output` during a fade. The shortfall is zero at both ends and peaks in the middle, proportional to the gap between the sources	Not reported at all
Derivative inputs	Nothing	Not checked against the value inputs. Inconsistent inputs blend consistently	Not reported
Fade duration	`fadeInTime`, `fadeOutTime`	All three levels reach the far end in exactly that time, divided by `timeScaleFactor`	`faderValue`, `isOn`, `isOff`
Fade time range	Fixed at one task period to 10 s	Out-of-range values are clamped and written back	Logged as a warning, once per write
Output rate during a fade	Nothing	Not limited. Use `SoftSwitch` when the output’s derivatives must stay within limits	Not reported
`timeScaleFactor`	Nothing	Not checked. 0 freezes; negative runs the fade backwards until it sticks	Not reported
`timeScaleFactor` persistence	Fixed	Forced to 1 at every controller start	Not reported
Task period	Not guarded here	A zero task period leaves the fade frozen. `SimpleSwitch` guards this; this block does not	Not reported
`faderValue`	Fixed	Always the unshaped fraction	Not applicable
`doInstantToggle`	The input	A level. While true, every cycle snaps	`faderValue` reads 0 or 1
Values that are not numbers	Nothing	Not caught by the range check	Not reported
Startup state	Fixed	All three outputs start on the `input1` set; `isOff` starts true	`isOff`
Channel count	Fixed at build time	All six inputs and three outputs share one channel count	Not reported

The block logs a warning when a fade time is written outside its range. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: SoftSwitch

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

Control3 3.30–3.34

SoftSwitch cross-fades between two sets of signals and their first and second derivatives, and can work out its own fade time from velocity, acceleration and jerk limits instead of taking a duration.

Use it for a handover where the output’s derivatives matter — where a feedforward path or a compliance model is consuming them, and a fade that respects a speed limit is worth more than a fade of a fixed length.

flowchart LR
    i1(["input1, input1Dot, input1DDot"]) --> B["SoftSwitch"]
    i2(["input2, input2Dot, input2DDot"]) --> B
    i3(["toggle"]) --> B
    i4(["doInstantToggle"]) --> B
    i5(["timeScaleFactor"]) --> B
    i6(["timeScaleFactorDot"]) --> B
    B --> o1(["output, outputDot, outputDDot"])
    B --> o2(["isOn"])
    B --> o3(["isOff"])
    B --> o4(["isDone"])
    B --> o5(["faderValue"])

The derivatives are correct here. outputDot really is the rate of change of output, right through the fade, including the part that comes from the blend itself moving. SimpleSwitch3D does not do this — if you need derivatives you can trust during a handover, this is the block.

Two ways to set the timing. With maxConstraintsEnable false you give a duration. With it true you give velocity, acceleration and jerk limits and the block computes the duration so the output respects them.

In limit mode, the timing is worked out at the moment you flip the toggle, from the gap between the inputs at that instant. If the inputs move apart afterwards, the limits will be exceeded.

Signals

Inputs

Path	Unit	Range	Description
`input1`	signal unit	unbounded	The set selected when `toggle` is false. Where the block starts.
`input1Dot`	signal unit per second	unbounded	Its rate of change. You supply this; it is used to make `outputDot` correct.
`input1DDot`	signal unit per second²	unbounded	Its acceleration.
`input2`	signal unit	unbounded	The set selected when `toggle` is true.
`input2Dot`	signal unit per second	unbounded	Its rate of change.
`input2DDot`	signal unit per second²	unbounded	Its acceleration.
`toggle`	-	true or false	Which set the output travels to. A level, not a pulse. Flipping it back mid-fade reverses smoothly, with no step in any derivative.
`doInstantToggle`	-	true or false	While true, all three outputs snap to the selected set. A level — leave it true and the block never fades again.
`timeScaleFactor`	-	any	Stretches the fade’s clock. 0 freezes it with nothing lost. 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 `outputDDot` will be wrong.

If the derivative inputs are not really the derivatives of the value inputs, the outputs will be a consistent blend of inconsistent data. Nothing checks this.

Outputs

Path	Unit	Description
`output`	signal unit	The blended value.
`outputDot`	signal unit per second	Its true rate of change, including the blend’s own contribution.
`outputDDot`	signal unit per second²	Its true acceleration.
`isOn`	-	The fade to `input2` is complete. Not just started.
`isOff`	-	The fade to `input1` is complete. Starts true.
`isDone`	-	No fade is in progress, in either direction.
`faderValue`	-	How far through the fade, 0 at `input1` and 1 at `input2`. This is the shaped fraction, so scaling another signal by it matches this switch’s own profile.

Parameters

Path	Unit	Default	Range	Effect
`maxConstraintsEnable`	-	false	-	False: the fade takes `fadeInTime` or `fadeOutTime`. True: the duration is derived from the limit parameters below.
`switchType`	-	0	0 or 1	0 quintic, 1 jerk-limited. See the table below. Changing it during a fade produces a kink — change it only when `isDone` is true.
`fadeInTime`	s	5.0	above 0	Fade duration to `input2`, when limits are off. A value under one task period makes the switch snap.
`fadeOutTime`	s	5.0	above 0	Fade duration back to `input1`, when limits are off.
`delayBeforeFadeIn`	s	0.0	0 upward	Wait before a fade to `input2` starts. Applies in both timing modes.
`delayBeforeFadeOut`	s	0.0	0 upward	Wait before a fade back starts.
`fadeInMaxVel`	signal unit per second	zeros	0 upward	Per channel. The most the output may move per second while fading in. 0 means this limit is not applied.
`fadeInMaxAcc`	signal unit per second²	zeros	0 upward	Per channel. 0 means not applied.
`fadeInMaxJerk`	signal unit per second³	zeros	0 upward	Per channel. 0 means not applied.
`fadeOutMaxVel`	signal unit per second	zeros	0 upward	Per channel, for the fade back.
`fadeOutMaxAcc`	signal unit per second²	zeros	0 upward	Per channel.
`fadeOutMaxJerk`	signal unit per second³	zeros	0 upward	Per channel.
`fadeInJerkFactor`	-	0.333	0 to 0.5	Shapes the jerk-limited profile. Ignored when `maxConstraintsEnable` is true — the block computes its own.
`fadeInAccFactor`	-	0.429	0 to 0.5	Same, and same caveat.
`fadeOutJerkFactor`	-	0.333	0 to 0.5	Same.
`fadeOutAccFactor`	-	0.429	0 to 0.5	Same.

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

`switchType`	What the machine does	Limits that apply
0 quintic	Value, velocity and acceleration all start and end at zero. The smoothest shape	Any of the three that is non-zero
1 jerk-limited	Reaches its acceleration and velocity plateaus and holds them, so it covers ground faster	A channel is ignored unless both its velocity and acceleration limits are set. A zero jerk limit degenerates the profile to a second-order one

Setup

Connect both sets of three signals. All six must have the same number of channels.
Leave toggle false. Confirm output matches input1 and isOff is true.
Start in time mode: leave maxConstraintsEnable false and set fadeInTime and fadeOutTime to a second or two.
Set toggle true and watch all three outputs travel to the input2 set.

Step 4 hands the machine over to whatever input2 is carrying, at whatever rate the gap and the fade time imply. In time mode nothing limits that rate. Check the gap first.
Confirm isOn and isDone go true and the outputs match the input2 set.
Now try limit mode: set fadeInMaxVel per channel, set maxConstraintsEnable true, and toggle again.
Confirm the fade actually got slower or faster. If nothing changed, the solve found no limits to apply and silently fell back to fadeInTime — nothing reports this.

Tuning

Decide which mode you want. Limits are usually the right answer for a handover on a real axis, because they bound what the machine does rather than how long it takes.
In limit mode, set the velocity limit first, per channel, in the signal’s own units. Leave acceleration and jerk at 0 until you need them.
Verify the mode took effect by comparing the fade duration against the time-mode default. A silent fallback looks exactly like a correctly derived five-second fade.
Remember the slowest channel sets the duration for all of them. One channel with a much smaller limit will slow the whole switch.
With the jerk-limited shape, set both a velocity and an acceleration limit per channel or that channel is skipped entirely.
Close the gap between the two input sets before switching wherever you can. In limit mode this shortens the fade automatically.
Use timeScaleFactor for an override, and set timeScaleFactorDot while you ramp it or outputDDot will be wrong for the duration of the ramp.

In limit mode the duration is whatever it needs to be. In time mode the duration is fixed and the velocity is whatever it turns out to be.

Symptom	Cause	Action
Setting limits changed nothing	The solve found nothing to constrain and fell back to the fade times, silently	Check every limit is non-zero on at least one channel
Limits are set but ignored with the jerk-limited shape	That shape skips any channel without both a velocity and an acceleration limit	Set both, per channel
The fade was slower than one channel’s limit implies	Expected: the slowest channel sets the duration for all	Raise that channel’s limits
The output exceeded the limit I set	The inputs moved apart after the toggle; the duration was fixed at the moment you flipped it	Close the gap before switching
`fadeInJerkFactor` has no effect	Expected: the factors are computed for you in limit mode	Turn limits off to use them
A kink appeared mid-fade	`switchType` was changed while a fade was running	Change it only when `isDone` is true
The output moved very fast in time mode	Expected: time mode does not limit the rate	Use limit mode
The switch snapped instead of fading	A fade time under one task period	Lengthen it
The outputs stepped instead of fading	`doInstantToggle` is true	Set it false — it is a level, not a pulse
The fade froze part-way	`timeScaleFactor` is 0	Set it above 0. Nothing was lost
A negative `timeScaleFactor` did not reverse the fade	Expected: the magnitude is used	Use the toggle to reverse
`outputDDot` was wrong while I changed the override	`timeScaleFactorDot` was left at 0	Set it while ramping
`isOn` and `isOff` are both false mid-fade	Expected: both require the fade to have completed	Use `faderValue` for progress
The derivative outputs never made sense	The derivative inputs may not match the value inputs	Nothing checks this — verify upstream
The machine moved when I flipped the toggle	Expected: the two input sets held different values	Match them first
Everything became invalid and stayed that way	An input that is not a number is not caught	Fix the upstream signal

A starting point for a limit-based handover on a single axis:

maxConstraintsEnable = true
switchType           = 0
fadeInMaxVel         = 0.5
fadeInMaxAcc         = 5.0
fadeOutMaxVel        = 1.0
fadeOutMaxAcc        = 10.0
fadeInTime           = 5.0
fadeOutTime          = 5.0

fadeInTime and fadeOutTime are still worth setting sensibly — they are what you fall back to if the limits do not apply.

Limits and errors

Limit	Set by	What happens	Reported
Derivative consistency	Fixed	`outputDot` and `outputDDot` are the true derivatives of `output`, through the fade	Not applicable
Timing mode	`maxConstraintsEnable`	Limits derive the duration; otherwise the fade times do	Not reported
Limit solve failure	Nothing	If no limit constrains anything, the block silently uses `fadeInTime`/`fadeOutTime` instead	Not reported
Limit validity window	Fixed	The duration is solved when the toggle changes, from the gap at that moment. Later input movement is not accounted for	Not reported
Limits per channel	The limit arrays	Each channel respects its own; the slowest sets the duration for all	Not reported
Zero limits	Checked	A zero limit is skipped, not treated as zero	Not reported
Jerk-limited shape	Fixed	A channel without both a velocity and an acceleration limit is ignored. A zero jerk limit degenerates the profile to second order	Not reported
Factor parameters	Fixed	The four factors are ignored in limit mode	Not reported
Output rate in time mode	Nothing	Not limited at all	Not reported
Sub-cycle fades	Checked	A fade time under one task period makes the switch snap	`isDone` stays true
Limit and time signs	Checked	Negatives are used as their magnitude	Read the values back
`switchType` mid-fade	Nothing	Not guarded. An in-flight fade changes shape and keeps its old timing	Not reported
`timeScaleFactor`	Partly checked	Negatives are negated. 0 freezes the fade with nothing lost	Not reported
Values that are not numbers	Nothing	Not checked anywhere	Not reported
Startup	Fixed	All three outputs start on the `input1` set; `isOff` and `isDone` start true, and any fade in flight is cleared	`isDone`
Channel count	Fixed at build time	All inputs, outputs and limit arrays share one channel count	Not reported

This block logs nothing, ever — unlike the other switches, it has no fade time ceiling and no warnings. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: LevelSwitch

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

Control3 3.30–3.34

LevelSwitch compares one signal against one level and publishes two complementary flags. A deadband holds the decision while the signal sits near the level, so the output does not chatter on noise.

Use it to raise a flag when a pressure, a speed or a position crosses a threshold.

flowchart LR
    i1(["input"]) --> B["LevelSwitch"]
    p1(["switchLevel"]) --> B
    p2(["deadband"]) --> B
    B --> o1(["isLower"])
    B --> o2(["isHigher"])

isHigher is always the exact opposite of isLower. Read whichever reads better in your logic; they can never disagree.

The deadband is split either side of the level. A deadband of 2 around a level of 5 switches to high at 6 and back to low at 4. Size it from the noise on your signal, not from the level.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to compare. Compared as-is, with no filtering — feed it a filtered signal if it is noisy beyond what the deadband can absorb.

Outputs

Path	Unit	Description
`isLower`	-	True while the input is below the level. Starts true, before the first comparison has run.
`isHigher`	-	True while the input is above the level. Always the complement of `isLower`.

Parameters

Path	Unit	Default	Range	Effect
`switchLevel`	signal unit	0.0	unbounded	The level to compare against. The output switches high at `switchLevel + deadband/2` and back low at `switchLevel - deadband/2`.
`deadband`	signal unit	0.0	0 upward	Total width of the hold region, split either side of the level. With 0 the output switches exactly at the level and will chatter on any noise. A negative value removes the hysteresis and is not rejected.

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

Setup

Connect the signal you want to watch to input.
Set switchLevel to the value you want to detect.
Leave deadband at 0 for a first look, and watch isHigher while the signal crosses the level.
If isHigher flickers at the crossing, the signal is noisy — go to Tuning.
Confirm isLower and isHigher are always opposite. They are computed to be, so a disagreement means you are reading two different cycles.

This block only reads a signal and raises a flag. It does not move anything and cannot be made to.

Tuning

Trace input while the machine does what you want to detect, and note how far the signal wanders when it is sitting still near the level.
Set deadband to about twice that wander. That is the whole tuning.
Check the crossing again. isHigher should switch once, cleanly, in each direction.
If it still chatters, the deadband is smaller than the noise. Double it.
If the flag now arrives too late, the deadband is too wide — remember it delays the switch by half its width in each direction.
If you cannot get both, the signal needs filtering upstream rather than a wider deadband here. A wider deadband costs you accuracy in both directions; a filter costs you a little delay in one.
Nothing here depends on the task rate, so none of this needs re-checking after a rate change.

The gap between the two switching points is the deadband.

Symptom	Cause	Action
The flag chatters at the crossing	`deadband` is smaller than the noise on the signal	Widen it, or filter the input
The flag chatters with `deadband` set	The signal is noisier than you measured	Trace the input at rest near the level and re-measure
The flag arrives later than expected	Expected: the deadband delays the switch by half its width	Narrow it, or move `switchLevel` down by half the deadband
The flag never switches	The signal never reaches `switchLevel ± deadband/2`	Check the level, and check the input is actually connected
The hysteresis disappeared	`deadband` is negative, which is not rejected	Write a positive value
`isHigher` reads true at exactly the level	Expected with a zero deadband: the tie goes to high	Set a deadband
`isLower` read true before anything ran	Expected: it starts true until the first cycle	Ignore the outputs until the controller is running
Both flags read the same	Not possible in one cycle	You are comparing readings from different cycles
The flag did not update after a restart	Expected: the previous decision is held for one cycle	Ignore the first cycle
A NaN reached the input and the flag froze	The decision is held when the input is not a number	Fix the upstream signal
I need to watch several signals	Not possible — this block is single channel	Use one instance per signal
I need to disable it	Not possible — there is no enable	Ignore the outputs in your own logic

A starting point for a signal that sits within ±0.5 of its value at rest:

switchLevel = <the value you want to detect>
deadband    = 2.0

Limits and errors

Limit	Set by	What happens	Reported
Switching point	`switchLevel`, `deadband`	High at `switchLevel + deadband/2`, low at `switchLevel - deadband/2`	`isLower`, `isHigher`
Inside the deadband	`deadband`	The decision is held — this is the hysteresis and the reason the block exists	Not reported
Exactly at the level, zero deadband	Fixed	Reads `isHigher`	Not reported
`deadband` sign	Nothing	Not checked. A negative value overlaps the two thresholds and removes the hysteresis	Not reported
`input` value	Nothing	Not checked. A NaN input holds the previous decision rather than switching	Not reported
Initial state	Fixed	`isLower` reads true and `isHigher` false until the first cycle runs	Not reported
Channel count	Fixed	One signal per instance, always	Not reported
Task rate	Not used	The block has no time dependence at all; the decision is instantaneous	Not applicable

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

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: FlipFlop

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

Control3 3.30–3.34

FlipFlop holds a true/false state that is flipped by holding its input true for a configured time. It also reports when the input rises and falls.

Use it to turn a held button into a latched mode, without the state flickering on a brief or bouncing contact.

flowchart LR
    i1(["input"]) --> B["FlipFlop"]
    i2(["reset"]) --> B
    p1(["setTimer"]) --> B
    B --> o1(["output"])
    B --> o2(["triggerRisingEdge"])
    B --> o3(["triggerFallingEdge"])

The output toggles; it does not follow the input. Hold the input true for setTimer seconds and the output flips to the opposite of whatever it was. Hold it again and it flips back. One flip per press, however long you hold.

triggerRisingEdge and triggerFallingEdge report the input, not the output. They are true for a single cycle when the input changes.

Signals

Inputs

Path	Unit	Range	Description
`input`	-	true or false	Hold it true for `setTimer` seconds to flip the output. Releasing before then flips nothing and arms the next attempt. This is a level, held for as long as you want it read.
`reset`	-	true or false	Forces `output` false and restarts the timer. The block clears it back to false once acted on, so it is a pulse. It does not stick while `input` is still held — the timer restarts and the output flips true again after `setTimer` seconds. Release `input` first.

Outputs

Path	Unit	Description
`output`	-	The latched state. Survives a controller restart — it is not cleared at startup.
`triggerRisingEdge`	-	True for one cycle when `input` goes from false to true.
`triggerFallingEdge`	-	True for one cycle when `input` goes from true to false.

Parameters

Path	Unit	Default	Range	Effect
`setTimer`	s	one task period	above 0	How long `input` must be held true before `output` flips. Values of 0 or below are replaced by one task period and written back, so this is also the shortest usable setting. Set it above the longest contact bounce you expect.

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

Setup

Connect your button, sensor or condition to input.
Set setTimer to how long the condition must hold before it counts — 50 ms is a reasonable first value for a physical button.
Hold input true and watch output flip after that time.
Release, hold again, and confirm output flips back. One flip per press.
Tap input briefly and confirm output does not change.
Pulse reset with input released, and confirm output goes false and stays false.

This block only latches a flag. It does not move anything and cannot be made to — but whatever your output enables downstream will act the moment it flips.

Tuning

There is one number here: setTimer. Everything else is wiring.
Trace input while the operator does what you want to detect. Look at how long the signal is genuinely held, and how long any bounce or glitch lasts.
Set setTimer above the longest glitch and comfortably below the shortest real press. For a physical button those are usually milliseconds and hundreds of milliseconds respectively, so there is a wide margin.
Confirm a real press flips the output and a glitch does not.
If a real press sometimes fails to register, setTimer is too long, or the input is dropping out mid-press. Trace triggerFallingEdge — a pulse there during the press means the input dropped and the timer restarted.
If glitches still get through, setTimer is shorter than the glitch. Lengthen it.
setTimer is in seconds, so a task-rate change does not move it — but the lower bound of one task period does change with the rate.

The delay between each input rise and the matching output change is setTimer.

Symptom	Cause	Action
The output follows the input instead of latching	It never did — this block toggles on a held input	Read the callout at the top
A press did nothing	It was shorter than `setTimer`, or the input dropped out mid-press	Trace `triggerFallingEdge` during the press
The output flipped when I wanted it set	Expected: every completed hold flips it	Check `output` before acting, or use `reset` to force it false
A reset did not stick	Expected: `input` was still held, so the timer restarted	Release `input` first, then reset
The output was still set after a restart	Expected: the latch is not cleared at startup	Pulse `reset` in your own startup logic
Glitches are getting through	`setTimer` is shorter than the glitch	Lengthen it
Real presses are being missed	`setTimer` is longer than the press	Shorten it
`setTimer` reads back as a tiny number	Expected: 0 and negatives are replaced by one task period	Write a positive value
The block never flips, whatever I do	`setTimer` is not a valid number	Rewrite it
`triggerRisingEdge` was true for only one cycle	Expected: both trigger outputs are one cycle wide	Latch it yourself if you need it longer
The trigger outputs do not match the output	Expected: they report the input, not the output	Watch `output` for the output’s changes
A `reset` write disappeared	Expected: the block clears it once acted on	Read `output` to confirm the reset took
The hold time changed after a task-rate change	Only if `setTimer` was at its lower bound of one task period	Set it explicitly
I need several of these	Not possible — this block is single channel	Use one instance per signal
I need to disable it	Not possible — there is no enable	Hold `input` false in your own logic

A starting point for a physical button on a 1 ms task:

setTimer = 0.05

Limits and errors

Limit	Set by	What happens	Reported
Hold time	`setTimer`	The output flips exactly once, `setTimer` seconds after the input rises	`output`
Repeated flips	Fixed	One flip per press. Holding longer changes nothing; release and hold again to flip back	`output`
Short presses	`setTimer`	Anything shorter is ignored entirely	`triggerRisingEdge` still pulses
`setTimer` at 0 or below	Checked	Replaced by one task period and written back	Read the value back
`setTimer` not a valid number	Nothing	Not checked. The timer never advances and the block never flips, silently	Not reported
`reset` while `input` is held	Nothing	The output clears, then flips true again after `setTimer`. A reset only sticks with the input released	Not reported
Startup state	Fixed	`output` is not cleared at startup and carries across a restart	Not reported
Trigger width	Fixed	Both trigger outputs are exactly one cycle wide	Not reported
Trigger source	Fixed	Both report the input’s edges, despite their names	Not reported
Channel count	Fixed	One signal per instance, always	Not reported

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

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Delay

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

Control3 3.30–3.34

Delay holds a signal back by a whole number of task cycles and passes it on unchanged. Use it to line signals up in time — a sensor reading against the command that produced it, a feedforward term against the feedback path it has to meet. It changes nothing about the signal’s size or shape: every frequency comes through at full amplitude, just later.

It is the one block here whose job is to add lag rather than avoid it.

flowchart LR
    i1(["input — signal to hold back"]) --> B["Delay"]
    B --> o1(["output — the same signal, later"])

Delay in seconds = delaysamples × task period [s]. On a 1 ms task, delaysamples 25 is 25 ms. The lag is the same at every frequency, and it reaches half a cycle of phase at $1/(2 \times$ delay$)$ Hz — 20 Hz for a 25 ms delay. Inside a feedback loop that is where the delay alone inverts the sign, so a delay in a loop costs stability directly.

This block has no enable, no disable, no isEnabled and no reset. It is always running. Set delaysamples to 0 to pass the signal straight through. The delay is counted in samples, not seconds — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signal to hold back. One element per channel; the channel count is fixed by the machine configuration.

Outputs

Path	Unit	Description
`output`	signal unit	The same signal, `delaysamples` cycles later, unchanged in size and shape. Equals `input` exactly while `delaysamples` is 0. Reads zero for the first `delaysamples` cycles after every controller start, then begins reproducing the input.

Parameters

Path	Unit	Default	Range	Effect
`delaysamples`	samples	0	0 – a ceiling fixed when the machine is built	How many task cycles to hold the signal back, shared by all channels. 0 passes the signal straight through. A value above the ceiling is corrected silently — see Limits and errors. Note the path name is all lower case.

delaysamples is persistent and survives a controller restart. The input and output do not. No parameters exist below this block.

Setup

Work out the delay you need in seconds, then divide by the task period to get samples. On a 1 ms task, 25 ms is 25 samples.
Find the ceiling: write a large number to delaysamples and read it back. The value you get is the largest delay this instance supports, and it is fixed when the machine is built.
Set delaysamples to 0 and link the source signal into input. output equals input sample for sample, which confirms the link.
Set delaysamples to the value from step 1. Read it back and confirm it was accepted.

Step 4 emits stale data for a moment. Raising the delay while the machine runs pushes out samples that were never recorded at the new depth. Change delaysamples with the axis at rest, or accept a brief burst of wrong values on output.
Trace input and output together and measure the offset between the same feature on each. It should be your delay in seconds.
Trace every element of both. An element that reads zero while the machine moves is an unwired channel.

Tuning

There is almost nothing to tune. The delay is either the right number of samples or it is not.

Measure the misalignment you are correcting, in seconds, off a trace of the two signals you want to line up.
Divide by the task period and round to the nearest whole number. This block cannot delay by a fraction of a sample, so the task rate sets how finely you can align.
Set delaysamples, then re-measure the offset on a trace. Adjust by one sample at a time.
If the alignment you need is finer than one task period, this block cannot deliver it. Raise the task rate, or accept the rounding.
Re-check delaysamples after any task-rate change. The delay is counted in samples, so the same setting is a different delay in seconds. Rescale it by the ratio of the old and new task periods.
If the delay sits inside a feedback loop, re-check the loop’s stability after every change. A delay costs phase margin at every frequency.

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

Symptom	Cause	Action
`output` reads zero for a while after every start	Expected: the block has nothing recorded yet, so it emits zeros for `delaysamples` cycles	Gate the consumer off a delay of at least that long after start
A burst of wrong values on `output` right after raising `delaysamples`	Expected: the deeper slots hold data that was never recorded	Change the delay at rest, not in motion
`output` jumped after lowering `delaysamples`	Expected: the output skips forward in time by the difference	Change the delay at rest, or step it down one sample at a time
The delay in seconds changed after a task-rate change	Expected: the delay is counted in samples, not seconds	Rescale `delaysamples` by the ratio of the task periods
`delaysamples` reads back lower than written	Above the ceiling for this instance	Work within the value you read back; the ceiling is fixed when the machine is built
You need a delay finer than one task period	Not possible — only whole samples are available	Raise the task rate, or accept the rounding
The loop that consumes `output` went unstable	Expected: a delay costs phase margin at every frequency	Reduce the delay, or retune the loop for it
You cannot switch the block off	Expected: there is no enable of any kind	Set `delaysamples` to 0, which is a true pass-through
You cannot flush the stored samples	There is no reset in this block	Set `delaysamples` to 0 and back, or restart the controller
`output` is a filtered version of `input` rather than a shifted one	Not possible — this block cannot change a signal’s shape	Check you are looking at this block’s output and not a filter’s
Some channels are delayed more than others	Not possible — all channels share one delay	Use a separate instance per channel group
A non-numeric value appeared on `output`	A non-numeric value reached `input` `delaysamples` cycles ago	Fix the source; the value clears itself after `delaysamples` cycles
The block costs more processing time than expected	Expected: the work grows with the delay, not with the signal	Use the smallest delay that does the job

A starting point for aligning a sensor reading with a 25 ms transport lag on a 1 ms task:

delaysamples = 25

Limits and errors

Limit	Set by	What happens	Reported
`delaysamples` ≤ the instance ceiling	Machine configuration	A larger value is replaced by the ceiling. The ceiling is not readable directly — discover it with Setup step 2	Silently; read `delaysamples` back
Delay resolution	Task rate	Whole samples only. The task period is the finest alignment available	Not reported
Delay in seconds	Task rate	Scales directly with the task period, so a task-rate change silently changes the delay in wall-clock terms	Not reported
`output`	Nothing	Unbounded — whatever the input carries reaches the output unchanged. Limit it downstream if the consumer needs a bound	Not reported
Stored samples	Nothing	There is no reset input and no enable. Setting `delaysamples` to 0 and back is the only way to flush from the parameter tree	Not reported
Channel count	Machine configuration	Fixed once the controller starts; it cannot be changed at runtime	Not reported

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

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: HostInModule

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

Control3 3.30–3.34

HostInModule is the entry point for a remote host commanding motion — a teleoperation link, a vision system, a hand controller. It turns a stream of positions arriving over a network into a setpoint the machine can safely follow.

Tracking is relative. The machine follows the host’s movement, not its absolute position, so the two do not need to start in the same place. You can engage tracking with the host anywhere and the machine will not jump.

flowchart LR
    i1(["input"]) --> B["HostInModule"]
    i2(["track/enable"]) --> B
    p1(["offset"]) --> B
    p2(["track/factor"]) --> B
    p3(["track/enableFader/fadeInTime, fadeOutTime"]) --> B
    p4(["track/syncFader/speed, enable"]) --> B
    p5(["track/watchdog/timeout, enable"]) --> B
    p6(["filter/order, omega, beta"]) --> B
    p7(["interpolator/sampleFactor"]) --> B
    B --> o1(["output"])
    B --> o2(["inputFilteredOffset"])
    B --> o3(["track/isTracking"])
    B --> o4(["track/enableFader/value"])
    B --> o5(["track/syncFader/value, fadeTime"])
    B --> o6(["filter/output"])
    B --> o7(["interpolator/output"])
    B --> o8(["reference, resetting"])

If the host stops writing track/enable, tracking is dropped after track/watchdog/timeout — a tenth of a second by default. This is the block’s main safety feature. Leave the watchdog on.

Two of the signals below are read-only in the tree. reference and resetting are published for you to watch, but only your application can set them. You cannot trigger a reset from the parameter tree.

Nothing here limits the machine’s speed. track/factor multiplies every movement the host makes, and it is not bounded. The limits belong in the blocks downstream — check they are in place before raising it.

An orientation instance has its signals under eulerZYX/ and quaternion/ instead of at the top level. Everything else below is the same.

Signals

Inputs

Path	Unit	Range	Description
`input`	host unit	unbounded	The host’s position stream, one value per channel. A value that is not a number poisons the output permanently — only a reset recovers it.
`track/enable`	-	true or false	Engages tracking. The host must keep writing this, not just set it once: the watchdog drops tracking if writes stop.

Outputs

Path	Unit	Description
`output`	machine unit	The setpoint for the machine.
`inputFilteredOffset`	host unit	The host’s input after filtering and the offset — what tracking actually follows. Trace this against `input` to see what the filter is doing.
`track/isTracking`	-	Tracking authority is not zero.
`track/enableFader/value`	-	How much authority tracking currently has, 0 to 1. Ramps rather than stepping.
`track/syncFader/value`	-	How far through a sync move, 0 to 1.
`track/syncFader/fadeTime`	s	Computed, not set: how long the current sync move will take. -1 means no sync move will happen.
`filter/output`	host unit	The filtered input, before the offset.
`interpolator/output`	host unit	The interpolated input, before the filter.
`reference`	machine unit	Where a reset sends the output. Set by your application, not from the tree.
`resetting`	-	A reset is in effect. Also application-set.

Parameters

Path	Unit	Default	Range	Effect
`offset`	host unit	zeros	unbounded	Added to the host’s input after filtering. Changing it does not jump the machine — the block deliberately absorbs the discontinuity.
`track/factor`	-	1	unbounded	Motion scaling. 0.1 makes the machine move a tenth of what the host does; 10 makes it move ten times as much. Not limited.
`track/enableFader/fadeInTime`	s	0.1	0 upward	How long tracking takes to reach full authority. 0 means instant.
`track/enableFader/fadeOutTime`	s	0.1	0 upward	How long it takes to release.
`track/syncFader/enable`	-	false	-	Whether to move the machine to the host’s absolute position when tracking engages. Off means pure relative tracking from wherever the machine is.
`track/syncFader/speed`	machine unit per second	0.1	0 upward	How fast that sync move goes. A speed of 0 means the machine never syncs and the output stays put. On an orientation instance the default is 1 rad/s.
`track/watchdog/enable`	-	true	-	Whether to drop tracking when the host stops writing. Leave this on.
`track/watchdog/timeout`	s	0.01	above 0	How long to wait before deciding the host is gone.
`filter/order`	-	2	0, 1 or 2	The low-pass order. 0 disables filtering. Values outside the range are clamped.
`filter/omega`	rad/s	15.7 (2.5 Hz)	above 0	The cut-off. Negative values are used as their magnitude.
`filter/beta`	-	0.707	above 0	Damping, order 2 only. 0.707 gives the flattest response.
`interpolator/sampleFactor`	-	1	1 upward	How many control cycles pass between host updates. 1 disables interpolation.

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

Setup

Connect the host’s stream to input and have it write track/enable every cycle it wants tracking.
Leave track/enable false. Confirm output is stationary.
Set interpolator/sampleFactor to how many control cycles pass between host updates. If the host writes at 100 Hz on a 1 kHz task, that is 10.
Set filter/omega — go to Tuning.
Set track/factor to 1 for a first test, and check the machine’s own speed and position limits are configured, because this block has none.
Leave track/syncFader/enable false so tracking starts from wherever the machine is.
Have the host raise track/enable and move slowly.

Step 7 gives a remote operator control of the machine. Start with a small track/factor, a slow host, and someone at the stop button.
Confirm output follows the host’s movement and track/isTracking is true.
Have the host stop writing track/enable entirely, and confirm tracking drops within track/watchdog/timeout.

Tuning

Set interpolator/sampleFactor first, from the host’s real update rate. Too low and you see a step at each host update; too high and the output is stale. Trace interpolator/output against input to check.
Set filter/omega from the noise on the host’s signal. Lower is smoother and adds more lag. Trace filter/output against interpolator/output.
Leave filter/order at 2 and filter/beta at 0.707 unless you have a reason. Order 1 has less lag and less rejection; order 0 is no filter at all.
Set track/factor from the working ratio you want between the host’s motion and the machine’s. Raise it in steps, checking the machine’s limits hold at each one.
Set the fade times from how abruptly you are willing for authority to change — a tenth of a second is a reasonable default for a hand controller.
Turn on the sync move only if the machine should meet the host’s absolute position. Set track/syncFader/speed to a safe approach speed and read track/syncFader/fadeTime back to see how long it will take.
Tighten track/watchdog/timeout as far as the host’s jitter allows. Too tight drops tracking on a network hiccup; too loose leaves the machine following a dead host for longer.

The output holds at its last value when tracking releases. It does not spring back.

Symptom	Cause	Action
The machine jumped when tracking engaged	The sync move is on and the host was far away	Turn `track/syncFader/enable` off, or lower the sync speed
The machine never reaches the host’s position	Expected without the sync move — tracking is relative	Turn the sync move on if you want absolute
The sync move never happens	`track/syncFader/speed` is 0	Set it above 0; check `track/syncFader/fadeTime` is not -1
Tracking dropped by itself	The host stopped writing `track/enable` and the watchdog fired	The host must write it continuously
Tracking drops on network hiccups	`track/watchdog/timeout` is too tight	Lengthen it
Tracking does not drop when the host dies	`track/watchdog/enable` is false	Set it true
The machine moves too far for the host’s movement	`track/factor` is too high	Lower it, and check the machine’s own limits
The machine overspeeds	This block has no speed limit	Set the limits downstream
The output is noisy	`filter/omega` is too high, or the order is 0	Lower the cut-off, or use order 2
The machine lags the host	The filter, the interpolator, or both	Raise `filter/omega`; check `sampleFactor` matches the host’s real rate
The output steps at each host update	`interpolator/sampleFactor` is too low	Set it to the real ratio
The output is stale and smooth	`sampleFactor` is too high	Lower it
Changing `offset` did not move the machine	Expected: the block absorbs the change deliberately	Nothing
Authority switches abruptly	The fade times are 0	Set them above 0
The output froze and stays wrong	A value that is not a number reached the input	Reset from your application; fix the link
I cannot reset from the tree	`reference` and `resetting` are read-only there	Your application must do it
A restart resumed tracking oddly	The filter and interpolator keep their history across a restart	Re-engage tracking after a start

A starting point for a hand controller at 100 Hz on a 1 kHz task:

track/factor                  = 1.0
track/enableFader/fadeInTime  = 0.1
track/enableFader/fadeOutTime = 0.1
track/syncFader/enable        = false
track/watchdog/enable         = true
track/watchdog/timeout        = 0.01
filter/order                  = 2
filter/omega                  = 15.7
filter/beta                   = 0.707
interpolator/sampleFactor     = 10

Limits and errors

Limit	Set by	What happens	Reported
Tracking	Fixed	Relative. The machine follows increments, scaled by `track/factor`. The host’s absolute position is irrelevant unless the sync move is on	`track/isTracking`
`track/factor`	Nothing	Not limited. It multiplies every host movement	Not reported
Machine speed and position	Nothing here	This block imposes no limits at all. They belong downstream	Not reported
Host loss	`track/watchdog/…`	Tracking is dropped if `track/enable` stops being written	`track/isTracking`
Authority	The enable fader	Ramps in and out rather than switching	`track/enableFader/value`
Sync move	`track/syncFader/…`	Speed-limited move to the host’s position on engage. Never completes before the fade-in does	`track/syncFader/value`, `…/fadeTime`
`syncFader/speed` of 0	Fixed	No sync move happens and the output holds	`…/fadeTime` reads -1
Filtering	`filter/…`	Order clamped to 0, 1 or 2; `omega` and `beta` used as magnitudes. Cannot be made unstable from the tree	`filter/output`
Interpolation	`interpolator/sampleFactor`	Interpolates between the last two host samples, so the output lags by one host period	`interpolator/output`
`offset` changes	Handled	Neither a filter transient nor a position jump — the block absorbs both	Not reported
Values that are not numbers	Nothing	Not checked. One bad sample poisons the output permanently until a reset	Not reported
Reset and reference	Application only	Not writable from the tree, only published	`resetting`, `reference`
Startup	Fixed	The filter and interpolator keep their history; the watchdog defaults tracking to off	Not reported
Channel count	Fixed at build time	Cannot be changed from the tree	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).