Transformation

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, 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

Outputs

Parameters

Both are persistent and survive a controller restart.

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

Setup

1. Set up the transducer first — transducer/ticksPerRevolution and the two gain factors. Verify it on its own before touching this block.
2. Set gearRatio from the drivetrain between the sensor and the actuator’s output. Never write 0.
3. 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.
4. Set actualLP1Filter/omega — go to Tuning.
5. If your instance has one, set the linearisation table under actualLinearizeLookup from measurements of the sensor’s error.
6. 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.
7. Set referenceLoadSide and reference the machine, remembering this value is in actuator units.

Tuning

1. 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.
2. Verify the conversion over a long move, not a short one.
3. Set actualLP1Filter/omega from the noise on your measurement and the bandwidth your control loop needs. Lower removes more noise and adds more lag.
4. 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.
5. 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.
6. Set the linearisation table only after the gain and offset are right. It corrects the shape of the sensor’s error, not its scale.
7. 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.

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

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