For the complete documentation index, see llms.txt. This page is also available as Markdown.

How do I tell YAMS my drum or sprocket size?

Goal: tell YAMS how far your elevator (or wheel, or linear slide) moves for each rotation, so you can give it targets in meters or inches instead of rotations.

YAMS turns rotations into distance with the mechanism circumference: the distance the mechanism moves for one rotation of its final shaft (after the gearbox). If the circumference is wrong, every height is off by the same factor, and the gains you tune will not make sense.

A swerve style wheel, its shaft, a gearbox and a NEO motor laid out in a row. The motor shaft is labelled Rotor, the shaft after the gearbox is labelled Mechanism, and the wheel's outer edge is labelled Measurement. Rotor and Mechanism are an angle and angular velocity; Measurement is a distance and linear velocity.
The circumference turns Mechanism rotations into a Measurement distance.

Find the circumference

The circumference belongs to the last part that turns: the drum, sprocket, pulley or wheel that moves the load.

  • Drum or wheel: circumference = 2 × π × radius = π × diameter.

  • Sprocket on chain: circumference = chain pitch × number of teeth. For example #25 chain (0.25 inch pitch) on a 22 tooth sprocket moves 5.5 inches per rotation.

Animation of a 4 inch drum and a 22 tooth sprocket on 0.25 inch pitch chain, each turning two rotations. The drum moves its cable 12.57 inches per rotation, 25.13 inches in total. The sprocket moves its chain 5.50 inches per rotation, 11 inches in total.
Each rotation of the mechanism moves it by one circumference.

Set it in YAMS

Use exactly one of these methods in your SmartMotorControllerConfig. They all set the same value, so if you call more than one, the last call wins. Pick the one that matches what you can measure. Each line below is a fragment that goes in the config chain.

A complete elevator config, using the sprocket:

A cascading elevator

In a cascading elevator each stage pulls the next, so the carriage moves faster than the chain or cable: with two moving stages, twice as fast. Tell the motor config with withCascadingElevatorStages(2), called after withGearing(...): it divides the gearing already set by the number of stages, so a withGearing call after it replaces the result. See withCascadingElevatorStages.

ElevatorConfig.withStages(...) is a different thing: it gives the height each stage travels, so YAMS can draw every stage on a 3D model. It does not change the gearing, so a cascading elevator needs both. See How do I show an elevator's stages on a 3D robot model?

Check it

  1. Deploy (or start the simulation) and open the motor's measurement/position value under NetworkTables > Mechanisms. It is in meters.

  2. On the robot, disable it and move the carriage by hand a known distance, for example 0.5 m with a tape measure.

  3. measurement/position should change by the same amount. If it changes by twice as much, or half, the circumference or the gearing is wrong.

If it did not work

  • The reading is off by a constant factor. Check the gearing first (withGearing), then the circumference. A cascading elevator also needs withCascadingElevatorStages, after withGearing: see A cascading elevator.

  • The reading goes the wrong way. The motor is inverted; see Troubleshooting.

Read more

Send the elevator to a height in meters: How do I set an elevator's target height?

Last updated

Was this helpful?