Rephrased TimerState as class instead of struct

Author: simon

RTClib.cpp

@@ -1273,6 +1273,46 @@ void RTC_PCF8523::calibrate(Pcf8523OffsetMode mode, int8_t offset) {
 
 extern const Pcf8523TimerDetails timer_details_table[];
 
+/**************************************************************************/
+/*!
+    @brief  Constructor for timer, from member timer and interrupt fields
+
+    @param timer_value The starting countdown value of the timer, from 0-255
+    @param timer_freq The countdown clock frequency of the timer
+    @param timer_enabled Whether the timer is enabled
+    @param irupt_flag Whether the timer has completed since this flag was last
+           cleared
+    @param irupt_signal_enabled Whether the timer's interrupt drives its
+    @associated pin(s)
+
+    @note The irupt_flag can only be cleared or preserved, when set by a timer
+    going off; it cannot be set with a write, if unset.
+*/
+/**************************************************************************/
+Pcf8523TimerState::Pcf8523TimerState(uint8_t timer_value, PCF8523TimerClockFreq timer_freq, bool timer_enabled, bool irupt_flag, bool irupt_signal_enabled) {
+  value = timer_value;
+  freq = timer_freq;
+  enabled = timer_enabled;
+
+  this->irupt_flag = irupt_flag;
+  irupt_enabled = irupt_signal_enabled;
+}
+
+/**************************************************************************/
+/*!
+    @brief  Copy constructor.
+    @param copy Pcf8523TimerState to copy.
+*/
+/**************************************************************************/
+Pcf8523TimerState::Pcf8523TimerState(const Pcf8523TimerState &copy) {
+  value = copy.value;
+  freq = copy.freq;
+  enabled = copy.enabled;
+
+  irupt_flag = copy.irupt_flag;
+  irupt_enabled = copy.irupt_enabled;
+}
+
 /**************************************************************************/
 /*!
 
@@ -1324,16 +1364,16 @@ void RTC_PCF8523::write_irupt(Pcf8523Timer irupt, Pcf8523IruptState *src) {
 /**************************************************************************/
 /*!
 
-    @brief Programs the selected timer from the given TimerState struct.
+    @brief Programs the selected timer from the given TimerState object.
     @param timer Which timer to program.
-    @param src The TimerState struct that programs the timer.
+    @param src The TimerState object that programs the timer.
 
     @note If the interrupt enable field is set, the square wave/CLKOUT
     function will be disabled, and the SqwPinMode set to "OFF."
     Instead, the INT function will be used.
 */
 /**************************************************************************/
-void RTC_PCF8523::write_timer(Pcf8523Timer timer, Pcf8523TimerState *src) {
+void RTC_PCF8523::write_timer(Pcf8523Timer timer, const Pcf8523TimerState &src) {
   /* setup the given timer in TimerState src */
 
   const Pcf8523TimerDetails *details = &(timer_details_table[timer]);
@@ -1344,19 +1384,23 @@ void RTC_PCF8523::write_timer(Pcf8523Timer timer, Pcf8523TimerState *src) {
   write_PCF8523_register(details->timer_en_register, clkout_ctrl);
 
   // set the timer value and frequencies
-  write_PCF8523_register(details->timer_value_register, src->value);
-  write_PCF8523_register(details->timer_freq_register, (uint8_t) src->freq);
+  write_PCF8523_register(details->timer_value_register, src.value);
+  write_PCF8523_register(details->timer_freq_register, (uint8_t) src.freq);
 
   // set the irupt flag/enable bits -- delegate to other function
-  write_irupt(timer, &(src->irupt_state));
+  Pcf8523IruptState irupt;
+  irupt.irupt_flag = src.irupt_flag;
+  irupt.irupt_enabled = src.irupt_enabled;
+
+  write_irupt(timer, &irupt);
 
   // enable the timer, if set
-  if (src->enabled) {
+  if (src.enabled) {
     clkout_ctrl = read_PCF8523_register(details->timer_en_register);
 
     // turn off the CLKOUT function if the interrupt is enabled,
     // enable the timer
-    if (src->irupt_state.irupt_enabled) {
+    if (src.irupt_enabled) {
       clkout_ctrl |= PCF8523_CLKOUT_DIS;
     }
     clkout_ctrl |= details->timer_en_mask;
@@ -1368,28 +1412,37 @@ void RTC_PCF8523::write_timer(Pcf8523Timer timer, Pcf8523TimerState *src) {
 /**************************************************************************/
 /*!
 
-    @brief Reads the state of selected timer into the given TimerState struct.
+    @brief Reads the state of selected timer into the returned TimerState object.
     @param timer Which timer to read.
-    @param dest The TimerState struct where the current timer state is written.
+    @return TimerState The timer and interrupt current state
 */
 /**************************************************************************/
-void RTC_PCF8523::read_timer(Pcf8523Timer timer, Pcf8523TimerState *dest) {
+Pcf8523TimerState RTC_PCF8523::read_timer(Pcf8523Timer timer) {
   /* return the timer contents into TimerState */
 
   const Pcf8523TimerDetails *details = &(timer_details_table[timer]);
 
   // retrieve the timer enabled bit
   uint8_t clkout_ctrl = read_PCF8523_register(details->timer_en_register);
-  dest->enabled = clkout_ctrl & details->timer_en_mask;
+  const bool enabled = clkout_ctrl & details->timer_en_mask;
 
   // retrieve the frequency scalar from the timer's register
-  dest->freq = (PCF8523TimerClockFreq) read_PCF8523_register(details->timer_freq_register);
+  const PCF8523TimerClockFreq freq = (PCF8523TimerClockFreq) read_PCF8523_register(details->timer_freq_register);
 
   // retrieve the timer value from the timer's register
-  dest->value = read_PCF8523_register(details->timer_value_register);
+  const uint8_t value = read_PCF8523_register(details->timer_value_register);
 
   // read the irupt flag/enable bits -- delegate to other function
-  read_irupt(timer, &(dest->irupt_state));
+  Pcf8523IruptState irupt;
+  read_irupt(timer, &irupt);
+
+  return Pcf8523TimerState(
+    value,
+    freq,
+    enabled,
+    irupt.irupt_flag,
+    irupt.irupt_enabled
+    );
 }
 
 

RTClib.h

@@ -367,13 +367,30 @@ typedef struct {
   bool irupt_enabled;  ///< whether the flag state is tied to the interrupt pin state
 } Pcf8523IruptState;
 
-/** Current state of a timer */
-typedef struct {
+/**************************************************************************/
+/*!
+    @brief  Current state of a timer
+
+    This class can be read from or written into the RTC. An update can be done
+    by reading, modifying, and then writing.
+
+    This class stores basic information in its public members about the timer
+    and its interrupt status: its countdown value and frequency, whether it is
+    running (enabled); its interrupt flag, and whether the interrupt is set to
+    drive associated pins.
+*/
+/**************************************************************************/
+class Pcf8523TimerState {
+public:
+  Pcf8523TimerState(uint8_t timer_value, PCF8523TimerClockFreq timer_freq, bool timer_enabled, bool irupt_flag, bool irupt_signal_enabled);
+  Pcf8523TimerState(const Pcf8523TimerState &copy);
+
   bool enabled;   ///< whether the timer is running
   uint8_t value;  ///< the current value of the timer
   PCF8523TimerClockFreq freq;     ///< the clock divider used
-  Pcf8523IruptState irupt_state;  ///< the timer's interrupt state
-} Pcf8523TimerState;
+  bool irupt_flag;                ///< the interrupt flag
+  bool irupt_enabled;             ///< the interrupt signal enable
+};
 
 /* registers and masks for interacting with a timer */
 typedef struct {
@@ -417,8 +434,9 @@ class RTC_PCF8523 {
   void deconfigureAllTimers(void);
   void calibrate(Pcf8523OffsetMode mode, int8_t offset);
 
-  void write_timer(Pcf8523Timer timer, Pcf8523TimerState *src);
-  void read_timer(Pcf8523Timer timer, Pcf8523TimerState *dest);
+  void write_timer(Pcf8523Timer timer, const Pcf8523TimerState &src);
+  Pcf8523TimerState read_timer(Pcf8523Timer timer);
+
   void write_irupt(Pcf8523Timer irupt, Pcf8523IruptState *src);
   void read_irupt(Pcf8523Timer irupt, Pcf8523IruptState *dest);
 };

examples/pcf8523_monitor_timer/pcf8523_monitor_timer.ino

@@ -11,7 +11,6 @@
 #define MONITOR_PIN 5
 
 RTC_PCF8523 rtc;
-Pcf8523TimerState state;
 
 void setup () {
   Serial.begin(9600);
@@ -22,33 +21,19 @@ void setup () {
 
   pinMode(MONITOR_PIN, INPUT_PULLUP);
 
-  /*
-  struct type signatures:
+  Pcf8523TimerState state = Pcf8523TimerState(
+    10,     // timer value
+    PCF8523_FrequencySecond, // timer frequency
+    true,   // timer set to run
+    false,  // timer interrupt flag (when timer has gone off)
+    true    // timer flag -> signal enable
+  );
 
-  typedef struct {
-    bool irupt_flag;    // whether the timer has gone off
-    bool irupt_enabled; // whether the flag state is tied to the interrupt pin state
-  } Pcf8523IruptState;
-
-  typedef struct {
-    bool enabled;                  // whether the timer is running
-    uint8_t value;                 // the current value of the timer
-    Pcf8523FrequencyDivision freq; // the clock divider used
-    Pcf8523IruptState irupt_state; // the timer's interrupt state
-  } Pcf8523TimerState;
-  */
-
-  state.enabled = true;
-  state.value = 10;
-  state.freq = PCF8523_FrequencySecond;
-  state.irupt_state.irupt_flag = false;
-  state.irupt_state.irupt_enabled = true;
-
-  rtc.write_timer(PCF8523_Timer_Countdown_B, &state);
+  rtc.write_timer(PCF8523_Timer_Countdown_B, state);
 }
 
 void loop () {
-    rtc.read_timer(PCF8523_Timer_Countdown_B, &state);
+    Pcf8523TimerState state = rtc.read_timer(PCF8523_Timer_Countdown_B);
     Serial.print("timer value: ");
     Serial.print(state.value, DEC);
     Serial.print(", enabled: ");
@@ -57,9 +42,9 @@ void loop () {
     Serial.print(state.freq, DEC);
     Serial.println();
     Serial.print("irupt flag: ");
-    Serial.print(state.irupt_state.irupt_flag, DEC);
+    Serial.print(state.irupt_flag, DEC);
     Serial.print(", enabled: ");
-    Serial.print(state.irupt_state.irupt_enabled, DEC);
+    Serial.print(state.irupt_enabled, DEC);
     Serial.println();
 
     Serial.print("Interrupt pin: ");

examples/pcf8523_set_timer/pcf8523_set_timer.ino

@@ -6,7 +6,6 @@
 #include "RTClib.h"
 
 RTC_PCF8523 rtc;
-Pcf8523TimerState state;
 
 void setup () {
   Serial.begin(9600);
@@ -15,33 +14,19 @@ void setup () {
     while (1);
   }
 
-  /*
-  struct type signatures:
-
-  typedef struct {
-    bool irupt_flag;    // whether the timer has gone off
-    bool irupt_enabled; // whether the flag state is tied to the interrupt pin state
-  } Pcf8523IruptState;
-
-  typedef struct {
-    bool enabled;                  // whether the timer is running
-    uint8_t value;                 // the current value of the timer
-    Pcf8523FrequencyDivision freq; // the clock divider used
-    Pcf8523IruptState irupt_state; // the timer's interrupt state
-  } Pcf8523TimerState;
-  */
-
-  state.enabled = true;
-  state.value = 10;
-  state.freq = PCF8523_FrequencySecond;
-  state.irupt_state.irupt_flag = false;
-  state.irupt_state.irupt_enabled = true;
-
-  rtc.write_timer(PCF8523_Timer_Countdown_A, &state);
+  Pcf8523TimerState state = Pcf8523TimerState(
+    10,     // timer value
+    PCF8523_FrequencySecond, // timer frequency
+    true,   // timer set to run
+    false,  // timer interrupt flag (when timer has gone off)
+    true    // timer flag -> signal enable
+  );
+
+  rtc.write_timer(PCF8523_Timer_Countdown_A, state);
 }
 
 void loop () {
-    rtc.read_timer(PCF8523_Timer_Countdown_A, &state);
+    Pcf8523TimerState state = rtc.read_timer(PCF8523_Timer_Countdown_A);
 
     Serial.print("timer value: ");
     Serial.print(state.value, DEC);
@@ -52,9 +37,9 @@ void loop () {
     Serial.println();
 
     Serial.print("irupt flag: ");
-    Serial.print(state.irupt_state.irupt_flag, DEC);
+    Serial.print(state.irupt_flag, DEC);
     Serial.print(", enabled: ");
-    Serial.print(state.irupt_state.irupt_enabled, DEC);
+    Serial.print(state.irupt_enabled, DEC);
     Serial.println();
 
     Serial.println();