Timing.hpp

#pragma once
/// \file Timing.hpp Header for the Timing functions of the BSP, including triggers and local time.

#include <cstdint>

namespace Bsp {
  namespace Timing {

    /// \brief Returns the number of internal triggers in the system.
    /// \return The number of internal triggers in the system.
    uint32_t GetNumberOfInternalTriggers(void);

    /// \brief Returns the number of external triggers in the system.
    /// \return The number of internal triggers in the system.
    uint32_t GetNumberOfExternalTriggers(void);

    /// \brief Returns the current system time.
    /// 
    /// This function must be thread safe.  It should read from a stable clock source that does
    /// not jump or change its rate.  It should not be affected by changes to the system time.
    /// \param [out] Seconds The number of seconds since the epoch.  This must be the same clock that
    /// the UdpInserter, Temperature, and Pose functions use to timestamp data.  Any epoch can
    /// be used (reboot, DLL load, etc.), but the same epoch must be used for all of these functions.
    /// \param [out] Microseconds The number of microseconds since the last second.
    void GetCurrentSystemTime(uint32_t& Seconds, uint32_t& Microseconds);

    /// \brief Configure one of the system's triggers.
    /// \param [in] ID The ID of the trigger to configure.  The first trigger is 1.
    /// \param [in] Mode The mode of the trigger (0 = disabled, 1 = unsynchronized,
    /// 2 = one-shot software, 3 = periodic software, 4 = one-shot hardware, 5 = periodic hardware).
    /// \param [in] ExternalID The ID of the external trigger to use.  The first external trigger is 1.
    /// Set to 0 for no external trigger.  Ignored if mode is not 4 or 5.
    /// \param [in] Period The period of the trigger in seconds.  Ignored if mode is not 3 or 5.
    /// \param [in] TrackingFactor The tracking factor of the trigger.  Ignored if mode is not 3 or 5.
    /// Value in range [0-1] telling fraction of discrepancy to correct when synchronizing with
    /// a new incoming trigger. A value of 1 completely synchronizes with each trigger.  A value
    /// of 0.1 shifts by 1 / 10th of the distance, smoothing the adjustment to handle jitter in
    /// the incoming hardware trigger while following long-time-scale drift.
    /// \return true if the trigger was successfully configured, false otherwise.
    bool ConfigureTrigger(uint16_t ID, uint8_t Mode, uint8_t ExternalID, double Period, float TrackingFactor);

    /// \brief Send a software trigger to the system.
    /// \param [in] ExternalID The ID of the trigger to send.  The first trigger is 1.
    /// \param [in] Seconds The time of the trigger in local clock time.
    /// \param [in] Microseconds The time of the trigger in local clock time.
    /// \return true if the trigger was successfully sent, false otherwise.
    bool SoftwareTrigger(uint8_t ExternalID, uint32_t Seconds, uint32_t Microseconds);

  }
}