AdvantageKit

AdvantageKit is a logging framework designed for FRC (FIRST Robotics Competition) robot code. Unlike traditional logging frameworks that record a limited set of user-defined values (like sensor data or PID errors), AdvantageKit records all data flowing into the robot code every loop cycle (e.g., every sensor value and button press).

Because AdvantageKit captures the complete input stream, it enables high-fidelity log replay. This allows developers to:

• Replay match data in a simulator to exactly replicate robot behavior.
• Log extra fields after a match has concluded.
• Modify control pipelines to see how they would have functioned during the actual match.
• Use logging as a safety net to verify any part of the code's logic by re-running it against recorded inputs.

AdvantageKit is a logging, telemetry, and replay framework designed for robotics. Its primary feature is log replay, which allows the full state of robot code to be replayed in a simulation environment using a recorded log file. This enables developers to debug robot behavior by running the exact same code in simulation that was used during a physical run.

AdvantageKit is often used alongside AdvantageScope, a telemetry application that can visualize data even if the robot code does not use AdvantageKit. For teams with simpler requirements, WPILib Data Logging is an alternative, though it does not support the log replay capability in simulation.

High-frequency odometry in AdvantageKit swerve templates allows data from drive motors, encoders, and gyros to be sampled at a rate significantly faster than the primary 50 Hz robot loop cycle (e.g., 250 Hz).

While the improvement in absolute mean error may be modest, the primary benefit is a massive reduction in standard deviation. In practical terms, this means that while an autonomous path might not end at a more 'accurate' coordinate, the robot will be much more consistent and precise across multiple runs, making robot behavior more predictable.

The SystemStats table in AdvantageKit now automatically tracks connected NetworkTables clients (such as dashboards and vision coprocessors). For every client, AdvantageKit logs:

• Connection status
• IP address
• Remote port
• Protocol version

This requires no additional logging in your user code.

AdvantageKit automatically logs many critical robot fields as inputs or outputs without requiring manual configuration.

Key Rules:

• Built-in inputs are available during replay with guaranteed accuracy and can be accessed in user code without manual logging.
• All other inputs (custom sensor data, etc.) must be logged using an IO interface.
• Built-in outputs are available under specific tables (e.g., RealOutputs, ReplayOutputs, RadioStatus) and can be visualized in AdvantageScope.

AdvantageKit automatically logs and replays several categories of inputs:

• Timestamp: Values from RobotController.getTime() and Timer.getTimestamp() are logged for deterministic replay.
  • Warning: Do not use RobotController.getMonotonicTime() or Timer.getMonotonicTimestamp() in user code; these provide real-time non-deterministic timestamps and should only be used in IO implementations or for profiling.
• Driver Station: All values from DriverStation or WPILib HID classes (Joystick, XboxController, etc.) are logged under the DriverStation table.
  • Danger: The waitForDsConnection method is incompatible with AdvantageKit.
• Dashboard Inputs: Inputs accessed via AdvantageKit dashboard classes are logged under the NetworkInputs table. See dashboard inputs documentation for details.

To ensure that log replay works correctly in simulation, the main robot code logic must remain single-threaded. Because thread execution timing cannot be consistently recreated in simulation, using extra threads in the main logic will cause discrepancies between real hardware and log replay.

Recommended Alternatives:

• Run control loops at a fixed frequency (e.g., 50Hz) within the main robot thread.
• Utilize the closed-loop features provided by your motor controllers.

If a thread is strictly necessary: Isolate the thread within an IO implementation. While high-frequency control loops or long-running tasks can exist within an IO implementation, they will not be recreated during log replay. The rest of the robot code will only see the values that are logged periodically via the IO layer.

The main Robot class must inherit from LoggedRobot instead of TimedRobot.

LoggedRobot behaves like TimedRobot but with two key differences:

1. It does not support adding extra periodic functions.
2. It provides the setUseTiming(boolean) method, which allows you to disable periodic timing to run cycles as fast as possible during replay. Even when timing is disabled, methods like Timer.getFPGATimestamp() will still return the correct timestamp from the real robot.

public class Robot extends LoggedRobot {
    ...
}

AdvantageKit stores data using string keys, where slashes (/) denote subtables (similar to NetworkTables).

Persistence Rule: All logged values are persistent. Once a value is logged, it will continue to appear in the log on subsequent cycles until it is explicitly updated with a new value.