Transducer

Transducer converts between a sensor’s raw units — encoder ticks, resolver counts, an analogue reading — and engineering units, in both directions. It also handles referencing: telling the machine that a particular raw reading corresponds to a particular real position.

For an incremental sensor it can additionally store that position to disk, so the machine knows where it is after a power cycle.

flowchart LR
    i1(["inputSoftwareSide"]) --> B["Transducer"]
    i2(["inputHardwareSide"]) --> B
    i3(["persistenceEvent"]) --> B
    i4(["disablePersistence"]) --> B
    i5(["referencing/softwareReferenceExternal"]) --> B
    p1(["gainNum, gainDen, ticksPerRevolution, offset"]) --> B
    p2(["referencing/softwareReferenceInternal, useSoftwareReferenceExternal"]) --> B
    p4(["referencing/reconnectToleranceHardwareSide"]) --> B
    p3(["enablePersistence, deltaTicksMax, numberOfPolePairs, enableSingleTurnCounter"]) --> B
    B --> o1(["outputSoftwareSide"])
    B --> o2(["outputHardwareSide"])
    B --> o3(["gain"])
    B --> o4(["referencing/hardwareSnapshot"])
    B --> o5(["atStoredTicks, deltaTicks, singleTurnCounter"])
    B --> o7(["referencing/isOpenLoop"])
    B --> o6(["isPersistenceEnabled"])

After referencing, the output to the drive is deliberately frozen until the software side has been re-based onto the new offset. Precisely: until recomputing the hardware output would land within referencing/reconnectToleranceHardwareSide of the frozen value, for more than 100 consecutive cycles. Because the test is against the frozen output rather than the measurement, reconnecting cannot step the drive by more than that tolerance, whatever the measurement did meanwhile.

It is a re-basing wait, not a timer, so it does not time out. If nothing re-bases the software side the output stays frozen indefinitely, with nothing reported — the safe outcome, but the axis stays held, and a further reference request is ignored while it is. If a drive stops responding right after referencing, this is where to look. referencing/:fromState.reset clears it.

Set referencing/reconnectToleranceHardwareSide for your hardware side. The default of 2 is sized for a hardware side carrying encoder ticks. On an instance whose hardware side carries metres or radians, 2 is enormous and would let a whole offset step through.

ticksPerRevolution of 0 breaks the conversion. The other two gain factors refuse a zero and keep their previous value; this one does not. Never write 0 to it.

Persistence is switched off at every startup, whatever enablePersistence says. Your application must re-enable it after each start.

Some of the parameters below only exist on an encoder-type instance. The type is fixed when the controller is built.

Signals

Inputs

Outputs

Parameters

All are persistent and survive a controller restart. No parameters exist below this block.

Setup

1. Establish your sensor’s resolution and set ticksPerRevolution. Never write 0.

2. Set gainNum and gainDen to express the rest of the conversion — a lead screw pitch, a pulley ratio, a unit change.

3. Read gain back. It should be gainNum ÷ gainDen × ticksPerRevolution, and it is the number of ticks per engineering unit. Check it against a hand calculation before going further.

4. Move the machine a known distance by hand and confirm outputSoftwareSide changes by that amount.

5. Decide whether you need persistence. An absolute encoder does not — leave enablePersistence false. A resolver or incremental encoder does.

6. Reference the machine: bring it to a known position, set the reference value, and trigger referencing from your application.

7. Confirm outputSoftwareSide now reads the true position.

   After referencing, the drive output is frozen until the commanded and measured positions agree. Expect a short pause before the axis responds again, and investigate if it never does.

8. Save your configuration, or the referenced offset is lost on the next reload.

Tuning

1. There is nothing dynamic to tune. Get the conversion right and the rest follows.
2. Derive the three gain factors from the drivetrain rather than measuring them — exact integers avoid rounding in a long-running position count.
3. Verify over a long move, not a short one. A 1% gain error is invisible over a millimetre and obvious over a metre.
4. Check the direction. A sensor wired backwards shows as outputSoftwareSide moving the wrong way, and is fixed with a negative gainNum.
5. Reference at a repeatable physical feature — a hard stop, a switch — not at an arbitrary position.
6. Set referencing/reconnectToleranceHardwareSide for the unit your hardware side carries. Leave it at 2 for encoder ticks; set a few thousandths for metres or radians. Do this before referencing.
7. If you use persistence, set deltaTicksMax to how far the machine could plausibly be moved while powered down. Leave it at -1 only if you accept the stored position unconditionally.
8. Re-check atStoredTicks after each start, together with isPersistenceEnabled — the first reads true whenever the second is false.

Referencing moves the line up or down. It never changes the slope.

A starting point for a 4096-tick encoder on a direct-driven axis:

ticksPerRevolution = 4096
gainNum            = 1
gainDen            = 1
offset             = 0
enablePersistence  = false
deltaTicksMax      = -1

Then read gain back and confirm it is 4096.

Limits and errors

The block logs when a stored-position check is skipped for a bad ticksPerRevolution, and logs the loaded position at startup. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.33.0 (69625c1).