Alerts.hpp

Go to the documentation of this file.

/*
 * Copyright (C) Cross The Road Electronics.  All rights reserved.
 * License information can be found in CTRE_LICENSE.txt
 * For support and suggestions contact support@ctr-electronics.com or file
 * an issue tracker at https://github.com/CrossTheRoadElec/Phoenix-Releases
 */
#pragma once
 
#include <optional>
#include <stdint.h>
#include <string>
#include <wpi/units/time.hpp>
 
namespace ctre {
namespace phoenix6 {
 
    /**
     * \brief Persistent alert with debouncing.
     *
     * On a FIRST robot controller, this shows up as a persistent
     * alert in the Driver Station and compatible NetworkTables
     * dashboards. Otherwise, this is a no-op.
     */
    class PhoenixAlert final {
    private:
        uint64_t handle{};
 
    public:
        /**
         * \brief Levels of urgency of the alert.
         */
        enum class Level {
            /** \brief High priority / Error */
            High = 0,
            /** \brief Medium priority / Warning */
            Medium = 1,
            /** \brief Low priority / Info */
            Low = 2,
        };
 
        /**
         * \brief Creates an invalid alert.
         */
        PhoenixAlert() = default;
 
        /**
         * \brief Creates a new alert.
         *
         * \param group Group identifier
         * \param id Alert identifier, unique within the group
         * \param level Alert urgency level
         * \param text Alert text to display when the alert is active
         */
        PhoenixAlert(char const *group, char const *id, Level level, char const *text = "");
 
        /**
         * \brief Creates a new alert.
         *
         * \param group Group identifier
         * \param id Alert identifier, unique within the group
         * \param level Alert urgency level
         * \param text Alert text to display when the alert is active
         */
        PhoenixAlert(std::string const &group, std::string const &id, Level level, std::string const &text = "") :
            PhoenixAlert{group.c_str(), id.c_str(), level, text.c_str()}
        {}
 
        /**
         * \returns Whether this alert is valid
         */
        bool IsValid() const { return !!handle; }
 
        /**
         * \returns Whether this alert is valid
         */
        explicit operator bool() const { return IsValid(); }
 
        /**
         * \brief Sets the time debounce of this alert, default 1 second.
         *
         * \param debounce Debounce time
         * \returns This alert
         */
        PhoenixAlert &WithDebounce(wpi::units::second_t debounce);
 
        /**
         * \brief Sets the alert state to active and optionally changes the text.
         * This should be called periodically, even if the active state does not
         * change.
         *
         * \param text New text to display
         */
        void SetActive(char const *text = nullptr);
 
        /**
         * \brief Sets the alert state to active and optionally changes the text.
         * This should be called periodically, even if the active state does not
         * change.
         *
         * \param text New text to display
         */
        void SetActive(std::optional<std::string> const &text)
        {
            SetActive(text ? text->c_str() : nullptr);
        }
 
        /**
         * \brief Sets the alert state to inactive.
         */
        void SetInactive();
    };
 
    /**
     * \brief Persistent multi-level alert with debouncing.
     *
     * On a FIRST robot controller, this shows up as a persistent
     * alert in the Driver Station and compatible NetworkTables
     * dashboards. Otherwise, this is a no-op.
     */
    class PhoenixMultiAlert final {
    private:
        uint64_t handle{};
 
    public:
        using Level = PhoenixAlert::Level;
 
        /** \brief Include High priority / Error */
        static constexpr uint32_t LevelFlag_High = 1 << (int)Level::High;
        /** \brief Include Medium priority / Warning */
        static constexpr uint32_t LevelFlag_Medium = 1 << (int)Level::Medium;
        /** \brief Include Low priority / Info */
        static constexpr uint32_t LevelFlag_Low = 1 << (int)Level::Low;
 
        /**
         * \brief Creates an invalid multi-level alert.
         */
        PhoenixMultiAlert() = default;
 
        /**
         * \brief Creates a new multi-level alert.
         *
         * \param group Group identifier
         * \param id Alert identifier, unique within the group
         * \param levelFlags Alert urgency levels to include
         * \param text Alert text to display when the alert is active
         */
        PhoenixMultiAlert(char const *group, char const *id, uint32_t levelFlags, char const *text = "");
 
        /**
         * \brief Creates a new multi-level alert.
         *
         * \param group Group identifier
         * \param id Alert identifier, unique within the group
         * \param levelFlags Alert urgency levels to include
         * \param text Alert text to display when the alert is active
         */
        PhoenixMultiAlert(std::string const &group, std::string const &id, uint32_t levelFlags, std::string const &text = "") :
            PhoenixMultiAlert{group.c_str(), id.c_str(), levelFlags, text.c_str()}
        {}
 
        /**
         * \returns Whether this alert is valid
         */
        bool IsValid() const { return !!handle; }
 
        /**
         * \returns Whether this alert is valid
         */
        explicit operator bool() const { return IsValid(); }
 
        /**
         * \brief Sets the time debounce of this alert, default 1 second.
         *
         * \param debounce Debounce time
         * \returns This alert
         */
        PhoenixMultiAlert &WithDebounce(wpi::units::second_t debounce);
 
        /**
         * \brief Sets the alert state to active at the given level and optionally changes
         * the text. This should be called periodically, even if the active state does not
         * change.
         *
         * \param level New alert urgency level
         * \param text New text to display
         */
        void SetActive(Level level, char const *text = nullptr);
 
        /**
         * \brief Sets the alert state to active at the given level and optionally changes
         * the text. This should be called periodically, even if the active state does not
         * change.
         *
         * \param level New alert urgency level
         * \param text New text to display
         */
        void SetActive(Level level, std::optional<std::string> const &text)
        {
            SetActive(level, text ? text->c_str() : nullptr);
        }
 
        /**
         * \brief Sets the alert state to inactive.
         */
        void SetInactive();
    };
 
}
}