– Estimation and maths

Docs: Observer

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

Control3 3.30–3.34

Observer estimates every state of a plant, including the ones no sensor measures — a velocity from position alone, a load torque from motor current, a temperature inside a body from its surface. It runs a model of the plant, compares the model’s predicted measurement against the real one, and uses the difference to pull the model back toward the truth every cycle.

It is a plant model plus one correction term. Without that term the model drifts away from reality; with it, the estimate converges and stays converged.

flowchart LR
    i1(["inputVector — the plant's input"]) --> B["Observer"]
    i2(["measurementVector — what the sensors read"]) --> B
    B --> o1(["stateVector — the estimated states"])
    B --> o2(["stateDotVector — rate of change of the estimate"])
    B --> o3(["outputVector — the predicted measurement"])

The model is $\dot{\hat{x}} = A\hat{x} + Bu + L(y_m - \hat{y})$ and $\hat{y} = C\hat{x} + Du$. Tuning is entirely observerGain ($L$): it sets how fast the estimate is pulled toward the measurement. Place the observer 3 to 10 times faster than the plant. Faster converges sooner and passes more sensor noise into every estimate, and past a point it makes the block diverge — see Limits and errors. observerGain at zero leaves an open-loop simulation that ignores the measurement entirely.

Every matrix is written as one flat list, filled column by column. For a 4-state 2-measurement system the first four values of observerGain are the gains from the first measurement to all four states.

This block has no enable, no disable and no reset you can reach. It always runs, and its estimate cannot be re-initialised from the parameter tree — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`inputVector`	plant input units	unbounded	What is being commanded into the real plant, one element per input. The observer needs this to predict how the plant will respond.
`measurementVector`	sensor units	unbounded	What the sensors actually read, one element per measurement. This is the truth the estimate is corrected against. Note the block’s predicted measurement is `outputVector` — do not confuse the two.

Outputs

Path	Unit	Description
`stateVector`	model state units	The estimated state, one element per state — the reason to use this block. It starts at zero after a controller start and converges from there. It is not cleared by a stop, so after a restart it briefly holds an estimate unrelated to the machine.
`stateDotVector`	model state units per second	Rate of change of the estimate on this cycle.
`outputVector`	sensor units	The measurement the model predicts, for comparison against `measurementVector`. Subtract the two to see how well the observer is tracking: that difference should be small and settle toward zero.

Parameters

Path	Unit	Default	Range	Effect
`observerGain`	model state units per sensor unit per second	all zeros	any	The one thing to tune. How hard the measurement pulls the estimate. Higher converges faster and passes more noise; too high makes the estimate grow without bound. States × measurements, column-major. Zero leaves an open-loop simulation.
`matrixA`	1/s	all zeros	any	Plant dynamics, states × states, column-major. Continuous-time.
`matrixB`	state units per input unit per second	all zeros	any	Input matrix, states × inputs, column-major.
`matrixC`	sensor unit per state unit	all zeros	any	Which states the sensors see, and how. Measurements × states, column-major. A state no row of this matrix reaches cannot be estimated at any gain.
`matrixD`	sensor unit per input unit	all zeros	any	Direct feed-through from input to predicted measurement, measurements × inputs, column-major. Usually zeros.
`stateVectorInit`	model state units	all zeros	any	Intended as the state a reset restores. It has no effect — the reset is not reachable and the estimate always starts at zero.

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

Setup

Write down your model’s dimensions: states, inputs, measurements. Read the lengths of stateVector, inputVector and measurementVector from the parameter tree and confirm they match. They are fixed when the machine is built.
Check that every state you want estimated is reachable through matrixC. A state that no measurement depends on, directly or through the dynamics, cannot be estimated at any gain.
Confirm your matrices are continuous-time. A discretised model will be wrong by a factor of the task period.
Write matrixA through matrixD as flat lists, column by column. For a 2×2 matrix the order is row 1 column 1, row 2 column 1, row 1 column 2, row 2 column 2.
Leave observerGain at zeros. Link inputVector from whatever commands the real plant, and measurementVector from the sensors.
Compare outputVector against measurementVector on one trace. With zero gain the model runs open loop, so the two will drift apart — but they should start out the same shape. If they are not, the model is wrong; fix that before adding any gain.
Raise observerGain from zero until outputVector tracks measurementVector closely.

Step 7 is where this block becomes unstable if you push it. Too high a gain does not merely pass noise — it makes the estimate grow without bound, and only a controller restart clears it. Raise it in steps and watch stateVector between each.
Confirm stateVector settles and stays settled with the machine at rest.

Tuning

Get the model right first, with observerGain at zero, per Setup step 6. No gain can rescue a wrong model — it will give you a confidently wrong estimate with a small-looking error.
Work out your plant’s fastest pole, in rad/s. Aim to place the observer 3 to 10 times faster than that. That factor, not a number, is the target.
Raise observerGain from zero in steps of roughly double. After each step, watch stateVector for a few seconds with the machine at rest.
Stop as soon as noise appears on stateVector. Every measurement’s noise reaches every estimated state through the gain, and the states no sensor measures are usually the noisiest.
Judge convergence by subtracting outputVector from measurementVector. That difference is the observer’s error signal: it should be small in steady state and settle quickly after a disturbance.
Test convergence deliberately: start the controller with the machine away from zero, and time how long stateVector takes to reach the truth. That time is your observer’s response.
Check the gain against your task period. A gain fast enough to converge in a few task periods will make the block diverge — the practical ceiling is an observer response no faster than about a fifth of the task period.
If you need both fast convergence and quiet estimates, and your model is uncertain, use a Kalman filter instead — it trades the two off explicitly.

Read the convergence time off any curve as the point it crosses 0.37.

Symptom	Cause	Action
`stateVector` grows without bound	`observerGain` too high for the task period, or a wrong model	Lower the gain, restart the controller, and re-check step 6 of Setup
Everything reads zero	Expected with unconfigured matrices — all default to zero	Write `matrixA` through `matrixD`
`outputVector` never comes near `measurementVector`	`observerGain` is zero, so the model runs open loop	Raise `observerGain`
`outputVector` tracks but one state never settles	That state is not reachable through `matrixC`, so no gain can estimate it	Add a measurement, or accept that the state is not observable
The estimate is noisy	Gain too high — every measurement’s noise reaches every state	Lower `observerGain` and accept slower convergence
The estimate converges too slowly	Gain too low	Raise `observerGain`, watching for noise and divergence
The estimate looks confident and is wrong	The model is wrong: a bad model produces a small error and a false estimate	Set `observerGain` to zero and re-verify the model open loop
The estimate is smooth but lags the machine	Gain too low, or the model’s dynamics are too slow	Raise the gain; if that adds noise, fix the model instead
The response has the right timescale but the wrong shape	A matrix was written row by row instead of column by column	Rewrite it column-major
One measurement seems to affect the wrong states	`observerGain` is transposed	Rewrite it column-major: states × measurements
The response is far faster or slower than your offline design	Discretised matrices were supplied; this block wants continuous-time ones	Convert back to continuous time
A wrong estimate immediately after a controller restart	Expected: the estimate is not cleared by a stop and starts from wherever it was	Wait for it to converge, or gate the consumer for a few observer time constants
`stateVectorInit` seems to be ignored	Expected: it has no effect, because the reset that would apply it is not reachable	Ignore this parameter
You cannot re-initialise the estimate	Expected: there is no reset input	Restart the controller
A value went non-numeric and stayed there	A non-numeric value reached a matrix or an input	Restart the controller; there is no way to clear it in service
You need a different number of states	Not possible — the dimensions are fixed when the machine is built	It needs a configuration change

A starting point for estimating velocity from a position measurement on a 1 ms task. Two states — position and velocity — one input, one measurement:

matrixA      = 0, 0, 1, 0
matrixB      = 0, 1
matrixC      = 1, 0
matrixD      = 0
observerGain = 200, 10000

matrixA is column-major. Start with observerGain at zeros and work Setup steps 6 and 7. This is a starting point, not a final tuning.

Limits and errors

Limit	Set by	What happens	Reported
`observerGain` against the task period	Nothing	Not checked, and this is the bound you will hit while tuning. Too high a gain makes the estimate grow without bound. Only a controller restart clears it	Not reported
Task period against the model’s poles	Nothing	Not checked. The same limit applies to `matrixA` alone: the task period must stay below 2 divided by the largest pole magnitude in rad/s	Not reported
Observability	Nothing	Not checked. A state no measurement reaches cannot be estimated at any gain, and the symptom is a state that simply drifts	Not reported
Model accuracy	Nothing	Not checked, and cannot be. A wrong model gives a confident, wrong estimate with a small error signal	Not reported
Matrix element order	Fixed	Column-major, always. A row-major list silently produces a transposed matrix	Not reported
Model time domain	Fixed	Continuous-time only	Not reported
Matrix dimensions	Machine configuration	Fixed when the machine is built. Read the array lengths to discover them	Not reported
Estimate state	Nothing	There is no reset input, so the estimate cannot be re-initialised in service. `stateVectorInit` has no effect. A restart is the only way	Not reported
`stateVector`, `outputVector`	Nothing	Unbounded	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: ObserverKalmanFilter

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

Control3 3.30–3.34

ObserverKalmanFilter estimates a joint’s position, velocity and torque from noisy sensor readings, using a model of the joint to reject noise the sensor cannot distinguish from signal. Its purpose is torque estimation: turning a noisy torque reading into a smooth one you can control against.

Unlike Observer, you do not tune a gain. You tell the filter how much to trust the model and how much to trust the sensors, and it works the gain out for itself, every update. That is the right structure when the model is approximate and the sensors are noisy.

flowchart LR
    i1(["inputVector — commanded torque"]) --> B["ObserverKalmanFilter"]
    i2(["measurementVector — measured position, velocity, torque"]) --> B
    i3(["stateVectorInit"]) --> B
    i4(["disable"]) --> B
    B --> o1(["stateVector — estimated position, velocity, torque"])
    B --> o2(["covarianceMatrix — the filter's own uncertainty"])
    B --> o3(["isEnabled"])

The model is $I\ddot{\theta} + b\dot{\theta} + k\theta = \tau - F$, where the friction force $F$ is $c_v\dot{\theta} + c_c\operatorname{sign}(\dot{\theta})$ — a velocity-proportional part plus a constant-magnitude part. Tuning is the ratio of processNoiseCovariance to measurementNoiseCovariance: raise the first to follow the sensors, raise the second to trust the model and smooth harder. The third diagonal element of processNoiseCovariance is what decides how fast the torque estimate may move.

measurementVector needs all three values — position, velocity and torque. Leaving the velocity element at zero tells the filter the joint is measured to be stationary, which fights its own estimate.

Never set measurementNoiseCovariance to zero. It is the natural way to say “trust the sensors completely” and it makes the filter’s arithmetic ill-conditioned. Never set frequencyDivider to zero either — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`inputVector`	N·m	unbounded	The torque commanded into the joint. The filter needs it to predict how the joint will respond. A single value.
`measurementVector`	mixed: rad, rad/s, N·m	unbounded	What the sensors read, as three values in this order: position, velocity, torque. All three are used.
`stateVectorInit`	mixed: rad, rad/s, N·m	unbounded	Intended as a starting estimate. It has no effect — nothing in the block reads it, because there is no reset to apply it.
`disable`	-	-	True freezes the filter: the estimate and the uncertainty both hold their last values and nothing advances. It is not a bypass and not a zeroing.

Outputs

Path	Unit	Description
`stateVector`	mixed: rad, rad/s, N·m	The estimate, as three values: position, velocity, and filtered torque — the reason to use this block. It starts at zero after a controller start and converges from there. Not cleared by a stop.
`covarianceMatrix`	mixed	The filter’s own estimate of its uncertainty, 3×3. Useful for watching convergence — the diagonal should settle and stay settled. Do not read it as a true confidence bound; see Limits and errors.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	Off by default. False freezes the filter entirely.
`processNoiseCovariance`	mixed	identity	any positive-definite	How much you distrust the model, 3×3. Raise it to let the estimate follow the sensors more closely. Its third diagonal element governs how fast the torque estimate may change.
`measurementNoiseCovariance`	mixed	identity	positive-definite; never zero	How much you distrust the sensors, 3×3. Raise it to smooth harder and converge more slowly.
`frequencyDivider`	cycles	1	1 or more	Task cycles between corrections. The prediction runs every cycle; the correction — the expensive part — runs every Nth. 0 faults the controller.
`model/inertia`	kg·m²	1.0	above 0	Joint inertia. Zero is not checked and breaks the filter.
`model/damping`	N·m·s/rad	10.0	0 upward	Viscous damping in the joint.
`model/stiffness`	N·m/rad	0.0	0 upward	Joint stiffness. Leave at 0 for a rigid joint.
`model/viscousFrictionCoefficient`	N·m·s/rad	0.10	0 upward	Velocity-proportional friction.
`model/coulombFrictionCoefficient_`	N·m	0.10	0 upward	Constant-magnitude friction. Note the trailing underscore in the path name — it is not a typo in your configuration.

All nine parameters are persistent and survive a controller restart. The inputs and outputs do not. No parameters exist below this block other than the five model/ entries listed above.

Setup

Measure or estimate the joint’s inertia, damping and stiffness. These are physical properties, not tuning knobs — get them roughly right before touching the covariances.
Set model/inertia, model/damping and model/stiffness. model/inertia must be above zero.
Set the two friction coefficients from the joint’s own friction measurement, or leave them at their defaults if you have no figure.
Link inputVector from the commanded torque, and all three elements of measurementVector from the sensors.
Confirm all three measurement elements move. Trace each one. A stuck zero on the velocity element is the most damaging misconfiguration of this block, because the filter treats it as a measurement of standstill.
Leave frequencyDivider at 1, and both covariances at identity.
Set enable true and watch element 2 of stateVector against the raw torque measurement on one trace. The estimate should be a smoothed version of the measurement, following it without the noise.

Step 7 is the only check that the model is right. If the estimate drifts away from the measurement rather than smoothing it, the model is wrong — go back to step 1. No covariance setting fixes a wrong model.
Raise frequencyDivider only if the block costs more processing time than you can afford. Its correction step is the expensive part.

Tuning

Get the model right first, per Setup step 7. The covariances trade noise against lag; they cannot correct a wrong inertia.
Tune the ratio, not the absolute values. Only the ratio of processNoiseCovariance to measurementNoiseCovariance affects the result, so leave one at identity and move the other.
Start by raising measurementNoiseCovariance — multiply the whole matrix by 10 — and watch element 2 of stateVector. It should get smoother and slower.
Stop when the lag becomes unacceptable for whatever consumes the estimate. Smoothness and lag are the whole trade here.
If you need the torque estimate to respond faster without touching the others, raise only the third diagonal element of processNoiseCovariance. That element governs the torque state alone.
Watch the diagonal of covarianceMatrix while you tune. It should settle to steady values. A diagonal that keeps growing means the filter is not getting useful corrections — check step 5 of Setup.
Tune empirically, from the traces. Do not compute the covariances from sensor datasheets and expect the theoretical result: this filter’s internal gain does not correspond exactly to the model it runs, so the numbers that work will not be the numbers theory predicts.
Re-check nothing after a task-rate change to the covariances themselves, but do re-check frequencyDivider — it counts cycles, so the correction rate in hertz moves with the task period.

Read the trade off any curve: smoother means slower.

Symptom	Cause	Action
The controller faulted as soon as `frequencyDivider` was written	It was set to 0	Set it to 1 or more and restart the controller
Everything reads zero and never moves	`enable` is false, or `disable` is true	Read `isEnabled`
The estimate is frozen at an old value	Expected: a disabled filter freezes rather than zeroing	Set `enable` true and `disable` false
The estimate drifts away from the torque measurement	The model is wrong — most often `model/inertia`	Re-measure the inertia; no covariance setting fixes this
The estimate fights the measured velocity	The velocity element of `measurementVector` is stuck at zero, so the filter reads standstill	Link all three measurement elements
The estimate is as noisy as the raw sensor	`measurementNoiseCovariance` too low relative to `processNoiseCovariance`	Multiply `measurementNoiseCovariance` by 10
The estimate lags the real torque badly	`measurementNoiseCovariance` too high	Lower it, or raise the third diagonal element of `processNoiseCovariance`
The torque estimate is slow but position and velocity are fine	The third diagonal element of `processNoiseCovariance` is too small	Raise that element alone
The estimate went to a non-numeric value and stayed there	`model/inertia` is 0, or a non-numeric value reached an input	Set a non-zero inertia, then restart the controller
`covarianceMatrix` looks healthy but the estimate is nonsense	The filter protects its uncertainty from bad values but not its estimate	Restart the controller
The filter behaved oddly after `measurementNoiseCovariance` was set to zero	Expected: zero makes the internal arithmetic ill-conditioned	Use a small positive value instead of zero
`covarianceMatrix`’s diagonal keeps growing	The corrections are not helping — check the measurements and `frequencyDivider`	Work Setup step 5
A stale estimate for a while after re-enabling	Expected: the filter resumes from where it froze, and still believes its old uncertainty	Re-enable with the joint near where it was, or restart
The estimate is wrong and there is no way to clear it	Expected: there is no reset in this block, and `stateVectorInit` has no effect	Restart the controller
The torque estimate carries a small constant offset at standstill	Expected: the friction model applies its constant term even at zero velocity	Lower `model/coulombFrictionCoefficient_`, or accept the offset
The correction rate changed after a task-rate change	Expected: `frequencyDivider` counts cycles, not seconds	Rescale it by the ratio of the task periods
Tuning from the sensor datasheet did not give the expected result	Expected: tune this filter empirically from traces	Work Tuning steps 2 to 4

A starting point for a joint with 0.5 kg·m² inertia on a 1 ms task, correcting every cycle, trusting the sensors and the model equally:

enable                          = true
frequencyDivider                = 1
model/inertia                   = 0.5
model/damping                   = 10.0
model/stiffness                 = 0.0
model/viscousFrictionCoefficient  = 0.10
model/coulombFrictionCoefficient_ = 0.10
processNoiseCovariance          = identity
measurementNoiseCovariance      = identity

Then work Tuning step 3. This is a starting point, not a final tuning.

Limits and errors

Limit	Set by	What happens	Reported
`frequencyDivider` ≥ 1	Nothing	Not checked. A value of 0 faults the controller. Always set 1 or more	Not reported
`model/inertia` > 0	Nothing	Not checked. Zero makes the estimate and the uncertainty non-numeric. Only a restart clears the estimate	Not reported
`measurementNoiseCovariance`	Nothing	Not checked. Zero or near-zero makes the filter’s internal arithmetic ill-conditioned, and the bad result reaches the estimate unprotected	Not reported
Estimate protection	Partial	The filter protects its uncertainty from non-numeric values but not its estimate, so `covarianceMatrix` can look healthy while `stateVector` is ruined	Not reported
Covariance meaning	Inherent	`covarianceMatrix` is useful for watching convergence but is not a true confidence bound — the filter’s internal gain does not correspond exactly to the model it runs. Tune empirically	Not reported
Measurement count	Fixed	Three measurements are required: position, velocity, torque. Supplying fewer leaves zeros that the filter treats as real readings	Not reported
Model accuracy	Nothing	Not checked, and cannot be. A wrong model gives a confident, wrong estimate	Not reported
Estimate state	Nothing	There is no reset input. `stateVectorInit` has no effect. A restart is the only way to clear a wrong estimate	Not reported
Estimate across a stop	Nothing	Not cleared by a stop or a start. A restart of the task resumes the old estimate	Not reported
`stateVector`, `covarianceMatrix`	Nothing	Unbounded	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: StateSpace

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

Control3 3.30–3.34

StateSpace runs a linear model of a plant from its four matrices. Use it as a reference model, a soft sensor, or a simulation you can commission against before the hardware exists. The whole model is configuration: A, B, C, D and the starting state are all parameters, so a system identified offline drops in without a code change.

flowchart LR
    i1(["inputVector — the model's input u"]) --> B["StateSpace"]
    i2(["disturbanceVector — added to the state rate"]) --> B
    i3(["reset"]) --> B
    B --> o1(["stateVector — the model state x"])
    B --> o2(["stateDotVector — rate of change of the state"])
    B --> o3(["outputVector — the model output y"])

The model is $\dot{x} = Ax + Bu + g$ and $y = Cx + Du$. The matrices are continuous-time, and the block integrates them at the task rate — do not supply a discretised model. Stability needs task period < $2/\lvert\lambda\rvert$ for every eigenvalue $\lambda$ of A: a model with a 200 Hz pole needs a task period under 1.6 ms. Nothing checks this — see Limits and errors.

Every matrix is written as one flat list, filled column by column. For a 4×4 A matrix the first four values are its first column, not its first row. Getting this wrong gives you a transposed model that is stable, plausible and wrong.

This block has no enable and no disable. It always runs.

Signals

Inputs

Path	Unit	Range	Description
`inputVector`	model input units	unbounded	The model’s input $u$, one element per input. Length is fixed when the machine is built.
`disturbanceVector`	model state units per second	unbounded	Added directly to the state rate, one element per state. It bypasses the B matrix, so its units are those of $\dot{x}$ and not of an input. Leave it at zero unless you are injecting a state disturbance deliberately.
`reset`	-	-	A rising value restores `stateVector` to `stateVectorInit` and zeroes `stateDotVector`. It is a one-shot — the block clears it. On the reset cycle `outputVector` keeps its previous value, so ignore it for one cycle.

Outputs

Path	Unit	Description
`stateVector`	model state units	The model state $x$, one element per state. This is the model’s entire memory. It starts at zero after a controller start — not at `stateVectorInit` — and is not cleared by a stop.
`stateDotVector`	model state units per second	The rate of change of the state on this cycle. It describes the transition out of the state published alongside it.
`outputVector`	model output units	The model output $y$, one element per output, computed from the state published in the same cycle.

Parameters

Path	Unit	Default	Range	Effect
`matrixA`	1/s	all zeros	any	System dynamics, states × states, column-major. Its eigenvalues are the model’s poles and decide both its behaviour and whether it is stable at your task rate.
`matrixB`	state units per input unit per second	all zeros	any	Input matrix, states × inputs, column-major. How the input drives each state.
`matrixC`	output unit per state unit	all zeros	any	Output matrix, outputs × states, column-major. Which states are visible, and how.
`matrixD`	output unit per input unit	all zeros	any	Feed-through matrix, outputs × inputs, column-major. A non-zero value routes the input to the output in the same cycle, with no delay.
`stateVectorInit`	model state units	all zeros	any	The state `reset` restores. It is not applied at startup — the state starts at zero regardless.

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

Setup

Write down your model’s dimensions: how many states, inputs and outputs. Read the lengths of stateVector, inputVector and outputVector from the parameter tree and confirm they match. They are fixed when the machine is built and cannot be changed at runtime.
Confirm your matrices are continuous-time. If your identification tool gave you a discrete model, convert it back, or the dynamics will be wrong by a factor of the task period.
Check your task period against your fastest pole: it must be below $2/\lvert\lambda\rvert$, and comfortably below for accuracy. Divide 2 by the largest pole magnitude in rad/s.

Step 3 is the check nothing does for you. A model that is perfectly stable on paper will grow without bound here if the task period is too slow for it, and the only symptom is the state running away.
Write matrixA as a flat list, column by column. For a 2×2 matrix $\begin{pmatrix} a & b \ c & d\end{pmatrix}$ the list is a, c, b, d.
Write matrixB, matrixC and matrixD the same way. Leave matrixD at zeros unless your model genuinely feeds through.
Set inputVector to zero and watch stateVector. With no input and no disturbance it should decay toward zero from wherever it is. If it grows, go back to step 3 or check for a transposed matrix.
Apply a small step on inputVector and compare outputVector against what your offline model predicts. A mismatch in shape means a transposed matrix; a mismatch in timescale means step 2.

Tuning

There is nothing to tune. The work is entering the model correctly and confirming it behaves as designed.

Verify the model offline first. This block reproduces what you give it; it cannot tell you the model is wrong.
Check stability at your task rate before anything else, per Setup step 3. This is the one property that depends on the controller and not on your model.
Verify element ordering with a deliberately asymmetric A matrix. A symmetric test matrix cannot tell a transposed model from a correct one.
Compare a step response against your offline tool. Match the shape first, then the timescale. Shape errors are ordering errors; timescale errors are discrete-versus-continuous errors.
Watch for slow drift in the amplitude of an oscillatory model. Integrating at the task rate distorts lightly damped poles, and the faster the pole relative to the task rate, the worse it gets. If it matters, raise the task rate.
Use reset between test runs so each starts from the same state, and set stateVectorInit to whatever that should be.

Read the model’s damping off the overshoot on any curve.

Symptom	Cause	Action
`stateVector` grows without bound	Task period too slow for the model’s fastest pole, or a transposed matrix	Check step 3 of Setup; then verify element ordering with an asymmetric matrix
Everything reads zero	Expected with unconfigured matrices — they all default to zero	Write `matrixA` through `matrixD`
The response has the right timescale but the wrong shape	A matrix was written row by row instead of column by column	Rewrite it column-major
The response is far faster or slower than your offline model	Discretised matrices were supplied, but this block wants continuous-time ones	Convert back to continuous time
The output moves the instant the input does	Expected: a non-zero `matrixD` feeds the input straight through	Set `matrixD` to zeros if your model has no feed-through
An oscillatory model slowly gains amplitude	Expected: integrating at the task rate distorts lightly damped poles	Raise the task rate, or add damping to the model
`stateVector` did not start at `stateVectorInit` after a restart	Expected: the state starts at zero, and `stateVectorInit` is only what `reset` restores	Pulse `reset` after every start
`outputVector` disagrees with `stateVector` for one cycle after a reset	Expected: the output is not recomputed on a reset cycle	Ignore the output for one cycle after a reset
`reset` had to be written again for a second reset	Expected: it is a one-shot and the block clears it	Write it true again
`disturbanceVector` has a much larger effect than expected	Expected: it adds to the state rate directly and bypasses `matrixB`	Scale it in state-rate units, not input units
The simulation kept running after the controller was stopped and started	Expected: the state is not cleared by a stop	Pulse `reset` after each start
A value went non-numeric and stayed there	A non-numeric value reached a matrix or an input	Fix the source, then pulse `reset` — that clears the state
You need a different number of states	Not possible — the dimensions are fixed when the machine is built	It needs a configuration change

A starting point for a 2 Hz second-order model with 0.7 damping, two states, one input, one output, on a 1 ms task. States are position and velocity:

matrixA         = 0, -157.91, 1, -17.59
matrixB         = 0, 157.91
matrixC         = 1, 0
matrixD         = 0
stateVectorInit = 0, 0

Note matrixA is column-major: the four values are row 1 column 1, row 2 column 1, row 1 column 2, row 2 column 2 — in that order.

Limits and errors

Limit	Set by	What happens	Reported
Task period against the model’s poles	Nothing	Not checked. The task period must stay below 2 divided by the largest pole magnitude in rad/s, and the eigenvalues are never computed. Too slow a task period makes the state grow without bound, with no warning and no flag. Only `reset` or a restart clears it	Not reported
Matrix element order	Fixed	Column-major, always. A row-major list silently produces a transposed model	Not reported
Model time domain	Fixed	Continuous-time only. There is no discrete-time mode, whatever else you may have read	Not reported
Matrix dimensions	Machine configuration	Fixed when the machine is built. Read the array lengths from the parameter tree to discover them	Not reported
`stateVector`, `outputVector`	Nothing	Unbounded. Bound them downstream if a consumer needs a limit	Not reported
Startup state	Fixed	The state starts at zero, not at `stateVectorInit`. Pulse `reset` to apply the initial state	Not reported
Model state	`reset`	`reset` restores `stateVectorInit`. There is no way to reset to zero from the parameter tree unless `stateVectorInit` is zero	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: Integrator

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

Control3 3.30–3.34

Integrator accumulates its input over time, with a limiter on each side: the input can be bounded before it is integrated, and the output after. It is the building block the library makes motion from — an acceleration integrated into a velocity, a velocity into a position.

Two things set it apart from a plain accumulator. It has a throttle for approaching a singularity: as inputLimiterScaleFactor falls, motion is scaled down — but only while it is falling, so an operator can always jog back out. And its output limiter can be told to hold the output where it is rather than pulling it back to the bound.

flowchart LR
    i1(["input — the signal to integrate"]) --> B["Integrator"]
    i2(["reference — what a reset restores"]) --> B
    i3(["reset"]) --> B
    i4(["inputLimiterScaleFactor"]) --> B
    B --> o1(["output — the integral"])
    B --> o2(["inputLimiterIsActive — per channel"])
    B --> o3(["outputLimiterIsActive — per channel"])
    B --> o4(["anyInputLimiterIsActive"])
    B --> o5(["anyOutputLimiterIsActive"])

output grows by input × task period each cycle. The two …IsActive outputs are +1 at the upper bound, −1 at the lower and 0 when inactive, so they tell you which side is limiting, per channel. The two any… outputs are plain true/false across all channels.

The scale factor does two different things depending on whether that channel’s input limiter is on:

Input limiter on — it scales the bounds, symmetrically, always.
Input limiter off — it scales the input itself, but only while the factor is falling. Once it starts rising the scaling stops, so motion away from the trouble is never throttled.

Both limiters are off by default, and so the block is a plain integrator until you enable them. The output is not cleared when the controller starts — it resumes from wherever it was.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit per second	unbounded	The signal to integrate. One element per channel. A reset writes zero here, so a trace shows zero on the reset cycle.
`reference`	signal unit	unbounded	What the output is set to on a reset, per channel.
`reset`	-	-	A rising value sets every channel’s output to its `reference` and zeroes `input`. It is a one-shot — the block clears it. Hold it true to pin the output at the reference.
`inputLimiterScaleFactor`	-	0 – 1 in practice	Scales either the input bounds or the input itself — see above. A single value for the whole block, even though the limiter enables are per channel. Negative values are used as their magnitude.

Outputs

Path	Unit	Description
`output`	signal unit	The integral, one element per channel. Not cleared by a controller stop or start — pulse `reset` if you need it at a known value.
`inputLimiterIsActive`	-	Per channel: +1 at the upper bound, −1 at the lower, 0 inactive.
`outputLimiterIsActive`	-	Same encoding for the output limiter.
`anyInputLimiterIsActive`	-	True while any channel’s input limiter is active.
`anyOutputLimiterIsActive`	-	True while any channel’s output limiter is active.

Parameters

Path	Unit	Default	Range	Effect
`inputLimiterEnable`	-	false	per channel	Bounds the input before integration. Off by default — and switching it off is what enables the singularity throttle.
`inputLimiterMin`	signal unit per second	−1.0	below the max, per channel	Lower input bound, scaled by `inputLimiterScaleFactor`. Swapped with the max if inverted.
`inputLimiterMax`	signal unit per second	+1.0	above the min, per channel	Upper input bound, scaled the same way.
`outputLimiterEnable`	-	false	per channel	Bounds the integral. Off by default, so the integral is unbounded until you set it.
`outputLimiterMin`	signal unit	−1.0	below the max, per channel
`outputLimiterMax`	signal unit	+1.0	above the min, per channel
`outputLimiterClampDisable`	-	false	per channel	Changes what hitting the bound means. False clamps the output onto the bound. True leaves it where it is and only forbids moving further past — so an output already outside is not yanked back.

All seven are persistent and survive a restart, and all are per channel. No parameters exist below this block.

Setup

Link input from whatever you are integrating, and reference from the value a reset should restore — often the machine’s measured position.
Leave both limiter enables false for a first pass. The block is then a plain integrator.
Pulse reset and confirm every channel’s output jumps to its reference.
Feed a known constant into input and confirm output ramps at that rate.
Set outputLimiterMin and outputLimiterMax to the real travel, then set outputLimiterEnable true. Drive into a bound and confirm outputLimiterIsActive reads +1 or −1 for that channel.

Step 5 stops the integral where you tell it to. If the output is already outside the band when you enable the limiter, it will jump to the bound — unless you set outputLimiterClampDisable, which holds it instead. Enable the limiter with the output inside the band.
Only if you need the singularity throttle: leave inputLimiterEnable false and link inputLimiterScaleFactor from whatever measures how close the machine is to trouble.

Tuning

Decide per channel whether you want the input limiter or the throttle. They are alternatives, selected by inputLimiterEnable, and they behave quite differently.
Use the input limiter when the input has a hard rate bound that always applies. The scale factor then narrows those bounds symmetrically.
Use the throttle when a supervisor computes a closeness measure — a manipulability figure near a singularity, say — and motion should fade out as it falls. Because the throttle releases as soon as the factor rises, motion out of the region is never slowed.
Set the output limiter from the real travel, not from what the signal happens to do.
Choose outputLimiterClampDisable deliberately. Clamping is right for a bound the output must sit exactly on; holding is right where being pulled back to the bound would itself be a disturbance.
Pulse reset after every controller start if the integral must begin from a known value.
Nothing here needs re-checking after a task-rate change.

Read the asymmetry off the gap between the two output curves during the rise.

Symptom	Cause	Action
The output resumed from an old value after a restart	Expected: the integral is not cleared at start	Pulse `reset` after every start
The output drifts over a long session	Expected: it is an integrator with no output bound unless you set one	Set `outputLimiterEnable` and its bounds
The output jumped to the bound when the limiter was enabled	Expected: it was already outside the band	Enable with the output inside, or set `outputLimiterClampDisable`
The output is stuck outside its bound	Expected with `outputLimiterClampDisable` set: it holds rather than pulling back	Clear that parameter if you want it clamped onto the bound
The output moves differently on the way down than on the way up for the same scale factor	Expected: the throttle applies only while the factor is falling	This is what lets you jog back out
The throttle does nothing	That channel’s `inputLimiterEnable` is true, so the factor scales the bounds instead	Switch the input limiter off to get the throttle
The scale factor throttles some channels and scales bounds on others	Expected: the factor is global and the limiter enables are per channel	Make the enables consistent across channels
The throttle stayed on after the factor stopped falling	Expected: it releases only on a rising factor, not a steady one	Raise the factor slightly to release it
`input` reads zero on a trace	You are looking at a reset cycle — a reset zeroes the input	Read it on a non-reset cycle
A limit reads back swapped	Expected: an inverted pair is corrected	Write the lower value to the min
`reset` had to be written again for a second reset	Expected: it is a one-shot	Write it true again, or hold it to pin the output
One channel limits and the others do not	Expected: every limit and both enables are per channel	Check each element
The integral went non-numeric and stayed there	A non-numeric input accumulated into the output	Pulse `reset` with a finite `reference`
I cannot tell whether the throttle is engaged	The block does not publish it	Compare the scale factor’s direction between cycles

A starting point for integrating a velocity into a position bounded to ±0.5, with the throttle available:

inputLimiterEnable        = false
outputLimiterEnable       = true
outputLimiterMin          = -0.5
outputLimiterMax          = 0.5
outputLimiterClampDisable = false

Limits and errors

Limit	Set by	What happens	Reported
`input`	`inputLimiterMin`/`Max` × `inputLimiterScaleFactor`, while `inputLimiterEnable` is set	Clamped before integration	`inputLimiterIsActive` (+1/−1/0), `anyInputLimiterIsActive`
`input`, with the limiter off	`inputLimiterScaleFactor`, only while it is falling	Scaled proportionally. Never scaled while the factor rises	Not reported — the latch is not published
`output`	`outputLimiterMin`/`Max`, while `outputLimiterEnable` is set	Clamped onto the bound, or held where it is when `outputLimiterClampDisable` is set. Unbounded when the limiter is off, which is the default	`outputLimiterIsActive`, `anyOutputLimiterIsActive`
Limit ordering	Fixed	An inverted min/max pair is swapped in place	Silently; read both back
`inputLimiterScaleFactor`	Sign forced	Used as its magnitude	Not reported
Throttle state	Not published	Whether the throttle is engaged cannot be read from the parameter tree	Not reported
Integral state	`reset`	Restored from `reference`. Not cleared by a controller stop or start	Not reported
Non-numeric input	Nothing	Accumulates and latches. `reset` clears it if `reference` is finite	Not reported
Channel count	Machine configuration	Fixed once the controller starts	Not reported

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

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: IntegratorRot3D

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

Control3 3.30–3.34

IntegratorRot3D integrates an angular velocity into an orientation. It is the rotational counterpart of Integrator: where that block accumulates a number, this one composes rotations, which cannot be done by adding three angles together.

The orientation is held as a quaternion and re-normalised every cycle, so it stays a valid rotation however long the controller runs — no gimbal lock and no drift out of the valid set.

flowchart LR
    i1(["input — angular velocity, three values"]) --> B["IntegratorRot3D"]
    i2(["reset"]) --> B
    i3(["manipulabilityGain"]) --> B
    B --> o1(["output — orientation quaternion, four values"])
    B --> o2(["reference — the reset target"])
    B --> o3(["pqrLocal — applied rate, body frame"])
    B --> o4(["pqrGlobal — applied rate, world frame"])
    B --> o5(["absVelOut — rate magnitude"])
    B --> o6(["absVelDotOut — its rate of change"])
    B --> o7(["absVelLimiterActive"])
    B --> o8(["absAccLimiterActive"])

The limits act on the magnitude of the angular rate, not on each axis. When a limit bites, all three components are scaled by the same factor, so the rotation slows without changing its axis. absVelMax bounds the rate’s magnitude and absAccMax how fast that magnitude may change.

manipulabilityGain does two different things depending on absVelLimiterOn:

On — it scales absVelMax, always, in both directions.
Off — it scales the rate itself, but only while the gain is falling. Motion out of the region that caused the throttle is never slowed.

The acceleration limit is deliberately relaxed while slowing toward a singularity. When the throttle demands a lower rate, the block allows whatever deceleration that needs — the limit only constrains speeding up.

reference is an output, not an input. The reset target can only be set from an application, not from the parameter tree — see Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	rad/s	unbounded	The angular velocity, three values. `inputAsLocal` decides whether these are in the body frame or the world frame — getting that wrong produces plausible motion about the wrong axis.
`reset`	-	-	Sets `output` back to `reference` and zeroes the input.
`manipulabilityGain`	-	0 – 1 in practice	How much rotation is allowed, typically from a measure of how close the machine is to a singularity. Negative values are used as their magnitude.

Outputs

Path	Unit	Description
`output`	-	The orientation, as a four-value quaternion. Always normalised. Not cleared when the controller starts — it resumes from the previous run’s attitude.
`reference`	-	The quaternion a reset restores. Readable only — it cannot be written from the parameter tree.
`pqrLocal`	rad/s	The rate actually applied, expressed in the body frame.
`pqrGlobal`	rad/s	The same rate in the world frame. Compare the two to confirm the frame switch is doing what you expect.
`absVelOut`	rad/s	The magnitude of the applied rate.
`absVelDotOut`	rad/s²	How fast that magnitude is changing.
`absVelLimiterActive`	-	True while the rate magnitude is being limited.
`absAccLimiterActive`	-	True while its rate of change is being limited.

Parameters

Path	Unit	Default	Range	Effect
`inputAsLocal`	-	false	-	True means `input` is in the body frame and the block rotates it into the world frame. False means it is already in the world frame.
`absVelLimiterOn`	-	false	-	Bounds the rate magnitude at `absVelMax` × `manipulabilityGain`. Switching it off is what enables the throttle instead.
`absVelMax`	rad/s	—	above 0	Maximum rate magnitude. Not checked.
`absAccLimiterOn`	-	false	-	Bounds how fast the rate magnitude may change.
`absAccMax`	rad/s²	—	above 0	That bound. Not checked, and a negative value is unsafe — see Limits and errors.

All five are persistent and survive a restart.

One sub-tree exists below this block, rateLimiter3D, which performs the acceleration limit. Do not configure it — this block overwrites its settings every cycle. Use absAccMax and absAccLimiterOn instead.

Setup

Decide which frame your angular velocity is in and set inputAsLocal to match. A body-frame rate fed as a world-frame one rotates about the wrong axis, and the result looks like plausible motion.
Set reference from your application to the orientation a reset should restore. It cannot be set from the parameter tree.
Pulse reset and confirm output matches reference.
Command a steady rate about one axis with both limiters off, and confirm the orientation rotates about that axis at the expected rate.
Compare pqrLocal against pqrGlobal. With the machine at its reference orientation they will agree; as it rotates they diverge, and that divergence confirms the frame handling.

Step 5 is the check that the frames are right. If the two never diverge as the machine rotates, the frame rotation is not happening and inputAsLocal is probably wrong.
Set absVelMax and switch absVelLimiterOn on. Command a rate above the limit and confirm absVelLimiterActive goes true and absVelOut settles at the limit.
Only if you need the singularity throttle: switch absVelLimiterOn off and link manipulabilityGain.

Tuning

Set absVelMax from the machine’s rated rotational speed — it is a magnitude, so it applies equally to a rotation about one axis and a combined one.
Set absAccMax from what the structure can take. It bounds how quickly the rotation speeds up; slowing down toward a singularity is deliberately exempt.
Choose per installation whether you want the limiter or the throttle. They are alternatives selected by absVelLimiterOn, exactly as in Integrator.
Use the throttle when a supervisor computes a closeness measure and rotation should fade out as it falls. Rotation away from the trouble is never slowed, which is the point.
Watch absVelOut and absVelDotOut while tuning. They are the two quantities the limits act on.
Nothing here needs re-checking after a task-rate change.

Read the asymmetry off the gap between the two curves during the rise.

Symptom	Cause	Action
The machine rotates about the wrong axis	`inputAsLocal` does not match the frame your rate is in	Switch it and re-check step 5 of Setup
`pqrLocal` and `pqrGlobal` never diverge	The frame rotation is not being applied	Check `inputAsLocal`
The orientation resumed from an old attitude after a restart	Expected: it is not cleared at start	Pulse `reset` after every start
I cannot set the reset target	Expected: `reference` is an output and is settable only from an application	Ask the application to set it
Rotation is slower on the way in than on the way out for the same gain	Expected: the throttle applies only while the gain is falling	This is what lets the machine rotate back out
The throttle does nothing	`absVelLimiterOn` is true, so the gain scales `absVelMax` instead	Switch the limiter off to get the throttle
The acceleration limit seems to be ignored while slowing down	Expected: it is relaxed while braking toward a singularity, so the machine may always reach the throttled rate	This is deliberate
One axis is limited and the others are not	Not possible — the limits act on the magnitude, so all three scale together	Check what consumes the output
The rotation axis changed when the limit bit	Not possible in this block	Check what follows it
Configuring the `rateLimiter3D` sub-tree had no effect	Expected: this block overwrites its settings every cycle	Use `absAccMax` and `absAccLimiterOn`
The rotation ran away or reversed	A negative `absAccMax` reaches the internal rate limiter, which then drives away from its target	Set it positive, then pulse `reset`
The orientation went non-numeric and stayed there	A non-numeric rate poisoned the quaternion	Pulse `reset` with a finite `reference`
The quaternion drifted out of normalisation	Not possible — it is re-normalised every cycle	Check what consumes it

A starting point for a wrist limited to 1 rad/s, with the throttle available:

inputAsLocal    = true
absVelLimiterOn = false
absVelMax       = 1.0
absAccLimiterOn = true
absAccMax       = 10.0

Limits and errors

Limit	Set by	What happens	Reported
Rate magnitude	`absVelMax` × `manipulabilityGain`, while `absVelLimiterOn` is set	Scaled down uniformly, preserving the axis	`absVelLimiterActive`, `absVelOut`
Rate magnitude, limiter off	`manipulabilityGain`, only while it is falling	Scaled proportionally. Never scaled while the gain rises	Not reported — the latch is not published
Rate of change of the magnitude	`absAccMax`, while `absAccLimiterOn` is set	Bounded — except while slowing toward a singularity, where whatever deceleration the throttle demands is allowed	`absAccLimiterActive`, `absVelDotOut`
`absVelMax`, `absAccMax`	Nothing	Not checked. A negative `absAccMax` reaches the internal rate limiter, which then drives the rate away from its target	Not reported
Individual axes	Nothing	Not bounded. Only the magnitude is limited	Not reported
Orientation validity	Guaranteed	The quaternion is re-normalised every cycle and stays a valid rotation indefinitely	Not applicable
`reference`	Not writable	It is registered as an output, so the reset target is settable only from an application	Not applicable
Orientation state	`reset`	Restored from `reference`. Not cleared by a controller stop or start	Not reported
`rateLimiter3D` sub-tree	Overwritten	Its `enable` and `rateLimit` are written every cycle by this block	Not reported
Non-numeric input	Nothing	Poisons the quaternion and latches. `reset` clears it if `reference` is finite	Not reported
Dimensions	Fixed	Always three rate inputs and one quaternion output	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: Polynomial

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

Control3 3.30–3.34

Polynomial evaluates a polynomial in its input: $y = a_0 + a_1u + a_2u^2 + \dots$. Its usual job is linearising a sensor — fit a curve to the sensor’s error offline, put the coefficients here, and the reading comes out proportional to the quantity it measures.

flowchart LR
    i1(["input — the raw value"]) --> B["Polynomial"]
    i2(["disable"]) --> B
    B --> o1(["output — the corrected value"])
    B --> o2(["isEnabled"])

coefficients[0] is the constant term and is always added. coefficients[1] multiplies the input, coefficients[2] the input squared, and so on up to order. So an identity correction is order = 1 with coefficients 0, 1.

Never write order larger than the coefficient array. The block does not check it, and a value past the end makes it read memory that is not part of the array. Find the ceiling with Setup step 2.

order = 0 gives zero, not the constant term. For a fixed offset use order = 1 with coefficients offset, 0.

Disabling this block outputs zero, not the input — and it writes zero into input too. In a sensor chain that takes everything downstream to zero with it.

Signals

Inputs

Path	Unit	Range	Description
`input`	raw sensor unit	unbounded	The value to correct. A single value, not an array. The block writes zero here on every disabled cycle, so a trace reads zero while it is off.

Outputs

Path	Unit	Description
`output`	corrected unit	The polynomial evaluated at `input`. Zero — not the input — while disabled, and zero whenever `order` is 0.
`isEnabled`	-	True when `enable` is true and `disable` is false. It does not mean the block is producing output: `order` = 0 gives zero while this still reads true.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	False makes the output zero.
`order`	-	1	1 up to the array length minus 1	How many powers of the input to use. Not checked — a value past the array length reads out of bounds. 0 gives zero output.
`coefficients`	mixed	0 in every element	any	The coefficients, constant term first. Element 1 multiplies the input, element 2 the input squared, and so on.

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

Setup

Fit the polynomial offline against known reference values. Two or three terms is usually enough; a high order fits noise rather than the sensor.
Find the coefficient array’s length by reading it back from the parameter tree. order must stay at least one below it.
Write order first, then coefficients. Writing the order afterwards from an application clears the coefficients you just set.
Write the coefficients with the constant term in element 0.
Apply a known reference value to the sensor and check output reads the right corrected value. Repeat at three or four points across the range — one point cannot tell a good fit from a bad one.

Step 5 is the only check that the fit is right. A polynomial that is correct at the point you tested and wrong everywhere else looks exactly like a working correction until the machine moves.
Confirm output matches input at the point where your correction should be neutral.

Tuning

There is nothing to tune at runtime — the coefficients are a calibration.

Take measurements across the whole working range, not just the middle. A polynomial is worst at the ends.
Use the lowest order that fits. Each extra term makes the curve wilder outside the range you measured.
Check the behaviour beyond your measured range. A cubic that fits well from 0 to 10 can be badly wrong at 15, and there is no limiter here.
Re-check the fit after any change to the sensor or its mounting.
Nothing here depends on the task rate.

Read the correction as the vertical distance from the straight line.

Symptom	Cause	Action
The output is zero and `isEnabled` reads true	`order` is 0	Set `order` to 1 or more; for a constant, use `order` 1 with coefficients `offset, 0`
The output is zero and the block is disabled	Expected: it outputs zero rather than passing through	Enable it; if a sensor chain went dead, this is why
`input` reads zero on a trace	You are looking at a disabled cycle — the block zeroes its own input	Enable it before judging the link
The coefficients went to zero after setting the order from an application	Setting the order clears the coefficient array	Write `order` first, then the coefficients
The correction is right at one point and wrong elsewhere	The fit was made from too few points	Re-fit across the whole range, per Tuning step 1
The output goes wildly wrong beyond the measured range	Expected: a polynomial diverges outside where it was fitted	Lower the order, or bound the output downstream
The output is very large or non-numeric for a large input	A high power of a large input overflows	Lower the order, or scale the input first
Nothing seems to change when I raise the order	The higher coefficients are zero	Write them
The controller behaves strangely after writing a large `order`	It was written past the coefficient array’s length, which reads out of bounds	Keep `order` below the array length; restart the controller
The correction is inverted	The coefficient signs are wrong, or the constant term is in the wrong element	Element 0 is the constant term
A non-numeric input produced a non-numeric output that then cleared	Expected: the block holds no state and recovers at once	Fix the source
You need this on several channels	Not possible — this block is single channel	Use one instance per channel

A starting point for an identity correction, which is what the block ships with:

enable       = true
order        = 1
coefficients = 0.0, 1.0

A second-order correction with a small offset:

order        = 2
coefficients = -0.05, 1.02, 0.003

Limits and errors

Limit	Set by	What happens	Reported
`order` below the coefficient array’s length	Nothing	Not checked. A larger value reads past the end of the array, which is undefined and can crash or produce nonsense. Discover the length by reading `coefficients` back	Not reported
`order` = 0	Fixed	The output is zero, not the constant term	Not reported; `isEnabled` still reads true
`output`	Nothing	Unbounded. A high order and a large input grow very quickly. Limit it downstream if the consumer needs a bound	Not reported
Fit quality	Nothing	Not checked, and cannot be. A polynomial that is wrong outside the range you fitted looks correct inside it	Not reported
Disabled behaviour	Fixed	Output zero, not a pass-through, and `input` is zeroed too	Not reported
Non-numeric input	Nothing	Produces a non-numeric output. The block is stateless and recovers immediately	Not reported
Channel count	Fixed	One channel per instance, always	Not reported

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

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Lookup

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

Control3 3.30–3.34

Lookup maps an input to an output through a table of points, interpolating straight lines between them. Outside the table the output is held at the nearest end value — it never extrapolates.

Use it to linearise a sensor, to schedule a gain against speed, or to describe any relationship that is easier to measure than to write down.

flowchart LR
    i1(["input"]) --> B["Lookup"]
    p1(["x"]) --> B
    p2(["y"]) --> B
    p3(["numPoints"]) --> B
    p4(["gain"]) --> B
    p5(["useSortedData"]) --> B
    B --> o1(["output"])
    B --> o2(["index"])

x must increase strictly, left to right. If any value is equal to or less than the one before it, the output is 0 — silently, with nothing to tell you the table was rejected. Since 0 is also a perfectly good output value, check your table’s order first whenever the output reads 0.

numPoints defaults to 0, and an unconfigured block outputs 0. Set it to how many of your x and y entries are real.

The table has a fixed maximum size, set when the controller is built — usually 7 points. A larger numPoints is silently reduced to it, and the ceiling is not published, so count your points against what you were given.

Signals

Inputs

Path	Unit	Range	Description
`input`	input unit	unbounded	The value to look up. Outside the table the output clamps to the nearest end. A value that is not a valid number freezes the output at its last value.

Outputs

Path	Unit	Description
`output`	output unit	The interpolated result, scaled by `gain`. Reads 0 when the table is empty or rejected.
`index`	-	Which table segment was used last. Diagnostic — it is the block’s internal search position, not a measurement.

Parameters

Path	Unit	Default	Range	Effect
`numPoints`	-	0	0 to the built-in maximum	How many entries of `x` and `y` are real. At 0 the output is 0. At 1 the output is `gain × y[0]` whatever the input. Values above the maximum are silently reduced.
`x`	input unit	zeros	strictly increasing	The input values of the table. Any entry not greater than the one before it makes the output 0.
`y`	output unit	zeros	unbounded	The output value at each corresponding `x`.
`gain`	-	1.0	unbounded	Multiplies every `y` value. Use it to rescale the whole table without editing it.
`useSortedData`	-	false	-	Lets the block remember where it looked last, so a slowly moving input searches less. Makes no difference to the answer. At the usual table sizes it makes no measurable difference to the cost either.

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

Setup

Measure or calculate the relationship you want, at as many points as your table allows.
Write the input values into x, in increasing order, and the matching output values into y.
Set numPoints to how many entries you filled.
Leave gain at 1.
Sweep input across the range and confirm output traces the shape you expect.
If output reads 0 everywhere, either numPoints is 0 or your x values are not strictly increasing. Check both.
Check the ends: below the first x the output should hold at the first y, above the last it should hold at the last.

Tuning

Put your points where the curve bends. Even spacing wastes points on the straight sections.
Always include a point at each end of the range you care about. Outside the table the output goes flat, and a client tracing an unexpected plateau is usually looking at a table that stops too early.
Check the interpolation error at the midpoint of your widest segment — that is where a piecewise-linear fit is worst.
Use gain to rescale the whole table, for a unit change or a calibration factor, rather than re-entering every y.
If the table is a sensor linearisation, take the measurements at the same temperature and load you will run at.
Nothing here depends on the task rate, and both the interpolation and the clamping are exact.

The flat sections at each end are the clamping, not a fault.

Symptom	Cause	Action
The output is 0 everywhere	`numPoints` is 0 — the default — or `x` is not strictly increasing	Check both. Nothing reports which
The output is 0 and my table looks fine	Two `x` entries are equal, which counts as not increasing	They must be strictly increasing
The output is a constant	`numPoints` is 1, so the output is always `gain × y[0]`	Set it to your real point count
The output goes flat at each end	Expected: the block clamps rather than extrapolating	Add points further out
Only part of my table is used	`numPoints` is smaller than the entries you filled	Raise it
`numPoints` reads back lower than I set	It exceeded the built-in maximum and was reduced	Use fewer points, or a larger instance
The output is scaled wrongly	`gain` multiplies every `y`	Check it is 1 unless you meant otherwise
The output has visible corners	Expected: the table is straight lines between points	Add points where the curve bends
The output froze	The input is not a valid number, which holds the last output	Fix the upstream signal
The output jumped when I edited the table	Expected: edits take effect on the next cycle, with no fade	Edit while the machine is stopped
`index` moves around unexpectedly	It is the internal search position, not a measurement	Ignore it
Turning on `useSortedData` changed the answer	It should not — it only changes how the block searches	Report it
I need extrapolation beyond the table	Not possible — the block clamps	Extend the table
I need more points	The maximum is fixed when the controller is built	Rebuild with a larger instance
I need this on several signals	Not possible — this block is single channel	Use one instance per signal

A starting point for a five-point sensor linearisation:

numPoints     = 5
x             = [0.0, 1.0, 2.0, 3.0, 4.0]
y             = <your measured outputs at those inputs>
gain          = 1.0
useSortedData = false

Limits and errors

Limit	Set by	What happens	Reported
Interpolation	The table	Straight lines between adjacent points, exact	`output`
Outside the table	Fixed	Clamped to the first or last `y`. There is no extrapolation	Not reported
`x` ordering	Checked	Must be strictly increasing over the first `numPoints`. Otherwise the output is 0	Not reported — 0 is also a valid result
`numPoints` above the maximum	Checked	Silently reduced to the maximum every cycle, so the block never reads past its table	Read the value back
Maximum point count	Fixed at build time	Not published. Usually 7	Not reported
`numPoints` of 0	Checked	Output is 0	Not reported
`numPoints` of 1	Checked	Output is `gain × y[0]` for any input	Not reported
`gain`	Nothing	Not checked. Multiplies every `y`, including on the one-point path — but not on either zero path	Not reported
Values that are not numbers	Nothing	Not checked. Such an input holds the previous output rather than propagating	Not reported
Table edits	The tree	Take effect on the very next cycle, with no fade or filtering	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: Gain

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

Control3 3.30–3.34

Gain multiplies each channel of its input by a gain and adds an offset. That is all it does.

The gain defaults to 0, so an unconfigured block outputs nothing. It does not pass its input through. Set gain to 1 on every channel before you expect a signal out of it.

flowchart LR
    i1(["input"]) --> B["Gain"]
    p1(["gain"]) --> B
    p2(["offset"]) --> B
    B --> o1(["output"])

The gain is applied first, then the offset: output = gain × input + offset. To undo it, subtract the offset before dividing.

Signals

Inputs

Path	Unit	Range	Description
`input`	signal unit	unbounded	The signals to scale. One value per channel.

Outputs

Path	Unit	Description
`output`	scaled unit	The scaled and offset signals, one per channel. Reads 0 on every channel until you set the gain.

Parameters

Path	Unit	Default	Range	Effect
`gain`	output unit per input unit	0.0	unbounded	Multiplies the input, per channel. At the default of 0 the output is just the offset. A negative gain inverts the signal.
`offset`	output unit	0.0	unbounded	Added after the multiplication, per channel.

Both are persistent and survive a controller restart. Both are per channel, so a four-channel block has four gains and four offsets. No parameters exist below this block.

Setup

Connect your signals to input. The channel count is fixed when the controller is built.
Set gain to 1 on every channel, unless you want scaling. This is not the default and the block will output zeros until you do.
Confirm output matches input.
Set the gain you actually want, per channel.
Set offset if you need one, remembering it is added after the multiplication.

This block only scales a signal. Whatever consumes output will see the change on the next cycle.

Tuning

There is nothing dynamic to tune. Both parameters take effect on the next cycle, with no fade and no filtering.
Work out the gain from the units: it is the output unit divided by the input unit. A block converting millimetres to metres has a gain of 0.001.
Set the offset from where the two scales differ at zero. A sensor reading 0.5 at true zero needs an offset of -0.5 after the gain, or a correction upstream.
Check both directions if anything downstream inverts this conversion — the inverse is (output − offset) ÷ gain, not output ÷ gain − offset.
Use a negative gain to reverse a signal’s sense. Nothing else in this block changes.
Nothing here depends on the task rate.

The flat line is what an unconfigured block gives you.

Symptom	Cause	Action
The output is 0 whatever the input does	`gain` is 0 — the default	Set it to 1, or to the scaling you want
The output is a constant, not 0	`gain` is 0 and `offset` is not	Set the gain
Only some channels work	`gain` is per channel and you set only some	Set every channel
The output is inverted	`gain` is negative	Check its sign
The offset is scaled differently than expected	The offset is added after the multiplication, so it is in output units	Convert it to output units
Undoing the conversion gives the wrong answer	The inverse is `(output − offset) ÷ gain`	Subtract before dividing
The output is invalid	An input that is not a valid number passes straight through	Fix the upstream signal
The output is enormous	A large gain and a large input	Check both
I need to switch it off	Not possible — there is no enable	Set `gain` to 1 and `offset` to 0
I need two-way conversion	Wrong block	Use `SignalConverter`
I need a non-linear conversion	Wrong block	Use `Lookup`
I need more channels	The count is fixed when the controller is built	Rebuild, or use a second instance

A starting point for a pass-through on four channels:

gain   = [1.0, 1.0, 1.0, 1.0]
offset = [0.0, 0.0, 0.0, 0.0]

Limits and errors

Limit	Set by	What happens	Reported
Scaling	`gain`, `offset`	`output = gain × input + offset`, per channel, every cycle	`output`
`gain` default	Fixed at 0	The output is the offset alone until you set it	Not reported
`gain` range	Nothing	Not checked. 0 is a legitimate setting meaning “output the offset”; negative inverts	Not reported
Values that are not numbers	Nothing	Not checked. They pass straight through to the output	Not reported
Overflow	Nothing	A large gain and a large input overflow silently	Not reported
State	None	The block has no memory. Nothing survives a cycle, and nothing needs resetting	Not applicable
Enable	None	There is no enable, disable or isEnabled	Not applicable
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).

Docs: SignalConverter

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

Control3 3.30–3.34

SignalConverter converts a quantity in both directions at once. One port multiplies by a gain and adds an offset; the other subtracts the offset and divides. The two are exact inverses, so a value sent out and read back comes home unchanged.

Use it wherever a quantity crosses a unit boundary both ways — a setpoint going out to hardware and a measurement coming back.

flowchart LR
    i1(["input"]) --> B["SignalConverter"]
    i2(["inverseInput"]) --> B
    p1(["gain"]) --> B
    p2(["offset"]) --> B
    p3(["inverseOutputReference"]) --> B
    p4(["doReferencing"]) --> B
    p5(["doReferencingAll"]) --> B
    p6(["invert"]) --> B
    B --> o1(["output"])
    B --> o2(["inverseOutput"])

invert decides which port multiplies. With it false — the default — inverseOutput multiplies and output divides. With it true they swap. Everything else about the block is the same.

Automatic referencing does not work correctly at the default invert setting. It computes an offset that suits the other direction, so unless your gain is 1 the result will be wrong. Set the offset by hand, or set invert to true, until this is fixed.

Signals

Inputs

Path	Unit	Range	Description
`input`	input unit	unbounded	With `invert` false this port divides: `output = (input − offset) ÷ gain`.
`inverseInput`	output unit	unbounded	With `invert` false this port multiplies: `inverseOutput = gain × inverseInput + offset`.

Outputs

Path	Unit	Description
`output`	output unit	The result on the `input` side. Reads 0 on any channel whose gain is 0, deliberately.
`inverseOutput`	input unit	The result on the `inverseInput` side. This is the port that referencing aims at.

Parameters

Path	Unit	Default	Range	Effect
`gain`	-	1.0	unbounded	The conversion factor, per channel. Shared by both directions, which is what makes them exact inverses. A gain of 0 makes the dividing side output 0 rather than failing.
`offset`	output unit	0.0	unbounded	Added on the multiplying side, subtracted on the dividing side, per channel. Referencing overwrites this.
`inverseOutputReference`	input unit	zeros	unbounded	The value referencing aims `inverseOutput` at, per channel.
`doReferencing`	-	false	-	Per channel: solve for the offset that puts `inverseOutput` at its reference. Cleared automatically. See the caveat above.
`doReferencingAll`	-	false	-	The same for every channel at once. Also cleared automatically.
`invert`	-	false	-	Swaps which port multiplies and which divides.

All are persistent and survive a controller restart. doReferencing and doReferencingAll are persistent too, so a configuration saved while one was set will re-reference on the next startup, against whatever the inputs happen to read then. Save your configuration after referencing, not during.

No parameters exist below this block.

Setup

Connect the two directions. With invert false, the multiplying direction is inverseInput to inverseOutput.
Set gain per channel, from the units: it is the multiplying side’s output unit divided by its input unit.
Leave offset at 0 for now.
Feed a known value into inverseInput and confirm inverseOutput is that value times the gain.
Feed inverseOutput back into input and confirm output returns the original. The round trip should be exact.
Set the offset by hand from a known reference point — see the caveat about automatic referencing above.

Tuning

There is nothing dynamic here. Both parameters take effect on the next cycle, with no fade and no filtering.
Set the gain from the units first, and check the round trip before worrying about the offset.
Set the offset from one known point: put the machine at a position you can measure, read inverseInput, and compute the offset that makes inverseOutput read the true value.
If you use doReferencing, verify the result rather than trusting it — read offset back and check inverseOutput really lands on inverseOutputReference. At a gain of 1 it will; away from 1 it will not.
Check both directions after every change. The two share one gain and one offset, so a change intended for one affects the other.
Use a gain of 0 deliberately if you want a channel’s dividing side muted — it outputs 0 rather than failing.
Nothing here depends on the task rate.

The dashed line is the round trip. It should always be the identity.

Symptom	Cause	Action
Referencing put the offset in the wrong place	The referencing formula suits `invert` true, and the default is false	Set the offset by hand, or set `invert` to true
Referencing looked right at a gain of 1	Expected: the two formulas agree only there	Verify at your real gain
The round trip does not return the input	The gain or offset changed between the two directions	They are shared, so check nothing else wrote them
One direction is scaled and the other is not	That is what the block does — one multiplies, one divides	Check `invert`
The multiplying and dividing ports are the wrong way round	`invert` is set the other way	Flip it
A channel’s output is 0	Its `gain` is 0, so the dividing side outputs 0 deliberately	Set a non-zero gain
The offset changed by itself	A referencing trigger fired	Check whether `doReferencing` was saved as true
Referencing happened at startup	The triggers are persistent, and one was saved as true	Save your configuration after referencing completes
Only some channels converted	`gain` and `offset` are per channel	Set every channel
The outputs are invalid	An input that is not a valid number passes straight through	Fix the upstream signal
I need the two directions scaled differently	Not possible — they share one gain, which is what makes them exact inverses	Use two `Gain` blocks
I need a non-linear conversion	Wrong block	Use `Lookup`
I need to switch it off	Not possible — there is no enable	Set `gain` to 1 and `offset` to 0
I need more channels	The count is fixed when the controller is built	Rebuild, or use a second instance

A starting point for a two-channel pass-through:

gain    = [1.0, 1.0]
offset  = [0.0, 0.0]
invert  = false

Limits and errors

Limit	Set by	What happens	Reported
Conversion	`gain`, `offset`	One port multiplies and adds, the other subtracts and divides. Exact inverses	`output`, `inverseOutput`
Direction	`invert`	Chooses which port does which	Not reported
A gain of 0	Checked	The dividing side outputs 0 rather than failing	Not reported
Automatic referencing	`doReferencing`	Computes an offset for the wrong direction when `invert` is false. Correct only at a gain of 1	Not reported — read `offset` and `inverseOutput` back
Referencing triggers	Fixed	Self-clearing, and persistent — a saved `true` fires once at startup	Not reported
`offset` after referencing	Fixed	Overwritten. A later configuration reload restores the saved value, not the referenced one	Read it back
Values that are not numbers	Nothing	Not checked. They pass through both paths	Not reported
State	None	The block has no memory, deliberately — some parent blocks run it twice in one cycle	Not applicable
Enable	None	There is no enable, disable or isEnabled	Not applicable
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).