allwpilib/wpilibc/src/main/native/include/frc/Alert.h

// Copyright (c) FIRST and other WPILib contributors.
// Open Source Software; you can modify and/or share it under the terms of
// the WPILib BSD license file in the root directory of this project.

#pragma once

#include <memory>
#include <string>
#include <vector>

#include <networktables/NTSendable.h>
#include <units/time.h>
#include <wpi/SmallVector.h>
#include <wpi/StringMap.h>
#include <wpi/sendable/SendableHelper.h>

namespace frc {

/**
 * Persistent alert to be sent via NetworkTables. Alerts are tagged with a type
 * of kError, kWarning, or kInfo to denote urgency. See Alert::AlertType for
 * suggested usage of each type. Alerts can be displayed on supported
 * dashboards, and are shown in a priority order based on type and recency of
 * activation.
 *
 * Alerts should be created once and stored persistently, then updated to
 * "active" or "inactive" as necessary. Set(bool) can be safely called
 * periodically.
 *
 * This API is new for 2025, but is likely to change in future seasons to
 * facilitate deeper integration with the robot control system.
 *
 * <pre>
 * class Robot {
 *   frc::Alert alert{"Something went wrong", frc::Alert::AlertType::kWarning};
 * }
 *
 * Robot::periodic() {
 *   alert.Set(...);
 * }
 * </pre>
 */
class Alert {
 public:
  /**
   * Represents an alert's level of urgency.
   */
  enum class AlertType {
    /**
     * High priority alert - displayed first on the dashboard with a red "X"
     * symbol. Use this type for problems which will seriously affect the
     * robot's functionality and thus require immediate attention.
     */
    kError,

    /**
     * Medium priority alert - displayed second on the dashboard with a yellow
     * "!" symbol. Use this type for problems which could affect the robot's
     * functionality but do not necessarily require immediate attention.
     */
    kWarning,

    /**
     * Low priority alert - displayed last on the dashboard with a green "i"
     * symbol. Use this type for problems which are unlikely to affect the
     * robot's functionality, or any other alerts which do not fall under the
     * other categories.
     */
    kInfo
  };

  /**
   * Creates a new alert in the default group - "Alerts". If this is the first
   * to be instantiated, the appropriate entries will be added to NetworkTables.
   *
   * @param text Text to be displayed when the alert is active.
   * @param type Alert urgency level.
   */
  Alert(std::string_view text, AlertType type);

  /**
   * Creates a new alert. If this is the first to be instantiated in its group,
   * the appropriate entries will be added to NetworkTables.
   *
   * @param group Group identifier, used as the entry name in NetworkTables.
   * @param text Text to be displayed when the alert is active.
   * @param type Alert urgency level.
   */
  Alert(std::string_view group, std::string_view text, AlertType type);

  /**
   * Sets whether the alert should currently be displayed. When activated, the
   * alert text will also be sent to the console. This method can be safely
   * called periodically.
   *
   * @param active Whether to display the alert.
   */
  void Set(bool active);

  /**
   * Updates current alert text. Use this method to dynamically change the
   * displayed alert, such as including more details about the detected problem.
   *
   * @param text Text to be displayed when the alert is active.
   */
  void SetText(std::string_view text);

 private:
  AlertType m_type;
  bool m_active = false;
  units::second_t m_activeStartTime;
  std::string_view m_text;

  class SendableAlerts : public nt::NTSendable,
                         public wpi::SendableHelper<SendableAlerts> {
   public:
    wpi::SmallVector<std::shared_ptr<Alert>> m_alerts;
    void InitSendable(nt::NTSendableBuilder& builder) override;

   private:
    std::vector<std::string> GetStrings(AlertType type) const;
  };

  static wpi::StringMap<SendableAlerts> groups;
};

}  // namespace frc