SystemClock.h

/*
 * MIT License
 * Copyright (c) 2018 Brian T. Park
 */
 
#ifndef ACE_TIME_SYSTEM_CLOCK_H
#define ACE_TIME_SYSTEM_CLOCK_H
 
#include <stdint.h>
#include "Clock.h"
#include "../hw/ClockInterface.h"
 
class SystemClockCoroutineTest;
class SystemClockLoopTest;
class SystemClockLoopTest_loop;
class SystemClockLoopTest_setup;
class SystemClockLoopTest_backupNow;
class SystemClockLoopTest_syncNow;
class SystemClockLoopTest_getNow;
 
namespace ace_time {
namespace clock {
 
template <typename T_CI>
class SystemClockTemplate: public Clock {
  public:
    static const uint8_t kSyncStatusOk = 0;
 
    static const uint8_t kSyncStatusError = 1;
 
    static const uint8_t kSyncStatusTimedOut = 2;
 
    static const uint8_t kSyncStatusUnknown = 128;
 
    void setup() {
      if (mBackupClock != nullptr) {
        setNow(mBackupClock->getNow());
      }
    }
 
    acetime_t getNow() const override {
      if (!mIsInit) return kInvalidSeconds;
 
      // Update mEpochSeconds by the number of seconds elapsed according to the
      // millis(). This method is expected to be called multiple times a second,
      // so the while() loop below will normally execute 0 times, until the
      // millis() clock goes past the mPrevKeepAliveMillis by 1 second.
      //
      // There are 2 reasons why this method will be called multiple times a
      // second:
      //
      // 1) A physical clock with an external display will want to refresh
      // its display 5-10 times a second, so that it can capture the transition
      // from one second to the next without too much jitter. So it will call
      // this method multiple times a second to check if one second has passed.
      //
      // 2) If the SystemClockCoroutine or SystemClockLoop classes is used,
      // then the keepAlive() method will be called perhaps 100's times per
      // second, as fast as the iteration speed of the global loop() function.
      while ((uint16_t) ((uint16_t) clockMillis() - mPrevKeepAliveMillis)
          >= 1000) {
        mPrevKeepAliveMillis += 1000;
        mEpochSeconds += 1;
      }
 
      return mEpochSeconds;
    }
 
    void setNow(acetime_t epochSeconds) override {
      syncNow(epochSeconds);
 
      // Also set the reference clock if possible.
      if (mReferenceClock != nullptr) {
        mReferenceClock->setNow(epochSeconds);
      }
    }
 
    void forceSync() {
      if (mReferenceClock) {
        acetime_t nowSeconds = mReferenceClock->getNow();
        syncNow(nowSeconds);
      }
    }
 
    acetime_t getLastSyncTime() const {
      return mLastSyncTime;
    }
 
    uint8_t getSyncStatusCode() const { return mSyncStatusCode; }
 
    int32_t getSecondsSinceSyncAttempt() const {
      return (int32_t) (clockMillis() - mPrevSyncAttemptMillis) / 1000;
    }
 
    int32_t getSecondsToSyncAttempt() const {
      return (int32_t) (mNextSyncAttemptMillis - clockMillis()) / 1000;
    }
 
    int16_t getClockSkew() const {
      return mClockSkew;
    }
 
    bool isInit() const { return mIsInit; }
 
  protected:
    friend class ::SystemClockLoopTest;
    friend class ::SystemClockCoroutineTest;
    friend class ::SystemClockLoopTest_loop;
    friend class ::SystemClockLoopTest_syncNow;
    friend class ::SystemClockLoopTest_setup;
    friend class ::SystemClockLoopTest_backupNow;
    friend class ::SystemClockLoopTest_getNow;
 
    // disable copy constructor and assignment operator
    SystemClockTemplate(const SystemClockTemplate&) = delete;
    SystemClockTemplate& operator=(const SystemClockTemplate&) = delete;
 
    explicit SystemClockTemplate(
        Clock* referenceClock /* nullable */,
        Clock* backupClock /* nullable */
    ) :
        mReferenceClock(referenceClock),
        mBackupClock(backupClock) {}
 
    explicit SystemClockTemplate() {}
 
    void initSystemClock(
        Clock* referenceClock /* nullable */,
        Clock* backupClock /* nullable */
    ) {
      mReferenceClock = referenceClock;
      mBackupClock = backupClock;
 
      mEpochSeconds = kInvalidSeconds;
      mPrevSyncAttemptMillis = 0;
      mNextSyncAttemptMillis = 0;
      mPrevKeepAliveMillis = 0;
      mIsInit = false;
      mSyncStatusCode = kSyncStatusUnknown;
    }
 
    Clock* getReferenceClock() const { return mReferenceClock; }
 
    unsigned long clockMillis() const { return T_CI::millis(); }
 
    void keepAlive() {
      getNow();
    }
 
    void backupNow(acetime_t nowSeconds) {
      if (mBackupClock != nullptr) {
        mBackupClock->setNow(nowSeconds);
      }
    }
 
    void syncNow(acetime_t epochSeconds) {
      if (epochSeconds == kInvalidSeconds) return;
 
      mLastSyncTime = epochSeconds;
      acetime_t skew = mEpochSeconds - epochSeconds;
      mClockSkew = skew;
      if (skew == 0) return;
 
      mEpochSeconds = epochSeconds;
      mPrevKeepAliveMillis = clockMillis();
      mIsInit = true;
 
      if (mBackupClock != mReferenceClock) {
        backupNow(epochSeconds);
      }
    }
 
    void setNextSyncAttemptMillis(uint32_t ms) {
      mNextSyncAttemptMillis = ms;
    }
 
    void setPrevSyncAttemptMillis(uint32_t ms) {
      mPrevSyncAttemptMillis = ms;
    }
 
    void setSyncStatusCode(uint8_t code) {
      mSyncStatusCode = code;
    }
 
  private:
    Clock* mReferenceClock;
    Clock* mBackupClock;
 
    mutable acetime_t mEpochSeconds = kInvalidSeconds;
    acetime_t mLastSyncTime = kInvalidSeconds; // time when last synced
    uint32_t mPrevSyncAttemptMillis = 0;
    uint32_t mNextSyncAttemptMillis = 0;
    mutable uint16_t mPrevKeepAliveMillis = 0; // lower 16-bits of clockMillis()
    int16_t mClockSkew = 0; // diff between reference and this clock
    bool mIsInit = false; // true if setNow() or syncNow() was successful
    uint8_t mSyncStatusCode = kSyncStatusUnknown;
};
 
using SystemClock = SystemClockTemplate<hw::ClockInterface>;
 
}
}
 
#endif