Add mechanism to control Shuffleboard recordings and add event markers (#1414)

wpilibc/src/main/native/include/frc/shuffleboard/RecordingController.h

@@ -0,0 +1,43 @@
+/*----------------------------------------------------------------------------*/
+/* Copyright (c) 2018 FIRST. All Rights Reserved.                             */
+/* Open Source Software - may be modified and shared by FRC teams. The code   */
+/* must be accompanied by the FIRST BSD license file in the root directory of */
+/* the project.                                                               */
+/*----------------------------------------------------------------------------*/
+
+#pragma once
+
+#include <memory>
+#include <string>
+
+#include <networktables/NetworkTable.h>
+#include <networktables/NetworkTableInstance.h>
+#include <wpi/SmallVector.h>
+#include <wpi/StringRef.h>
+
+#include "frc/shuffleboard/ShuffleboardEventImportance.h"
+
+namespace frc {
+namespace detail {
+
+class RecordingController final {
+ public:
+  explicit RecordingController(nt::NetworkTableInstance ntInstance);
+  virtual ~RecordingController() = default;
+
+  void StartRecording();
+  void StopRecording();
+  void SetRecordingFileNameFormat(wpi::StringRef format);
+  void ClearRecordingFileNameFormat();
+
+  void AddEventMarker(wpi::StringRef name, wpi::StringRef description,
+                      ShuffleboardEventImportance importance);
+
+ private:
+  nt::NetworkTableEntry m_recordingControlEntry;
+  nt::NetworkTableEntry m_recordingFileNameFormatEntry;
+  std::shared_ptr<nt::NetworkTable> m_eventsTable;
+};
+
+}  // namespace detail
+}  // namespace frc

wpilibc/src/main/native/include/frc/shuffleboard/Shuffleboard.h

@@ -9,6 +9,8 @@
 
 #include <wpi/StringRef.h>
 
+#include "frc/shuffleboard/RecordingController.h"
+#include "frc/shuffleboard/ShuffleboardEventImportance.h"
 #include "frc/shuffleboard/ShuffleboardInstance.h"
 
 namespace frc {
@@ -97,8 +99,77 @@ class Shuffleboard final {
    */
   static void DisableActuatorWidgets();
 
+  /**
+   * Starts data recording on the dashboard. Has no effect if recording is
+   * already in progress.
+   */
+  static void StartRecording();
+
+  /**
+   * Stops data recording on the dashboard. Has no effect if no recording is in
+   * progress.
+   */
+  static void StopRecording();
+
+  /**
+   * Sets the file name format for new recording files to use. If recording is
+   * in progress when this method is called, it will continue to use the same
+   * file. New recordings will use the format.
+   *
+   * <p>To avoid recording files overwriting each other, make sure to use unique
+   * recording file names. File name formats accept templates for inserting the
+   * date and time when the recording started with the {@code ${date}} and
+   * {@code ${time}} templates, respectively. For example, the default format is
+   * {@code "recording-${time}"} and recording files created with it will have
+   * names like {@code "recording-2018.01.15.sbr"}. Users are
+   * <strong>strongly</strong> recommended to use the {@code ${time}} template
+   * to ensure unique file names.
+   * </p>
+   *
+   * @param format the format for the
+   */
+  static void SetRecordingFileNameFormat(wpi::StringRef format);
+
+  /**
+   * Clears the custom name format for recording files. New recordings will use
+   * the default format.
+   *
+   * @see #setRecordingFileNameFormat(String)
+   */
+  static void ClearRecordingFileNameFormat();
+
+  /**
+   * Notifies Shuffleboard of an event. Events can range from as trivial as a
+   * change in a command state to as critical as a total power loss or component
+   * failure. If Shuffleboard is recording, the event will also be recorded.
+   *
+   * <p>If {@code name} is {@code null} or empty, no event will be sent and an
+   * error will be printed to the driver station.
+   *
+   * @param name        the name of the event
+   * @param description a description of the event
+   * @param importance  the importance of the event
+   */
+  static void AddEventMarker(wpi::StringRef name, wpi::StringRef description,
+                             ShuffleboardEventImportance importance);
+
+  /**
+   * Notifies Shuffleboard of an event. Events can range from as trivial as a
+   * change in a command state to as critical as a total power loss or component
+   * failure. If Shuffleboard is recording, the event will also be recorded.
+   *
+   * <p>If {@code name} is {@code null} or empty, no event will be sent and an
+   * error will be printed to the driver station.
+   *
+   * @param name        the name of the event
+   * @param importance  the importance of the event
+   */
+  static void AddEventMarker(wpi::StringRef name,
+                             ShuffleboardEventImportance importance);
+
  private:
   static detail::ShuffleboardInstance& GetInstance();
+  static detail::RecordingController& GetRecordingController();
 
   // TODO usage reporting
 

wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardEventImportance.h

@@ -0,0 +1,36 @@
+/*----------------------------------------------------------------------------*/
+/* Copyright (c) 2018 FIRST. All Rights Reserved.                             */
+/* Open Source Software - may be modified and shared by FRC teams. The code   */
+/* must be accompanied by the FIRST BSD license file in the root directory of */
+/* the project.                                                               */
+/*----------------------------------------------------------------------------*/
+
+#pragma once
+
+namespace frc {
+
+// Maintainer note: this enum is mirrored in WPILibJ and in Shuffleboard
+// Modifying the enum or enum strings requires a corresponding change to the
+// Java enum and the enum in Shuffleboard
+
+enum ShuffleboardEventImportance { kTrivial, kLow, kNormal, kHigh, kCritical };
+
+inline wpi::StringRef ShuffleboardEventImportanceName(
+    ShuffleboardEventImportance importance) {
+  switch (importance) {
+    case kTrivial:
+      return "TRIVIAL";
+    case kLow:
+      return "LOW";
+    case kNormal:
+      return "NORMAL";
+    case kHigh:
+      return "HIGH";
+    case kCritical:
+      return "CRITICAL";
+    default:
+      return "NORMAL";
+  }
+}
+
+}  // namespace frc