Docs: Migrating from 3.23.1 to 3.24.0 — `stictionFrictionForce = 0` users

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

Control3 3.30–3.34

Who this applies to

If on 3.23.1 you set stictionFrictionForce = 0 on a FrictionCompensation block to remove chatter near zero velocity under friction feedforward, you must change your config when upgrading to 3.24.0. Without the change, the behavior you relied on is lost.

If you never set stictionFrictionForce below coulombFrictionForce, no change is required — your config keeps working with identical behavior.

What changed and why

The 3.23.1 hotfix relaxed the parameter clamp from Fs ≥ Fc to Fs ≥ 0 so the established workaround of setting Fs = 0 (which makes g(0) = 0 in the static Stribeck curve) was honored again. That removed the ±Fc step at every zero crossing and stopped the chatter.

3.24.0 reverts that relaxation — the textbook invariant stictionFrictionForce ≥ coulombFrictionForce is enforced for every model by writeback at the start of each iterate. Setting Fs below Fc is silently raised to Fc. The chatter would return.

Instead, 3.24.0 introduces a new model value — CONTINUOUS_TANH — based on Makkar et al. 2005, a continuously-differentiable tanh-based formulation. It eliminates the zero-crossing discontinuity by construction, without needing to abuse the stiction parameter. See papers/README.md for the literature.

How to migrate

Three changes per affected actuator config:

1. Switch the model

In your config (control.xml, *.link.json, or wherever you set parameters), set:

model = 2

2 corresponds to CONTINUOUS_TANH. Values: 0 = LUGRE_DYNAMIC, 1 = STATIC_SIGN (the pre-3.24.0 default), 2 = CONTINUOUS_TANH.

If your existing config still has useStaticFriction = 0/1, it continues to work. The legacy key is registered as PARAMETER_VOLATILE: loaded from control.xml at boot, but dropped from runtime saves — once you save the config, only model is persisted. At startup the alias is mapped to model (1 → STATIC_SIGN, 0 → LUGRE_DYNAMIC) only when model itself has not been set; an explicit model = N in the same XML always wins. A one-shot deprecation warning is logged per block whenever the alias is applied. If neither model nor useStaticFriction is set, the block falls back to STATIC_SIGN (the pre-3.24.0 default). Replace useStaticFriction with model = N to silence the warning and to enable CONTINUOUS_TANH.

2. Restore `stictionFrictionForce` to a physical value

Set stictionFrictionForce to its actual measured/physical value, satisfying stictionFrictionForce ≥ coulombFrictionForce. Typical ratio is Fs ≈ 1.5·Fc to 2·Fc. Do not leave it at 0 — under CONTINUOUS_TANH it would be writeback-clamped up to coulombFrictionForce anyway, and you’d lose the Stribeck overshoot the new model is designed to represent.

3. Set `coulombVelocity`

Set the new parameter:

coulombVelocity = stribeckVelocity / 10

Default is 0.001, which matches DEFAULT_STRIBECKVELOCITY / 10 = 0.01 / 10. For most setups, this default just works. If your stribeckVelocity is significantly different from 0.01, scale coulombVelocity proportionally. See friction-model.md §2.2 for the full tuning recipe.

Example diff

For a config previously running on 3.23.1:

- stictionFrictionForce = 0          # 3.23.1 hack to smooth zero crossing
+ stictionFrictionForce = 18         # physical stiction, satisfies Fs >= Fc=10
+ model                 = 2          # CONTINUOUS_TANH (Makkar 2005)
+ coulombVelocity       = 0.001      # = stribeckVelocity / 10

coulombFrictionForce, stribeckVelocity, viscousFrictionDamping, and preSlidingDisplacement keep their old values.

What you give up, what you gain

Give up:

The Fs = 0 parameter hack. It’s now writeback-clamped.

Gain:

A C¹ friction model — derivative is bounded everywhere, including at v = 0. No step changes at zero crossings.
A textbook-supported formulation citable to Makkar et al. 2005 — auditable against published literature.
The textbook Fs ≥ Fc invariant is restored, matching every standard friction-model implementation (Simscape, Modelica, etc.).
CollisionDetector near-zero-speed sensitivity is preserved (no velocity deadzone).

Verification

After updating the config, drive the actuator through a zero-velocity crossing and observe the friction feedforward output. Expected:

Output transitions smoothly through zero (no step).
Peak friction force near |v| ≈ stribeckVelocity exceeds coulombFrictionForce and approaches stictionFrictionForce (the Stribeck overshoot).
At higher speeds (|v| ≫ stribeckVelocity), the friction force settles to coulombFrictionForce + viscousFrictionDamping·v.

Unit tests T1, T2, T3 in test/utest_frictioncompensation.cpp exercise this on the simulated block — T1 documents the old chatter source in STATIC_SIGN, T2 asserts continuity in CONTINUOUS_TANH, T3 reproduces the customer’s sinusoid scenario in both modes side-by-side.

References

User guide: friction-model.md
Papers: papers/README.md
3.23.1 hotfix branch: fix/friction-stiction-below-coulomb

– Migration notes