> 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/guide/drivetrain.md).

# Drivetrain

The drivetrain is a CTRE swerve drive, generated by **Tuner X**. Most of it is CTRE's code; the template adds Commands v3 support, logging, and the simulator.

| File                                      | What it is                                                                                                                              |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `generated/TunerConstants.java`           | Every swerve setting: CAN IDs, gear ratios, wheel size, module offsets, gains. **Written by Tuner X. Regenerate it; don't edit it.**    |
| `subsystems/CommandSwerveDrivetrain.java` | CTRE's `SwerveDrivetrain`, made into a Commands v3 `Mechanism`                                                                          |
| `SwerveTelemetry.java`                    | Logging for the drivetrain. See [Logging](https://docs.raidrobotics.org/commands-v3-state-machine/guide/logging.md#drivetrain-logging). |

## TunerConstants

`TunerConstants` is generated by the Tuner X Swerve Project Generator for one specific drivetrain. When the drivetrain changes (new modules, new IDs, a new robot), regenerate it in Tuner X and replace the file. Don't hand-edit it: the next regeneration overwrites your changes.

A few values the rest of the code uses:

| Value                | What it is                                                                    |
| -------------------- | ----------------------------------------------------------------------------- |
| `kCANBus`            | The swerve drive's CAN bus (`"canivore"`). Separate from the mechanisms' bus. |
| `kSpeedAt12Volts`    | Top speed, used to scale the joysticks (`Robot.maxSpeed`)                     |
| `createDrivetrain()` | Builds the `CommandSwerveDrivetrain`. `Robot` calls it once.                  |

The steer motors use `FusedCANcoder` feedback, a Phoenix Pro feature. Without a Pro license it falls back to `RemoteCANcoder` automatically.

{% hint style="info" %}
CAN IDs 0 to 19 are left for the swerve drive. Mechanisms start at 20 (see `Constants.CAN`).
{% endhint %}

## CommandSwerveDrivetrain

`CommandSwerveDrivetrain` extends Tuner X's `SwerveDrivetrain` and implements `Mechanism`, so commands can require it.

### Driving it

Every drivetrain command applies a CTRE **swerve request**: an object that describes how to drive (field-centric, robot-centric, idle, point the wheels, ...).

```java
public Command applyRequest(String name, Supplier<SwerveRequest> request)
```

`applyRequest` re-reads the request every loop, so the request can change while the command runs. Teleop uses this as the drivetrain's default command (see [Driver controls](https://docs.raidrobotics.org/commands-v3-state-machine/guide/teleop.md)). Autos use `AutoDrive`, which calls `setControl` directly from a coroutine (see [Autonomous](https://docs.raidrobotics.org/commands-v3-state-machine/guide/autonomous.md)).

### Field-centric "forward"

In field-centric driving, pushing the stick forward drives away from the driver, whichever way the robot faces. The drivetrain needs to know which way is "away from the driver":

* **Automatically**: `periodic()` sets it from the alliance color. Blue's forward is 0°; red's is 180°. It applies once as soon as the alliance is known, and after that only while disabled, so driving never changes mid-match.
* **By hand**: `seedFieldCentricCommand()` makes the way the robot faces right now "forward". The driver's left bumper runs it. It requires nothing, so it won't interrupt driving.

### Running while disabled

```java
@Override
public boolean controllableDuringDisabled() {
    return true;
}
```

This lets drivetrain commands run while the robot is disabled. `Robot` uses it to apply an idle request whenever the robot is disabled, so the drive motors go to their configured neutral mode. It's the Commands v3 version of v2's `ignoringDisable(true)`.

### Alerts

Every drive motor, steer motor, CANcoder and the Pigeon 2 is registered in an `AlertableCollection`. Faults show up as alerts on the dashboard, grouped under **Swerve**.

### Simulation

In the simulator, the drivetrain simulates itself. `startSimThread()` runs CTRE's swerve physics every 4 ms, faster than the 20 ms robot loop, so the PID gains behave more like they do on the real robot.

## Position estimate

The drivetrain keeps track of where the robot is on the field (its **pose**), blending three sources:

* the wheel encoders (odometry),
* the Pigeon 2 gyro,
* the Limelights, through `addVisionMeasurement(...)`. See [Vision](https://docs.raidrobotics.org/commands-v3-state-machine/guide/vision.md).

Read it with `drivetrain.getState().Pose`. It's logged as `Drive/Pose`.

Autos tell the drivetrain where the robot starts with `resetPose(...)`; see [Autonomous](https://docs.raidrobotics.org/commands-v3-state-machine/guide/autonomous.md).

## Characterization (SysId)

SysId measures how the drivetrain actually responds to voltage, so its gains can be calculated rather than guessed. The routines are in `CommandSwerveDrivetrain`, and the buttons are in the **SysId Drivetrain** utility opmode (`SysIdUtility`):

| Hold     | Runs                 |
| -------- | -------------------- |
| View + Y | Dynamic, forward     |
| View + X | Dynamic, reverse     |
| Menu + Y | Quasistatic, forward |
| Menu + X | Quasistatic, reverse |

Which routine runs (translation, steer or rotation) is set by `sysIdRoutineToApply` in `CommandSwerveDrivetrain`. It's translation by default. Run each of the four tests exactly once per log. The SysId state is written to the `.hoot` log.

{% hint style="danger" %}
SysId drives the robot on its own, and the dynamic tests drive hard. Give it plenty of space, and let go of the buttons to stop.
{% endhint %}


---

# 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/guide/drivetrain.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.
