Document GpioInterface and GpioPin.

Author: dhebbeker

robot-control-src/GpioInterface.hpp

@@ -3,17 +3,70 @@
 
 #include <cstdint>
 
-class GpioInterface {
+/**
+ * Interface for digital input and output pins.
+ *
+ * Implementations may provide access to the pins of the microprocessor or
+ * external pins of IO-expanders.
+ *
+ * Parameters and return values are compatible to the Arduino library.
+ */
+class GpioInterface
+{
 public:
+	/**
+	 * Sets output value of the pin.
+	 * @param value may be HIGH or LOW (see Arduino.h)
+	 * @pre Configure the mode to OUTPUT using setMode().
+	 */
 	virtual void write(const std::uint8_t value) = 0;
+
+	/**
+	 * Reads the value of the pin.
+	 * @return Either HIGH or LOW (see Arduino.h).
+	 * @pre Configure the mode to INPUT or INPUT_PULLUP using setMode().
+	 */
 	virtual int read() = 0;
+
+	/**
+	 * Configures the pin to be either input or output.
+	 * @param mode INPUT, OUTPUT, or INPUT_PULLUP (see Arduino.h).
+	 */
 	virtual void setMode(const std::uint8_t mode) = 0;
 
-	virtual ~GpioInterface() {};
+	virtual ~GpioInterface() = default;
 };
 
+/** @name Digital I/O function overload for GpioInterface objects.
+ *
+ *  These functions provide an interface to GpioInterface objects compatible
+ *  to the Arduino library digital I/O functions.
+ */
+/** @{ */ /* Start group for digital I/O */
+
+/**
+ * Sets output value of the pin.
+ * @param gpio digital output pin
+ * @param value may be HIGH or LOW (see Arduino.h)
+ * @pre Configure the mode to OUTPUT using pinMode().
+ */
 void digitalWrite(GpioInterface& gpio, const std::uint8_t value);
+
+/**
+ * Reads the value of the pin.
+ * @param gpio digital input pin
+ * @return Either HIGH or LOW (see Arduino.h).
+ * @pre Configure the mode to INPUT or INPUT_PULLUP using pinMode().
+ */
 int digitalRead(GpioInterface& gpio);
+
+/**
+ * Configures the pin to be either input or output.
+ * @param gpio digital pin
+ * @param mode INPUT, OUTPUT, or INPUT_PULLUP (see Arduino.h).
+ */
 void pinMode(GpioInterface& gpio, const std::uint8_t mode);
 
+/** @} */ /* End group for digital I/O */
+
 #endif /* GPIOINTERFACE_HPP_ */

robot-control-src/GpioPin.hpp

@@ -1,77 +1,130 @@
-#ifndef ROBOT_CONTROL_SRC_DIGITALPIN_HPP_
-#define ROBOT_CONTROL_SRC_DIGITALPIN_HPP_
+#ifndef GPIOPIN_HPP_
+#define GPIOPIN_HPP_
 
 #include "GpioInterface.hpp"
 #include <Arduino.h>
 
+/**
+ * Extension of GpioInterface for the processors general purpose input/output pins.
+ *
+ * Adds method to set PWM duty cycle.
+ *
+ * @tparam PIN is the Arduino pin number
+ */
 template<std::uint8_t PIN>
-class DigitalPin: public GpioInterface {
+class GpioPin: public GpioInterface
+{
 public:
 	static constexpr std::uint8_t pin = PIN;
 
 	virtual int read() override
-	{
-		return readS();
-	}
-	virtual void setMode(const std::uint8_t mode) override
-	{
-		setModeS(mode);
-	}
-	virtual void write(const std::uint8_t value) override
-	{
-		writeS(value);
-	}
-	void setDutyCycle(const int dutyCycle) const
-	{
-		setDutyCycleS(dutyCycle);
-	}
-	static int readS()
 	{
 		return digitalRead(pin);
 	}
-	static void setModeS(const std::uint8_t mode)
+
+	virtual void setMode(const std::uint8_t mode) override
 	{
 		pinMode(pin, mode);
 	}
-	static void writeS(const std::uint8_t value)
+
+	virtual void write(const std::uint8_t value) override
 	{
 		digitalWrite(pin, value);
 	}
-	static void setDutyCycleS(const int dutyCycle)
+
+	/**
+	 * Sets PWM duty cycle.
+	 * @param dutyCycle between 0 and 255
+	 */
+	void setDutyCycle(const int dutyCycle) const
 	{
 		analogWrite(pin, dutyCycle);
 	}
 };
 
-template<std::uint8_t PIN>
-void analogWrite(const DigitalPin<PIN>& gpio, const int dutyCycle)
-{
-	analogWrite(gpio.pin, dutyCycle);
-}
+/* If digitalPinToInterrupt is defined as C preprocessor macro it needs to be
+ * undefined. digitalPinToInterrupt must be overloaded for GpioPin. This is
+ * not possible for macros.
+ */
+#if defined(digitalPinToInterrupt)
 
+/**
+ * Wrapper for digitalPinToInterrupt.
+ *
+ * Encapsulates the digitalPinToInterrupt functionality before it is undefined.
+ * In contrast to the C preprocessor macro this function can be overridden.
+ *
+ * @param pinNumber is the Arduino pin number
+ * @return interrupt number
+ */
 inline constexpr int digitalPinToInterruptWrapper(const int pinNumber)
 {
 	return digitalPinToInterrupt(pinNumber);
 }
 
+/* Undefine macro in order to enable function declaration with the same name. */
 #undef digitalPinToInterrupt
 
+/**
+ * Getter for the interrupt number for a digital input pin.
+ *
+ * This is an adapter to digitalPinToInterruptWrapper().
+ * @param pinNumber is the Arduino pin number
+ * @return interrupt number
+ */
 inline constexpr int digitalPinToInterrupt(const int pinNumber)
 {
 	return digitalPinToInterruptWrapper(pinNumber);
 }
 
+#endif /* defined(digitalPinToInterrupt) */
+
+/** @name Function overload for GpioPin objects.
+ *
+ *  These functions provide an interface to GpioPin objects compatible
+ *  to the Arduino library functions.
+ */
+/** @{ */ /* Start group for function overloads */
+
+/**
+ * Getter for the interrupt number for a digital input pin.
+ *
+ * This is an overload to digitalPinToInterrupt().
+ * @tparam PIN is the Arduino pin number
+ * @return interrupt number
+ */
 template<std::uint8_t PIN>
-int constexpr digitalPinToInterrupt(const DigitalPin<PIN>& gpio)
+int constexpr digitalPinToInterrupt(const GpioPin<PIN>& gpio)
 {
-	return digitalPinToInterruptWrapper(gpio.pin);
+	return digitalPinToInterrupt(gpio.pin);
 }
 
+/**
+ * Attach function to be called on external interrupt.
+ *
+ * @param gpio is the input pin to attach interrupt to
+ * @param interruptServiceRoutine is the function to be called when interrupt occurs
+ * @param mode may be LOW, CHANGE, RISING, FALLING (see Arduino.h)
+ * @tparam PIN is the Arduino pin number
+ */
 template<std::uint8_t PIN>
-void attachInterrupt(const DigitalPin<PIN>& gpio, void (* const interruptServiceRoutine)(void), const int mode)
+void attachInterrupt(const GpioPin<PIN>& gpio, void (* const interruptServiceRoutine)(void), const int mode)
 {
 	attachInterrupt(digitalPinToInterrupt(gpio.pin), interruptServiceRoutine, mode);
 }
 
+/**
+ * Sets PWM duty cycle to pin.
+ * @tparam PIN is the Arduino pin number
+ * @param gpio output pin to set duty cycle to.
+ * @param dutyCycle between 0 and 255
+ */
+template<std::uint8_t PIN>
+void analogWrite(const GpioPin<PIN>& gpio, const int dutyCycle)
+{
+	analogWrite(gpio.pin, dutyCycle);
+}
+
+/** @} */ /* End group for function overloads */
 
-#endif /* ROBOT_CONTROL_SRC_DIGITALPIN_HPP_ */
+#endif /* GPIOPIN_HPP_ */