Cleanup

Author: mikaelpatel

src/Button.h

@@ -22,18 +22,17 @@
 #include "GPIO.h"
 
 /**
- * Debounced input pin template class using GPIO. Internal pullup
+ * Debounced Input Pin template class using GPIO. The internal pullup
  * resistor is used. The button/switch should be connected to ground.
  * @param[in] PIN board pin for input signal.
  */
 template<BOARD::pin_t PIN>
 class Button {
 public:
   /**
-   * Construct debounced input pin (Button) instance with given
-   * template parameters. Initiate GPIO pins input mode with pullup
-   * resistor.
-   * @param[in] ms debouce time (Default 50 ms).
+   * Construct debounced input pin instance with given template
+   * parameters. Initiate GPIO pins input mode with pullup resistor.
+   * @param[in] ms debounce time limit (Default 50 ms).
    */
   Button(uint16_t ms = 50) :
     DEBOUNCE(ms),
@@ -44,18 +43,18 @@ class Button {
   }
 
   /**
-   * Return true(1) if button change was detected, otherwise false(0).
-   * Rising or falling edge is determined by reading the debounced pin
-   * state.
-   * @return true(1) if button change was detected, otherwise false(0).
+   * Return true(1) if a button state change was detected, otherwise
+   * false(0). Rising or falling edge is determined by reading the
+   * debounced pin state.
+   * @return bool.
    */
   bool ischanged()
   {
-    // Check debounce time has elapsed
+    // Check if debounce time limit has elapsed
     if (millis() - m_timestamp < DEBOUNCE) return (false);
     m_timestamp = millis();
 
-    // Check for pin state change
+    // Check for the pin state has changed
     bool state = m_pin;
     if (state == m_state) return (false);
     m_state = state;
@@ -100,7 +99,7 @@ class Button {
   /** Timestamp for latest pin read. */
   uint16_t m_timestamp;
 
-  /** Latest pin read. */
+  /** Latest pin read; debounced pin state. */
   bool m_state;
 };
 

src/Hardware/AVR/Board.h

@@ -1,6 +1,6 @@
 /**
  * @file Board.h
- * @version 1.5
+ * @version 1.6
  *
  * @section License
  * Copyright (C) 2017, Mikael Patel
@@ -33,15 +33,35 @@
  */
 #define GPIO_REG(pin) ((pin) >> 4)
 
-/** Maximum port control register address for atomic bit instructions. */
-#define GPIO_ATOMIC_MAX GPIO_PIN(0x40,0)
-
 /**
  * Return pin mask from board pin value.
  * @return pin mask
  */
 #define GPIO_MASK(pin) _BV((pin) & 0xf)
 
+/** Maximum port control register address for atomic bit instructions. */
+#define GPIO_ATOMIC_MAX GPIO_PIN(0x40,0)
+
+/**
+ * Forces given expression to be atomic. Higher port addresses
+ * cannot be accessed with a single instruction and require
+ * disabling of interrupts to become atomic.
+ * @param[in] expr expression to be atomic.
+ */
+#define GPIO_ATOMIC(expr)					\
+  do {								\
+    if (PIN < GPIO_ATOMIC_MAX) {				\
+      expr;							\
+    }								\
+    else {							\
+      uint8_t sreg = SREG;					\
+      __asm__ __volatile__("cli" ::: "memory");			\
+      expr;							\
+      SREG = sreg;						\
+      __asm__ __volatile__("" ::: "memory");			\
+    }								\
+  } while (0)
+
 #if defined(__AVR_ATmega168__) || defined(__AVR_ATmega328P__)
 /**
  * GPIO digital pin symbols for ATmega168/ATmega328P based boards.

src/Hardware/AVR/GPIO.h

@@ -1,6 +1,6 @@
 /**
  * @file Hardware/AVR/GPIO.h
- * @version 1.5
+ * @version 1.6
  *
  * @section License
  * Copyright (C) 2017, Mikael Patel
@@ -21,30 +21,10 @@
 
 #include "Hardware/AVR/Board.h"
 
-/**
- * Forces given expression to be atomic. Higher port addresses
- * cannot be accessed with a single instruction and require
- * disabling of interrupts to become atomic.
- * @param[in] expr expression to be atomic.
- */
-#define GPIO_ATOMIC(expr)					\
-  do {								\
-    if (PIN < GPIO_ATOMIC_MAX) {				\
-      expr;							\
-    }								\
-    else {							\
-      uint8_t sreg = SREG;					\
-      __asm__ __volatile__("cli" ::: "memory");			\
-      expr;							\
-      SREG = sreg;						\
-      __asm__ __volatile__("" ::: "memory");			\
-    }								\
-  } while (0)
-
 /**
  * General Purpose Digital I/O pin template class. Highly optimized
- * pin access. The PIN address is bit pointer to the port control
- * register and pin bit position. See Hardware/AVR/Board.h for details.
+ * pin access. The PIN address is a bit pointer to the port control
+ * register. See Hardware/AVR/Board.h for details.
  * @param[in] PIN board pin definition.
  */
 template<BOARD::pin_t PIN>

src/Hardware/SAM/Board.h

@@ -20,8 +20,8 @@
 #define HARDWARE_SAM_BOARD_H
 
 /**
- * Board pin values are bit-pointers and constructed from port control
- * register index and pin bit position.
+ * Board pin values are constructed from port control register index
+ * and pin bit position.
  * @param[in] index control register index.
  * @param[in] pin pin bit position in control register.
  */

src/Hardware/SAM/GPIO.h

@@ -23,7 +23,7 @@
 
 /**
  * General Purpose Digital I/O pin template class. Highly optimized
- * pin access. The PIN address is the port control register index and
+ * pin access. The PIN address is a port control register index and
  * pin bit position. See Hardware/SAM/Board.h for details.
  * @param[in] PIN board pin definition.
  */

src/SRPI.h

@@ -45,15 +45,16 @@ class SRPI {
    * Return deserialized value according to the template bit order
    * parameter. Generates a positive clock pulse for each bit
    * transfer.
-   * @param[out] value from data input signal.
+   * @return read byte.
    */
-  void operator>>(uint8_t& value)
+  uint8_t read()
   {
+    uint8_t res = 0;
     if (BITORDER == LSBFIRST) {
       uint8_t mask = 1;
       do {
 	m_clock.toggle();
-	value |= (m_data ? mask : 0);
+	res |= (m_data ? mask : 0);
 	m_clock.toggle();
 	mask <<= 1;
       } while (mask);
@@ -62,11 +63,21 @@ class SRPI {
       uint8_t mask = 0x80;
       do {
 	m_clock.toggle();
-	value |= (m_data ? mask : 0);
+	res |= (m_data ? mask : 0);
 	m_clock.toggle();
 	mask >>= 1;
       } while (mask);
     }
+    return (res);
+  }
+
+  /**
+   * Serial input operator. Shorthand for read().
+   * @param[out] value from data input signal.
+   */
+  void operator>>(uint8_t& value)
+  {
+    value = read();
   }
 
 protected:

src/SRPIO.h

@@ -47,7 +47,7 @@ class SRPIO {
    * parameter. Generate a positive clock pulse for each bit transfer.
    * @param[in] value to data output signal.
    */
-  void operator<<(uint8_t value)
+  void write(uint8_t value)
   {
     if (BITORDER == LSBFIRST) {
       uint8_t mask = 1;
@@ -70,13 +70,22 @@ class SRPIO {
     m_data.input();
   }
 
+  /**
+   * Serial output operator. Shorthand for write().
+   * @param[in] value to data output signal.
+   */
+  void operator<<(uint8_t value)
+  {
+    write(value);
+  }
+
   /**
    * Return deserialized value according to the template bit order
    * parameter. Generates a positive clock pulse for each bit
    * transfer.
-   * @param[out] value from data input signal.
+   * @return byte read from data input signal.
    */
-  void operator>>(uint8_t& value)
+  uint8_t read()
   {
     if (BITORDER == LSBFIRST) {
       uint8_t mask = 1;
@@ -98,6 +107,15 @@ class SRPIO {
     }
   }
 
+  /**
+   * Serial input operator. Shorthand for read().
+   * @param[out] value from data input signal.
+   */
+  void operator>>(uint8_t& value)
+  {
+    value = read();
+  }
+
 protected:
   GPIO<DATA_PIN> m_data;
   GPIO<CLOCK_PIN> m_clock;

src/SRPO.h

@@ -23,9 +23,9 @@
 
 /**
  * Shift Register Parallel Output (SRPO) template class using GPIO.
+ * @param[in] BITORDER LSBFIRST or MSBFIRST.
  * @param[in] DATA_PIN board pin for data output signal.
  * @param[in] CLOCK_PIN board pin for clock output signal.
- * @param[in] BIT_ORDER LSBFIRST or MSBFIRST.
  */
 template<uint8_t BITORDER, BOARD::pin_t DATA_PIN, BOARD::pin_t CLOCK_PIN>
 class SRPO {
@@ -46,7 +46,7 @@ class SRPO {
    * parameter. Generate a positive clock pulse for each bit transfer.
    * @param[in] value to data output signal.
    */
-  void operator<<(uint8_t value)
+  void write(uint8_t value)
   {
     if (BITORDER == LSBFIRST) {
       uint8_t mask = 1;
@@ -68,6 +68,15 @@ class SRPO {
     }
   }
 
+  /**
+   * Serial output operator. Shorthand for write().
+   * @param[in] value to data output signal.
+   */
+  void operator<<(uint8_t value)
+  {
+    write(value);
+  }
+
 protected:
   GPIO<DATA_PIN> m_data;
   GPIO<CLOCK_PIN> m_clock;

src/Software/Serial.h

@@ -32,7 +32,7 @@ class Serial : public ::Stream {
 public:
   /**
    * Construct Output only Software Serial instance with
-   * given template parameters. Initiate GPIO transit pin
+   * given template parameters. Initiate GPIO transmit pin
    * to output mode and set default baudrate (57600 bps).
    */
   Serial() :