Gearbox

Gearbox applies a transmission ratio in both directions, and applies it the right way round for each kind of signal: speeds and positions scale by the ratio, torques and forces scale by its reciprocal. That is what a real gearbox does, and getting it wrong by hand is the usual way a drivetrain conversion goes astray.

flowchart LR
    i1(["inputLoadSide"]) --> B["Gearbox"]
    i2(["inputMotorSide"]) --> B
    p1(["nLoadSide"]) --> B
    p2(["nMotorSide"]) --> B
    B --> o1(["outputMotorSide"])
    B --> o2(["outputLoadSide"])
    B --> o3(["gain"])

Which channels are which is fixed when the controller is built, by position: the first group is kinematic (position, velocity), the rest are mechanic (torque, force). The split is not visible in the tree — you cannot read it back, so check with whoever configured the machine.

By default every channel is kinematic. The mechanic count defaults to zero, so unless it was set at build time nothing gets the reciprocal.

A tooth count of 0 is refused, safely. Write one and the block keeps the previous value rather than dividing by zero. It does not tell you it did.

Your instance may present its channels by name instead of as arrays, at LoadToMotor/<name>/input and MotorToLoad/<name>/output. Both forms behave identically; only the paths differ.

Signals

Inputs

On a named instance these appear as LoadToMotor/<name>/input and MotorToLoad/<name>/input.

Outputs

Parameters

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

A reduction of 10 to 1 — the motor turning ten times per output turn — is nLoadSide = 1, nMotorSide = 10, giving a gain of 0.1. A load-side speed of 1 then becomes a motor-side speed of 0.1… which is backwards for a reduction, so check gain against a known speed before trusting the sense.

Setup

1. Establish which of your channels are kinematic and which are mechanic. This was fixed when the controller was built and cannot be read back.
2. Set nLoadSide and nMotorSide from the drivetrain.
3. Read gain back and confirm it is the ratio you expect.
4. Put a known value on inputLoadSide for a kinematic channel and confirm outputMotorSide is that value times gain.
5. Do the same for a mechanic channel and confirm it is divided instead. If it is multiplied, that channel is on the wrong side of the split and the controller needs rebuilding.
6. Send a value through both directions and confirm it returns unchanged.

Tuning

1. There is nothing dynamic to tune. Both parameters take effect on the next cycle.
2. Get the two tooth counts from the drivetrain drawing, not from a measured ratio — the exact integers avoid rounding in long-running position integrations.
3. Verify the direction of the ratio with a slow move before running anything fast. A ratio inverted by mistake is a factor of gain squared out.
4. Verify the kinematic and mechanic split by checking a torque channel explicitly. This is the one thing this block does that a plain gain does not, and the one thing you cannot see in the tree.
5. Confirm the round trip. Load to motor and back should return the input exactly.
6. Nothing here depends on the task rate.

The two curves crossing at 1 is the whole point: at a ratio of one a gearbox does nothing to either kind of signal.

A starting point for a 10:1 reduction:

nLoadSide  = 1
nMotorSide = 10

Then read gain back and confirm it is 0.1.

Limits and errors

This block logs nothing during operation. It may log at startup if the tooth counts are zero. Every other condition above shows as a value on a trace, or not at all.

Verified against motorcortex-control3 3.30.0 (bc348fd).