> For the complete documentation index, see [llms.txt](https://docs.raidrobotics.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raidrobotics.org/commands-v3-state-machine/how-to/add-a-mechanism.md).

# Add a mechanism

This walks through turning a template mechanism into a real one, using an arm as the example. The same steps work for any mechanism: pick the template closest to what it does.

| If the mechanism...                              | Copy              |
| ------------------------------------------------ | ----------------- |
| Moves to positions (arm, wrist, pivot, elevator) | `Mechanism1.java` |
| Spins (intake, rollers, feeder, shooter wheel)   | `Mechanism2.java` |

{% stepper %}
{% step %}

## Copy and rename the file

Copy `subsystems/Mechanism1.java` to `subsystems/Arm.java`. Rename the class, and change every `"Mechanism1"` string to `"Arm"`: the logging table, and the prefix in each command's name.

```java
private final TelemetryTable table = RobotLog.table("Arm");
...
}).named("Arm." + name);
```

The table name should match the class name. RAIDSystems names mechanisms the same way, so the log, the schematic and the code all use one name.
{% endstep %}

{% step %}

## Add its wiring to Constants

Add its CAN ID (and any sensor ports) to `Constants.java`. Keep each ID a plain number:

{% code title="Constants.java" %}

```java
public static final int ARM_MOTOR = 22;
```

{% endcode %}

Then create the device in the mechanism with both values from `Constants`, as one plain line:

```java
private final TalonFX motor = new TalonFX(Constants.CAN.ARM_MOTOR, Constants.CAN.MECHANISM_BUS);
```

RAIDSystems reads that line to find the device. See [RAIDSystems and RAIDLogs rules](https://docs.raidrobotics.org/commands-v3-state-machine/reference/raid-tools.md).
{% endstep %}

{% step %}

## Fill in the constants

Work down the `TODO`s in part 1: gear ratio, length and mass from CAD, the travel limits, and the positions it goes to. Leave the gains at the template's values until you can tune on the robot.
{% endstep %}

{% step %}

## Add it to the superstructure

In `Superstructure.java`:

1. Add a field: `public final Arm arm = new Arm();`
2. Add a command for it to **every** state in `createStateMachine()`. A state must say what every mechanism does, even if it's "stay stowed".

```java
final var idle = machine.addState(Command.parallel(
    mechanism1.goTo("Stow", Mechanism1.STOW),
    mechanism2.stop(),
    arm.goTo("Stow", Arm.STOW)
).named("Superstructure.Idle"));
```

If it can collide with another mechanism, put that rule here, not in either mechanism. See [The superstructure state machine](https://docs.raidrobotics.org/commands-v3-state-machine/guide/superstructure.md#rules-between-mechanisms).
{% endstep %}

{% step %}

## Add it to the simulator

In `SuperstructureSim.java`, grab the motor's sim state, pick a physics model, and add its three steps to `update()`. See [Simulation](https://docs.raidrobotics.org/commands-v3-state-machine/guide/simulation.md#adding-a-mechanism-to-the-simulation).
{% endstep %}

{% step %}

## Add it to the drawing

Optionally, add a ligament for it to the superstructure's `Mechanism2d` drawing so you can see it move in the simulator.
{% endstep %}

{% step %}

## Try it in the simulator

Run `./gradlew run` and step through every state. Watch `Arm/Angle (deg)` follow `Arm/Target (deg)`, and `Arm/Command` change with the state.
{% endstep %}
{% endstepper %}

## Variations

* **An elevator**: heights instead of angles, and `GravityTypeValue.Elevator_Static`. See `SimpleSuperstructure-v3`'s `Elevator.java`.
* **An absolute encoder on the joint** (FusedCANcoder, Phoenix Pro): see `SimpleSuperstructure-v3`'s `Arm.java`. Delete the `motor.setPosition(STOW)` line.
* **A flywheel that needs an exact speed**: use `VelocityVoltage` (or `VelocityTorqueCurrentFOC`) and add Slot0 gains.
* **A different game piece sensor**: change only `hasGamePiece()`.


---

# 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://docs.raidrobotics.org/commands-v3-state-machine/how-to/add-a-mechanism.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.
