TELEMETRY.md

Telemetry

Add gversion support

Gversion is a useful debugging tool run during the build process that generates metadata regarding the current version of the code base. It captures and stores information such as the source repository, branch, code version (e.g. git sha), build date, etc. These values are generated and stored as constants that can then be printed to the console or logged at runtime.

This information is useful if you want to know/confirm what code is actually deployed/running on the robot. Furthermore, if the information is added to logs captured during a match, the information can be used to pull the exact code base that was used for the match.

When working and testing multiple versions (branches) of code, it is common to accidently deploy the wrong code to the robot. Having the build information included as part of the software allows one to sanity check what is actually running.

One very important bit of informaton that gversion captures is the DIRTY field. When set to 1, it means that the code running on the robot has changes to files that are not under source control (untracked and/or uncommitted changes), so it won't be possible to recreate the build at a later time.

It is good practice to have all code deployed during competiton under source control (i.e. DIRTY=0)

Summary of changes:

1. .gitignore
   • Tell git to ignore the generated file: src/main/java/frc/robot/BuildConstants.java
   • We generally don't want to commit/track changes to files that are auto-generated during the build process
2. build.gradle
   1. Install the gversion plugin
   2. Configure the gversion options
      • Set the source directory to src/main/java
      • Set the class package to frc.robot
      • Set the generated class name to BuildConstants

Note: In this step, we are only generating the BuildConstants.java file. We actually use the information as part of the next step

Sample generated BuildConstants.java file:

package frc.robot;

/** Automatically generated file containing build version information. */
public final class BuildConstants {
  public static final String MAVEN_GROUP = "";
  public static final String MAVEN_NAME = "RomiReference2023";
  public static final String VERSION = "unspecified";
  public static final int GIT_REVISION = 10;
  public static final String GIT_SHA = "ca519191c35b21fb5342d3b9abae602a7997064a";
  public static final String GIT_DATE = "2023-05-21 20:36:49 EDT";
  public static final String GIT_BRANCH = "master";
  public static final String BUILD_DATE = "2023-05-21 22:07:58 EDT";
  public static final long BUILD_UNIX_TIME = 1684721278402L;
  public static final int DIRTY = 1;

  private BuildConstants() {}
}

Install AdvantageKit

AdvantageKit is an amazing tool that allows real-time logging of code deployed and running on a robot. AdvantageKit is a library that can be integrated with your code and runs on the actual robot. AdvantageScope is the accompanying tool that enables off-line analysis of the logged data in multiple ways. AdvantageScope runs on a computer and reads the logs generated by the robot.

Summary of changes:

1. .gitignore
   1. Tell git to ignore the generated files ending with: .wpilog
      • Most wpilog files are useful only during development/debugging. One exception is logs captured during an actual competition/match. It may be useful to save them for post-match analysis to debug/understand what happened
2. build.gradle
   1. Install the AdvantageKit library
3. Constants.java
   1. Add REPLAY_MODE build constant to control whether we are running a physical/simulation or playing back from an existing log file
4. Robot.java
   1. Replace the TimedRobot class with AdvantageKit's LoggedRobot class.
   2. Add the metadata values generated by gversion (BuildConstants.java) to the log
   3. Setup AdvantageKit replay, real-time, and simulation logging
5. vendordeps/AdvantageKit.json
   1. The AdvantageKit libraries

AdvantageKit-ify the Drivetrain subsystem

In order to capture the relevant data for each subsystem, AdvantageKit suggests an IO abstraction paradigm to separate out the interface from implementation.

This change is likely the most complicated looking one, but at the high-level, we take the existing Drivetrain.java and put the Romi low-level HW implementation specific (gyro, motor controllers, etc) portions into DriveRomi.java that implements a new common drivetrain interface that we define in DriveIO.java. The result is Drivetrain.java doesn't contain anything specific to the Romi hardware. However, the Drivetrain is aware of the high-level physical properties of the robot, such as the wheel diameter, track width, etc.

Summary of changes:

1. RobotContainer.java
   1. Create and pass a DriveIORomi instance to the new Drivetrain constructor
2. Drivetrain.java
   1. Update to use tje DriveIO interface
      • The DriveTrain constructor now takes in an object that implement the DriveIO interface
      • The class now includes a DriveIOInputs*AutoLogged* object that gets updated regularly in the periodic() function.
3. DriveIO.java
   1. Define a Drivetrain IO interface called DriveIO
      1. Define a DriveIOInputs class that defines all of the drivetrain measurements and values that we want to include in the log.
         • The class uses the @Autolog annotation which automatically generates the relevant AdvantageKit specific logging code.
         • The units of position are reported in radians, so there isn't an assumption on the wheel diameter. Radians can be converted as needed by the upper Drivetrain layer.
      2. Define public methods that allow us to read/write drivetrain specific information :
         • updateInputs(): called periodically by the drivetrain to update the measure values from the drivetrain (encoder values, gyro angles, etc)
         • setDriveVoltage(): sets the actual voltages of the left and right motors of the drivetrain
4. DriveIORomi.java
   1. Implement the Romi DriveIO interface called DriveIORomi
      • This is where the motors, gyros, and accelerometer HW is instantiated and initialized.