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

# How the robot code fits together

The template is organized around one question: **who is allowed to tell a motor what to do?** The answer is "only the mechanism that owns it, and only when the superstructure says so". Everything else in the project follows from that.

## The layers

```mermaid
flowchart LR
    T[DriveTeleop<br/>buttons] --> R
    A[ExampleAuto<br/>steps] --> R
    R[Requests<br/>&quot;I want to intake&quot;] --> SM[State machine<br/>&quot;what the robot does&quot;]
    SM --> M1[Mechanism1.goTo]
    SM --> M2[Mechanism2.intake]
    M1 --> Motor1[Motor]
    M2 --> Motor2[Motor]
    T --> DT[Drivetrain]
    A --> DT
```

Each layer has one job:

| Layer                                              | Its job                                                                | It never...                                   |
| -------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------- |
| **Opmodes** (`DriveTeleop`, `ExampleAuto`)         | Decide what the driver or the auto *wants*, and drive the robot        | ...runs a mechanism directly                  |
| **Requests** (`requestIntake()`, `requestScore()`) | Hold up a flag while someone wants something                           | ...move anything                              |
| **Superstructure** (the state machine)             | Decide what *every* mechanism does, based on the flags and the sensors | ...reads a controller                         |
| **Mechanisms** (`Mechanism1`, `Mechanism2`)        | Own their motor; offer readings and commands                           | ...know about other mechanisms or controllers |

The drivetrain is the one exception: opmodes command it directly, because driving is the driver's job, not the state machine's.

## Why it's built this way

**Teleop and auto can't disagree.** A button and an auto step make the same request. If intaking works in teleop, it works in auto, with the same positions and the same timing. Tuning one tunes the other.

**Mechanisms can't collide.** Only the state machine moves mechanisms, and each state says what *every* mechanism does. There's no way for one button to raise the arm while another button runs the intake into it. When two mechanisms can collide, the rule between them lives in one place: the superstructure.

**The simulator runs the real code.** Mechanisms only talk to their motor objects. In the simulator a physics model sits behind those motors, and nothing else in the code can tell the difference.

**Logs explain matches.** Because every decision goes through one state machine, logging the state and the requests answers most "why did the robot do that?" questions after a match.

## The rest of this section

* [Commands v3 in this project](https://docs.raidrobotics.org/commands-v3-state-machine/concepts/commands-v3.md): the parts of WPILib's Commands v3 the template uses, and how.
* [Opmodes](https://docs.raidrobotics.org/commands-v3-state-machine/concepts/opmodes.md): how the Driver Station's opmode list works, and what belongs in an opmode versus `Robot.java`.
* [Requests](https://docs.raidrobotics.org/commands-v3-state-machine/concepts/requests.md): the "ask, don't do" pattern that connects buttons and autos to the state machine.


---

# 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/concepts/concepts.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.
