Canandcolor.h

// Copyright (c) Redux Robotics and other contributors.
// This is open source and can be modified and shared under the 3-clause BSD license.
 
#pragma once
#include <cinttypes>
#include <mutex>
#include <condition_variable>
#include <optional>
#include <units/time.h>
#include <units/temperature.h>
#include "redux/canand/CanandDevice.h"
#include "redux/canand/CanandEventLoop.h"
#include "redux/canand/CanandSettingsManager.h"
#include "redux/frames/Frame.h"
 
#include "redux/sensors/canandcolor/CanandcolorData.h"
#include "redux/sensors/canandcolor/CanandcolorDetails.h"
#include "redux/sensors/canandcolor/CanandcolorDigout.h"
#include "redux/sensors/canandcolor/CanandcolorDigoutSlot.h"
#include "redux/sensors/canandcolor/CanandcolorProximityConfig.h"
#include "redux/sensors/canandcolor/CanandcolorSettings.h"
 
 
/**
 * Namespace for all classes relating to the Canandcolor
*/
namespace redux::sensors::canandcolor {
/**
 * Class for the CAN interface of the <a href="https://docs.reduxrobotics.com/canandcolor/index.html">Canandcolor.</a>
 * 
 * 
 * <p>
 * Operations that receive data from the device (proximity, color, faults, temperature) generally do not block. 
 * The object receives data asynchronously from the CAN packet receive thread and reads thus return the last data received.
 * </p>
 * <p>
 * Operations that set settings or change offsets will generally wait for up to 50ms by default as they will usually
 * wait for a confirmation packet to be received in response -- unless the blocking timeout is set to zero, in which case
 * the operations will not block.
 * </p>
 * 
 * Example code:
 * ```cpp
 * Canandcolor canandcolor{0}; // device id 0 
 * 
 * // Reading the Canandcolor
 * canandcolor.GetProximity(); // returns a proximity value [0..1). Larger values are distances closer to the sensor.
 * 
 * // these are all bounded [0..1)
 * canandcolor.GetRed();
 * canandcolor.GetGreen();
 * canandcolor.GetBlue();
 * canandcolor.GetWhite();
 * 
 * 
 * // Changing configuration
 * CanandcolorSettings settings{};
 * settings.SetProximityFramePeriod(10_ms); // set the proximity frame period to be sent every 10 ms
 * settings.SetColorFramePeriod(40_ms); // set the position frame period to be sent every 40 ms
 * settings.SetColorConfig(CanandcolorColorPeriod::k40ms); // set the color sensor integration to happen over 80 milliseconds
 * canandcolor.SetSettings(settings, 50_ms); // apply the new settings to the device, with maximum 50 ms timeout per settings op
 * 
 * // Faults
 * canandcolor.ClearStickyFaults(); // clears all sticky faults (including the power cycle flag). This call does not block.
 * 
 * // The power cycle flag will always be true on boot until the sticky faults have been cleared, 
 * // so if this is true the device has rebooted sometime between clearStickyFaults and now.
 * CanandcolorFaults faults = canandcolor.GetStickyFaults(); // fetches faults
 * fmt::print("Canandcolor rebooted: {}\n", faults.powerCycle);
 * 
 * // Timestamped data
 * redux::frames::FrameData<double> proxFrame = canandcolor.GetProximityFrame().GetFrameData(); // gets current proximity + timestamp together
 * proxFrame.GetValue(); // fetched position in rotations
 * proxFrame.GetTimestamp(); // timestamp of the previous position
 * ```
 */
class Canandcolor : public redux::canand::CanandDevice {
  protected:
 
    // internal state
    /** internal Frame variable holding current proximity state */
    redux::frames::Frame<double> proximity{0.0, 0_ms};
 
    /** internal Frame variable holding current color state */
    redux::frames::Frame<CanandcolorColorData> color{CanandcolorColorData{0.0, 0.0, 0.0, 0.0}, 0_ms};
 
    /** internal Frame variable holding current digital output state */
    redux::frames::Frame<digout::DigoutSlotState> digout{digout::DigoutSlotState{0}, 0_ms};
 
    /** internal Frame variable holding current status value state */
    redux::frames::Frame<CanandcolorStatus> status{CanandcolorStatus{0, 0, false, 0_degC}, 0_ms};
 
    /** internal settings manager */
    redux::canand::CanandSettingsManager<CanandcolorSettings> stg{*this};
 
  private:
 
    redux::canand::CanandAddress addr;
    units::second_t lastMessageTime{0_s};
  public:
 
    /**
     * Instantiates a new Canandcolor object. This object will be constant with respect to whatever CAN id assigned to it,
     * so if a device changes id it may change which device this object reads from.
     * @param canID the device id to use [0..63]
     */
    Canandcolor(int canID);
    inline ~Canandcolor() {redux::canand::RemoveCANListener(this);}
 
    /**
     * Gets the currently sensed proximity normalized between [0..1].
     * Proximity decreases as objects get further away from the sensor face and increases as they approach the sensor.
     * Proximities that are too close will saturate at 1.0.
     * 
     * <p>
     * Note that proximity is not given a unit as different materials and sensor configurations can greatly vary how proximity translates to actual distance. 
     * It is generally presumed that users will have to finetune specific thresholds for applications anyway and units may not be meaningful or accurate.
     * </p>
     * 
     * @return proximity value (range [0..1])
     */
    double GetProximity();
 
    /**
     * Red intensity, normalized [0..1) where 0 is none and 1 is as bright as possible.
     * @return red intensity [0..1)
     */
    double GetRed();
 
    /**
     * Green intensity, normalized [0..1) where 0 is none and 1 is as bright as possible.
     * @return green intensity [0..1)
     */
    double GetGreen();
 
    /**
     * Blue intensity, normalized [0..1) where 0 is none and 1 is as bright as possible.
     * @return blue intensity [0..1)
     */
    double GetBlue();
 
    /**
     * White intensity, normalized [0..1)
     * This can be used as a proxy for proximity at ranges too close for the normmal proximity sensor to give useful values.
     * @return absolute position in fraction of a rotation [0..1)
     */
    double GetWhite();
 
    /**
     * Returns a CanandcolorColorData object which can also convert to HSV.
     * @return color object
     */
    CanandcolorColorData GetColor();
 
    /**
     * Returns a DigoutSlotState object representing the current state of the digital outputs.
     * @return color object
     */
    digout::DigoutSlotState GetDigoutState();
 
    /**
     * Returns sticky faults.
     * Sticky faults are the active faults, except once set they do not become unset until ClearStickyFaults() 
     * is called.
     * 
     * @return CanandcolorFaults of the sticky faults.
     */
    CanandcolorFaults GetStickyFaults();
 
    /**
     * Returns an object representing currently active faults.
     * Active faults are only active for as long as the error state exists.
     * 
     * @return CanandcolorFaults of the active faults
     */
    CanandcolorFaults GetActiveFaults();
 
    /**
     * Get onboard device temperature readings in degrees Celsius.
     * @return temperature in degrees Celsius
     */
    units::celsius_t GetTemperature();
 
    /**
     * Clears sticky faults. 
     * 
     * <p>It is recommended to clear this during initialization, so one can check if the device loses power during operation later. </p>
     * <p>This call does not block, so it may take up to the next status frame (default every 1000 ms) for the sticky faults to be updated. To check for validity,
     * use CanandcolorFaults::FaultsValid() for faults returned by GetStickyFaults()</p>
     */
    void ClearStickyFaults();
 
    /**
     * Controls "party mode" -- an device identification tool that blinks the onboard LED
     * various colors at a user-specified strobe period.
     * The strobe period of the LED will be (50 milliseconds * level). Setting this to 0 disables party mode.
     * 
     * This function does not block.
     * 
     * @param level the party level value to set. 
     */
    void SetPartyMode(uint8_t level);
 
 
    /**
     * Fetches the Canandcolor's current configuration in a blocking manner.
     * This function will block for at up to 0.5 seconds waiting for the device to reply, so it is best
     * to put this in an init function, rather than the main loop.
     * 
     * @param timeout maximum number of seconds to wait for settings before giving up
     * @param missingTimeout maximum number of seconds to wait for each settings retry before giving up
     * @param attempts number of attempts to try and fetch values missing from the first pass
     * @return Received set of CanandcolorSettings of device configuration.
     */
    inline CanandcolorSettings GetSettings(units::second_t timeout = 500_ms, units::second_t missingTimeout = 50_ms, uint32_t attempts = 3) { 
        return stg.GetSettings(timeout, missingTimeout, attempts); 
    };
 
    /**
     * Sets whether or not the onboard lamp LED is to be powered.
     * 
     * <p><b>This value does not persist on device reboot!</b> 
     * Use CanandcolorSettings.SetLampLED and Canandcolor.SetSettings to set this persistently. <p>
     * 
     * <p> The LED can also be physically turned off regardless of setting with the onboard switch. </p>
     * 
     * <p> The LED is useful for measuring the color of objects that do not themselves emit light (e.g. most game pieces)
     * or for using the white channel to estimate very close proximity. </p>
     * 
     * By factory default the lamp is enabled.
     * @param lamp whether to enable or disable the lamp LED
     */
    void SetLampLED(bool lamp);
 
    /**
     * Sets the brightness of the onboard lamp LED.
     * 
     * <p><b>This value does not persist on device reboot!</b> 
     * Use CanandcolorSettings.SetLampLEDBrightness and Canandcolor.SetSettings to set this persistently.
     * </p>
     * By factory default this setting is set to max brightness (1.0)
     * @param brightness scaled brightness from 0.0 (off) to 1.0 (max brightness)
     */
    void SetLampLEDBrightness(double brightness);
 
    /**
     * Tells the Canandcolor to begin transmitting its settings; once they are all transmitted (after ~200-300ms),
     * the values can be retrieved from Canandcolor::GetSettingsAsync()
     */
    inline void StartFetchSettings() { return stg.StartFetchSettings(); };
 
    /**
     * Non-blockingly returns a CanandcolorSettings object of the most recent known settings values received from the device.
     *
     * <p> <b>Most users will probably want to use Canandcolor::GetSettings instead. </b> </p>
     * 
     * One can call this after a Canandcolor::StartFetchSettings() call, and use CanandcolorSettings::AllSettingsReceived()
     * to check if/when all values have been seen. As an example:
     * 
     * ```cpp
     * 
     * // somewhere in an init function
     * Canandcolor canandcolor{0};
     * canandcolor.StartFetchSettings();
     * 
     * // ...
     * // somewhere in a loop function
     * 
     * if (canandcolor.GetSettingsAsync().AllSettingsReceived()) {
     *   // do something with the settings object
     *   fmt::print("Canandcolor lamp enabled: {}\n", *canandcolor.GetSettingsAsync().GetLampLED());
     * }
     * ```
     * 
     * 
     * If this is called after Canandcolor::SetSettings(CanandcolorSettings), this method will return a settings object where only
     * the fields where the device has echoed the new values back will be populated. To illustrate this, consider the following:
     * ```cpp
     * // somewhere in an init function
     * Canandcolor canandcolor{0};
     * 
     * CanandcolorSettings stg{};
     * stg.SetProximityFramePeriod(0.1_s);
     * canandcolor.SetSettings(stg);
     * canandcolor.StartFetchSettings();
     * 
     * // right after the fetch...
     * canandcolor.GetSettingsAsync().GetProximityFramePeriod(); // will likely return nullopt as the device hasn't confirmed the previous transaction
     * 
     * // after up to ~300 ms...
     * canandcolor.GetSettingsAsync().GetProximityFramePeriod(); // will likely return 100 ms
     * ```
     * 
     * @return CanandcolorSettings object of known settings
     */
    inline CanandcolorSettings GetSettingsAsync() { return stg.GetKnownSettings(); }
 
    /**
     * Applies the settings from a CanandcolorSettings object to the device. 
     * For more information, see the CanandcolorSettings class documentation.
     * 
     * Example:
     * ```cpp
     * CanandcolorSettings stg;
     * Canandcolor color{0};
     * // After configuring the settings object...
     * 
     * CanandcolorSettings failed = color.SetSettings(stg); 
     * if (failed.IsEmpty()) {
     *     // success
     * } else {
     *     // handle failed settings
     * }
     * ```
     * 
     * @param settings the CanandcolorSettings to update the device with
     * @param timeout maximum time in seconds to wait for each setting to be confirmed (default 50 ms). Set to 0 to not check (and not block).
     * @param attempts the maxinum number of attempts to write each individual settings
     * @return CanandcolorSettings object of unsuccessfully set settings. 
     */
    inline CanandcolorSettings SetSettings(CanandcolorSettings& settings, units::second_t timeout = 50_ms, uint32_t attempts = 3) {
      return stg.SetSettings(settings, timeout, attempts);
    }
 
    /**
     * Sets an indexed slot on a Canandcolor digital output. 
     * 
     * These condition slots are used to determine the value of the digital outputs. 
     * For more information on how these slots work, see https://docs.reduxrobotics.com/canandcolor/programming/digital-ports.html
     * 
     * @param digout The digital output associated with the slot to write
     * @param slotIndex The index of the slot to write to (0-15)
     * @param slotConfig The actual slot data (see DigoutSlot)
     * @param timeout The timeout to wait for a confirmation message (default 50_ms, set to 0_s to not block)
     * @return whether or not the slot update was successful
     */
    bool SetDigoutSlot(CanandcolorDigout digout, uint8_t slotIndex, const digout::DigoutSlot& slotConfig, units::second_t timeout = 50_ms);
 
    /**
     * Fetches a digout slot's configuration.
     * 
     * These condition slots are used to determine the value of the digital outputs. 
     * For more information on how these slots work, see https://docs.reduxrobotics.com/canandcolor/programming/digital-ports.html
     * 
     * @param digout digital output associated with the slot to fetch from
     * @param slotIndex The index of the slot to fetch from (0-15)
     * @param timeout The timeout to wait for the slot to be retrieved (default 50_ms, set to 0_s to not block)
     * @return std::optional with DigoutSlot object on success, nullopt on failure
     */
    std::optional<digout::DigoutSlot> GetDigoutSlot(CanandcolorDigout digout, uint8_t slotIndex, units::second_t timeout = 50_ms);
    
    /**
     * Clears all configured "slots" on the specified digital output.
     * @param digout the digital output to clear slots on
     */
    void ClearAllDigoutSlots(CanandcolorDigout digout);
 
    /**
     * Resets the device to factory defaults, and then wait for all settings to be broadcasted back.
     * @param timeout how long to wait for the new settings to be confirmed by the device in seconds (suggested at least 0.35 seconds)
     * @return CanandcoderSettings object of received settings. Use AllSettingsReceived to verify success.
     */
    inline CanandcolorSettings ResetFactoryDefaults(units::second_t timeout = 500_ms) {
        return stg.SendReceiveSettingCommand(details::SettingCommand::kResetFactoryDefault, timeout, true);
    }
 
    /**
     * Returns the proximity reading frame.
     * @return the proximity reading frame, which will hold the current proximity in the same units as ::GetProximity()
     * @see Frame
     */
    inline redux::frames::Frame<double>& GetProximityFrame() { return proximity; }
 
    /**
     * Returns the color reading frame, which includes CAN timestamp data.
     * @return the color reading frame, which will hold timestamped color readings
     * @see Frame
     */
    inline redux::frames::Frame<CanandcolorColorData>& GetColorFrame() { return color; }
 
    /**
     * Returns the digital output state frame, which includes CAN timestamp data.
     * @return the digital output state frame 
     */
    inline redux::frames::Frame<digout::DigoutSlotState>& GetDigoutFrame() { return digout; }
 
    /**
     * Returns the current status frame, which includes CAN timestamp data.
     * FrameData objects are immutable.
     * @return the current status frame, as a CanandcolorStatus record.
     */
    inline redux::frames::Frame<CanandcolorStatus>& GetStatusFrame() { return status; }
 
    /* various behind the scenes stuff */
    void HandleMessage(redux::canand::CanandMessage& msg) override;
    redux::canand::CanandAddress& GetAddress() override;
    inline std::string GetDeviceClassName() override { return "Canandcolor"; };
    inline redux::canand::CanandFirmwareVersion GetMinimumFirmwareVersion() override { 
        return redux::canand::CanandFirmwareVersion{2024, 1, 0};
    }
 
};
}