[2027] Change gear ratios from output:input to input:output to match the rest of the ecosystem

[qwertychouskie]

I'm not sure how many places have this, but at least at https://github.com/wpilibsuite/allwpilib/blob/2027/wpimath/src/main/java/org/wpilib/math/system/plant/LinearSystemId.java#L28, output:input is used for the gearbox ratio. This is the opposite of what every vendor (AFAIK) uses (and probably many libraries as well), which leads to a situation that is confusing at best and a massive footgun at worst.

[calcmogul]

This is the opposite of what every vendor (AFAIK) uses

Could you provide some documentation and examples of this? Also, are they speed ratios or torque ratios? Based on the nomenclature in https://en.wikipedia.org/wiki/Gear_train, wpimath uses torque ratios (i.e., output/input), not speed ratios (i.e., input:output).

and probably many libraries as well

Could you provide examples?

[bhall-ctre]

Based on how the sim classes and LinearSystemId.createDCMotorSystem work, WPILib uses ratios >1 for reductions. The documentation is unclear, as such a ratio is input motor rotor rotations per output mechanism rotation, which is input:output, but that's also equivalent to output torque over input torque. The docs don't specify whether the ratio is in terms of torque or position/velocity (we explicitly document the latter in Phoenix 6); it must be torque for output:input to be correct.

[calcmogul]

ElevatorSim and SingleJointedArmSim document that values greater than 1 are reductions, but the wpimath LinearSystem factories don't seem to. The gist for wpimath gear ratio inputs is "20:1 in docs becomes 20/1 in code". Users will have to keep looking it up either way because it's not intuitively clear whether 20:1 from a gearbox datasheet should become 20/1 or 1/20 in code.

wpimath's models come from https://file.tavsys.net/control/controls-engineering-in-frc.pdf, and I picked G > 1 vs G < 1 for reductions effectively at random, because the math works out fine either way as long as you're consistent.

[bhall-ctre]

Using G > 1 for reductions is fine and I believe matches most libraries, the confusion here is that can either be input:output or output:input depending on the units (rotations vs Newton-meters respectively), and the docs don't specify which is being used when they refer to "output to input".

[qwertychouskie]

This is the opposite of what every vendor (AFAIK) uses

Could you provide some documentation and examples of this?

https://www.revrobotics.com/maxplanetary-system-kit/
https://www.revrobotics.com/rev-41-1600/
https://www.gobilda.com/5103-series-planetary-gearbox-19-2-1-ratio-24mm-length-8mm-rex-shaft/
https://wcproducts.com/products/versaplanetary-gearbox
etc

Also, are they speed ratios or torque ratios? Based on the nomenclature in en.wikipedia.org/wiki/Gear_train, wpimath uses torque ratios (i.e., output/input), not speed ratios (i.e., input:output).

They use rotations-in:rotations-out, so 3:1 would mean 3 rotations in results in 1 rotation out.

[bhall-ctre]

They use rotations-in:rotations-out, so 3:1 would mean 3 rotations in results in 1 rotation out.

That is equivalent to torque-out:torque-in, which is what the WPILib documentation intends to mean by "output to input".

[qwertychouskie]

They use rotations-in:rotations-out, so 3:1 would mean 3 rotations in results in 1 rotation out.

That is equivalent to torque-out:torque-in, which is what the WPILib documentation intends to mean by "output to input".

To be honest, I don't think I've ever heard of torque-out:torque-in, so that documentation would definitely send me the complete wrong direction. On the plus side, it sounds like no code changes are needed, just a documentation update.

[KangarooKoala]

Huh, #7647 describes the argument as input/output. This is why we need better documentation...