CollisionDetector

CollisionDetector notices when an actuator meets something it was not expecting. It compares the torque the controller asked for against the torque the machine actually developed, and flags a discrepancy that persists.

The trick is that the commanded torque is delayed to match the measurement’s own lag before the two are compared, so the difference stays flat during ordinary motion and the threshold can be tight.

flowchart LR
    i1(["torqueReference"]) --> B["CollisionDetector"]
    i2(["torqueActual"]) --> B
    i3(["reset"]) --> B
    i4(["disable"]) --> B
    p1(["enable"]) --> B
    B --> o1(["torqueError"])
    B --> o2(["isEnabled"])
    B --> s1(["collisionDetector — the detection settings and results"])
    B --> s2(["collisionReferenceFilter — the delay matching"])

The thresholds are not on this block. They live one level down, under collisionDetector. Set collisionDetector/tooHigh and collisionDetector/tooLow to your collision thresholds and collisionDetector/timeWindow to how long the discrepancy must persist.

The detection result is also one level down, at collisionDetector/noError. This block publishes only torqueError — read noError from the sub-tree to know whether a collision was detected.

The block ships disabled. enable defaults to false. Nothing happens until you set it.

Signals

Inputs

Outputs

The detection flags themselves — isTooLow, isTooHigh, noError — are under collisionDetector.

Parameters

That is the only parameter at this level. Everything that shapes the detection is in the two sub-trees below:

All are persistent and survive a controller restart.

Setup

1. Connect the controller’s torque command to torqueReference and the measured torque to torqueActual. Both must be in the same units — nothing converts between them.

2. Leave enable false for now.

3. Run the machine through its normal motion and trace torqueError. It should stay small and flat. If it swings during acceleration, the two signals are not in the same units, or one is scaled differently.

4. Note the largest excursion of torqueError during normal motion, including the fastest move and the hardest acceleration.

5. Set collisionDetector/tooHigh and collisionDetector/tooLow outside that, with margin.

6. Set collisionDetector/timeWindow — go to Tuning.

7. Set enable true.

   Whatever acts on collisionDetector/noError will act the moment it goes false. If that is a stop, confirm the thresholds are wide enough for normal motion before you enable, or the machine will stop on its own first move.

8. Push against the actuator by hand, gently, and confirm the detection comes up.

Tuning

1. Trace torqueError for a full working cycle before setting any threshold. The whole design aims to keep this flat; if it is not flat, fix that first.
2. If torqueError swings during acceleration, the delay matching is not suiting your drive. The internal delay is fixed at about 15 milliseconds at a 1 kHz task rate and is not adjustable. Widen the thresholds, or filter torqueActual upstream so its lag is closer to that.
3. Set the collision thresholds from the largest normal excursion, with margin — typically twice it.
4. Set timeWindow longer than the transient you want to ignore and shorter than the time you can afford to keep pushing. Ten to fifty milliseconds is a reasonable range.
5. Test with a real obstruction, not just by hand. A soft obstruction produces a slower error rise and needs a longer timeWindow to be tolerated, or a lower threshold to be caught.
6. Set the warning levels inside the collision thresholds if you want an early indication before stopping.
7. Re-check torqueError after any change to the drive tuning or to the feedforward path — both change the lag this block is matching.

The flat section is what makes a tight threshold possible.

A starting point, once you have traced torqueError:

enable                          = true
collisionDetector/tooHigh       =  <twice the largest normal excursion>
collisionDetector/tooLow        = -<the same>
collisionDetector/timeWindow    = 0.02
collisionReferenceFilter/enable = true

Limits and errors

This block logs nothing, ever. Every condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).