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

# Requests

A **request** is how a button or an auto step asks for something without doing it. It's the glue between the opmodes and the state machine, and it's the reason teleop and auto can't behave differently.

## What a request is

A request is a command that raises a flag for as long as it runs, and lowers it when it stops, however it stops: button released, toggled off, auto step finished, robot disabled. It requires no mechanism, so it never interrupts anything. Some other code reads the flag every loop and decides what to do about it.

The whole pattern is one method, in `util/Requests.java`:

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

```java
public static Command hold(String name, Consumer<Boolean> flag) {
    return Command.noRequirements(coroutine -> {
        flag.accept(true);
        coroutine.park();                       // wait here until something cancels us
    })
        .whenCanceled(() -> flag.accept(false))
        .whenExited(() -> flag.accept(false))
        .named(name);
}
```

{% endcode %}

## Making a request

The superstructure keeps one `boolean` per request, and offers a command that holds it up:

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

```java
private boolean wantIntake = false;

/** Asks to pick up a game piece, for as long as the command runs (hold the button). */
public Command requestIntake() {
    return Requests.hold("Superstructure.RequestIntake", want -> wantIntake = want);
}
```

{% endcode %}

The state machine only ever **reads** `wantIntake`. Only the request command **writes** it.

## Using a request

Because a request is just a command, any trigger can hold it up:

```java
controller.rightTrigger().whileTrue(superstructure.requestIntake());   // flag up while held
controller.view().toggleOnTrue(vision.ignore());                       // flag up until pressed again
coroutine.await(superstructure.intakeUntilHolding());                  // flag up until the job is done
```

## Requests for autos

A button's request runs until the button is released. An auto step needs a request that ends **when the job is done**, so the next step can start. The superstructure offers one of each:

| For buttons (runs until released) | For autos (ends when done)                                                   |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `requestIntake()`                 | `intakeUntilHolding()`: ends once a piece is in                              |
| `requestScore()`                  | `scoreUntilDone()`: ends once the piece is out and the robot is back to IDLE |

`intakeUntilHolding()` is just the button's request with an end condition:

```java
public Command intakeUntilHolding() {
    return requestIntake().until(() -> state == State.HOLDING).named("Superstructure.IntakeUntilHolding");
}
```

`scoreUntilDone()` also skips itself, with a log line, if there's no game piece to score. That way an auto that missed a piece doesn't sit waiting to score nothing.

{% hint style="warning" %}
Always give an auto's request a timeout: `superstructure.intakeUntilHolding().withTimeout(Seconds.of(3))`. A missed game piece should cost a second, not the rest of the auto.
{% endhint %}

## Requests aren't just for the superstructure

`Vision.ignore()` is a request too. While it runs, the drivetrain stops believing the Limelights. The driver toggles it with the View button, and autos hold it up for the whole autonomous period. See [Vision](https://docs.raidrobotics.org/commands-v3-state-machine/guide/vision.md#turning-vision-off).

## Why not just run the mechanism from the button?

Because then the button decides what the robot does, and so does the auto, and so does any other button that touches the same mechanism. With requests, the button only says what the driver **wants**. The state machine decides what the robot **does**, using the sensors and every other request at once. For example, holding the score button does nothing until the mechanism is actually in position: the state machine waits for `mechanism1.isAt(SCORE)` before it moves to SCORING.


---

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