Class MatchSummary

java.lang.Object
frc.spectrumLib.telemetry.MatchSummary
public final class MatchSummary extends Object
A short summary of the run, kept as it happens: battery, brownouts, loop overruns, CAN drops and reboots, Driver Station drops, vision counts, how auto went, alerts raised and peak motor temperatures. Every value is logged under Summary/... once a second, in every log.

In an FMS match (match type not NONE) the summary is also written as <log name>.summary.json next to the log, so the pit laptop and the log site can read it without parsing the log. It is written when auto ends, when the Driver Station drops, on an E-stop and when teleop ends, and each write replaces the last: the matches most worth a summary are the ones that never reach the end of teleop. Power is usually cut on the way off the field, so the file is written at once: the JSON is built on the main thread and a background thread writes it (tmp file, fsync, rename, folder fsync). Practice runs get the log keys only. The keys and the file are documented in docs/match-summary.md.

Everything is fed from logged inputs (motor inputs, the Driver Station, the robot clock, battery and brownout inputs the robot passes in, the controller's brownout fault count logged here as SummaryInputs/Brownout), so a replayed log recomputes the same summary. The scope is the whole log: one log is one boot, and the robot is powered off between matches.

Main thread only, apart from the file write. Per loop it is a few compares per registered device; logging is once a second.

  • Field Details

    • VERSION

      public static final int VERSION
      Bumped when a field changes meaning or is removed. Adding a field does not bump it.
      See Also:

    • LOW_VOLTS

      public static final double LOW_VOLTS
      Battery thresholds whose time below is totalled.
      See Also:

    • VERY_LOW_VOLTS

      public static final double VERY_LOW_VOLTS
      See Also:

  • Constructor Details

    • MatchSummary

      public MatchSummary(File logFolder)
      Creates the summary and starts listening for alerts. Create it early in the robot's constructor, on the main thread, so alerts raised while the robot starts are counted, and before the main thread is made real-time, since the file writer's thread starts here.
      Parameters:
      logFolder - the folder the log is written to, for the file; null for no file (replay)

  • Method Details

    • setBrownedOutAvailable

      public void setBrownedOutAvailable(boolean available)
      Says whether the browned-out flag passed to periodic(double, boolean) comes from an API that works here. Until this is called it is taken not to, and brownouts are counted only from the controller's fault count, or not at all.

    • addDevice

      public void addDevice(String name, String busLabel, BooleanSupplier connected, BooleanSupplier reset, DoubleSupplier tempCelsius)
      Tracks a CAN device: when it drops off and comes back, reboots, and its peak temperature. More than half the devices on a bus quiet at once counts as a drop of that bus.
      Parameters:
      name - shown in the summary
      busLabel - the bus, as its health is logged (e.g. CANivore)
      connected - the device's logged connected input
      reset - its logged reboot input, or null
      tempCelsius - its logged temperature, or null

    • addMechanism

      public void addMechanism(Mechanism mechanism, Function<String,String> busLabel)
      Tracks a mechanism's leader and followers from its MotorInputs. Does nothing for a mechanism with no hardware attached.
      Parameters:
      mechanism - the mechanism
      busLabel - turns a config's bus name into the label its health is logged under

    • addVisionSource

      public void addVisionSource(String name, LongSupplier accepted, LongSupplier rejected)
      Tracks a vision source's running accepted and rejected counts.
      Parameters:
      name - the source, e.g. LL-Back/MT2
      accepted - observations accepted since boot
      rejected - observations rejected since boot

    • autoStarted

      public void autoStarted(String routine)
      Records the auto routine that just started. Call from autonomousInit().
      Parameters:
      routine - its name

    • autoEnded

      public void autoEnded(String reason, double seconds)
      Records why the auto ended, as the robot's own auto tracking logged it, so the summary and that log agree. Main thread.
      Parameters:
      reason - the logged reason, recorded as is
      seconds - how long the auto ran

    • periodic

      public void periodic(double batteryVolts, boolean brownedOut)
      Advances every accumulator, logs the summary once a second, and on a loop that calls for the file (see MatchSummary.Write) hands it to the writer. Call once per loop, after the command scheduler, so this loop's motor inputs have been read and the auto's end has been reported.
      Parameters:
      batteryVolts - the logged battery voltage
      brownedOut - the logged brownout state (see setBrownedOutAvailable(boolean))