> For the complete documentation index, see [llms.txt](https://yams.yassrobotics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yams.yassrobotics.com/documentation/reference/mechanism-configs.md).

# Mechanism configs

Every mechanism is built from two configs: a mechanism config that says what the mechanism is, and a [`SmartMotorControllerConfig`](https://yams.yassrobotics.com/documentation/reference/editor/config.md) that says how its motor behaves.

<figure><img src="https://1354553280-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZM0CFmYiQzcrY4zDcTtZ%2Fuploads%2Fgit-blob-9ac4402ed53c7caf15787f40f7a6245c3ef8a7c2%2Fmech-two-configs.png?alt=media" alt="A diagram. A mechanism config, which says what the mechanism is, such as its length, mass, hard stops and how it is drawn, and a SmartMotorControllerConfig, which says how its motor behaves, such as gearing, PID, feedforward, soft limits and current, both go into the mechanism class. The mechanism then drives the simulation&#x27;s physics and Mechanism2d, and the real robot&#x27;s commands and telemetry."><figcaption><p>Two configs go into one mechanism.</p></figcaption></figure>

```java
SmartMotorController motor  = new SparkWrapper(spark, DCMotor.getNEO(1), motorConfig); // how the motor behaves
ArmConfig            config = new ArmConfig()                                          // what the arm is
    .withLength(Feet.of(3))
    .withHardLimits(Degrees.of(-30), Degrees.of(110))
    .withTelemetry("Arm", TelemetryVerbosity.HIGH);
Arm arm = new Arm(config, motor);
```

## The pages

| Page                                                                                                                  | Config               | For                                                       |
| --------------------------------------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------- |
| [Shared options](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md)           | all four below       | Telemetry, hard limits, and how the mechanism is drawn.   |
| [ArmConfig](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/arm-config.md)                    | `ArmConfig`          | Arms that swing against gravity.                          |
| [ElevatorConfig](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/elevator-config.md)          | `ElevatorConfig`     | Elevators and linear slides.                              |
| [PivotConfig](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/pivot-config.md)                | `PivotConfig`        | Turrets and wrists. A pivot does not account for gravity. |
| [FlyWheelConfig](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/flywheel-config.md)          | `FlyWheelConfig`     | Shooters, rollers, intakes and anything else that spins.  |
| [SwerveDriveConfig](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/swerve-drive-config.md)   | `SwerveDriveConfig`  | The whole swerve drive base.                              |
| [SwerveModuleConfig](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/swerve-module-config.md) | `SwerveModuleConfig` | One swerve module.                                        |

## Which options each config has

| Option                                                                                                                                                                                                                                                             | Arm      | Elevator    | Pivot    | FlyWheel |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ----------- | -------- | -------- |
| [`withTelemetry`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md#withtelemetry)                                                                                                                                         | ✅        | ✅           | ✅        | ✅        |
| [`withSimColor`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md#withsimcolor)                                                                                                                                           | ✅        | ✅           | ✅        | ✅        |
| [`withMechanismPositionConfig`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md#withmechanismpositionconfig)                                                                                                             | ✅        | ✅           | ✅        | ✅        |
| [`withHardLimits`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md#withhardlimits)                                                                                                                                       | ✅ angles | ✅ distances | ✅ angles | ❌        |
| [`withLength`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/arm-config.md#withlength)                                                                                                                                                   | ✅        | ❌           | ❌        | ❌        |
| [`withCarriageWeight`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/elevator-config.md#withcarriageweight)                                                                                                                              | ❌        | ✅           | ❌        | ❌        |
| [`withAngle`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/elevator-config.md#withangle), [`withHorizontalElevator`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/elevator-config.md#withhorizontalelevator) | ❌        | ✅           | ❌        | ❌        |
| [`withDiameter`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/flywheel-config.md#withdiameter)                                                                                                                                          | ❌        | ❌           | ❌        | ✅        |
| [`withSpeedometerSimulation`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/flywheel-config.md#withspeedometersimulation)                                                                                                                | ❌        | ❌           | ❌        | ✅        |

The swerve configs are different enough to have their own pages and their own option lists.

## What simulation needs

{% hint style="warning" %}
Most mechanism config options describe the mechanism to the simulator and do nothing on the real robot. Some of them are **required** in simulation: if one is missing, the mechanism throws an exception when it is created in simulation, and the robot code stops. A missing option on the mechanism config throws that mechanism's own exception, such as an `ArmConfigurationException` or a `PivotConfigurationException`. A missing option on the motor config, such as an elevator's starting height, throws a `SmartMotorControllerConfigurationException`. Each option page says where the option is used.
{% endhint %}

| Mechanism  | Must be set for simulation to start                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Arm`      | [`withLength`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/arm-config.md#withlength), [`withHardLimits`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md#withhardlimits), and a [starting position](https://yams.yassrobotics.com/documentation/reference/editor/config/encoders.md#withstartingposition) inside the hard limits.                                                                                                                                                                                                                                                                                       |
| `Elevator` | [`withCarriageWeight`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/elevator-config.md#withcarriageweight), [`withHardLimits`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md#withhardlimits) or [`withStages`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/elevator-config.md#withstages), a [circumference](https://yams.yassrobotics.com/documentation/reference/editor/config/gearing-and-units.md#withmechanismcircumference), and a [starting position](https://yams.yassrobotics.com/documentation/reference/editor/config/encoders.md#withstartingposition) inside the hard limits. |
| `Pivot`    | [`withHardLimits`](https://yams.yassrobotics.com/documentation/reference/mechanism-configs/shared-options.md#withhardlimits), and a [starting position](https://yams.yassrobotics.com/documentation/reference/editor/config/encoders.md#withstartingposition) inside the hard limits.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `FlyWheel` | Nothing on the mechanism config. Its moment of inertia comes from the [motor config](https://yams.yassrobotics.com/documentation/reference/editor/config/simulation.md#withmomentofinertia).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Options that live on the motor config

Several things you might look for on a mechanism config are on the motor's config, because they change what the motor controller does:

| Looking for                                            | It is                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Soft limits                                            | [`withSoftLimits`](https://yams.yassrobotics.com/documentation/reference/editor/config/limits-and-protection.md#withsoftlimits)                                                                                                                                                                                                 |
| Where the mechanism starts                             | [`withStartingPosition`](https://yams.yassrobotics.com/documentation/reference/editor/config/encoders.md#withstartingposition)                                                                                                                                                                                                  |
| Gear ratio, drum or wheel size                         | [Gearing and units](https://yams.yassrobotics.com/documentation/reference/editor/config/gearing-and-units.md)                                                                                                                                                                                                                   |
| Gains, feedforward, motion profile                     | [Closed loop control](https://yams.yassrobotics.com/documentation/reference/editor/config/closed-loop-control.md), [Feedforward](https://yams.yassrobotics.com/documentation/reference/editor/config/feedforward.md), [Motion profiles](https://yams.yassrobotics.com/documentation/reference/editor/config/motion-profiles.md) |
| Mass or moment of inertia of an arm, pivot or flywheel | [`withMomentOfInertia`](https://yams.yassrobotics.com/documentation/reference/editor/config/simulation.md#withmomentofinertia)                                                                                                                                                                                                  |
| An absolute encoder                                    | [Encoders](https://yams.yassrobotics.com/documentation/reference/editor/config/encoders.md)                                                                                                                                                                                                                                     |

## Code reference

* [`ArmConfig`](https://github.com/Yet-Another-Software-Suite/YAMS/blob/master/yams/java/yams/core/mechanisms/config/ArmConfig.java)
* [`ElevatorConfig`](https://github.com/Yet-Another-Software-Suite/YAMS/blob/master/yams/java/yams/core/mechanisms/config/ElevatorConfig.java)
* [`PivotConfig`](https://github.com/Yet-Another-Software-Suite/YAMS/blob/master/yams/java/yams/core/mechanisms/config/PivotConfig.java)
* [`FlyWheelConfig`](https://github.com/Yet-Another-Software-Suite/YAMS/blob/master/yams/java/yams/core/mechanisms/config/FlyWheelConfig.java)
* [`SwerveDriveConfig`](https://github.com/Yet-Another-Software-Suite/YAMS/blob/master/yams/java/yams/core/mechanisms/config/SwerveDriveConfig.java)
* [`SwerveModuleConfig`](https://github.com/Yet-Another-Software-Suite/YAMS/blob/master/yams/java/yams/core/mechanisms/config/SwerveModuleConfig.java)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://yams.yassrobotics.com/documentation/reference/mechanism-configs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
