Mechanism Types

This project includes two main reusable mechanism patterns: Flywheel and PositionJoint.

Pick the one that matches what your mechanism is actually supposed to control before you start copying constants or tuning gains.

Use Flywheel when

Choose Flywheel for mechanisms where the main goal is to control speed, not hold a physical position.

Common examples:

  • shooter wheels

  • intake rollers

  • feeder rollers

  • conveyors

Flywheel usually fits mechanisms that:

  • spin continuously

  • do not need an absolute encoder offset

  • are primarily commanded in velocity or voltage

  • do not need gravity compensation

In this codebase, Flywheel config is simpler:

  • motor CAN IDs

  • motor inversion

  • gear ratio

  • current limit

  • CAN bus

Its gains are also velocity-focused: kP, kI, kD, kS, kV, kA, plus acceleration and tolerance values.

Use PositionJoint when

Choose PositionJoint for mechanisms where the main goal is to move to and hold a position.

Common examples:

  • arms

  • pivots

  • wrists

  • elevators

PositionJoint usually fits mechanisms that:

  • have a meaningful physical position range

  • need motion limits

  • need a known sensor zero or offset

  • may need gravity compensation

  • are commanded to setpoints such as angles or heights

In this codebase, PositionJoint config includes everything a Flywheel uses plus:

  • gravity model

  • encoder type

  • encoder ID

  • encoder offset

Its gains also include position-specific fields such as kG, max velocity, max acceleration, min position, max position, tolerance, and a default setpoint.

Quick comparison

  • Flywheel: “spin at this speed”

  • PositionJoint: “move to this position”

  • Flywheel: simpler hardware config, usually no external position reference

  • PositionJoint: more setup because closed-loop motion depends on sensor alignment and safe travel limits

  • Flywheel: best for continuous rotation mechanisms

  • PositionJoint: best for bounded joints and linear mechanisms

How to choose

Ask this question:

Is failure mostly about wrong speed, or mostly about wrong position?

  • If wrong speed is the main problem, use Flywheel.

  • If wrong position is the main problem, use PositionJoint.

If a mechanism can crash into hard stops, over-rotate, or must hold a specific angle or extension, it should usually be modeled as PositionJoint.

Where to look next

  • To configure hardware IDs and ports, continue to Configure Robot.

  • To inspect the shared subsystem patterns directly, see Subsystems.