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

# Logging

The robot writes two kinds of log file. After a match, the pit crew uploads both to RAIDLogs, which reads them to find problems: brownouts, CAN errors, motors at their current limit, a driver request that nothing answered.

| File          | Written by                | Contains                                                                                                                                                                                                |
| ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`.wpilog`** | WPILib (`DataLogManager`) | Everything our code logs with `table.log(...)`, everything in NetworkTables (including each Limelight's table), and the Driver Station state. This is where **our** numbers go: states, targets, poses. |
| **`.hoot`**   | CTRE Phoenix, by itself   | Every signal of every CTRE device (position, current, temperature, faults, ...) at full rate, one file per CAN bus. We never log motor signals by hand.                                                 |

All of it is set up in `RobotLog.java`. Search the code for `LOGGING:` to find every place values are logged.

## How to log something

Each class that logs keeps one **table**, named after the class:

```java
private final TelemetryTable table = RobotLog.table("Mechanism1");   // once, as a field
table.log("Position (deg)", angle.in(Degrees));                      // every loop
RobotLog.event("Mechanism1 hit its soft limit");                     // when something happens
```

`table.log` shows the value live (in the simulator's **NetworkTables › Telemetry**, in Elastic, or in AdvantageScope) **and** saves it in the `.wpilog`. There's nothing else to do.

`RobotLog.event` writes a line with the time it happened, to the log and the console. Use it for things that happen once and matter later: a state change, an auto step, a sensor that stopped answering. Don't use it for values that change every loop.

### Rules of thumb

* **Log what the code decided** (state, target, "at target", "has game piece"). The `.hoot` file already has what the motors did.
* **Put the unit in the name**: `Position (deg)`, `Height (m)`.
* **One table per mechanism, named like its class.** RAIDSystems names mechanisms the same way, so the log, the schematic and the code all use one name.
* **Don't build strings every loop** (`"x=" + x`). Log the number.

## What RobotLog does

### At startup: `RobotLog.start()`

`Robot`'s constructor calls this first, so nothing that happens during startup is missed. It:

1. Starts the `.wpilog` with `DataLogManager.start()`, and logs all of NetworkTables.
2. Logs the Driver Station state: the control word, the opmode and the joysticks.
3. Creates the `DS:enabled` and `DS:autonomous` entries. RAIDLogs times everything from when the robot was enabled and looks for those names exactly. WPILib 2027 folded them into `DS:controlWord`, so the template writes them itself.
4. Writes a "Robot code started" event.

Where the `.wpilog` goes:

| Running on                                | Goes to                                            |
| ----------------------------------------- | -------------------------------------------------- |
| Robot, with a USB stick in the controller | The USB stick (preferred: pull it after the match) |
| Robot, no USB stick                       | The controller's own storage                       |
| Simulator                                 | The project's `logs/` folder                       |

The `.hoot` files start on their own when the robot is first enabled. To also catch the time before the first enable (for example, a device that browns out while the robot sits disabled on the field), uncomment `SignalLogger.start()` in `RobotLog.start()`.

### Every loop: `RobotLog.periodic()`

`Robot.robotPeriodic()` calls this last, every loop. It logs the robot-wide numbers:

| Entry                                                                    | Meaning                                     |
| ------------------------------------------------------------------------ | ------------------------------------------- |
| `DS:enabled`, `DS:autonomous`                                            | Written only when they change               |
| `Robot/LoopTimeMs`                                                       | How long this loop's code took              |
| `Robot/MatchTime (s)`                                                    | Match time remaining                        |
| `SystemStats/BatteryVoltage`                                             | Battery voltage                             |
| `SystemStats/BrownedOut`                                                 | Whether the controller is browned out       |
| `SystemStats/CPUTemp (C)`                                                | Controller CPU temperature                  |
| `SystemStats/CANBus/Utilization`                                         | Mechanism bus load, 0 to 1 (every 5th loop) |
| `SystemStats/CANBus/OffCount`, `ReceiveErrorCount`, `TransmitErrorCount` | Mechanism bus errors (every 5th loop)       |

Reading the CAN bus status isn't free, so it's done every 5th loop (10 times a second).

Add robot-wide values here as they come up, like which auto was picked, or whether the robot is in a manual override mode. Mechanism values belong in the mechanism.

## Drivetrain logging

`SwerveTelemetry` logs the drivetrain. The drivetrain calls `telemeterize(...)` every time its odometry updates; `Robot` hooks it up with `drivetrain.registerTelemetry(...)`.

| Entry                                          | Meaning                                                   |
| ---------------------------------------------- | --------------------------------------------------------- |
| `Drive/Pose`                                   | Where the robot thinks it is (wheels + gyro + Limelights) |
| `Drive/MeasuredSpeeds`                         | How fast it's really moving, from the wheel encoders      |
| `Drive/CommandedSpeeds`                        | How fast the code asked it to move                        |
| `Drive/Field`                                  | The same pose, as a field widget for the dashboard        |
| `Drive/OdometryPeriod (s)`, `Drive/FailedDaqs` | Health of the odometry thread                             |

Commanded versus measured speed is how RAIDLogs spots a drivetrain that isn't doing what it's told. The whole drive state also goes into the `.hoot` file (`DriveState`), time-aligned with the motor signals.

To see each module in AdvantageScope's swerve view, also log `ModuleStates` and `ModuleTargets`. The lines are in a comment in `SwerveTelemetry.java`.

## Names RAIDLogs looks for

RAIDLogs finds some entries by how their names **end**. Keep these exactly as written:

| Entry                                                                            | Logged in                                         |
| -------------------------------------------------------------------------------- | ------------------------------------------------- |
| `DS:enabled`, `DS:autonomous`                                                    | `RobotLog.java`                                   |
| `SystemStats/BatteryVoltage`, `SystemStats/BrownedOut`, `SystemStats/CANBus/...` | `RobotLog.java`                                   |
| `Robot/LoopTimeMs`                                                               | `RobotLog.java`                                   |
| `Superstructure/State`                                                           | `Superstructure.java`                             |
| `Drive/Pose`, `Drive/MeasuredSpeeds`, `Drive/CommandedSpeeds`                    | `SwerveTelemetry.java`                            |
| `/limelight.../...`                                                              | Each Limelight publishes it; logged automatically |

If a name must change, a programmer can map it by hand in **RAIDLogs › Event setup › Signals**. The full list of entries is in [Log entries](https://docs.raidrobotics.org/commands-v3-state-machine/reference/log-entries.md).

## After a match

1. Pull the USB stick (or download the logs from the controller).
2. Convert the `.hoot` files for RAIDLogs. In the RAIDLogs project, run:

   ```bash
   bun run hoots <folder>
   ```

   This uses CTRE's `owlet` tool.
3. Upload the `.wpilog`, the converted hoot files, and the Driver Station's `.dslog` to RAIDLogs.

## Custom values in the hoot file

Values that must line up exactly with a motor signal can go into the `.hoot` file too:

```java
SignalLogger.writeString("RobotLog", "started");
```

Use this sparingly. Everything else goes through `table.log(...)`.


---

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