> 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/robot-and-constants.md).

# Robot and Constants

Two files hold the project together: `Robot.java` builds everything, and `Constants.java` says what's plugged in where.

## Robot.java

`Robot` is the robot program. It builds every piece of hardware **once**, when the code starts, and then runs the command scheduler every loop. It's also the map of the project: its header comment lists every file.

### What it builds

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

```java
public final CommandXboxController controller = new CommandXboxController(Constants.Controllers.DRIVER_PORT);

public final CommandSwerveDrivetrain drivetrain = TunerConstants.createDrivetrain();
public final Superstructure superstructure = new Superstructure();
public final Vision vision = new Vision(drivetrain);

public final AutoDrive autoDrive = new AutoDrive(drivetrain);
```

{% endcode %}

These fields are `public final` so every opmode can reach them through its `robot` parameter. See [Opmodes](https://docs.raidrobotics.org/commands-v3-state-machine/concepts/opmodes.md).

It also has two speed limits that teleop uses to scale the joysticks:

| Field            | Value                                                                           |
| ---------------- | ------------------------------------------------------------------------------- |
| `maxSpeed`       | The drivetrain's top speed at 12 V, from `TunerConstants.kSpeedAt12Volts` (m/s) |
| `maxAngularRate` | 3/4 of a rotation per second (rad/s)                                            |

### What the constructor does

1. **Starts the log files** with `RobotLog.start()`. See [Logging](https://docs.raidrobotics.org/commands-v3-state-machine/guide/logging.md).
2. **Hooks up drivetrain logging**: the drivetrain hands its state to `SwerveTelemetry` every odometry update.
3. **Idles the drivetrain while disabled**, whichever opmode is picked:

   ```java
   RobotModeTriggers.disabled().whileTrue(
       drivetrain.applyRequest("Drivetrain.DisabledIdle", () -> idle)
   );
   ```
4. **Adds the simulator**, on a laptop only. This is the one place in the project that checks `isSimulation()`:

   ```java
   if (isSimulation()) {
       final var sim = new SuperstructureSim(superstructure);
       sim.preload();      // start with a game piece, like a match. Remove to start empty.
   }
   ```

### Every loop

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

```java
@Override
public void robotPeriodic() {
    final long loopStart = System.nanoTime();
    scheduler.run();
    RobotLog.periodic((System.nanoTime() - loopStart) / 1e6);
}
```

{% endcode %}

`scheduler.run()` does everything: reads the buttons, runs each scheduled command for one step, and calls every periodic that a class registered with `addPeriodic`. `RobotLog.periodic` runs last, so the loop time it logs covers the whole loop.

{% hint style="info" %}
`Main.java` only starts `Robot`. Don't add anything to it.
{% endhint %}

## Constants.java

`Constants` is the robot's **wiring sheet**: every CAN ID, port and network name, in one file.

### What goes here, and what doesn't

| Here                                   | Not here                                                                                                        |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| CAN IDs and CAN bus names              | Gains, gear ratios, setpoints, speeds. Those live in the mechanism's own file, next to the code that uses them. |
| DIO ports                              | The swerve drive's IDs. Tuner X generates those into `TunerConstants.java`; don't copy them.                    |
| Controller ports                       |                                                                                                                 |
| Limelight names and mounting positions |                                                                                                                 |
| Field size                             |                                                                                                                 |

The rule is simple: if you'd need it to wire or re-wire the robot, it goes here. If you'd need it to tune the robot, it goes in the mechanism.

### What's in it

| Class         | Contents                                                                                                                                           |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Controllers` | `DRIVER_PORT = 0` (the Driver Station's USB order). A commented-out `OPERATOR_PORT` for a second controller.                                       |
| `CAN`         | `MECHANISM_BUS` (the controller's built-in bus), and the mechanisms' motor IDs. IDs 0 to 19 are left for the swerve drive; mechanisms start at 20. |
| `DIO`         | `MECHANISM_2_BEAM_BREAK = 0`                                                                                                                       |
| `Vision`      | `CAMERAS`: each Limelight's name and where it's mounted. `TAG_IDS`: which AprilTags the cameras may use.                                           |
| `Field`       | The field's length and width in meters, for autos and vision.                                                                                      |

### Moving the mechanisms to a CANivore

`MECHANISM_BUS` is `new CANBus()`, the controller's built-in bus (RAIDSystems calls it "rio"). To move the mechanisms to a CANivore, change only that line:

```java
public static final CANBus MECHANISM_BUS = new CANBus("canivore");
```

On a CANivore (CAN FD), Phoenix Pro devices can time-sync their signals. The swerve drive's bus is separate: it's `TunerConstants.kCANBus`.

### Keep it readable for RAIDSystems

RAIDSystems' **Sync code** finds every `new TalonFX(ID, BUS)` (and CANcoder, CANrange, ...) in the project and follows the ID and bus back to this file. Keep each line in a shape its parser understands:

* Each ID is a plain `public static final int NAME = number;` with no math and no lookups.
* Each bus is a `public static final CANBus NAME = new CANBus("name");`.
* Create each device in the mechanism class that owns it. RAIDSystems (and RAIDLogs) group devices into mechanisms by the class they're created in.

See [RAIDSystems and RAIDLogs rules](https://docs.raidrobotics.org/commands-v3-state-machine/reference/raid-tools.md).


---

# 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/robot-and-constants.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.
