AdvantageKit 2025: Log Replay, Streamlined

Technical Programming
1

AdvantageKit Banner
AdvantageKit Banner5635Ă—1024 448 KB

What is AdvantageKit?

AdvantageKit is a a logging, telemetry, and replay framework developed by Team 6328. AdvantageKit enables log replay, where the full state of the robot code can be replayed in simulation based on a log file (What is AdvantageKit?).

AdvantageKit is not a general-purpose logging framework. Users interested in traditional logging should use WPILib data logging or Epilogue.

To learn more, check out the documentation or take a look at our conference from the 2024 FIRST Championship:

We began our journey with AdvantageKit and log replay in 2021, and we’ve been excited to watch the community response over the past 3 years. AdvantageKit was used by 335 teams in 2024, and we’re grateful for all of the feedback and contributions we’ve received from our users.

Log Replay, Streamlined

The 2025 release of AdvantageKit brings some major updates to streamline the process of setting up and using log replay. The key features are highlighted below, or check the full changelog for details.

:house: All-New Template Projects

The AdvantageKit template projects have been reimagined from the ground up with improved features and documentation:

  • The reimagined swerve templates for robots based on the Spark and TalonFX support advanced features like high-frequency odometry, on-controller feedback loops, and automated characterization routines. The TalonFX version of the template now optionally integrates with CTRE’s swerve project generator for calibration.
  • The brand new vision template project demonstrates how AdvantageKit can be used to create a deterministic and replayable pose estimation pipeline, with support for high-frequency sampling, simulation with PhotonLib, and advanced filtering options.
  • All other template projects have been cleaned up and streamlined.
  • Every template project includes now detailed setup and tuning instructions, available here.

We recommend checking the documentation pages linked above for more information about the new features available in each template project.

Every AdvantageKit template is open-source and fully customizable:

  • No black boxes: Users can view and adjust all layers of the control stack, including advanced features of the swerve and vision templates.
  • Customizable: IO implementations can be adjusted to support any hardware configuration, including a combination of devices from multiple vendors.
  • Replayable: Every aspect of the control logic, pose estimation, etc. can be replayed and logged in simulation using AdvantageKit’s deterministic replay features with guaranteed accuracy.

:tada: No Shims

Since its initial release, AdvantageKit has relied on shimming some WPILib classes to enable deterministic replay. Thanks to a collaborative effort with the WPILib team, we are thrilled to announce that AdvantageKit no longer uses WPILib shims. Deterministic logging and replay is still fully supported with minimal changes to the user experience. See this page for details on the data available during replay.

...

No Shims

:stopwatch: Replay Watch

Replay watch is a new feature allowing rapid iteration of replayed code, taking advantage of AdvantageKit’s deterministic replay features to replay faster than real time without losing accuracy. The video below shows how replay watch can be used to rapidly iterate on simple code. Check the pose estimation example and documentation for more detail.

This update includes additional features to streamline the log replay process, even without replay watch:

  • Log files automatically open in AdvantageScope when replay completes. This behavior can be configured using the WPILOGWriter class.
  • The filenames for replayed logs use number indices when replaying multiple times (e.g. mylog_sim_2.wpilog instead of mylog_sim_sim.wpilog)

:clipboard: Record Logging

Custom record classes can be logged as structs, including support for single values and arrays as inputs or outputs. This enables efficient logging of custom complex data types, such as pose observations. Check the documentation for details.

Record Struct
Record Struct1438Ă—600 91 KB

Example Code

This code below shows how this feature is used in the new vision template for logging pose observations:

@AutoLog
public static class VisionIOInputs {
  public PoseObservation[] poseObservations = new PoseObservation[0];
}

public static record PoseObservation(
    double timestamp,
    Pose3d pose,
    double ambiguity,
    int tagCount,
    double averageTagDistance,
    PoseObservationType type) {}

public static enum PoseObservationType {
  MEGATAG_1,
  MEGATAG_2,
  PHOTONVISION
}

:1234: 2D Array Logging

In addition to single values and arrays, 2D arrays can now be logged as inputs or outputs. All data types supported by standard array logging also support 2D arrays, including primitives, structs, and records. Check the documentation for details.

Translation2d[][] visionSamples = new Translation2d[][] {
    new Translation2d[] { new Translation2d(), new Translation2d() },
    new Translation2d[] { new Translation2d(), new Translation2d() }
}

Logger.recordOutput("VisionSamples", visionSamples);

:rotating_light: Alerts Logging

The state of any alerts created through WPILib’s persistent alerts API will be automatically logged as outputs. These alerts can be visualized using AdvantageScope’s :chart_with_downwards_trend: Line Graph tab. Check the documentation for details.

Alerts Logging
Alerts Logging2142Ă—292 36.3 KB

:satellite: Radio Logging

Status data from the VH-109 radio is automatically logged as an output. This includes useful information about the connection status, bandwidth usage, etc. Check the documentation for details.

Radio Logging
Radio Logging2132Ă—1174 289 KB

:open_book: New Documentation Site

The AdvantageKit documentation has been updated to a modern look, with a reorganized layout and detailed template project documentation. The new documentation site also supports easier navigation via the sidebar, a built-in search feature, and a refined mobile interface. This documentation can be accessed at docs.advantagekit.org.

The new log replay comparison page breaks down AdvantageKit’s features and capabilities compared to similar logging tools like Hoot Replay.

Documentation Screenshot
Documentation Screenshot1920Ă—1160 133 KB

:construction: Build System Updates

AdvantageKit is currently transitioning to a new build system for library components, which will simplify development and the process of external contribution. We will have more updates to share soon. Additionally, AdvantageKit is in the process of moving Maven hosting from GitHub Packages to the WPILib Artifactory site. This change is intended to provide a more stable and seamless experience when installing and using AdvantageKit. AdvantageKit v4.0.0-beta-1 remains hosted on GitHub Packages, but look for updates soon.

What’s Next?

The AdvantageKit 2025 beta is now released! To get started, check out the installation guide. Projects based on AdvantageKit 2024 or the 2025 alpha cannot be directly upgraded, as this release includes significant changes to the project build. We highly recommend starting with one of the template projects and copying code as necessary from older versions.

THIS IS A BETA RELASE, which means that you will encounter issues not present in stable releases. Feedback, feature requests, and bug reports are welcome on the GitHub issues page. Keep an eye out for updates!

44 Likes
2

I aspire to be this good at release posts! :heart_eyes:

Good riddance to shimming! I am excited to see how this plays out this year!

4 Likes
3

Uh…

image
image1388Ă—792 112 KB

This is kind of funny; but is there anywhere the documentation is accessible other than docs.advantagekit.org because BU seems to think it’s dangerous? (I can connect from a personal hotspot but it’s more convenient to be able to access it normally).

EDIT: The markdown docs source is available at AdvantageKit/docs/docs at main · Mechanical-Advantage/AdvantageKit · GitHub.

1 Like
4

We’ve seen a couple of reports of advantagekit.org being blocked by firewalls because the domain was registered within the last few months. The markdown source can be accessed at the link you found, and it should also be possible to browse the site using a cellular hotspot. We expect the issue to clear up over time once the domain is no longer marked as recently registered.

5

Also having the same issue with the domain being blocked on the network im usually on (not my network). I also was able to fix it by switching to my personal cell hotspot. Although I just got a could not connect error

6

To be clear, this is a client-side blocking issue, not a problem with the documentation site (which has a current, valid certificate and is hosted through GitHub Pages).

The advantagescope.org and advantagekit.org domains were registered in mid September, 2024, and as @jonahb55 said some of the security appliance vendors by default block “newly registered domains” as they are frequently used by malicious actors. (Which, to be clear, we are not. :smirk: ) Since we are now several months past registration, hopefully we’re about past that window, but some filters may also block any sites with programming information as “hacking” by default.

We encourage anyone running into these issues to contact their IT or support department and ask that they unblock or whitelist these domains.

4 Likes
7

These templates are very dope. I’d been building out simulation stuff the last few months and you just… did everything I did, but better. Very excited.

Question about the TalonFX implementation. What would you say are the differences between this and the subsystem code generated by CTRE’s Swerve Generator? This definitely sticks to the IO paradigm, which keeps the architecture consistent across the app, as opposed to being a bit of an outlier in our code last year. I’m really just curious what you lose by using this. These days, the drivetrain is really, one of those things where I want to just “set it and forget it”.

2 Likes
8

The critical difference between the AdvantageKit template and CTRE’s swerve library is that our template allows the entire swerve stack to be accessed in replay. This includes the pose estimator, which is particularly useful for tuning in replay (especially with replay watch). The CTRE library needs to be isolated to an IO implementation, where elements like the pose estimator and kinematics can’t be debugged in replay (and of course, using it outside an IO implementation isn’t an option because that would break deterministic replay for the whole project).

The AdvantageKit code is designed to closely match the capabilities of the CTRE swerve code, with support for features like automatic calibration (with Tuner X), high-frequency odometry, on-controller PID, fused/sync/remote CANcoders, and CANivore time sync (for CANivore/Pheonix Pro users). It also includes a few features that aren’t part of the CTRE code, like on-robot feedforward and wheel radius characterization routines and integration with persistent alerts for disconnected devices. It can also be used with a combination of hardware from different vendors, such replacing the Pigeon 2 with a NavX (more complex changes require writing additional code, in line with the philosophy discussed below).

The biggest difference is that the projects have significantly different APIs, where the AdvantageKit template is focused around a relatively basic drive subsystem and includes several example commands (for field-relative drive and auto aiming). Our philosophy is to support all of the basics that teams have come to expect, but make the project as easy as possible to expand and customize (with no black boxes). This differs a bit from the apparent objectives of CTRE’s library, but we feel better it aligns with the goals of AdvantageKit and log replay (which is intended for experienced users who are interested in having more control).

One implementation difference between the CTRE and AdvantageKit code is that CTRE runs the kinematics and odometry thread in native code. Theoretically this is more performant, but we haven’t seen any evidence that it makes a difference for practical applications. The AdvantageKit templates perform very well even in pure Java, so I don’t think this should be a major consideration.

We have made every effort to maximize the stability and performance of the AdvantageKit swerve templates. They have been tested on the RIO 1 and RIO 2, and we’ve worked with several teams to alpha-test the projects before release. However, these are still beta releases and subject to change. As with any beta version, I would recommend waiting for the kickoff release if you’re particularly concerned about having a smooth experience.

7 Likes
9

I’m curious, why the switch to LoggedMechanism2d?
May have missed it, but I haven’t seen the reason in the docs.

10

This is related to the removal of shims. We need to be able to read the internal state of a Mechanism2d for logging, without relying on NetworkTables or the Sendable interface. This was previously achieved by adding additional methods to Mechanism2d and its related classes (which weren’t part of the standard interface). The simplest alternative is to provide our own versions of the classes for now, though we may revisit this in the future (especially with potential changes to Sendable under discussion).

The “logged” versions of these classes are identical to the WPILib implementations, so switching just requires swapping the class name and import path.

1 Like
11

Cool! I assumed there was some kind of change to be similar with the other Logged classes, but if that’s the case it’s not a problem.

12

The other logged classes are specifically used for input logging, so they essentially act as pre-built IO interfaces. Mechanism objects have always been used as outputs, so the implementation can almost entirely match the standard classes.

1 Like
13

Thanks for the thorough response! I definitely see the appeal. I think you’ve convinced me to give it a shot. Going to port over my sim project to this and check it out.

1 Like
14

What are some features of the CTRE project that the new AK template doesn’t include? I totally understand the logic here just wondering what, if anything, we’re missing out on by not using the CTRE project.

15

I’ll explain some of the nuances below, but the critical difference between these libraries is still the support for log replay. Users not interested in log replay should take advantage of another logging framework like Epilogue (and a different swerve template like CTRE’s), and users interested in log replay will see significant benefits from being able to replay the swerve stack with the AdvantageKit template. The other differences outlined below are relatively small compared to that key divide.

In terms of API differences, CTRE’s library is built around commanding “swerve requests” that include built-in controllers and kinematics. Built-in control requests also run at a higher frequency than the regular loop cycle, though as I said the benefits of this have yet to be demonstrated for typical use cases. The AdvantageKit template uses a different structure, where the drive subsystem has a generic setter that accepts a velocity setpoint (here). It includes a default set of commands for common tasks like field-oriented joystick drive, auto aiming, feedforward characterization, and wheel radius measurement. But the expectation is that the internals of these commands might be customized by the user, so they aren’t abstracted away as cleanly as CTRE’s API. I would encourage you to look through the AdvantageKit template and the docs for CTRE’s swerve requests if you’re curious about exactly what each provides out of the box, since there are overlaps and differences in both directions.

This is what I mean by a difference in philosophy; our goal is to provide a starting point that we expect users to customize, while CTRE’s apparent goal is to abstract away any complexity that most users won’t need to worry about. Both are valid approaches, but we feel the first is more fitting for the type of users already interested in log replay.

There are a couple of features that are intentionally omitted due to complexity, with the expectation that users who want them can integrate them as they see fit. This includes the coupling ratio (which our tests suggest has a negligible effect in most cases), a 254-style “swerve setpoint generator”, and more advanced physics simulation (such as maple-sim). I believe CTRE’s library includes the coupling ratio, but not the swerve setpoint generator or advanced simulation. Many of these potential additions are explained in the customization section of the documentation, along with related topics (like how to integrate with non-CTRE hardware).

The AdvantageKit template may also be slightly behind on supporting new hardware. For example, my understanding is that CTRE’s swerve library will be updated at some point to support the Talon FXS. We aren’t able to start developing these kinds of changes until CTRE releases their version (since we rely on their TunerConstants file), and our ability to test these hardware variants will be more limited. Thus, much of this falls under the same umbrella as custom hardware setups where we expect users who want to use bleeding-edge hardware to use our code as a starting point for customization.

7 Likes
16

Thanks for the detailed breakdown. I definitely appreciate the open source nature of AdvantageKit over the CTRE project, just making sure we’re not missing any “secret sauce” that would contribute to auto reliability or teleop responsiveness.
Thanks for all the hard work you put into this update!

1 Like
17

Hey jonah,

We don’t use akit but added radio logging to our code.
Is there a way to make it show up as json? Right now, it is showing up as a string for us(we use DogLog to log) and im wondering if there’s a way to set the entry tag to “json” like how akit does it. Thanks!\

Here’s our radio logging code:

18

I think you already got an answer, but NetworkTables has a standard json type that will be decoded by AdvantageScope. I’m not familiar enough with DogLog to comment on how to use it to publish specific NetworkTables types.

2 Likes
19

Just wondering, what exactly is the benefit of logging the Radio data? Do you think it can be used when making calls to the refs for disconnects or other things or is it just a useful source of data for system checks?

1 Like
20

AdvantageKit radio logging is absolutely not an official source of information that should be used in connection with referee calls on the field. It is primarily intended as a diagnostic source for teams while practicing, and may have some (unofficial) utility when debugging other radio issues on the field.

2 Likes