ImpedanceModel

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

Outputs

Parameters

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

1. Set all three gains to 0. With no coefficients the output is only externalTorque, so nothing unexpected reaches the actuator.

2. Link inputPVA from the machine’s measured state and measuredPVA from the state you want it to hold. Confirm both on a trace.

3. Confirm the displacement is what you expect: subtract the two positions on a trace. That difference is what the spring will act on.

4. Set enable true and confirm isEnabled reads true. outputTorque should still be zero, because the gains are zero.

5. 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.

6. Check the sign. If the force pushes the machine away from measuredPVA, your two PVA inputs are swapped.

7. Raise dampingGain next, then massGain only if you need the machine to resist acceleration.

Tuning

1. Set the stiffness from the process: how hard should the machine resist being pushed off position? That is $K$ in newtons per metre.
2. Set the damping for stability, not for feel. Compute $\zeta = D/(2\sqrt{KM})$ and aim near 1. Below about 0.5 contact bounces.
3. Set the mass last, and usually leave it small. It resists acceleration and amplifies any noise on inputPVA/acceleration.
4. 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.
5. Use massLookup if the machine’s apparent inertia changes across its workspace. It is driven by absolute position, unlike the other two.
6. Verify each coefficient by reading its table output in the sub-tree and multiplying by the gain. Nothing publishes the product.
7. 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.

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

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).