Diagnosing oscillation, saturation and slip

1. Engineering problem

“The robot behaves badly” has several causes with different cures. Oscillation needs a gain or rate change, saturation needs a limit or reference change, and slip needs a traction or acceleration limit. Distinguishing them from a log saves guesswork.

2. When is this needed?

• A robot shakes, lags or overshoots.
• After a payload or floor change.
• During commissioning of acceleration limits.

3. Selection and design decisions

Signatures: oscillation: the error changes sign repeatedly with a regular period; saturation: the output sits at its limit for a long fraction of the time and the measurement approaches the target slowly (a rate-limited response); slip: wheel speed rises well above the true speed (from IMU, LiDAR or a second odometry source) during acceleration or on a slippery floor. The Nav2 velocity smoother README (read 2026-11-06) describes limiting velocity commands by kinematic constraints, including acceleration, and notes that deadband regions can avoid sending tiny values that draw high current at a stand-still.

4. Advantages and disadvantages

• Acceleration limits prevent slip and saturation and slow the robot.
• Filtering reduces noise and adds delay.
• Independent reference sources are needed to see slip at all.

5. Requirements and constraints

• Command, measurement and limit are logged at the loop rate.
• A second speed estimate exists to detect slip.
• Limits are recorded in the configuration.

6. Architecture

command, measured speed, limit, reference speed ─▶ analyser: saturation %, error sign changes, slip ratio ─▶ diagnosis

7. Implementation

1. Record a bag with command, measurement, limits and a reference speed.
2. Run the analysis (below) on the problem section.
3. Identify the signature and apply the first cure.
4. Repeat the test and compare.
5. Add a monitor for the fault to your diagnostics.

def analyse(cmd, meas, limit, v_ref=None):
    sat = sum(1 for c in cmd if abs(c) >= limit - 1e-9) / len(cmd)
    err = [c - m for c, m in zip(cmd, meas)]
    zc = sum(1 for a, b in zip(err, err[1:]) if a * b < 0)
    out = [f"saturated {sat * 100:.0f} % of samples", f"error sign changes {zc} in {len(err)} samples"]
    if v_ref is not None:
        slip = [(m - r) / r for m, r in zip(meas, v_ref) if r > 0.05]
        out.append(f"wheel speed exceeds the reference by {max(slip) * 100:.0f} % at worst (slip)")
    return out
sat_case = analyse([1.0] * 8 + [0.4] * 2, [0.1, 0.3, 0.5, 0.7, 0.8, 0.9, 0.95, 1.0, 1.0, 0.9], 1.0)
osc_case = analyse([0.5, 0.6, 0.4, 0.6, 0.4, 0.6, 0.4, 0.5], [0.5, 0.45, 0.55, 0.45, 0.55, 0.45, 0.55, 0.5], 1.0)
slip_case = analyse([0.6] * 5, [0.6, 0.62, 0.9, 1.0, 0.7], 1.0, [0.6, 0.6, 0.6, 0.6, 0.6])
for name, o in (("saturation", sat_case), ("oscillation", osc_case), ("slip", slip_case)):
    print(name + ":", "; ".join(o))

Printed (checked by the site’s tests):

saturation: saturated 80 % of samples; error sign changes 0 in 10 samples
oscillation: saturated 0 % of samples; error sign changes 5 in 8 samples
slip: saturated 0 % of samples; error sign changes 0 in 5 samples; wheel speed exceeds the reference by 67 % at worst (slip)

Reading it: the first log has the output at its limit in 80 % of the samples with no error sign changes (saturation, a slow rate-limited rise); the second has 5 sign changes in 8 samples with no saturation (oscillation); the third shows the wheel speed 67 % above the 0.6 m/s reference at worst (slip). The logs are illustrative.

8. Real examples

• Robot jerking at start: the command saturates for the first second; reducing the acceleration demand fixes it.

9. Failure scenarios

• Retuning gains for a fault that is saturation.
• Raising the speed limit beyond what the motor and traction allow.
• No reference speed, so slip looks like good odometry.

10. Troubleshooting

1. Plot command and measurement on one axis.
2. Check the saturation fraction first.
3. Check slip on the surface where it happens.

11. Validation

• The analyser prints the lines shown (executed by the site tests).
• After the fix the signature is gone in a repeat test.

12. Engineering checklist

• Command, measurement, limit logged
• Reference speed available
• Fault identified by signature
• One change at a time
• Monitors added

13. Further references

• Nav2 velocity smoother README (jazzy): nav2_velocity_smoother, read 2026-11-06.

Related on FixTheRobot