– Physical models and compensation

Docs: AdmittanceModel

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

Control3 3.30–3.34

AdmittanceModel turns a measured force into a motion setpoint. It solves the equation of motion of a virtual mass on a spring and damper, in real time, and publishes the resulting position, velocity and acceleration for a position controller to track. That is what makes a stiff machine feel compliant: you push, the virtual mass moves, and the servo follows it.

Every physical coefficient is a lookup table, not a constant. Mass, damping and stiffness each vary with their own input, and two further tables scale mass and damping by position and velocity — so a machine whose apparent inertia should change across its workspace needs no gain scheduling elsewhere.

flowchart LR
    i1(["measuredTorque — the external force"]) --> B["AdmittanceModel"]
    i2(["actuatorFeedForwardTorque"]) --> B
    i3(["actuatorVirtualMass — input to the mass table"]) --> B
    i4(["inputPVA — jog and offset"]) --> B
    i5(["referencePVA — integrator references"]) --> B
    i6(["externalMassFactor"]) --> B
    i7(["externalDampingFactor"]) --> B
    i8(["connectSpringReferencePosition"]) --> B
    i9(["disableDynamics"]) --> B
    i10(["disable"]) --> B
    B --> o1(["outputPVA — the motion setpoint"])
    B --> o2(["outputTorque — spring plus damper force"])
    B --> o3(["springForce"])
    B --> o4(["damperForce"])
    B --> o5(["massCoefficient — the effective mass"])
    B --> o6(["accelerationTorque"])
    B --> o7(["accelerationTorqueCorrection"])
    B --> o8(["springReferencePosition"])
    B --> o9(["enabled"])

The virtual system is $M\ddot{x} + D\dot{x} + Kx = F$. With the default stiffness of 0 it is first order: terminal velocity $F/D$, time constant $M/D$. With stiffness set, aim at $\omega_n = \sqrt{K/M}$ [rad/s] and $\zeta = D/(2\sqrt{KM})$ — target $\zeta$ near 1 to avoid a bouncy contact. Read the effective mass off massCoefficient; it is the mass table’s output times the position and velocity scalings, not the number in the table.

A positive measuredTorque produces motion in the negative direction by default. Set useNegativeCoefficients true to reverse that.

The spring produces no force until connectSpringReferencePosition is set true. Until then the spring’s anchor follows the output, so there is nothing to push against. If you configured stiffness and see no spring force, this is why.

Signals

Inputs

Path	Unit	Range	Description
`measuredTorque`	N or N·m	unbounded	The external force the operator or environment applies. Non-numeric values are treated as zero.
`actuatorFeedForwardTorque`	N or N·m	unbounded	The actuator’s own modelled torque, added to the force target after `actuatorFeedForwardGain`. Non-numeric values are treated as zero.
`actuatorVirtualMass`	kg or kg·m²	unbounded	The input to the mass lookup table, not a mass. The table converts it into the mass the virtual system uses.
`inputPVA/position`	m or rad	unbounded	Added directly to `outputPVA/position`. An offset, not a setpoint.
`inputPVA/velocity`	m/s or rad/s	unbounded	Added directly to `outputPVA/velocity` — this is the jog path. It also trims the spring anchor while the anchor is connected.
`inputPVA/acceleration`	m/s² or rad/s²	unbounded	Feeds the mass-correction term only.
`referencePVA/position`	m or rad	unbounded	The position integrator’s reference.
`referencePVA/velocity`	m/s or rad/s	unbounded	The velocity integrator’s reference, and what the velocity is pinned to while the block is disabled.
`referencePVA/acceleration`	m/s² or rad/s²	-	Registered but never used. Ignore it.
`externalMassFactor`	-	0.1 – 100	Runtime scaling on the mass. The range is not enforced on this path — see Limits and errors.
`externalDampingFactor`	-	0.1 – 100	Runtime scaling on the damping. Not enforced, and a negative value is unsafe — see Limits and errors.
`connectSpringReferencePosition`	-	-	True freezes the spring’s anchor where the machine is, so the spring starts pulling back toward it. False re-anchors it to the current position every cycle, which means no spring force. The block clears this itself on a position reset.
`disableDynamics`	-	-	True pins the velocity to `referencePVA/velocity` and forces `outputTorque` to zero, while leaving the block enabled. Use it to hold the model rigidly at a commanded state.
`disable`	-	-	True does the same and also reads back on `enabled`. Use it for a runtime override from a supervisor; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`outputPVA/position`	m or rad	The motion setpoint — the reason to use this block. Position is held while the block is disabled, not zeroed.
`outputPVA/velocity`	m/s or rad/s	Velocity setpoint, including anything added through `inputPVA/velocity`.
`outputPVA/acceleration`	m/s² or rad/s²	Acceleration setpoint, optionally smoothed.
`outputTorque`	N or N·m	Spring plus damper force. Chain this to the next model’s force input to build a coupled chain. Zero while disabled or while `disableDynamics` is set.
`springForce`	N or N·m	The spring’s contribution after its own limit, including any position-limit push-back.
`damperForce`	N or N·m	The damper’s contribution after its own limit.
`massCoefficient`	kg or kg·m²	The effective mass actually used — the table output times both scalings. Watch this, not the table.
`accelerationTorque`	N or N·m	The net accelerating force before limiting.
`accelerationTorqueCorrection`	N or N·m	What the noise canceller contributed, zero when it is off.
`springReferencePosition`	m or rad	Where the spring is currently anchored.
`enabled`	-	True when `enable` is true and `disable` is false. Note the path is `enabled`, not `isEnabled`.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	False pins the velocity to its reference and zeroes `outputTorque`. Position still holds.
`useNegativeCoefficients`	-	false	-	False negates the force, so a positive `measuredTorque` gives negative motion. True passes the sign through. The name reads backwards against its effect.
`measuredTorqueDeadZone`	N or N·m	0.1	0 upward	Forces smaller than this produce no motion. Raise it to stop a noisy sensor creeping the machine.
`actuatorFeedForwardGain`	-	1.0	any	Scales `actuatorFeedForwardTorque` before it joins the force target. Not checked.
`massCorrection`	-	0.0	any	Scales an acceleration feedback term that partly cancels the virtual mass. Leave at 0 unless commissioning with support. Not checked.
`springTorqueLimit`	N or N·m	10	0 upward	Caps `springForce`. Set it to what the machine may push back with.
`damperTorqueLimit`	N or N·m	10	0 upward	Caps `damperForce`.
`anc/enable`	-	false	-	Switches on active noise cancellation, which projects a repeating disturbance forward and subtracts it. Leave off unless you have a periodic disturbance.
`anc/averageMaxSamples`	samples	250	1 upward	Fast averaging window. Not checked.
`anc/slowAverageMaxSamples`	samples	1000	100 – 2000	Slow averaging window. Corrected silently if out of range.

All ten are persistent and survive a restart.

Most of the configuration is below this block, in fifteen sub-trees. The ones you will use: massLookup, dampingLookup and stiffnessLookup for the three physical coefficients; positionCoefficientLookup and velocityCoefficientLookup for their position and velocity scaling; velocityIntegrator and positionIntegrator for the motion limits; positionLimitLookup for push-back near a limit; velocityLimiterLookup for the taper that slows the machine as it approaches one; torqueLimiter for the accelerating force; and five low-pass filters — massLowPass, accelerationLowPass, massLookupLowPass, dampingLookupLowPass and stiffnessLookupLowPass — that keep table steps from stepping the coefficients. See lookup.md, integrator.md and low-pass-1.md.

velocityCoefficientLookup ships unconfigured, and an unconfigured table returns zero, which is then floored at 0.01. That multiplies your mass by 0.01. Configure it — a single point returning 1.0 leaves the mass alone — before you trust any mass number. See Limits and errors.

Setup

Configure velocityCoefficientLookup first: one point, y = 1.0, numPoints = 1. Without this the effective mass is a fiftieth of what the mass table says.
Configure massLookup with the mass or inertia you want the operator to feel. A single point is enough if it does not vary.
Set stiffnessLookup to zero and leave connectSpringReferencePosition false. Tune the mass and damper first; the spring comes later.
Configure dampingLookup. Start high — a heavily damped virtual system is safe to push on.
Set springTorqueLimit and damperTorqueLimit to forces the machine may safely produce, and set the two integrators' output limits to the axis’s real travel and speed.
Set measuredTorqueDeadZone above your force sensor’s noise floor. Confirm the machine does not creep with nobody touching it.
Set enable true and check enabled reads true. Push the machine and confirm it moves away from the push. If it moves into your hand, flip useNegativeCoefficients.

Step 7 is the first time the machine moves under operator force. Have the axis clear and a hand on the stop. A mass that is too light or damping that is too low will make it run away from a light touch.
Read massCoefficient and confirm it is the mass you intended. It is the table output times both scalings, so it is the number that matters.
Only now add the spring: configure stiffnessLookup, then set connectSpringReferencePosition true where you want the anchor.

Tuning

Tune in this order — mass, damper, spring — and change one at a time. The three interact, and the spring is meaningless until the first two feel right.
Set the mass by feel, then verify with massCoefficient. Heavier feels more substantial and responds more slowly; lighter is quicker and easier to destabilise.
Set the damper from the terminal velocity you want: a steady push of $F$ settles at $F/D$. Read the terminal velocity off a trace and divide.
Check the time constant: $M/D$, in seconds. That is how long the machine takes to reach 63% of its terminal velocity. Too short and the machine feels twitchy; too long and it feels sluggish.
Add stiffness only when the machine should return to a position. Aim for $\zeta = D/(2\sqrt{KM})$ near 1 — below about 0.5 the contact will bounce.
If friction or inertia varies across the workspace, use the position and velocity coefficient tables to raise mass and damping where the machine feels light. They can only raise, never lower — the position scaling is floored at 1 and the velocity scaling at 0.01.
Use velocityLimiterLookup to taper the speed as the machine nears a position limit, and positionLimitLookup to push back. A hard clamp on the integrator alone arrives as a jolt.
Leave massCorrection at 0 and the noise canceller off unless you are commissioning with support. Both change the force balance in ways that are hard to read off a trace.

Read the time constant off any curve as the point it crosses 63% of its final value.

Symptom	Cause	Action
The machine feels far lighter than the mass table says	`velocityCoefficientLookup` is unconfigured, so the mass is multiplied by 0.01	Configure it: one point, `y` = 1.0. Then read `massCoefficient` back
The machine moves into the push instead of away	The sign convention	Flip `useNegativeCoefficients`
The machine creeps with nobody touching it	`measuredTorqueDeadZone` below the sensor’s noise floor	Raise it until the creep stops
The machine runs away from a light touch	Mass too low or damping too low	Raise `dampingLookup` first, then `massLookup`
Motion is sticky, then jumps	The dead zone is too large, or friction elsewhere is not compensated	Lower the dead zone; check the feedforward path’s friction model
No spring force at all, with stiffness configured	Expected: the anchor follows the output until you connect it	Set `connectSpringReferencePosition` true
The spring snapped the machine when engaged	The anchor was set while the machine was displaced	Engage it where you want the rest position to be
Contact bounces or oscillates	Damping too low for the stiffness	Raise `dampingLookup` until $\zeta$ is near 1, or lower the stiffness
The machine feels heavy in one part of the workspace only	Expected if `positionCoefficientLookup` is shaped that way	Flatten that table, or accept it — it exists to stabilise light regions
`massCoefficient` moved on its own	Expected: the mass table is driven by `actuatorVirtualMass` and scaled by position and velocity	Trace all three inputs to see which moved
Motion is jerky when crossing a table breakpoint	A step in a lookup table	The coefficient low-passes smooth this; lower their cut-offs, or soften the table
Reaching a position limit arrives as a jolt	Only the integrator’s hard clamp is set	Configure `velocityLimiterLookup` to taper the speed and `positionLimitLookup` to push back
`outputTorque` went to zero and motion stopped	Expected while `disable` or `disableDynamics` is set	Read `enabled`
Position held but velocity went to zero on disable	Expected: velocity is pinned to its reference, position holds	This is the designed idle state
The machine drifted over a long session	Two integrations with no reset reachable from the parameter tree	Restart the controller, or have the application call its reset
A force spike appeared after a bad sensor reading	Expected: non-numeric torque readings are treated as zero, but a large finite spike passes	Lower `torqueLimiter`’s limits
Everything went non-numeric and stayed there	A non-numeric value reached `inputPVA` or a lookup table, which are not guarded	Restart the controller
The machine became unstable after an external factor was written	A zero or negative `externalDampingFactor` — negative damping adds energy	Write a value between 0.1 and 100 and restart
Motion is right but forces look wrong	The two limits are clipping	Read `springForce` and `damperForce` against `springTorqueLimit` and `damperTorqueLimit`

A conservative starting point for a 1 ms task, damper-only compliance with no spring, on an axis whose travel is ±0.5:

enable                    = true
useNegativeCoefficients   = false
measuredTorqueDeadZone    = 0.5
actuatorFeedForwardGain   = 1.0
massCorrection            = 0.0
springTorqueLimit         = 10.0
damperTorqueLimit         = 10.0
anc/enable                = false
velocityCoefficientLookup: numPoints = 1, x = 0, y = 1.0
massLookup:                numPoints = 1, x = 0, y = 2.0
dampingLookup:             numPoints = 1, x = 0, y = 40.0
stiffnessLookup:           numPoints = 1, x = 0, y = 0.0

That gives an effective mass of 4 (mass 2 × position scaling 2), damping 80, and a time constant of 0.05 s. This is a starting point, not a final tuning.

Limits and errors

Limit	Set by	What happens	Reported
`velocityCoefficientLookup` configured	Nothing	Not checked. Unconfigured it returns zero, floored to 0.01, multiplying your mass by 0.01. Nothing warns	Not reported; visible on `massCoefficient`
`externalMassFactor`, `externalDampingFactor` within 0.1 – 100	Nothing on the input path	Not checked when written as an input. A zero or negative mass factor is caught by the mass floor; a negative damping factor is not caught anywhere and makes the virtual system unstable	Not reported
Effective mass ≥ 0.00001	Fixed	A smaller or non-numeric mass is replaced by that floor, and the mass table’s gain is permanently rewritten as a side effect	Not reported; visible on `massCoefficient` and in the table’s gain
`springForce`	`springTorqueLimit`	Clamped	Not reported; compare `springForce` against the limit
`damperForce`	`damperTorqueLimit`	Clamped	Not reported
Accelerating force	`torqueLimiter` sub-tree	Clamped when that limiter is enabled. It is disabled by default, so the force is unbounded until you enable it	Not reported
`outputPVA/velocity`	`velocityIntegrator` output limits, tapered by `velocityLimiterLookup`	Clamped, and tapered toward zero near a position limit	Not reported
`outputPVA/position`	`positionIntegrator` output limits	Clamped hard. Without a velocity taper the clamp arrives as a jolt	Not reported
`anc/averageMaxSamples`	Nothing	Not checked	Not reported
`actuatorFeedForwardGain`, `massCorrection`	Nothing	Not checked	Not reported
Model state	Nothing reachable	There is no reset input. The block integrates twice and cannot be re-zeroed from the parameter tree — only an application call or a restart	Not reported
Non-numeric inputs	Partial	`measuredTorque`, `actuatorFeedForwardTorque` and the mass-correction term are guarded and treated as zero. `inputPVA` and the lookup tables are not	Not reported
Channel count	Fixed	One axis 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: ImpedanceModel

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

Control3 3.30–3.34

ImpedanceModel is the opposite of AdmittanceModel: motion goes in, force comes out. Given how far the machine has been displaced from a desired state, it produces the reaction force a virtual mass, spring and damper would exert. Use it to make a force-controlled machine behave like a defined mechanical system.

It stays stable against a stiff environment, because it has no internal state — no integration, nothing to wind up. Its output depends only on this cycle’s inputs.

flowchart LR
    i1(["inputPVA — where the machine is"]) --> B["ImpedanceModel"]
    i2(["measuredPVA — where it should be"]) --> B
    i3(["externalTorque"]) --> B
    i4(["disable"]) --> B
    B --> o1(["outputTorque — the reaction force"])
    B --> o2(["isEnabled"])

Force $= K,\Delta x + D,\Delta\dot{x} + M,\Delta\ddot{x}$ plus externalTorque, where each $\Delta$ is inputPVA minus measuredPVA. Each coefficient is a gain times a lookup table, so all three can be non-linear. Aim at $\omega_n = \sqrt{K/M}$ [rad/s] and $\zeta = D/(2\sqrt{KM})$ — target $\zeta$ near 1 so contact does not bounce.

Stiffness ships engaged at 100, unlike the admittance block whose spring defaults to off. An unconfigured instance with any displacement produces force straight away.

Enabling is a step, not a ramp. The block is algebraic, so the full force appears on the first cycle. Bring it in by raising the gains from zero instead.

Signals

Inputs

Path	Unit	Range	Description
`inputPVA/position`	m or rad	unbounded	Where the machine actually is. It also drives the mass table, so the virtual mass can vary with position.
`inputPVA/velocity`	m/s or rad/s	unbounded
`inputPVA/acceleration`	m/s² or rad/s²	unbounded	Only matters when the mass term is non-zero.
`measuredPVA/position`	m or rad	unbounded	Where the machine should be — the rest position the spring pulls toward. Despite the name, this is the reference, not a measurement.
`measuredPVA/velocity`	m/s or rad/s	unbounded	The velocity the damper measures against.
`measuredPVA/acceleration`	m/s² or rad/s²	unbounded
`externalTorque`	N or N·m	unbounded	Added straight to the output, unscaled. Use it to chain another model’s force in.
`disable`	-	-	True forces `outputTorque` to zero. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`outputTorque`	N or N·m	The reaction force: spring plus damper plus inertia plus `externalTorque`. Zero while disabled. It appears at full value on the first enabled cycle — there is no ramp.
`isEnabled`	-	True when `enable` is true and `disable` is false.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	False forces `outputTorque` to zero.
`stiffnessGain`	-	1	0 upward	Scales the stiffness table. Higher resists displacement more. Not checked — a negative value pushes the machine away from the rest position instead of toward it.
`dampingGain`	-	1	0 upward	Scales the damping table. Higher resists motion more. Not checked — a negative value drives the machine instead of damping it.
`massGain`	-	1	0 upward	Scales the mass table. Higher makes the machine resist acceleration more. Forced away from zero, but not away from negative.

All four are persistent and survive a restart.

The three coefficients live below this block, as lookup tables: stiffnessLookup driven by the relative position, dampingLookup by the relative velocity, and massLookup by the absolute input position. Each ships as a single point — stiffness 100, damping 10, mass 1 — so a constant coefficient needs no table work. See lookup.md.

The effective coefficients are not published. What the block actually uses is the gain times the table output, and neither is visible on an output. To check one, read the table’s own output in its sub-tree and multiply by the gain yourself.

Setup

Set all three gains to 0. With no coefficients the output is only externalTorque, so nothing unexpected reaches the actuator.
Link inputPVA from the machine’s measured state and measuredPVA from the state you want it to hold. Confirm both on a trace.
Confirm the displacement is what you expect: subtract the two positions on a trace. That difference is what the spring will act on.
Set enable true and confirm isEnabled reads true. outputTorque should still be zero, because the gains are zero.
Raise stiffnessGain from 0 toward 1 in steps. outputTorque should oppose the displacement — pushing the machine back toward measuredPVA.

Step 5 puts real force into the actuator, at full value. The block has no ramp: whatever gain you write takes effect on the next cycle, against whatever displacement exists at that moment. Raise it in small steps with the machine near its rest position.
Check the sign. If the force pushes the machine away from measuredPVA, your two PVA inputs are swapped.
Raise dampingGain next, then massGain only if you need the machine to resist acceleration.

Tuning

Set the stiffness from the process: how hard should the machine resist being pushed off position? That is $K$ in newtons per metre.
Set the damping for stability, not for feel. Compute $\zeta = D/(2\sqrt{KM})$ and aim near 1. Below about 0.5 contact bounces.
Set the mass last, and usually leave it small. It resists acceleration and amplifies any noise on inputPVA/acceleration.
Use the tables rather than the gains for anything non-linear — a spring that stiffens with displacement, or a damper that softens at speed. The gains are one number each; the tables are a curve.
Use massLookup if the machine’s apparent inertia changes across its workspace. It is driven by absolute position, unlike the other two.
Verify each coefficient by reading its table output in the sub-tree and multiplying by the gain. Nothing publishes the product.
Nothing here needs re-checking after a task-rate change. The block does not integrate and has no task-rate-dependent limit.

Read the effective stiffness off the slope of any line.

Symptom	Cause	Action
The machine is pushed away from the rest position instead of toward it	The two PVA inputs are swapped, or a gain is negative	Check step 3 of Setup, then check every gain is positive
Force appeared as soon as the block was enabled	Expected: the block is algebraic and has no ramp, and stiffness defaults to 100	Set the gains to 0 before enabling and raise them from there
The machine runs away instead of settling	A negative `dampingGain` — negative damping adds energy	Set it positive
Contact bounces or oscillates	Damping too low for the stiffness	Raise `dampingGain` until $\zeta$ is near 1, or lower the stiffness
Contact feels dead and heavy	Damping too high, or the mass term too large	Lower `dampingGain`, then `massGain`
The force is noisy	`massGain` is amplifying noise on the acceleration input	Lower `massGain`, or filter the acceleration upstream
The force does not match the stiffness you configured	Expected: the effective stiffness is the gain times the table output	Read the table’s output in its sub-tree and multiply
Force with no displacement at all	`externalTorque` is non-zero and passes straight through	Trace that input
The machine feels stiffer in one part of its travel	Expected if `massLookup` or a coefficient table is shaped that way	Flatten the table, or accept it
Changing the stiffness table changed the force at a different displacement than expected	The stiffness table is driven by the relative position, so its own input moves with the displacement	Shape the table against the displacements you actually work at
Changing the mass table did nothing at standstill	Expected: the mass term multiplies relative acceleration, which is zero at rest	Check it during a move
`outputTorque` went to zero	`enable` is false or `disable` is true	Read `isEnabled`
A non-numeric value appeared and then cleared itself	Expected: the block holds no state, so it recovers as soon as the inputs are clean	Fix the source
The block drifted over a long session	Not possible — there is no state to drift	Look upstream
You need this on several axes	Not possible — one axis per instance	Use one instance per axis

A starting point for a 1 N·m per 0.01 rad spring with critical damping, mass term off:

enable        = true
stiffnessGain = 1.0
dampingGain   = 1.0
massGain      = 0.0
stiffnessLookup: numPoints = 1, x = 0, y = 100.0
dampingLookup:   numPoints = 1, x = 0, y = 20.0
massLookup:      numPoints = 1, x = 0, y = 1.0

Raise the gains from 0 as Setup step 5 describes. This is a starting point, not a final tuning.

Limits and errors

Limit	Set by	What happens	Reported
`stiffnessGain`, `dampingGain`	Nothing	Not checked, including negative. A negative stiffness pushes the machine away from its rest position; a negative damping drives it instead of damping it. Both make the virtual system an energy source	Not reported
`massGain`	Forced away from zero	A value within 0.001 of zero is replaced by ±0.001. Negative values are still accepted	Not reported
Effective coefficients	Nothing	The gain times the table output. Neither product is published — read the table output in its sub-tree and multiply	Not reported
`outputTorque`	Nothing	Unbounded — whatever the coefficients and displacement produce. Bound it in the actuator’s own limiter	Not reported
Enabling	Nothing	The full force appears on the first enabled cycle. There is no ramp	Not reported
Stability	Structural	The block has no state and does not integrate, so it cannot diverge on its own. There is no task-rate limit to respect and nothing to rescale after a task-rate change	Not applicable
Block state	None	Nothing to reset, nothing survives a stop	Not applicable
Channel count	Fixed	One axis 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: MassSpringDamperModel

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

Control3 3.30–3.34

MassSpringDamperModel simulates a point mass on a spring and damper, coupled to a neighbouring model. Its purpose is chains: connect several instances and you have a flexible structure, a series-elastic joint, or a multi-body compliance model built from copies of one block.

It does both compliance directions in one block. By default it behaves like an admittance — force in, motion out. Set enableImpedance and it behaves like an impedance — motion in, force out — and adds an inertia term to its output force.

flowchart LR
    i1(["inputForce — external force on the mass"]) --> B["MassSpringDamperModel"]
    i2(["inputState — external state, impedance mode only"]) --> B
    i3(["connectedForce — force from the next model"]) --> B
    i4(["connectedState — state of the previous model"]) --> B
    B --> o1(["outputState — this mass's motion"])
    B --> o2(["outputForce — coupling force"])
    B --> o3(["mass — effective mass"])
    B --> o4(["damping — effective damping"])
    B --> o5(["stiffness — effective stiffness"])
    B --> o6(["relativePosition — spring extension"])
    B --> o7(["relativeVelocity"])

The mass obeys $M\ddot{x} =$ inputForce $+$ connectedForce $-$ outputForce, and the coupling force is $K,\Delta x + D,\Delta\dot{x}$, plus $M,\Delta\ddot{x}$ in impedance mode. Aim at $\omega_n = \sqrt{K/M}$ [rad/s] and $\zeta = D/(2\sqrt{KM})$ — target $\zeta$ near 1. Keep the task period below $2/\omega_n$ or the simulation grows without bound; nothing checks this.

To build a chain: connect this model’s outputForce to the previous model’s connectedForce, and the previous model’s outputState to this one’s connectedState. The spring anchors on connectedState.

This block has no enable and no disable. disableDynamics pins the motion to connectedState but still publishes a coupling force, so a chain keeps transmitting while it is set.

Signals

Inputs

Path	Unit	Range	Description
`inputForce`	N or N·m	unbounded	The external force pushing on this mass. Forces smaller than `inputForceDeadZone` are ignored.
`inputState`	m, m/s, m/s²	unbounded	An externally measured state, as `x`, `xDot` and `xDDot` together. Only read in impedance mode — in the default admittance mode it is ignored entirely.
`connectedForce`	N or N·m	unbounded	The coupling force from the next model in the chain. Added directly to the net force.
`connectedState`	m, m/s, m/s²	unbounded	The previous model’s state. It is the spring’s anchor and the reference both integrators return to.

Outputs

Path	Unit	Description
`outputState`	m, m/s, m/s²	This mass’s position, velocity and acceleration, together. Chain it to the next model’s `connectedState`. Starts at zero and is not cleared by a stop.
`outputForce`	N or N·m	The coupling force the spring and damper transmit. Chain it to the previous model’s `connectedForce`. Not zeroed by `disableDynamics`.
`mass`	kg or kg·m²	The effective mass — `massGain` times the mass table’s output. Watch this, not the table.
`damping`	N·s/m	The effective damping.
`stiffness`	N/m	The effective stiffness.
`relativePosition`	m or rad	The spring’s extension or compression. In admittance mode this is `outputState` minus `connectedState`; in impedance mode `inputState` minus `connectedState`.
`relativeVelocity`	m/s or rad/s	The velocity across the damper, from the same source as above.

Parameters

Path	Unit	Default	Range	Effect
`enableImpedance`	-	false	-	False gives admittance: the coupling force is spring + damper, computed from this block’s own motion. True gives impedance: the coupling force is computed from `inputState` instead, and gains an inertia term.
`massGain`	-	1	0.001 upward	Scales the mass table. Values below 0.001 are corrected up, so the mass gain can never be zero or negative.
`stiffnessGain`	-	1	any	Scales the stiffness table. Its sign is forced positive, so a negative value acts as its magnitude.
`dampingGain`	-	1	any	Scales the damping table. Its sign is forced positive too.
`disableDynamics`	-	false	-	True pins `outputState` to `connectedState` every cycle, so the mass stops moving on its own. It does not stop the coupling force.
`inputForceDeadZone`	N or N·m	0.1	0 upward	Forces smaller than this do not push the mass. Raise it to stop a noisy force reading creeping the model.

All six are persistent and survive a restart.

The three coefficients live below this block, as lookup tables: massLookup driven by this mass’s own position, dampingLookup by the relative velocity, and stiffnessLookup by the relative position. Each ships as a single point at 1.0. The two integrators — velocityIntegrator and positionIntegrator — carry the motion limits. See lookup.md and integrator.md.

Never let massLookup return zero. The mass divides the net force, and a zero mass makes the simulation non-numeric. A table that is not strictly increasing in x also returns zero, so check monotonicity as well as values.

Setup

Configure massLookup with the mass you want this point to have. A single point is enough if it does not vary with position. Confirm it never returns zero.
Configure dampingLookup and stiffnessLookup. Start with a low stiffness and generous damping — a soft, well-damped model is safe to experiment with.
Compute $\omega_n = \sqrt{K/M}$ and check the task period is below $2/\omega_n$, comfortably. A stiff spring on a slow task will not simulate; it will diverge.

Step 3 is the check nothing does for you. There is no warning and no clamp. Too stiff a spring for the task rate makes outputState grow without bound, and the only way out is a restart.
Set the integrators' output limits to the travel and speed this mass may have.
Leave enableImpedance false for a first pass. Link inputForce and watch outputState respond.
Read mass, damping and stiffness back and confirm they are the values you intended. They are the gain times the table output.
To chain: link this model’s outputForce to the previous model’s connectedForce, and that model’s outputState to this one’s connectedState. Build the chain one link at a time and check each is stable before adding the next.

Tuning

Set the mass first, from the physical mass this point represents.
Set the stiffness from the compliance you are modelling. For a series-elastic joint that is the spring’s real rate.
Set the damping for stability: compute $\zeta = D/(2\sqrt{KM})$ and aim near
1. Below about 0.5 the model rings, and in a chain that ringing couples between links.
Re-check step 3 of Setup after every stiffness or mass change. The stability bound moves with both.
Use the tables rather than the gains for anything non-linear — a progressive spring, or a damper that softens at speed.
Choose the mode deliberately, and not mid-run. Switching enableImpedance changes which inputs matter: admittance mode ignores inputState, and impedance mode stops using this block’s own position for the coupling force.
In a chain, tune from one end. Each link’s connectedState is the previous link’s output, so an unstable link destabilises everything after it.

Read the damping ratio off the overshoot on any curve.

Symptom	Cause	Action
`outputState` grew without bound	The task period is too slow for the stiffness and mass	Work step 3 of Setup, then restart the controller
Everything went non-numeric	`massLookup` returned zero — either its value is zero or its `x` values are not strictly increasing	Fix the table, then restart the controller
The mass does not move at all	`disableDynamics` is set, or `inputForce` is inside the dead zone	Clear `disableDynamics`; lower `inputForceDeadZone`
The mass still transmits force while `disableDynamics` is set	Expected: that parameter pins the motion, not the force	Set the stiffness and damping gains to 0 as well
`outputForce` does not respond to this mass’s own motion	Expected in impedance mode: the coupling force is computed from `inputState`	Clear `enableImpedance`, or link `inputState`
`inputState` seems to be ignored	Expected in admittance mode, which is the default	Set `enableImpedance` if you meant impedance
The force gained an extra term when the mode changed	Expected: impedance mode adds an inertia term to the coupling force	This is the mode’s purpose
The model rings after a force step	Damping too low for the stiffness	Raise `dampingGain` until $\zeta$ is near 1
The model is sluggish	Damping too high, or the mass too large	Lower `dampingGain`, then the mass
A chain oscillates although each link looks fine alone	Links couple, and a lightly damped link excites its neighbours	Raise damping across the chain, and tune from one end
The effective coefficients are not what the table says	Expected: each is the gain times the table output	Read `mass`, `damping` and `stiffness` — all three are published
A negative stiffness or damping gain had no effect on the sign	Expected: both are forced positive	Use the table values if you need a sign change, though a negative spring is unphysical
`massGain` reads back as 0.001 after writing 0	Expected: it is floored	Set a real value
The simulation kept running after a controller stop and start	Expected: the state is not cleared at start	Set `disableDynamics` for a cycle to pin it back to `connectedState`
The mass feels heavier at one end of its travel	Expected if `massLookup` is shaped that way — it is driven by this mass’s own position	Flatten the table
A non-numeric value appeared and will not clear	There is no reset input, and the integrators hold it	Restart the controller

A starting point for a soft, well-damped single mass on a 1 ms task — $\omega_n$ = 4.5 rad/s, $\zeta$ = 1.1, comfortably inside the stability bound:

enableImpedance    = false
massGain           = 1.0
stiffnessGain      = 1.0
dampingGain        = 1.0
disableDynamics    = false
inputForceDeadZone = 0.1
massLookup:      numPoints = 1, x = 0, y = 1.0
stiffnessLookup: numPoints = 1, x = 0, y = 20.0
dampingLookup:   numPoints = 1, x = 0, y = 10.0

This is a starting point, not a final tuning.

Limits and errors

Limit	Set by	What happens	Reported
Task period against the model’s natural frequency	Nothing	Not checked. The task period must stay below 2 divided by $\sqrt{K/M}$. Too stiff a spring for the task rate makes the state grow without bound; only a restart clears it	Not reported
Effective mass above zero	Nothing	Not checked. `massGain` is floored at 0.001, but the mass table can still return zero — including when its `x` values are not strictly increasing, which returns zero by design. The result is a division by zero	Not reported; visible on `mass`
`stiffnessGain`, `dampingGain`	Sign forced	Both are used as their magnitude, so a negative value cannot invert the force	Not reported; read the value back
`massGain` ≥ 0.001	Fixed	Corrected up, which also excludes negatives	Not reported; read the value back
`outputForce`	Nothing	Unbounded. Bound it downstream, and remember it is not zeroed by `disableDynamics`	Not reported
`outputState`	The two integrators' output limits	Clamped by whatever those sub-trees are set to	Not reported
Non-numeric inputs	Nothing	Not guarded anywhere. A non-numeric value latches into the integrators and there is no reset input to clear it	Not reported
Model state	`disableDynamics`	Pins the state to `connectedState`. That is the only reset, and it is a parameter rather than a linkable input	Not reported
Channel count	Fixed	One mass per instance. A chain is several instances	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: FrictionCompensation

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

Control3 Superseded. The current release is 3.34.

FrictionCompensation computes the friction force an axis is fighting at a given velocity, so a feedforward path can cancel it before the feedback loop has to. It is what turns a machine that sticks and then jumps into one that moves smoothly from rest.

It offers three friction models, each from a published paper, chosen with one parameter. They differ in how they behave at zero velocity, and that difference is the whole reason to pick one over another.

flowchart LR
    i1(["input — velocity"]) --> B["FrictionCompensation"]
    i2(["outputScalingFactor"]) --> B
    i3(["disable"]) --> B
    B --> o1(["output — friction force"])
    B --> o2(["isEnabled"])

The shared curve is $g(v) = F_c + (F_s - F_c)e^{-(v/v_s)^2}$: friction falls from stictionFrictionForce at rest to coulombFrictionForce once the velocity is well past stribeckVelocity. That drop is why a machine breaks away and then runs light. Viscous damping adds viscousFrictionDamping × velocity on top. Below a velocity of coulombFrictionForce × preSlidingDisplacement / stictionFrictionForce — 0.001 at the defaults — models 0 and 1 produce no friction force at all.

The default model is 1, STATIC_SIGN, and it is the wrong one for feedforward. It steps by twice the stiction force as the axis reverses. For feedforward use model 2, CONTINUOUS_TANH, which is smooth through zero. Model 1 is the default only for backward compatibility.

The block starts disabled — enable defaults to false.

Signals

Inputs

Path	Unit	Range	Description
`input`	m/s or rad/s	unbounded	The velocity to compute friction for — normally the velocity reference, not the measurement, since this is a feedforward term. One element per channel.
`outputScalingFactor`	-	0 – 1	Fades the output force. It is clamped and rate-limited in place, so reading this path back gives the rate-limited value, not what you wrote. Inside a feedforward controller this path is written every cycle from a position table and a link into it has no effect.
`disable`	-	-	True forces the output to zero and clears the model’s internal state. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	N or N·m	The friction force at the given velocity, after scaling. One element per channel. Zero while disabled — not a pass-through, because a friction model’s idle value is no force.
`isEnabled`	-	True when `enable` is true and `disable` is false. Note it can read true while `outputScalingFactor` has faded the output to zero.

Parameters

Path	Unit	Default	Range	Effect
`model`	-	1	0, 1 or 2	Which friction model to use. See the table below. Set this explicitly — leaving it unset gives model 1.
`enable`	-	false	-	False forces the output to zero and clears the internal state.
`coulombFrictionForce`	N or N·m	10	0 upward	Friction once the axis is moving. The floor of the curve. Corrected to 0 if negative.
`stictionFrictionForce`	N or N·m	20	at least `coulombFrictionForce`	Friction at rest — the force needed to break away. Corrected up to the Coulomb force if you set it lower.
`viscousFrictionDamping`	N·s/m or N·m·s/rad	1.0	0 upward in practice	Friction proportional to speed. Not checked — a negative value makes friction drive the axis.
`stribeckVelocity`	m/s or rad/s	0.01	1e-6 – 0.01	How quickly friction falls from stiction to Coulomb. Corrected silently if out of range.
`preSlidingDisplacement`	m or rad	0.002	1e-9 – 0.01	How far the axis deflects before it breaks away. Models 0 and 1 only. It also sets the zero-velocity dead band — see the blockquote.
`contactDamping`	N·s/m	0.0	0 upward	Bristle contact damping, model 0 only. Leave at 0 for feedforward — non-zero adds transient forces during velocity changes.
`coulombVelocity`	m/s or rad/s	0.001	1e-6 upward	How sharply model 2 rises through zero. Smaller is sharper and closer to model 1. Model 2 only.
`outputScalingFactorRate`	1/s	10.0	above 0	How fast `outputScalingFactor` may change. The default fades fully in 0.1 s on any task rate. Not checked — 0 freezes the scaling factor where it is.

`model`	What the machine does	Parameters that matter
0 `LUGRE_DYNAMIC`	Models the deflection before breakaway, so stick-slip and hysteresis at reversal are reproduced. Has internal state	`preSlidingDisplacement`, `contactDamping`, plus the shared curve
1 `STATIC_SIGN`	Classical Stribeck curve. Steps discontinuously across zero velocity — use it for steady-state analysis, not feedforward	The shared curve, `preSlidingDisplacement` for the dead band
2 `CONTINUOUS_TANH`	Smooth everywhere, including through zero. The right choice for friction feedforward	`coulombVelocity`, plus the shared curve

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

A legacy useStaticFriction parameter is still read from older configuration files and mapped onto model at startup, with a warning in the log. It is not saved back. Update your configuration to set model directly.

Setup

Set model to 2 if this is a feedforward path, which is the usual case. Set it explicitly — an unset model gives model 1.
Set enable false while you measure.
Measure Coulomb friction: move the axis at a steady moderate speed with the loop closed and no friction compensation, and read the force the feedback controller supplies. That is coulombFrictionForce.
Measure stiction: command a slowly rising force from rest and note the force at which the axis breaks away. That is stictionFrictionForce. It must be at least the Coulomb force, and the block will correct it upward if it is not.
Measure viscous damping: repeat step 3 at two or three speeds. The slope of force against speed is viscousFrictionDamping.
Leave stribeckVelocity at 0.01 and preSlidingDisplacement at 0.002 for a first pass. Both are refinements.
Set enable true and confirm isEnabled reads true. Check the sign: the output must oppose motion — positive force for positive velocity.

Step 7 adds real force to the actuator. If the sign is wrong the compensation adds to friction instead of cancelling it, and the axis will accelerate away. Have the axis clear.
Check the feedback controller’s own output has dropped at steady speed. That drop is what the compensation bought you.

Tuning

Measure, do not dial. Every parameter here is a physical property of your axis, and steps 3 to 5 of Setup measure them directly. Tuning by watching the error is how you end up over-compensating.
Get the Coulomb force right first — it dominates everywhere except near rest.
Then stiction. Too much and the axis lurches from rest; too little and it still sticks.
Then viscous damping, at the top of your speed range where it matters most.
Refine stribeckVelocity only if the transition from rest to moving feels wrong. Lower it to make friction drop off sooner.
With model 2, use coulombVelocity to set how sharply the force rises through zero. Smaller is sharper and cancels more friction near rest, but a very small value approaches model 1’s discontinuity and reintroduces chatter.
With model 0, preSlidingDisplacement is the real deflection before breakaway. Leave contactDamping at 0 for feedforward.
Check both directions of travel. Friction is rarely symmetric, and this block models it as symmetric — if the two differ a lot, this block will compensate the average.
Use outputScalingFactor to fade compensation in and out — for example to reduce it where the axis is well supported. Its rate limit is in units per second and holds its meaning across task rates.

Read the stiction force off the peak near zero and the Coulomb force off the flat part beyond it.

Symptom	Cause	Action
The axis chatters or buzzes around zero velocity	Model 1’s discontinuity at zero	Set `model` to 2
The axis lurches from rest	`stictionFrictionForce` too high	Re-measure it with Setup step 4
The axis still sticks at rest	Stiction too low, or the dead band is swallowing the command	Raise `stictionFrictionForce`; if that does not help, lower `preSlidingDisplacement` to narrow the dead band
No friction force at all at very low speed	Expected: models 0 and 1 have a dead band below the velocity in the blockquote	Use model 2, which has no dead band
The axis accelerates away instead of moving smoothly	The sign is wrong, or friction is over-compensated	Check the sign first; then halve every force parameter
The axis runs faster the harder it is pushed, with no friction	`viscousFrictionDamping` is negative	Set it to zero or positive
Compensation is right at low speed and too strong at high speed	`viscousFrictionDamping` too high	Re-measure with Setup step 5
Compensation is right at high speed and too weak near rest	`stictionFrictionForce` too low, or `stribeckVelocity` too high	Raise stiction; lower the Stribeck velocity
`stictionFrictionForce` reads back higher than written	Expected: it is corrected up to the Coulomb force	Raise the Coulomb force, or accept the correction
`stribeckVelocity` or `preSlidingDisplacement` reads back different	Outside the accepted band	Work within the value you read back
The output faded to zero but `isEnabled` reads true	`outputScalingFactor` has been driven to 0	Read that path; inside a feedforward controller it is written from a position table
`outputScalingFactor` will not move	`outputScalingFactorRate` is 0	Set a positive rate
A scaling change arrived as a slow ramp	Expected: it is rate-limited	Raise `outputScalingFactorRate`
The output ramps up over a moment after enabling, with model 0	Expected: the deflection starts from zero and loads up	Use model 1 or 2 if that transient matters
The block behaves like model 1 when you configured model 2	`model` was left unset, so it resolved to 1	Write `model` = 2 explicitly and check the log for a deprecation warning
A warning about `useStaticFriction` at startup	An old configuration file still sets the retired parameter	Set `model` directly and remove it
Friction differs between directions and the block cannot match both	The model is symmetric by construction	Compensate the average, or handle the asymmetry upstream
Every channel gets the same friction	Expected: all parameters are shared across channels	Use one instance per axis
The output went non-numeric	A non-numeric velocity reached `input`	Fix the source, then disable and re-enable to clear the state

A starting point for feedforward on a rotary axis on a 1 ms task, with measured values substituted at steps 3 to 5 of Setup:

model                   = 2
enable                  = true
coulombFrictionForce    = 10.0
stictionFrictionForce   = 20.0
viscousFrictionDamping  = 1.0
stribeckVelocity        = 0.01
coulombVelocity         = 0.001
preSlidingDisplacement  = 0.002
contactDamping          = 0.0
outputScalingFactorRate = 10.0

Limits and errors

Limit	Set by	What happens	Reported
`stictionFrictionForce` ≥ `coulombFrictionForce`	Fixed	Stiction is raised to match the Coulomb force. This is what keeps model 2’s curve the right way up	Silently; read the value back
`coulombFrictionForce` ≥ 0	Fixed	A negative value is replaced by 0	Silently; read the value back
`stribeckVelocity` within 1e-6 – 0.01	Fixed	Replaced by the nearest edge	Silently; read the value back
`preSlidingDisplacement` within 1e-9 – 0.01	Fixed	Replaced by the nearest edge. The bound is the same for a linear or rotary axis	Silently; read the value back
`contactDamping` ≥ 0, `coulombVelocity` ≥ 1e-6	Fixed	Replaced by the nearest edge	Silently; read the value back
`viscousFrictionDamping`	Nothing	Not checked. A negative value makes friction drive the axis instead of resisting it	Not reported
`outputScalingFactorRate`	Nothing	Not checked. 0 freezes the scaling factor at its present value — including at 0, which silences the output while `isEnabled` still reads true. A negative value is unsafe	Not reported
`outputScalingFactor` within 0 – 1	Fixed	Clamped, then rate-limited, and written back to the input path	Not reported; read the path back
`output`	Nothing	Unbounded — whatever the model computes. Bound it in the actuator’s own limiter	Not reported
Model state	`disable`, or `enable` false	A disabled cycle clears the internal state completely	Not reported
Channels	Shared	Every channel uses the same parameters. One instance cannot model two different axes	Not reported

The block logs one warning, at startup only: that a configuration file still sets the retired useStaticFriction parameter, naming the model it was mapped to. Every other failure above shows as a value on a trace, not as a message.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: FrictionCompensation

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

Control3 Current release

flowchart LR
    i1(["input — velocity"]) --> B["FrictionCompensation"]
    i2(["outputScalingFactor"]) --> B
    i3(["disable"]) --> B
    B --> o1(["output — friction force"])
    B --> o2(["isEnabled"])

The shared curve is $g(v) = F_c + (F_s - F_c)e^{-(v/v_s)^2}$: friction falls from stictionFrictionForce at rest to coulombFrictionForce once the velocity is well past stribeckVelocity. That drop is why a machine breaks away and then runs light. Viscous damping adds viscousFrictionDamping × velocity on top. Below a velocity of coulombFrictionForce × preSlidingDisplacement / stictionFrictionForce — 0.001 at the defaults — models 0 and 1 produce no friction force at all.

The block starts disabled — enable defaults to false.

Signals

Inputs

Path	Unit	Range	Description
`input`	m/s or rad/s	unbounded	The velocity to compute friction for — normally the velocity reference, not the measurement, since this is a feedforward term. One element per channel.
`outputScalingFactor`	-	0 – 1	Fades the output force. The block never writes this path, so reading it back gives exactly what you wrote — write it once and leave it, and the fade still completes. The value actually multiplying the output is that command clamped to 0 – 1 and moved towards by at most `outputScalingFactorRate` per second; it is not published, so read the fade off `output` itself. Inside a feedforward controller this path is written every cycle from a position table and a link into it has no effect.
`disable`	-	-	True forces the output to zero and clears the model’s internal state. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	N or N·m	The friction force at the given velocity, after scaling. One element per channel. Zero while disabled — not a pass-through, because a friction model’s idle value is no force.
`isEnabled`	-	True when `enable` is true and `disable` is false. Note it can read true while `outputScalingFactor` has faded the output to zero.

The applied scaling factor is deliberately not a published signal. output carries its effect, and outputScalingFactor carries the command.

Parameters

Path	Unit	Default	Range	Effect
`model`	-	1	0, 1 or 2	Which friction model to use. See the table below. Set this explicitly — leaving it unset gives model 1.
`enable`	-	false	-	False forces the output to zero and clears the internal state.
`coulombFrictionForce`	N or N·m	10	0 upward	Friction once the axis is moving. The floor of the curve. Corrected to 0 if negative.
`stictionFrictionForce`	N or N·m	20	at least `coulombFrictionForce`	Friction at rest — the force needed to break away. Corrected up to the Coulomb force if you set it lower.
`viscousFrictionDamping`	N·s/m or N·m·s/rad	1.0	0 upward in practice	Friction proportional to speed. Not checked — a negative value makes friction drive the axis.
`stribeckVelocity`	m/s or rad/s	0.01	1e-6 – 0.01	How quickly friction falls from stiction to Coulomb. Corrected silently if out of range.
`preSlidingDisplacement`	m or rad	0.002	1e-9 – 0.01	How far the axis deflects before it breaks away. Models 0 and 1 only. It also sets the zero-velocity dead band — see the blockquote.
`contactDamping`	N·s/m	0.0	0 upward	Bristle contact damping, model 0 only. Leave at 0 for feedforward — non-zero adds transient forces during velocity changes.
`coulombVelocity`	m/s or rad/s	0.001	1e-6 upward	How sharply model 2 rises through zero. Smaller is sharper and closer to model 1. Model 2 only.
`outputScalingFactorRate`	1/s	10.0	above 0	How fast `outputScalingFactor` may change. The default fades fully in 0.1 s on any task rate. Not checked — 0 freezes the scaling factor where it is.

`model`	What the machine does	Parameters that matter
0 `LUGRE_DYNAMIC`	Models the deflection before breakaway, so stick-slip and hysteresis at reversal are reproduced. Has internal state	`preSlidingDisplacement`, `contactDamping`, plus the shared curve
1 `STATIC_SIGN`	Classical Stribeck curve. Steps discontinuously across zero velocity — use it for steady-state analysis, not feedforward	The shared curve, `preSlidingDisplacement` for the dead band
2 `CONTINUOUS_TANH`	Smooth everywhere, including through zero. The right choice for friction feedforward	`coulombVelocity`, plus the shared curve

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

Setup

Set model to 2 if this is a feedforward path, which is the usual case. Set it explicitly — an unset model gives model 1.
Set enable false while you measure.
Measure Coulomb friction: move the axis at a steady moderate speed with the loop closed and no friction compensation, and read the force the feedback controller supplies. That is coulombFrictionForce.
Measure stiction: command a slowly rising force from rest and note the force at which the axis breaks away. That is stictionFrictionForce. It must be at least the Coulomb force, and the block will correct it upward if it is not.
Measure viscous damping: repeat step 3 at two or three speeds. The slope of force against speed is viscousFrictionDamping.
Leave stribeckVelocity at 0.01 and preSlidingDisplacement at 0.002 for a first pass. Both are refinements.
Set enable true and confirm isEnabled reads true. Check the sign: the output must oppose motion — positive force for positive velocity.

Step 7 adds real force to the actuator. If the sign is wrong the compensation adds to friction instead of cancelling it, and the axis will accelerate away. Have the axis clear.
Check the feedback controller’s own output has dropped at steady speed. That drop is what the compensation bought you.

Tuning

Measure, do not dial. Every parameter here is a physical property of your axis, and steps 3 to 5 of Setup measure them directly. Tuning by watching the error is how you end up over-compensating.
Get the Coulomb force right first — it dominates everywhere except near rest.
Then stiction. Too much and the axis lurches from rest; too little and it still sticks.
Then viscous damping, at the top of your speed range where it matters most.
Refine stribeckVelocity only if the transition from rest to moving feels wrong. Lower it to make friction drop off sooner.
With model 2, use coulombVelocity to set how sharply the force rises through zero. Smaller is sharper and cancels more friction near rest, but a very small value approaches model 1’s discontinuity and reintroduces chatter.
With model 0, preSlidingDisplacement is the real deflection before breakaway. Leave contactDamping at 0 for feedforward.
Check both directions of travel. Friction is rarely symmetric, and this block models it as symmetric — if the two differ a lot, this block will compensate the average.
Use outputScalingFactor to fade compensation in and out — for example to reduce it where the axis is well supported. Its rate limit is in units per second and holds its meaning across task rates. A single write is enough; the fade runs to completion on its own.

Read the stiction force off the peak near zero and the Coulomb force off the flat part beyond it.

Symptom	Cause	Action
The axis chatters or buzzes around zero velocity	Model 1’s discontinuity at zero	Set `model` to 2
The axis lurches from rest	`stictionFrictionForce` too high	Re-measure it with Setup step 4
The axis still sticks at rest	Stiction too low, or the dead band is swallowing the command	Raise `stictionFrictionForce`; if that does not help, lower `preSlidingDisplacement` to narrow the dead band
No friction force at all at very low speed	Expected: models 0 and 1 have a dead band below the velocity in the blockquote	Use model 2, which has no dead band
The axis accelerates away instead of moving smoothly	The sign is wrong, or friction is over-compensated	Check the sign first; then halve every force parameter
The axis runs faster the harder it is pushed, with no friction	`viscousFrictionDamping` is negative	Set it to zero or positive
Compensation is right at low speed and too strong at high speed	`viscousFrictionDamping` too high	Re-measure with Setup step 5
Compensation is right at high speed and too weak near rest	`stictionFrictionForce` too low, or `stribeckVelocity` too high	Raise stiction; lower the Stribeck velocity
`stictionFrictionForce` reads back higher than written	Expected: it is corrected up to the Coulomb force	Raise the Coulomb force, or accept the correction
`stribeckVelocity` or `preSlidingDisplacement` reads back different	Outside the accepted band	Work within the value you read back
The output faded to zero but `isEnabled` reads true	`outputScalingFactor` has been driven to 0	Read that path; inside a feedforward controller it is written from a position table
The output will not fade after writing `outputScalingFactor`	`outputScalingFactorRate` is 0	Set a positive rate
A scaling change arrived as a slow ramp	Expected: it is rate-limited	Raise `outputScalingFactorRate`
`outputScalingFactor` reads back exactly what was written while the force is still ramping	Expected: the path is the command, and the block does not write it	Watch `output` to see the fade; there is no signal carrying the applied factor
`outputScalingFactor` was written above 1 or below 0 and the force did not follow	Expected: the command is clamped to 0 – 1 on the way to the output, and the path keeps the raw value	Write a value inside the range so the path and the effect agree
The output ramps up over a moment after enabling, with model 0	Expected: the deflection starts from zero and loads up	Use model 1 or 2 if that transient matters
The block behaves like model 1 when you configured model 2	`model` was left unset, so it resolved to 1	Write `model` = 2 explicitly and check the log for a deprecation warning
A warning about `useStaticFriction` at startup	An old configuration file still sets the retired parameter	Set `model` directly and remove it
Friction differs between directions and the block cannot match both	The model is symmetric by construction	Compensate the average, or handle the asymmetry upstream
Every channel gets the same friction	Expected: all parameters are shared across channels	Use one instance per axis
The output went non-numeric	A non-numeric velocity reached `input`	Fix the source, then disable and re-enable to clear the state

A starting point for feedforward on a rotary axis on a 1 ms task, with measured values substituted at steps 3 to 5 of Setup:

model                   = 2
enable                  = true
coulombFrictionForce    = 10.0
stictionFrictionForce   = 20.0
viscousFrictionDamping  = 1.0
stribeckVelocity        = 0.01
coulombVelocity         = 0.001
preSlidingDisplacement  = 0.002
contactDamping          = 0.0
outputScalingFactorRate = 10.0

Limits and errors

Limit	Set by	What happens	Reported
`stictionFrictionForce` ≥ `coulombFrictionForce`	Fixed	Stiction is raised to match the Coulomb force. This is what keeps model 2’s curve the right way up	Silently; read the value back
`coulombFrictionForce` ≥ 0	Fixed	A negative value is replaced by 0	Silently; read the value back
`stribeckVelocity` within 1e-6 – 0.01	Fixed	Replaced by the nearest edge	Silently; read the value back
`preSlidingDisplacement` within 1e-9 – 0.01	Fixed	Replaced by the nearest edge. The bound is the same for a linear or rotary axis	Silently; read the value back
`contactDamping` ≥ 0, `coulombVelocity` ≥ 1e-6	Fixed	Replaced by the nearest edge	Silently; read the value back
`viscousFrictionDamping`	Nothing	Not checked. A negative value makes friction drive the axis instead of resisting it	Not reported
`outputScalingFactorRate`	Nothing	Not checked. 0 freezes the scaling factor at its present value — including at 0, which silences the output while `isEnabled` still reads true. A negative value is unsafe	Not reported
`outputScalingFactor` within 0 – 1	Fixed	The command is clamped, then approached at `outputScalingFactorRate`. The input path itself is never modified	Not reported, and the applied factor is not published; read the fade off `output`
`output`	Nothing	Unbounded — whatever the model computes. Bound it in the actuator’s own limiter	Not reported
Model state	`disable`, or `enable` false	A disabled cycle clears the internal state completely	Not reported
Channels	Shared	Every channel uses the same parameters. One instance cannot model two different axes	Not reported

Verified against motorcortex-control3 3.32.1 (340db23).

Docs: BacklashCompensation

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

Control3 3.30–3.34

BacklashCompensation produces a position offset that follows the direction of travel, to take up the lost motion in a gearbox. When an axis reverses, the motor must cross the backlash gap before the load moves; this block adds the offset in the direction the axis is going, so the position loop pre-loads the correct flank of the gear.

The offset slews between its two values rather than stepping, so a reversal does not put a position discontinuity into the loop.

flowchart LR
    i1(["input — velocity, or any signed direction signal"]) --> B["BacklashCompensation"]
    i2(["disable"]) --> B
    B --> o1(["output — the position offset"])
    B --> o2(["isEnabled"])

The offset is +positionCorrection while the input is positive and -positionCorrection while it is negative. At standstill it holds the last direction, because the flank in contact does not change until the axis moves the other way. The transition takes at least $2 \times$ positionCorrection $/$ rateLimit seconds, and settles with a time constant of $1/$omega — 3.2 ms at the default.

Three parameters must be set before this block does anything. enable defaults to false, positionCorrection to 0 and rateLimit to 0, which freezes the output. All three are needed.

To switch compensation off, disable the block — do not zero positionCorrection. A zero correction freezes the offset where it is rather than removing it. See Limits and errors.

Signals

Inputs

Path	Unit	Range	Description
`input`	m/s or rad/s	unbounded	The direction signal. Inside an actuator loop this is the velocity target. Only its sign matters, after the dead zone. One element per channel.
`disable`	-	-	True forces every output to zero immediately, without slewing. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`output`	m or rad	The position offset, one element per channel. It starts at zero after a controller start, and is not cleared by a stop — so it holds a stale offset until the block runs again. Zero while disabled.
`isEnabled`	-	True when `enable` is true and `disable` is false. It does not mean the block is producing an offset — a zero `positionCorrection` or `rateLimit` leaves it inert.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	false	-	False forces every output to zero.
`positionCorrection`	m or rad	0.0	per channel	The offset magnitude — normally half the measured backlash. A zero value makes the block skip that channel entirely, freezing its output rather than clearing it. Not checked, so a large value is a large position shift.
`rateLimit`	m/s or rad/s	0.0	above 0, per channel	How fast the offset may slew. Zero freezes the output, which is the default. Set it before anything else.
`deadzone`	m/s or rad/s	0.0	0 upward, per channel	Input magnitudes below this count as standstill, so the offset holds. Raise it above the noise on your velocity signal.
`omega`	rad/s	314	above 0, below 2/task period [s]	How sharply the offset settles once it is within the rate limit. Shared by all channels, unlike the three above. Not checked.
`returnToZero`	-	false	-	False holds the last direction’s offset at standstill, which is physically correct. True returns the offset to zero at standstill.

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

Setup

Measure the backlash: drive the axis one way until the load moves, reverse slowly, and record how far the motor turns before the load moves again. That distance is the gap.
Set positionCorrection to half the gap, in motor units, for each channel.
Set rateLimit to a slew rate the loop can absorb. Divide twice the correction by the time you are willing to spend crossing it — 0.1 s is a reasonable starting point.

Step 3 is mandatory, not optional. rateLimit defaults to 0 and a zero slew rate freezes the output. Without it the block is silently inert, and isEnabled will still read true.
Set deadzone above the noise on your velocity signal, so the offset does not chatter between its two values at standstill.
Leave returnToZero false. Holding the last direction is correct: the gear flank in contact does not change until the axis moves the other way.
Set enable true. Drive the axis one way and confirm output slews to +positionCorrection, then reverse and confirm it slews to the negative value.
Watch the position loop’s error through a reversal, with and without the block. The error at reversal should be smaller with it.

Tuning

Get the magnitude from the measurement in Setup step 1, not by feel. Too much offset is as bad as none — it pre-loads the wrong flank.
Tune rateLimit against the position loop. Too fast and the offset itself is a disturbance the loop must reject; too slow and the compensation arrives after the reversal is over.
Time the reversal: twice the correction divided by the rate limit. Compare that against how long your axis actually spends reversing.
Raise deadzone until the offset stops chattering at standstill, and no further. A large dead zone delays the compensation at low speed, where backlash matters most.
Leave omega alone unless the settle at the end of the slew is visibly slow. It only shapes the last part of the transition. Keep it below 2 divided by the task period.
Re-check omega after a task-rate change — its safe ceiling scales with the task period.
If the axis has different backlash in each direction, this block cannot represent it: it applies the same magnitude both ways. Compensate the average.

Read the crossing time off any curve as the span between the two flat levels.

Symptom	Cause	Action
`output` stays at zero with `isEnabled` true	`rateLimit` is 0, or `positionCorrection` is 0	Set both; `rateLimit` defaults to 0 and freezes the output
`output` froze at a value and will not change	`positionCorrection` was set back to 0, which skips the channel instead of clearing it	Disable the block to clear the offset
The offset did not return to zero when compensation was switched off	Same cause	Use `enable` false, not `positionCorrection` = 0
The offset chatters between its two values at standstill	`deadzone` below the noise on the velocity signal	Raise `deadzone`
The offset swings at standstill even with a dead zone set	`returnToZero` is true	Set it false — holding the last direction is correct
The position jumped when the block was disabled	Expected: disabling steps the output to zero without slewing	Disable only at standstill, or accept the step
The position jumped after a controller restart	Expected: the offset is not cleared by a stop and holds a stale value	Disable and re-enable once at start
The position loop fights the offset	`rateLimit` too high, so the offset itself is a disturbance	Lower `rateLimit`
Compensation arrives too late at reversal	`rateLimit` too low, or `deadzone` too large	Raise the rate limit; lower the dead zone
The error at reversal got worse, not better	Too much correction, so the wrong flank is pre-loaded	Halve `positionCorrection` and re-measure the backlash
The offset oscillates or grows during the transition	`omega` at or above 2 divided by the task period	Lower `omega`
One channel adopted another channel’s direction	A stationary channel can pick up a moving channel’s offset sign when `returnToZero` is false	Use one instance per channel, or set `returnToZero` true
Backlash differs by direction and the block cannot match it	The magnitude is the same both ways by construction	Compensate the average
A non-numeric value appeared on `output`	A non-numeric velocity reached `input`	Disable the block for a cycle to clear it, then fix the source

A starting point for an axis with 1 mm of measured backlash on a 1 ms task, crossing in about 0.1 s:

enable             = true
positionCorrection = 0.0005
rateLimit          = 0.01
deadzone           = 0.001
omega              = 314.0
returnToZero       = false

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

Limits and errors

Limit	Set by	What happens	Reported
`rateLimit` above 0	Nothing	Not checked, and it defaults to 0. A zero slew rate freezes the output permanently while `isEnabled` still reads true	Not reported
`positionCorrection` non-zero	Nothing	A zero value makes the block skip that channel, so its output holds its last value instead of returning to zero	Not reported
`positionCorrection` magnitude	Nothing	Not checked. The offset shifts both the measured position and the position target, so a large value is a large shift	Not reported
`omega` below 2/task period [s]	Nothing	Not checked. At or above the bound the transition oscillates or grows instead of settling. 2000 on a 1 ms task	Not reported
`output`	Nothing	Bounded in practice by `positionCorrection`, but nothing enforces that	Not reported
Disabling	Fixed	Steps the output to zero without slewing, unlike a direction reversal	Not reported
Offset across a stop	Nothing	Not cleared at start. There is no reset input — disabling is the only way to clear it	Not reported
Non-numeric input	Nothing	Not guarded. A disabled cycle clears the result	Not reported
Channel independence	Partial	The held direction at standstill is shared between channels, so on a multi-channel instance a stationary channel can adopt a moving one’s sign. Use one instance per channel where this matters	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: Gearbox

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

Control3 3.30–3.34

Gearbox applies a transmission ratio in both directions, and applies it the right way round for each kind of signal: speeds and positions scale by the ratio, torques and forces scale by its reciprocal. That is what a real gearbox does, and getting it wrong by hand is the usual way a drivetrain conversion goes astray.

flowchart LR
    i1(["inputLoadSide"]) --> B["Gearbox"]
    i2(["inputMotorSide"]) --> B
    p1(["nLoadSide"]) --> B
    p2(["nMotorSide"]) --> B
    B --> o1(["outputMotorSide"])
    B --> o2(["outputLoadSide"])
    B --> o3(["gain"])

Which channels are which is fixed when the controller is built, by position: the first group is kinematic (position, velocity), the rest are mechanic (torque, force). The split is not visible in the tree — you cannot read it back, so check with whoever configured the machine.

By default every channel is kinematic. The mechanic count defaults to zero, so unless it was set at build time nothing gets the reciprocal.

A tooth count of 0 is refused, safely. Write one and the block keeps the previous value rather than dividing by zero. It does not tell you it did.

Your instance may present its channels by name instead of as arrays, at LoadToMotor/<name>/input and MotorToLoad/<name>/output. Both forms behave identically; only the paths differ.

Signals

Inputs

Path	Unit	Range	Description
`inputLoadSide`	load-side unit	unbounded	Values on the load side, converted to the motor side. One per channel.
`inputMotorSide`	motor-side unit	unbounded	Values on the motor side, converted to the load side.

On a named instance these appear as LoadToMotor/<name>/input and MotorToLoad/<name>/input.

Outputs

Path	Unit	Description
`outputMotorSide`	motor-side unit	`inputLoadSide` converted. Kinematic channels are multiplied by `gain`, mechanic channels divided by it.
`outputLoadSide`	load-side unit	`inputMotorSide` converted, the other way round.
`gain`	-	`nLoadSide ÷ nMotorSide`, recomputed every cycle. Read this to confirm the ratio you configured.

Parameters

Path	Unit	Default	Range	Effect
`nLoadSide`	teeth	1	non-zero	The tooth count on the load side. Need not be a whole number — write the ratio directly if you prefer, with `nMotorSide` at 1. A 0 is refused and the previous value kept.
`nMotorSide`	teeth	1	non-zero	The tooth count on the motor side. Same treatment.

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

A reduction of 10 to 1 — the motor turning ten times per output turn — is nLoadSide = 1, nMotorSide = 10, giving a gain of 0.1. A load-side speed of 1 then becomes a motor-side speed of 0.1… which is backwards for a reduction, so check gain against a known speed before trusting the sense.

Setup

Establish which of your channels are kinematic and which are mechanic. This was fixed when the controller was built and cannot be read back.
Set nLoadSide and nMotorSide from the drivetrain.
Read gain back and confirm it is the ratio you expect.
Put a known value on inputLoadSide for a kinematic channel and confirm outputMotorSide is that value times gain.
Do the same for a mechanic channel and confirm it is divided instead. If it is multiplied, that channel is on the wrong side of the split and the controller needs rebuilding.
Send a value through both directions and confirm it returns unchanged.

Tuning

There is nothing dynamic to tune. Both parameters take effect on the next cycle.
Get the two tooth counts from the drivetrain drawing, not from a measured ratio — the exact integers avoid rounding in long-running position integrations.
Verify the direction of the ratio with a slow move before running anything fast. A ratio inverted by mistake is a factor of gain squared out.
Verify the kinematic and mechanic split by checking a torque channel explicitly. This is the one thing this block does that a plain gain does not, and the one thing you cannot see in the tree.
Confirm the round trip. Load to motor and back should return the input exactly.
Nothing here depends on the task rate.

The two curves crossing at 1 is the whole point: at a ratio of one a gearbox does nothing to either kind of signal.

Symptom	Cause	Action
A torque channel scaled the same way as a speed channel	That channel is on the kinematic side of the split	The split is fixed at build time — the controller needs rebuilding
Everything scaled the same way	The mechanic channel count is 0, which is the default	Same
The conversion is inverted	The two tooth counts are the wrong way round	Read `gain` back and check it against a known speed
A tooth count I wrote did not take	It was 0, which is refused	Write a non-zero value
A tooth count of 0 gave no warning	Expected: the block keeps the previous value silently	Read it back
Everything became invalid	A tooth count that is not a valid number passes the zero check and poisons `gain`	Rewrite both counts
Every channel inverted	A tooth count is negative, which is accepted	Check both signs
The round trip does not return the input	Something changed the ratio between the two directions	Check nothing else writes the tooth counts
I cannot tell which channels are kinematic	The split is not published	Ask whoever configured the machine
The channel paths are names, not arrays	Your instance was built with named channels	Both forms behave identically
Two named channels move together	Two channels were given the same name at build time, which silently merges them	The controller needs rebuilding
I need to switch it off	Not possible — there is no enable	Set both tooth counts equal
I need a non-linear transmission	Wrong block	Use `Lookup`

A starting point for a 10:1 reduction:

nLoadSide  = 1
nMotorSide = 10

Then read gain back and confirm it is 0.1.

Limits and errors

Limit	Set by	What happens	Reported
Ratio	`nLoadSide`, `nMotorSide`	`gain = nLoadSide ÷ nMotorSide`, recomputed every cycle	`gain`
Kinematic channels	Fixed at build time	Multiplied by `gain` going to the motor side, divided coming back	Not reported
Mechanic channels	Fixed at build time	Divided by `gain` going to the motor side, multiplied coming back	Not reported
The kinematic/mechanic split	Fixed at build time	Not published. Cannot be read or changed from the tree	Not reported
A tooth count of 0	Checked	Refused — the previous value is kept, so the block can never divide by zero	Not reported
A negative tooth count	Nothing	Accepted. Inverts every channel	`gain` reads negative
Values that are not numbers	Nothing	Not checked. They pass the zero test and poison every channel	Not reported
Round trip	Fixed	The two directions are exact inverses	Not reported
Channel order	Fixed at build time	The split is by position, so inserting a channel changes which side its neighbours fall on	Not reported
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 during operation. It may log at startup if the tooth counts are zero. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Transformation

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

Control3 Superseded. The current release is 3.34.

Transformation is the conversion stage between an actuator’s engineering units and a drive’s raw units. It converts setpoints going out, converts and conditions measurements coming back, and holds the gear ratio that relates the two sides.

It contains a transducer, and on the measurement side a linearisation table, an IIR filter and a low-pass filter.

flowchart LR
    i1(["inputSoftwareSide"]) --> B["Transformation"]
    i2(["inputHardwareSide"]) --> B
    p1(["gearRatio"]) --> B
    p2(["referenceLoadSide"]) --> B
    B --> o1(["outputSoftwareSide"])
    B --> o2(["outputHardwareSide"])
    B --> s1(["transducer"])
    B --> s2(["actualLP1Filter"])
    B --> s3(["actualFilter, actualLinearizeLookup"])

Almost everything you configure is in the sub-trees. The sensor resolution and referencing are under transducer; the measurement filtering is under actualLP1Filter and actualFilter; the linearisation table is under actualLinearizeLookup. This block itself has only two parameters.

The filtered measurement and its velocity are not published. The block computes both and passes them to its parent in software, but neither appears in the tree — so you can see outputSoftwareSide before the low-pass, and you cannot see the result after it.

gearRatio of 0 is not refused and produces an invalid measurement path. Never write 0 to it.

Not every instance has every sub-tree. A block configured for one direction only gets the linearisation table and the IIR filter; a block that converts both ways does not. If actualLinearizeLookup is missing from your tree, that is why.

Signals

Inputs

Path	Unit	Range	Description
`inputSoftwareSide`	actuator unit	unbounded	The setpoint to send to the drive. Multiplied by `gearRatio`, then converted to raw units.
`inputHardwareSide`	ticks	unbounded	The raw sensor reading. Converted to actuator units, then divided by `gearRatio`.

Outputs

Path	Unit	Description
`outputSoftwareSide`	actuator unit	Where the machine is, in actuator units. On a both-ways instance this is unfiltered; on a measurement-only instance it has been through the linearisation table and the IIR filter. Either way it has not been through the low-pass.
`outputHardwareSide`	ticks	The setpoint for the drive.

Parameters

Path	Unit	Default	Range	Effect
`gearRatio`	ticks-side unit per actuator unit	see below	non-zero	Multiplies the outgoing setpoint and divides the incoming measurement. A 0 is not refused and makes the measurement path invalid.
`referenceLoadSide`	actuator unit	0.0	unbounded	The position used when referencing. This is in actuator units, while the transducer’s own reference parameters below are in motor-side units — do not confuse the two.

Both are persistent and survive a controller restart.

The parameters that matter most are in the sub-trees:

Path	Effect
`transducer/ticksPerRevolution`, `…/gainNum`, `…/gainDen`	The sensor conversion. See the `Transducer` page.
`transducer/offset`, `transducer/referencing/…`	Referencing.
`actualLP1Filter/omega`	The measurement low-pass cut-off, in radians per second.
`actualFilter/…`	The IIR filter’s numerator and denominator — used as a notch, typically. Measurement-only instances.
`actualLinearizeLookup/x`, `…/y`, `…/numPoints`	The sensor linearisation table, six points. Measurement-only instances.

Setup

Set up the transducer first — transducer/ticksPerRevolution and the two gain factors. Verify it on its own before touching this block.
Set gearRatio from the drivetrain between the sensor and the actuator’s output. Never write 0.
Move the machine a known distance by hand and confirm outputSoftwareSide changes by that amount in actuator units. This checks the transducer and the gear ratio together.
Set actualLP1Filter/omega — go to Tuning.
If your instance has one, set the linearisation table under actualLinearizeLookup from measurements of the sensor’s error.
If your instance has one, set the IIR filter under actualFilter to notch out any structural frequency you need removed. Leave it as a pass-through until you know you need it.
Set referenceLoadSide and reference the machine, remembering this value is in actuator units.

Tuning

Get the conversion exactly right before any filtering. A gain error looks like a scaling problem at every speed; a filter problem only appears when things move.
Verify the conversion over a long move, not a short one.
Set actualLP1Filter/omega from the noise on your measurement and the bandwidth your control loop needs. Lower removes more noise and adds more lag.
You cannot see the low-pass’s output in the tree, so judge it by its effect on the loop rather than by watching the signal: too low a cut-off shows as sluggish or oscillatory position control.
Use the IIR filter for a specific structural frequency, not for general smoothing — that is the low-pass’s job. Design it as a discrete-time filter and enter the coefficients directly.
Set the linearisation table only after the gain and offset are right. It corrects the shape of the sensor’s error, not its scale.
Re-check everything after a task-rate change: the low-pass cut-off is in radians per second and does not move, but the IIR coefficients are discrete-time and do depend on the rate.

The block corrects the low-pass’s lag by one sample before handing the result on, which is why the measurement the controller sees is less delayed than the filter alone would give.

Symptom	Cause	Action
The measurement is invalid	`gearRatio` is 0, which is not refused	Set a non-zero ratio
The measurement is proportionally wrong	The gear ratio or the transducer conversion	Check the transducer alone first, then the ratio
The machine moves the wrong way	A sign error in the gear ratio or the transducer gain	Use a negative value on one of them, not both
The setpoint and the measurement disagree by a constant	The transducer offset, or referencing has not been done	Reference the machine
I cannot see the filtered measurement	It is not published	Judge the filter by its effect on the control loop
`actualLinearizeLookup` is missing from my tree	Your instance converts both ways, and only measurement-only instances have it	Nothing — it is fixed when the controller is built
`actualFilter` is missing	Same reason	Nothing
The measurement is noisy	`actualLP1Filter/omega` is too high	Lower it, and accept more lag
Position control became sluggish or unstable	`actualLP1Filter/omega` is too low for the loop	Raise it
The IIR filter did nothing after a task-rate change	Its coefficients are discrete-time and depend on the rate	Recalculate and re-enter them
Referencing put the machine in the wrong place	`referenceLoadSide` is in actuator units, unlike the transducer’s own reference	Check which one you set
The drive stopped responding after referencing	The transducer holds its output until the positions agree	See the `Transducer` page
I need to bypass the conversion	Not possible — there is no enable, and the two sides are in different units	Set `gearRatio` to 1 and check the transducer

A starting point for a direct-driven axis:

gearRatio               = 1.0
referenceLoadSide       = 0.0
actualLP1Filter/omega   = 200.0
transducer/…            = <see the Transducer page>

Limits and errors

Limit	Set by	What happens	Reported
Conversion	`gearRatio` and the transducer	The setpoint is multiplied by the ratio, the measurement divided by it	`outputSoftwareSide`, `outputHardwareSide`
`gearRatio` of 0	Not checked	The measurement path becomes invalid	Not reported
Values that are not numbers	Nothing	Not checked at this level. The sub-modules behave differently: the lookup freezes, the filters propagate	Not reported
Measurement filtering	The three sub-trees	Linearisation, then the IIR filter, then the low-pass — but only a measurement-only instance has the first two	Not reported
Filtered outputs	Fixed	Computed and not published. The filtered measurement and its velocity go to the parent in software only	Not applicable
Filter lag	Fixed	The block advances the filtered signal by one sample using the filter’s own derivative, recovering most of the low-pass’s delay	Not reported
`referenceLoadSide` units	Fixed	Actuator units, unlike the transducer’s own reference parameters	Not reported
Sub-modules present	Fixed at build time	Depends on which directions the instance converts	Not reported
Enable	None	There is no enable, disable or isEnabled, despite what older documentation said	Not applicable
Channel count	Fixed	One axis per instance, always	Not reported

This block logs nothing itself. The transducer below it logs during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Transformation

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

Control3 Current release

It contains a transducer, and on the measurement side a linearisation table, an IIR filter and a low-pass filter, applied in that order.

flowchart LR
    i1(["inputSoftwareSide"]) --> B["Transformation"]
    i2(["inputHardwareSide"]) --> B
    p1(["gearRatio"]) --> B
    p2(["referenceLoadSide"]) --> B
    B --> o1(["outputSoftwareSide"])
    B --> o2(["outputHardwareSide"])
    B --> s1(["transducer"])
    B --> s2(["actualFilter, actualLP1Filter"])
    B --> s3(["actualLinearizeLookup"])

Almost everything you configure is in the sub-trees. The sensor resolution and referencing are under transducer; the measurement filtering is under actualLP1Filter and actualFilter; the linearisation table is under actualLinearizeLookup. This block itself has only two parameters.

The filtered measurement and its velocity are not published. The block computes both and passes them to its parent in software, but neither appears in the tree — so you can see outputSoftwareSide before the low-pass, and you cannot see the result after it.

gearRatio of 0 is not refused and produces an invalid measurement path. Never write 0 to it.

Not every instance has every sub-tree. The linearisation table is created only for a block that converts one way, towards software; a block that converts both ways does not have it. If actualLinearizeLookup is missing from your tree, that is why. actualFilter and actualLP1Filter are present on every block that has a measurement side at all, whichever direction it converts.

The measurement chain

The measurement side runs in a fixed order:

inputHardwareSide → transducer → actualLinearizeLookup → actualFilter → actualLP1Filter
                                 (one-way blocks only)     (IIR)         (low-pass)

outputSoftwareSide is published after actualFilter and before actualLP1Filter, so the leaf you can trace shows the IIR’s effect but not the low-pass’s.

actualFilter is a full IIR of up to order 6 — two notches plus a low-pass — and it is the right place for a structural resonance or a mains-frequency pickup, because it acts on the measurement before actualLP1Filter derives a velocity from it. It is pass-through by default (order 1, num[0] = den[0] = 1), so an unconfigured block conditions nothing here.

A switched-off actualFilter is a bypass, not a mute. On its own an IIRFilter outputs zero when it is disabled, when order is 0, or when den[0] is 0 — and a measured position that reads zero is far worse than an unfiltered one. This block therefore guards it: whenever the filter is not actually filtering, the unfiltered measurement is passed to the low-pass instead. You can disable actualFilter safely.

Signals

Inputs

Path	Unit	Range	Description
`inputSoftwareSide`	actuator unit	unbounded	The setpoint to send to the drive. Multiplied by `gearRatio`, then converted to raw units.
`inputHardwareSide`	ticks	unbounded	The raw sensor reading. Converted to actuator units, then divided by `gearRatio`.

Outputs

Path	Unit	Description
`outputSoftwareSide`	actuator unit	Where the machine is, in actuator units. On a both-ways instance this is unfiltered; on a measurement-only instance it has been through the linearisation table and the IIR filter. Either way it has not been through the low-pass.
`outputHardwareSide`	ticks	The setpoint for the drive.

Parameters

Path	Unit	Default	Range	Effect
`gearRatio`	ticks-side unit per actuator unit	see below	non-zero	Multiplies the outgoing setpoint and divides the incoming measurement. A 0 is not refused and makes the measurement path invalid.
`referenceLoadSide`	actuator unit	0.0	unbounded	The position used when referencing. This is in actuator units, while the transducer’s own reference parameters below are in motor-side units — do not confuse the two.

Both are persistent and survive a controller restart.

The parameters that matter most are in the sub-trees:

Path	Effect
`transducer/ticksPerRevolution`, `…/gainNum`, `…/gainDen`	The sensor conversion. See the `Transducer` page.
`transducer/offset`, `transducer/referencing/…`	Referencing.
`actualLP1Filter/omega`	The measurement low-pass cut-off, in radians per second.
`actualFilter/…`	The IIR filter’s numerator and denominator — used as a notch, typically. Measurement-only instances.
`actualLinearizeLookup/x`, `…/y`, `…/numPoints`	The sensor linearisation table, six points. Measurement-only instances.

Setup

Set up the transducer first — transducer/ticksPerRevolution and the two gain factors. Verify it on its own before touching this block.
Set gearRatio from the drivetrain between the sensor and the actuator’s output. Never write 0.
Move the machine a known distance by hand and confirm outputSoftwareSide changes by that amount in actuator units. This checks the transducer and the gear ratio together.
Set actualLP1Filter/omega — go to Tuning.
If your instance has one, set the linearisation table under actualLinearizeLookup from measurements of the sensor’s error.
If your instance has one, set the IIR filter under actualFilter to notch out any structural frequency you need removed. Leave it as a pass-through until you know you need it.
Set referenceLoadSide and reference the machine, remembering this value is in actuator units.

Tuning

Get the conversion exactly right before any filtering. A gain error looks like a scaling problem at every speed; a filter problem only appears when things move.
Verify the conversion over a long move, not a short one.
Set actualLP1Filter/omega from the noise on your measurement and the bandwidth your control loop needs. Lower removes more noise and adds more lag.
You cannot see the low-pass’s output in the tree, so judge it by its effect on the loop rather than by watching the signal: too low a cut-off shows as sluggish or oscillatory position control.
Use the IIR filter for a specific structural frequency, not for general smoothing — that is the low-pass’s job. Design it as a discrete-time filter and enter the coefficients directly.
Set the linearisation table only after the gain and offset are right. It corrects the shape of the sensor’s error, not its scale.
Re-check everything after a task-rate change: the low-pass cut-off is in radians per second and does not move, but the IIR coefficients are discrete-time and do depend on the rate.

The block corrects the low-pass’s lag by one sample before handing the result on, which is why the measurement the controller sees is less delayed than the filter alone would give.

Symptom	Cause	Action
The measurement is invalid	`gearRatio` is 0, which is not refused	Set a non-zero ratio
The measurement is proportionally wrong	The gear ratio or the transducer conversion	Check the transducer alone first, then the ratio
The machine moves the wrong way	A sign error in the gear ratio or the transducer gain	Use a negative value on one of them, not both
The setpoint and the measurement disagree by a constant	The transducer offset, or referencing has not been done	Reference the machine
I cannot see the filtered measurement	It is not published	Judge the filter by its effect on the control loop
`actualLinearizeLookup` is missing from my tree	Your instance converts both ways, and only measurement-only instances have it	Nothing — it is fixed when the controller is built
`actualFilter` is missing	Same reason	Nothing
The measurement is noisy	`actualLP1Filter/omega` is too high	Lower it, and accept more lag
Position control became sluggish or unstable	`actualLP1Filter/omega` is too low for the loop	Raise it
The IIR filter did nothing after a task-rate change	Its coefficients are discrete-time and depend on the rate	Recalculate and re-enter them
Referencing put the machine in the wrong place	`referenceLoadSide` is in actuator units, unlike the transducer’s own reference	Check which one you set
The drive stopped responding after referencing	The transducer holds its output until the positions agree	See the `Transducer` page
I need to bypass the conversion	Not possible — there is no enable, and the two sides are in different units	Set `gearRatio` to 1 and check the transducer

A starting point for a direct-driven axis:

gearRatio               = 1.0
referenceLoadSide       = 0.0
actualLP1Filter/omega   = 200.0
transducer/…            = <see the Transducer page>

Limits and errors

Limit	Set by	What happens	Reported
Conversion	`gearRatio` and the transducer	The setpoint is multiplied by the ratio, the measurement divided by it	`outputSoftwareSide`, `outputHardwareSide`
`gearRatio` of 0	Not checked	The measurement path becomes invalid	Not reported
Values that are not numbers	Nothing	Not checked at this level. The sub-modules behave differently: the lookup freezes, the filters propagate	Not reported
Measurement filtering	The three sub-trees	Linearisation, then the IIR filter, then the low-pass — but only a measurement-only instance has the linearisation table	Not reported
`actualFilter` switched off	Guarded by this block	The unfiltered measurement is passed to the low-pass. A bare `IIRFilter` would output 0 here	The filter’s own `isEnabled`
Filtered outputs	Fixed	Computed and not published. The filtered measurement and its velocity go to the parent in software only	Not applicable
Filter lag	Fixed	The block advances the filtered signal by one sample using the filter’s own derivative, recovering most of the low-pass’s delay	Not reported
`referenceLoadSide` units	Fixed	Actuator units, unlike the transducer’s own reference parameters	Not reported
Sub-modules present	Fixed at build time	Depends on which directions the instance converts	Not reported
Enable	None	There is no enable, disable or isEnabled, despite what older documentation said	Not applicable
Channel count	Fixed	One axis per instance, always	Not reported

This block logs nothing itself. The transducer below it logs during referencing. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Transducer

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

Control3 Superseded. The current release is 3.34.

Transducer converts between a sensor’s raw units — encoder ticks, resolver counts, an analogue reading — and engineering units, in both directions. It also handles referencing: telling the machine that a particular raw reading corresponds to a particular real position.

For an incremental sensor it can additionally store that position to disk, so the machine knows where it is after a power cycle.

flowchart LR
    i1(["inputSoftwareSide"]) --> B["Transducer"]
    i2(["inputHardwareSide"]) --> B
    i3(["persistenceEvent"]) --> B
    i4(["disablePersistence"]) --> B
    i5(["referencing/softwareReferenceExternal"]) --> B
    p1(["gainNum, gainDen, ticksPerRevolution, offset"]) --> B
    p2(["referencing/softwareReferenceInternal, useSoftwareReferenceExternal"]) --> B
    p3(["enablePersistence, deltaTicksMax, numberOfPolePairs, enableSingleTurnCounter"]) --> B
    B --> o1(["outputSoftwareSide"])
    B --> o2(["outputHardwareSide"])
    B --> o3(["gain"])
    B --> o4(["referencing/hardwareSnapshot"])
    B --> o5(["atStoredTicks, deltaTicks, singleTurnCounter"])
    B --> o6(["isPersistenceEnabled"])

After referencing, the output to the drive is deliberately frozen until the commanded and measured positions have agreed closely for a moment. This stops the drive being stepped by the whole size of the correction. If the two never agree, the output stays frozen indefinitely with nothing reported — so if a drive stops responding right after referencing, this is where to look.

ticksPerRevolution of 0 breaks the conversion. The other two gain factors refuse a zero and keep their previous value; this one does not. Never write 0 to it.

Persistence is switched off at every startup, whatever enablePersistence says. Your application must re-enable it after each start.

Some of the parameters below only exist on an encoder-type instance. The type is fixed when the controller is built.

Signals

Inputs

Path	Unit	Range	Description
`inputSoftwareSide`	engineering unit	unbounded	The setpoint to convert to raw units.
`inputHardwareSide`	ticks	unbounded	The sensor reading to convert to engineering units.
`persistenceEvent`	-	enumeration	Commands a store or load of the position file. Encoder instances only.
`disablePersistence`	-	true or false	Suspends the file handling. Forced true at every startup.
`referencing/softwareReferenceExternal`	engineering unit	unbounded	The value the captured raw reading should correspond to, when `useSoftwareReferenceExternal` is true.

Outputs

Path	Unit	Description
`outputSoftwareSide`	engineering unit	The converted sensor reading — where the machine thinks it is.
`outputHardwareSide`	ticks	The converted setpoint, for the drive. Held after referencing until the interlock clears.
`gain`	ticks per engineering unit	The combined conversion factor. Read this back to check your three factors multiply to what you expect.
`referencing/hardwareSnapshot`	ticks	The raw reading captured for referencing.
`atStoredTicks`	-	The position from the file matches the sensor. Reads true whenever persistence is off, so read `isPersistenceEnabled` alongside it.
`deltaTicks`	ticks	How far the sensor is from the stored position.
`singleTurnCounter`	revolutions	Whole turns counted, for a sensor that only reports position within one turn.
`isPersistenceEnabled`	-	The file handling is active.

Parameters

Path	Unit	Default	Range	Effect
`gainNum`	-	1	non-zero	Numerator of the conversion. A 0 is refused and the previous value kept.
`gainDen`	-	1	above 0	Denominator. A value of 0 or below is refused and the previous value kept.
`ticksPerRevolution`	ticks	1	above 0	The sensor’s resolution. Multiplied into the gain. A negative value is used as its magnitude, but 0 is not refused and will break the conversion. Encoder instances only.
`offset`	ticks	0.0	unbounded	The raw reading that corresponds to zero engineering units. Referencing overwrites this — save your configuration afterwards, or a reload will undo it.
`referencing/softwareReferenceInternal`	engineering unit	0.0	unbounded	The value referencing aims at, when the external one is not selected.
`referencing/useSoftwareReferenceExternal`	-	true	-	Whether to use the external reference input instead of the internal parameter.
`enablePersistence`	-	false	-	Whether to store the position to a file. Only for a sensor that does not remember its own absolute position. Turn it off for an absolute encoder.
`deltaTicksMax`	ticks	-1	-1, or 0 upward	How far the sensor may differ from the stored position and still be trusted. The default of -1 means no check.
`numberOfPolePairs`	-	1	1 upward	For resolver-type sensors, how many electrical revolutions make one mechanical one.
`enableSingleTurnCounter`	-	false	-	Counts whole turns, for a sensor that reports only within one turn.

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

Setup

Establish your sensor’s resolution and set ticksPerRevolution. Never write 0.
Set gainNum and gainDen to express the rest of the conversion — a lead screw pitch, a pulley ratio, a unit change.
Read gain back. It should be gainNum ÷ gainDen × ticksPerRevolution, and it is the number of ticks per engineering unit. Check it against a hand calculation before going further.
Move the machine a known distance by hand and confirm outputSoftwareSide changes by that amount.
Decide whether you need persistence. An absolute encoder does not — leave enablePersistence false. A resolver or incremental encoder does.
Reference the machine: bring it to a known position, set the reference value, and trigger referencing from your application.
Confirm outputSoftwareSide now reads the true position.

After referencing, the drive output is frozen until the commanded and measured positions agree. Expect a short pause before the axis responds again, and investigate if it never does.
Save your configuration, or the referenced offset is lost on the next reload.

Tuning

There is nothing dynamic to tune. Get the conversion right and the rest follows.
Derive the three gain factors from the drivetrain rather than measuring them — exact integers avoid rounding in a long-running position count.
Verify over a long move, not a short one. A 1% gain error is invisible over a millimetre and obvious over a metre.
Check the direction. A sensor wired backwards shows as outputSoftwareSide moving the wrong way, and is fixed with a negative gainNum.
Reference at a repeatable physical feature — a hard stop, a switch — not at an arbitrary position.
If you use persistence, set deltaTicksMax to how far the machine could plausibly be moved while powered down. Leave it at -1 only if you accept the stored position unconditionally.
Re-check atStoredTicks after each start, together with isPersistenceEnabled — the first reads true whenever the second is false.

Referencing moves the line up or down. It never changes the slope.

Symptom	Cause	Action
The conversion is wildly wrong or invalid	`ticksPerRevolution` is 0, which is not refused	Set it to the sensor’s real resolution
A gain factor I wrote did not take	`gainNum` was 0, or `gainDen` was 0 or negative — both are refused	Read them back
The machine moves the wrong way	The gain’s sign is wrong	Use a negative `gainNum`
The distance is proportionally wrong	The three factors do not multiply to the right ratio	Check `gain` against a hand calculation
The drive stopped responding after referencing	Expected briefly: the output is held until the positions agree	If it never resumes, the positions are not converging — check the drive
The referenced position was lost after a restart	Referencing overwrites `offset`, and a configuration reload restores the saved value	Save the configuration after referencing
`atStoredTicks` reads true and I do not trust it	It reads true whenever persistence is off	Read `isPersistenceEnabled` too
Persistence is off even though I enabled it	It is forced off at every startup	Re-enable it from your application after each start
The stored position is accepted when it should not be	`deltaTicksMax` is -1, which means no check	Set a real window
The position jumps by a whole revolution	The single-turn counter is needed, or miscounted	Enable it and set `numberOfPolePairs`
Everything became invalid	A gain factor that is not a valid number passes the zero checks	Rewrite all three
Some parameters are missing from the tree	Your instance is not an encoder type	The type is fixed when the controller is built
I need a non-linear conversion	Wrong block	Put a `Lookup` after it

A starting point for a 4096-tick encoder on a direct-driven axis:

ticksPerRevolution = 4096
gainNum            = 1
gainDen            = 1
offset             = 0
enablePersistence  = false
deltaTicksMax      = -1

Then read gain back and confirm it is 4096.

Limits and errors

Limit	Set by	What happens	Reported
Conversion	`gainNum`, `gainDen`, `ticksPerRevolution`	Their product is the ticks per engineering unit, both directions	`gain`
`gainNum` of 0	Checked	Refused — the previous value is kept	Read it back
`gainDen` of 0 or below	Checked	Refused — the previous value is kept	Read it back
`ticksPerRevolution` of 0	Not checked	The gain becomes 0 and the conversion divides by zero	Not reported
Values that are not numbers	Nothing	Not checked. They pass the zero tests and poison both directions	Not reported
Referencing	The reference value and a captured raw snapshot	Solves for the `offset` that makes them correspond, and overwrites `offset`	`referencing/hardwareSnapshot`, `offset`
Output after referencing	Fixed	Held until the commanded and measured positions agree closely for a short, fixed period. No timeout, nothing reported if they never do	Not reported
Persistence at startup	Fixed	Always disabled, whatever the parameter says	`isPersistenceEnabled`
Stored position check	`deltaTicksMax`	Compares the sensor against the stored position. A default of -1 means no check	`atStoredTicks`, `deltaTicks`
`atStoredTicks`	Fixed	Reads true when persistence is off, so it means “nothing to distrust”, not “a check passed”	Read `isPersistenceEnabled` too
Persistence file errors	Partly	A zero or negative `ticksPerRevolution` skips the stored-position check, and is logged	Controller log
Instance type	Fixed at build time	A non-encoder instance has no persistence, no turn counter and no `ticksPerRevolution`	Not reported
Channel count	Fixed	One sensor per instance, always	Not reported

The block logs when a stored-position check is skipped for a bad ticksPerRevolution, and logs the loaded position at startup. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).

Docs: Transducer

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

Control3 Current release

For an incremental sensor it can additionally store that position to disk, so the machine knows where it is after a power cycle.

flowchart LR
    i1(["inputSoftwareSide"]) --> B["Transducer"]
    i2(["inputHardwareSide"]) --> B
    i3(["persistenceEvent"]) --> B
    i4(["disablePersistence"]) --> B
    i5(["referencing/softwareReferenceExternal"]) --> B
    p1(["gainNum, gainDen, ticksPerRevolution, offset"]) --> B
    p2(["referencing/softwareReferenceInternal, useSoftwareReferenceExternal"]) --> B
    p4(["referencing/reconnectToleranceHardwareSide"]) --> B
    p3(["enablePersistence, deltaTicksMax, numberOfPolePairs, enableSingleTurnCounter"]) --> B
    B --> o1(["outputSoftwareSide"])
    B --> o2(["outputHardwareSide"])
    B --> o3(["gain"])
    B --> o4(["referencing/hardwareSnapshot"])
    B --> o5(["atStoredTicks, deltaTicks, singleTurnCounter"])
    B --> o7(["referencing/isOpenLoop"])
    B --> o6(["isPersistenceEnabled"])

After referencing, the output to the drive is deliberately frozen until the software side has been re-based onto the new offset. Precisely: until recomputing the hardware output would land within referencing/reconnectToleranceHardwareSide of the frozen value, for more than 100 consecutive cycles. Because the test is against the frozen output rather than the measurement, reconnecting cannot step the drive by more than that tolerance, whatever the measurement did meanwhile.

It is a re-basing wait, not a timer, so it does not time out. If nothing re-bases the software side the output stays frozen indefinitely, with nothing reported — the safe outcome, but the axis stays held, and a further reference request is ignored while it is. If a drive stops responding right after referencing, this is where to look. referencing/:fromState.reset clears it.

Set referencing/reconnectToleranceHardwareSide for your hardware side. The default of 2 is sized for a hardware side carrying encoder ticks. On an instance whose hardware side carries metres or radians, 2 is enormous and would let a whole offset step through.

ticksPerRevolution of 0 breaks the conversion. The other two gain factors refuse a zero and keep their previous value; this one does not. Never write 0 to it.

Persistence is switched off at every startup, whatever enablePersistence says. Your application must re-enable it after each start.

Some of the parameters below only exist on an encoder-type instance. The type is fixed when the controller is built.

Signals

Inputs

Path	Unit	Range	Description
`inputSoftwareSide`	engineering unit	unbounded	The setpoint to convert to raw units.
`inputHardwareSide`	ticks	unbounded	The sensor reading to convert to engineering units.
`persistenceEvent`	-	enumeration	Commands a store or load of the position file. Encoder instances only.
`disablePersistence`	-	true or false	Suspends the file handling. Forced true at every startup.
`referencing/softwareReferenceExternal`	engineering unit	unbounded	The value the captured raw reading should correspond to, when `useSoftwareReferenceExternal` is true.

Outputs

Path	Unit	Description
`outputSoftwareSide`	engineering unit	The converted sensor reading — where the machine thinks it is.
`outputHardwareSide`	ticks	The converted setpoint, for the drive. Held after referencing until the interlock clears.
`gain`	ticks per engineering unit	The combined conversion factor. Read this back to check your three factors multiply to what you expect.
`referencing/hardwareSnapshot`	ticks	The raw reading captured for referencing.
`atStoredTicks`	-	The position from the file matches the sensor. Reads true whenever persistence is off, so read `isPersistenceEnabled` alongside it.
`deltaTicks`	ticks	How far the sensor is from the stored position.
`singleTurnCounter`	revolutions	Whole turns counted, for a sensor that only reports position within one turn.
`isPersistenceEnabled`	-	The file handling is active.
`referencing/isOpenLoop`	-	The open-loop flag the parent block feeds in, published so the value stays visible. It is no longer part of the reconnect test — an open loop does not release the post-referencing freeze.

Parameters

Path	Unit	Default	Range	Effect
`gainNum`	-	1	non-zero	Numerator of the conversion. A 0 is refused and the previous value kept.
`gainDen`	-	1	above 0	Denominator. A value of 0 or below is refused and the previous value kept.
`ticksPerRevolution`	ticks	1	above 0	The sensor’s resolution. Multiplied into the gain. A negative value is used as its magnitude, but 0 is not refused and will break the conversion. Encoder instances only.
`offset`	ticks	0.0	unbounded	The raw reading that corresponds to zero engineering units. Referencing overwrites this — save your configuration afterwards, or a reload will undo it.
`referencing/softwareReferenceInternal`	engineering unit	0.0	unbounded	The value referencing aims at, when the external one is not selected.
`referencing/useSoftwareReferenceExternal`	-	true	-	Whether to use the external reference input instead of the internal parameter.
`referencing/reconnectToleranceHardwareSide`	hardware-side unit	2	above 0	How close the recomputed hardware output must come to the frozen one before the output reconnects, for more than 100 consecutive cycles. A write is taken as its absolute value. The default suits encoder ticks only — see Limits and errors.
`enablePersistence`	-	false	-	Whether to store the position to a file. Only for a sensor that does not remember its own absolute position. Turn it off for an absolute encoder.
`deltaTicksMax`	ticks	-1	-1, or 0 upward	How far the sensor may differ from the stored position and still be trusted. The default of -1 means no check.
`numberOfPolePairs`	-	1	1 upward	For resolver-type sensors, how many electrical revolutions make one mechanical one.
`enableSingleTurnCounter`	-	false	-	Counts whole turns, for a sensor that reports only within one turn.

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

Setup

Establish your sensor’s resolution and set ticksPerRevolution. Never write 0.
Set gainNum and gainDen to express the rest of the conversion — a lead screw pitch, a pulley ratio, a unit change.
Read gain back. It should be gainNum ÷ gainDen × ticksPerRevolution, and it is the number of ticks per engineering unit. Check it against a hand calculation before going further.
Move the machine a known distance by hand and confirm outputSoftwareSide changes by that amount.
Decide whether you need persistence. An absolute encoder does not — leave enablePersistence false. A resolver or incremental encoder does.
Reference the machine: bring it to a known position, set the reference value, and trigger referencing from your application.
Confirm outputSoftwareSide now reads the true position.

After referencing, the drive output is frozen until the commanded and measured positions agree. Expect a short pause before the axis responds again, and investigate if it never does.
Save your configuration, or the referenced offset is lost on the next reload.

Tuning

There is nothing dynamic to tune. Get the conversion right and the rest follows.
Derive the three gain factors from the drivetrain rather than measuring them — exact integers avoid rounding in a long-running position count.
Verify over a long move, not a short one. A 1% gain error is invisible over a millimetre and obvious over a metre.
Check the direction. A sensor wired backwards shows as outputSoftwareSide moving the wrong way, and is fixed with a negative gainNum.
Reference at a repeatable physical feature — a hard stop, a switch — not at an arbitrary position.
Set referencing/reconnectToleranceHardwareSide for the unit your hardware side carries. Leave it at 2 for encoder ticks; set a few thousandths for metres or radians. Do this before referencing.
If you use persistence, set deltaTicksMax to how far the machine could plausibly be moved while powered down. Leave it at -1 only if you accept the stored position unconditionally.
Re-check atStoredTicks after each start, together with isPersistenceEnabled — the first reads true whenever the second is false.

Referencing moves the line up or down. It never changes the slope.

Symptom	Cause	Action
The conversion is wildly wrong or invalid	`ticksPerRevolution` is 0, which is not refused	Set it to the sensor’s real resolution
A gain factor I wrote did not take	`gainNum` was 0, or `gainDen` was 0 or negative — both are refused	Read them back
The machine moves the wrong way	The gain’s sign is wrong	Use a negative `gainNum`
The distance is proportionally wrong	The three factors do not multiply to the right ratio	Check `gain` against a hand calculation
The drive stopped responding after referencing	Expected briefly: the output is held until the positions agree	If it never resumes, the positions are not converging — check the drive
The referenced position was lost after a restart	Referencing overwrites `offset`, and a configuration reload restores the saved value	Save the configuration after referencing
`atStoredTicks` reads true and I do not trust it	It reads true whenever persistence is off	Read `isPersistenceEnabled` too
Persistence is off even though I enabled it	It is forced off at every startup	Re-enable it from your application after each start
The stored position is accepted when it should not be	`deltaTicksMax` is -1, which means no check	Set a real window
The drive stopped responding right after referencing, with nothing reported	Expected: the output is frozen until the software side is re-based. It is a wait, not a timer	Have the application follow the disconnect flag and re-base its setpoint onto the measured actual; or assert `referencing/:fromState.reset`
The drive stepped when the output reconnected	`referencing/reconnectToleranceHardwareSide` is too large for the unit the hardware side carries — the default of 2 on a metres-or-radians instance	Set it to a few thousandths and re-reference
Reconnecting takes far longer than expected	The tolerance is tight enough that the re-based value rarely holds it for 100 consecutive cycles	Loosen it, or reduce the noise on the software side
A reference request was ignored	Expected: requests are ignored while the hardware side is still disconnected from the previous one	Wait for the freeze to clear, or reset it
The freeze did not clear on an open-loop axis	Expected: `referencing/isOpenLoop` does not release the freeze	Re-base the software side; the flag is published for visibility only
The position jumps by a whole revolution	The single-turn counter is needed, or miscounted	Enable it and set `numberOfPolePairs`
Everything became invalid	A gain factor that is not a valid number passes the zero checks	Rewrite all three
Some parameters are missing from the tree	Your instance is not an encoder type	The type is fixed when the controller is built
I need a non-linear conversion	Wrong block	Put a `Lookup` after it

A starting point for a 4096-tick encoder on a direct-driven axis:

ticksPerRevolution = 4096
gainNum            = 1
gainDen            = 1
offset             = 0
enablePersistence  = false
deltaTicksMax      = -1

Then read gain back and confirm it is 4096.

Limits and errors

Limit	Set by	What happens	Reported
Conversion	`gainNum`, `gainDen`, `ticksPerRevolution`	Their product is the ticks per engineering unit, both directions	`gain`
`gainNum` of 0	Checked	Refused — the previous value is kept	Read it back
`gainDen` of 0 or below	Checked	Refused — the previous value is kept	Read it back
`ticksPerRevolution` of 0	Not checked	The gain becomes 0 and the conversion divides by zero	Not reported
Values that are not numbers	Nothing	Not checked. They pass the zero tests and poison both directions	Not reported
Referencing	The reference value and a captured raw snapshot	Solves for the `offset` that makes them correspond, and overwrites `offset`	`referencing/hardwareSnapshot`, `offset`
Output after referencing	Fixed	Held until the commanded and measured positions agree closely for a short, fixed period. No timeout, nothing reported if they never do	Not reported
Persistence at startup	Fixed	Always disabled, whatever the parameter says	`isPersistenceEnabled`
Stored position check	`deltaTicksMax`	Compares the sensor against the stored position. A default of -1 means no check	`atStoredTicks`, `deltaTicks`
Post-referencing freeze	The reconnect condition	The hardware output is held until recomputing it would land within `referencing/reconnectToleranceHardwareSide` of the frozen value, for more than 100 consecutive cycles. A re-basing wait, not a timer — it does not time out, and a further reference request is ignored while it holds	Not reported directly; read the referencing state group
`referencing/reconnectToleranceHardwareSide`	Default 2	Sized for a hardware side carrying encoder ticks. On one carrying metres or radians, 2 would let a whole offset step through on reconnect. A negative write is taken as its absolute value	Read the value back
Reconnect step	The tolerance	Bounded by construction: the test is against the frozen output, not the measurement, so reconnecting cannot move the hardware output by more than the tolerance	Not reported
`atStoredTicks`	Fixed	Reads true when persistence is off, so it means “nothing to distrust”, not “a check passed”	Read `isPersistenceEnabled` too
Persistence file errors	Partly	A zero or negative `ticksPerRevolution` skips the stored-position check, and is logged	Controller log
Instance type	Fixed at build time	A non-encoder instance has no persistence, no turn counter and no `ticksPerRevolution`	Not reported
Channel count	Fixed	One sensor per instance, always	Not reported

The block logs when a stored-position check is skipped for a bad ticksPerRevolution, and logs the loaded position at startup. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.33.0 (69625c1).

Docs: TorqueSensorModule

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

Control3 3.30–3.34

TorqueSensorModule is the signal-conditioning chain for a joint torque sensor. It converts raw sensor counts to engineering units, corrects the sensor’s non-linearity, removes its dominant noise frequency, and then splits the result into two signals: a slow one that is the load the joint is carrying, and a fast one that is the structure vibrating around it.

That split is the point. The two need different treatment — the load goes to a force controller, the vibration drives an active-damping correction that this block also produces.

flowchart LR
    i1(["sensorTorqueActual — raw sensor counts"]) --> B["TorqueSensorModule"]
    i2(["sensorTorqueReference — commanded torque"]) --> B
    i3(["disable"]) --> B
    B --> o1(["staticTorqueActual — the load"])
    B --> o2(["dynamicTorqueActual — the vibration"])
    B --> o3(["disturbanceCorrection — damping output"])
    B --> o4(["isEnabled"])

The chain is: counts → engineering units → non-linearity correction → notch filter → split. The static branch low-passes the result. The dynamic branch subtracts sensorTorqueReference first, then high-passes it, so it measures deviation from what was commanded. That deviation drives a controller whose smoothed output is disturbanceCorrection.

Almost everything is configured below this block, in seven sub-trees. This page’s own eight paths are the wiring; the tuning is in the sub-trees.

disturbanceCorrection reads zero until you configure the controller sub-tree. Its gains all default to zero. The two torque outputs work regardless.

Signals

Inputs

Path	Unit	Range	Description
`sensorTorqueActual`	counts	unbounded	The raw torque sensor reading, before any conversion.
`sensorTorqueReference`	N·m	unbounded	The torque being commanded. It is subtracted in the dynamic branch only — the static output is the absolute load and does not use it. Leave it at zero if you only want the load.
`disable`	-	-	True forces `disturbanceCorrection` to zero. The two torque outputs keep working. Use it for a runtime override; use `enable` for the configured intent.

Outputs

Path	Unit	Description
`staticTorqueActual`	N·m	The load the joint is carrying — the slow content of the conditioned signal. Published whether or not the block is enabled, so you can commission the whole chain with the correction disconnected.
`dynamicTorqueActual`	N·m	The vibration: the fast content of the conditioned signal, measured relative to `sensorTorqueReference`. Also published while disabled.
`disturbanceCorrection`	N·m	The damping correction derived from the vibration. The only output gated by `enable`. Zero until the `controller` sub-tree is configured.
`isEnabled`	-	True when `enable` is true and `disable` is false. It does not mean a correction is being produced.

Parameters

Path	Unit	Default	Range	Effect
`enable`	-	true	-	False forces `disturbanceCorrection` to zero and leaves both torque outputs reporting.

One parameter at this level. The configuration lives in seven sub-trees:

Sub-tree	What it does	Where to read
`transducer`	Counts to newton-metres, and the sensor tare	`transducer.md`
`polynomialCorrection`	Corrects the sensor’s non-linearity, up to 5th order	`polynomial.md`
`IIRFilter`	Notch filter for the sensor’s dominant noise frequency. Ships as a pass-through — it does nothing until you supply coefficients. Note the capitalised path name	`iir-filter.md`
`staticTorqueFilter`	Low-pass that extracts the load. Its cut-off sets the split frequency	`low-pass-1.md`
`dynamicTorqueFilter`	High-pass that extracts the vibration. Its cut-off is the other half of the split	`high-pass-2.md`
`controller`	The damping controller. Its gains default to zero	`pid.md`
`vibrationCorrectionFilter`	Smooths the correction. Its cut-off is forced to 1 Hz at every start and cannot be configured — see Limits and errors	`low-pass-1.md`

enable is persistent and survives a restart, as is everything in the sub-trees.

Setup

Set enable false. Both torque outputs still report, so the whole conditioning chain can be commissioned with nothing reaching the machine.
Configure transducer with your sensor’s counts-per-newton-metre. Apply a known load and confirm staticTorqueActual reads the right value in N·m.
Tare the sensor with no load applied. This needs an application call — there is no parameter for it. If your application does not offer one, work around it with an offset in the transducer sub-tree.
If the sensor is non-linear, configure polynomialCorrection. Check it against known loads across the range, not at one point.
Trace staticTorqueActual with the joint held still and look for a dominant noise frequency. If there is one, design a notch for it and write the coefficients into the IIRFilter sub-tree. Design them for your task rate — those coefficients are in samples, not seconds.
Set the split: staticTorqueFilter’s cut-off decides what counts as load, and dynamicTorqueFilter’s decides what counts as vibration. Start with both around the frequency where your structure rings.
Feed sensorTorqueReference from your torque command and confirm dynamicTorqueActual sits near zero while the joint tracks that command.
Configure the controller sub-tree. Set its output limits and integrator limits before any gain — its integrator bounds default to ±0.1, which binds almost at once.

Step 8 is what makes the block act on the machine. Until now every output has been observation only. Set enable true last, and raise the controller’s gains from zero with the joint clear.

Tuning

Get the units right before anything else. If staticTorqueActual is not in real newton-metres, every downstream number is wrong.
Tune the notch against a measurement, not a guess. Trace the raw signal at rest, find the peak, and design for that frequency.
Set the split frequency from the structure, not from feel. Below your structure’s ringing frequency is load; above it is vibration. If the two overlap, this block cannot separate them.
Check the split works: apply a steady load and confirm it appears on staticTorqueActual and not on dynamicTorqueActual. Then excite the structure and confirm the reverse.
Tune the controller last, and as a controller — set its output limits and integrator limits first, then raise the proportional gain until the ringing is damped, then back off.
Watch disturbanceCorrection on a trace while you do it. If it saturates or sits pinned, the controller’s integrator limits are too tight.
Re-check the notch coefficients after any task-rate change. They are defined in samples, so the same coefficients are a different filter at a different rate.

Read the split off the two curves: the load appears on one and the ringing on the other.

Symptom	Cause	Action
`disturbanceCorrection` reads zero with `isEnabled` true	Expected: the `controller` sub-tree’s gains all default to zero	Configure the controller, per Setup step 8
`disturbanceCorrection` saturates or sits pinned	The controller’s integrator limits default to ±0.1	Raise them in the `controller` sub-tree before raising `ki`
A correction appears at full value the moment the block is enabled	The controller keeps integrating while disabled, so it re-enables already wound	Enable with the joint at rest, or reset the controller first
Both torque outputs read zero	The notch filter was disabled in its own sub-tree, which outputs zero rather than passing through	Re-enable it, or leave it as the pass-through it ships as
The notch does nothing	Expected: it ships as a pass-through with no coefficients	Design a notch and write `num` and `den` into the `IIRFilter` sub-tree
The notch behaves nothing like the design	Its coefficients were designed for a different sample rate	Redesign at the controller’s actual task period
`staticTorqueActual` is in the wrong units	The `transducer` sub-tree is not configured for your sensor	Work Setup step 2
`staticTorqueActual` has an offset with no load	The sensor is not tared	Tare it — this needs an application call, not a parameter
`staticTorqueActual` is right at one load and wrong at another	The sensor is non-linear and `polynomialCorrection` is not configured	Work Setup step 4 with several known loads
The load appears on `dynamicTorqueActual`	The split frequency is too low	Raise `dynamicTorqueFilter`’s cut-off
Vibration appears on `staticTorqueActual`	The split frequency is too high	Lower `staticTorqueFilter`’s cut-off
`dynamicTorqueActual` is large even when the joint is tracking well	`sensorTorqueReference` is not linked, so the whole load reads as deviation	Link the commanded torque
Changing `vibrationCorrectionFilter`’s cut-off had no effect	Expected: it is forced to 1 Hz at every start and your value is overwritten	It cannot be changed from configuration
A non-numeric value appeared and will not clear	There is no reset in this block, and the filters hold it	Restart the controller
You need this on several joints	Not possible — one sensor per instance	Use one instance per joint

A starting point for a joint whose structure rings near 25 Hz on a 1 ms task, with the correction path not yet active:

enable = false
transducer:          configure counts per Nm for your sensor
polynomialCorrection: leave at its pass-through default at first
IIRFilter:           leave as pass-through until a noise peak is measured
staticTorqueFilter:  omega = 63.0     (10 Hz)
dynamicTorqueFilter: omega = 157.0    (25 Hz), beta = 1.0
controller:          kp = 0, ki = 0, kd = 0, output limits set first

Then work Setup step 8. This is a starting point, not a final tuning.

Limits and errors

Limit	Set by	What happens	Reported
`vibrationCorrectionFilter` cut-off	Fixed in code	Forced to 1 Hz every time the controller initialises, overriding whatever your configuration sets. It is the one setting in the sub-trees you cannot change	Not reported; read the sub-tree value back after a restart
`controller` gains	Nothing	All default to zero, so `disturbanceCorrection` is zero until configured. Its integrator bounds default to ±0.1	Not reported
Notch coefficients	Nothing	Not checked for stability. A badly designed set can make the whole chain grow without bound — see the filter’s own page	Not reported
Sensor tare	Not exposed	Taring is available only through an application call, not from the parameter tree	Not reported
`staticTorqueActual`, `dynamicTorqueActual`	Nothing	Unbounded, and published whether or not the block is enabled	Not reported
`disturbanceCorrection`	The `controller` sub-tree’s own output limits	Bounded only by what you set there. Zero while disabled	Not reported
Chain state	Nothing	There is no reset input. The filters and the controller hold their state across a stop, and a non-numeric value can only be cleared by a restart	Not reported
Channel count	Fixed	One sensor 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).