diff include/Utilities.h @ 72:d837fb676977

Documentation updates and include Arduino-type constants in Utilities.h

--- a/include/Utilities.h	Fri Jul 17 17:53:40 2015 +0100
+++ b/include/Utilities.h	Fri Jul 17 20:09:50 2015 +0100
@@ -15,6 +15,12 @@
 
 #include "BeagleRT.h"
 
+#define HIGH 0x1
+#define LOW  0x0
+
+#define INPUT 0x0
+#define OUTPUT 0x1
+
 /// Set the given bit in \c word to 1.
 #define setBit(word,bit) 			((word) | (1 << (bit)))
 
@@ -72,7 +78,7 @@
  * values are between 0 and 1, corresponding to the range 0 to 5V.
  *
  * Unlike analogWriteFrame(), the value written will affect \b only the frame specified, with
- * future values unchanged. This is more efficient than analogWriteFrame() so is better suited
+ * future values unchanged. This is faster than analogWriteFrame() so is better suited
  * to applications where every frame will be written to a different value. If
  * BEAGLERT_FLAG_ANALOG_OUTPUTS_PERSIST is not set within context->flags, then
  * analogWriteFrameOnce() and analogWriteFrame() are equivalent.
@@ -86,11 +92,94 @@
  */
 void analogWriteFrameOnce(BeagleRTContext *context, int frame, int channel, float value);
 
+/**
+ * \brief Read a digital input, specifying the frame number (when to read) and the pin.
+ *
+ * This function returns the value of a digital input, at the time indicated by \c frame.
+ * The value is 0 if the pin is low, and nonzero if the pin is high (3.3V).
+ *
+ * \param context The I/O data structure which is passed by BeagleRT to render().
+ * \param frame Which frame (i.e. what time) to read the digital input. Valid values range
+ * from 0 to (context->digitalFrames - 1).
+ * \param channel Which digital pin to read. 16 pins across the P8 and P9 headers of the
+ * BeagleBone Black are available. See the constants P8_xx and P9_xx defined in
+ * digital_gpio_mapping.h.
+ * \return Value of the digital input.
+ */
 int digitalReadFrame(BeagleRTContext *context, int frame, int channel);
+
+/**
+ * \brief Write a digital output, specifying the frame number (when to write) and the pin.
+ *
+ * This function sets the value of a digital output, at the time indicated by \c frame.
+ * A value of 0 sets the pin low; any other value sets the pin high (3.3V).
+ *
+ * The value written will persist for all future frames.
+ *
+ * \param context The I/O data structure which is passed by BeagleRT to render().
+ * \param frame Which frame (i.e. what time) to write the digital output. Valid values range
+ * from 0 to (context->digitalFrames - 1).
+ * \param channel Which digital output to write. 16 pins across the P8 and P9 headers of the
+ * BeagleBone Black are available. See the constants P8_xx and P9_xx defined in
+ * digital_gpio_mapping.h.
+ * \param value Value to write to the output.
+ */
 void digitalWriteFrame(BeagleRTContext *context, int frame, int channel, int value);
+
+/**
+ * \brief Write a digital output, specifying the frame number (when to write) and the pin.
+ *
+ * This function sets the value of a digital output, at the time indicated by \c frame.
+ * A value of 0 sets the pin low; any other value sets the pin high (3.3V).
+ *
+ * Unlike digitalWriteFrame(), the value written will affect \b only the frame specified, with
+ * future values unchanged. This is faster than digitalWriteFrame() so is better suited
+ * to applications where every frame will be written to a different value.
+ *
+ * \param context The I/O data structure which is passed by BeagleRT to render().
+ * \param frame Which frame (i.e. what time) to write the digital output. Valid values range
+ * from 0 to (context->digitalFrames - 1).
+ * \param channel Which digital output to write. 16 pins across the P8 and P9 headers of the
+ * BeagleBone Black are available. See the constants P8_xx and P9_xx defined in
+ * digital_gpio_mapping.h.
+ * \param value Value to write to the output.
+ */
 void digitalWriteFrameOnce(BeagleRTContext *context, int frame, int channel, int value);
 
+/**
+ * \brief Set the direction of a digital pin to input or output.
+ *
+ * This function sets the direction of a digital pin, at the time indicated by \c frame.
+ * Valid values are \c INPUT and \c OUTPUT. All pins begin as inputs by default.
+ *
+ * The value written will persist for all future frames.
+ *
+ * \param context The I/O data structure which is passed by BeagleRT to render().
+ * \param frame Which frame (i.e. what time) to set the pin direction. Valid values range
+ * from 0 to (context->digitalFrames - 1).
+ * \param channel Which digital output to write. 16 pins across the P8 and P9 headers of the
+ * BeagleBone Black are available. See the constants P8_xx and P9_xx defined in
+ * digital_gpio_mapping.h.
+ * \param value Direction of the pin (\c INPUT or \c OUTPUT).
+ */
 void pinModeFrame(BeagleRTContext *context, int frame, int channel, int mode);
+
+/**
+ * \brief Set the direction of a digital pin to input or output.
+ *
+ * This function sets the direction of a digital pin, at the time indicated by \c frame.
+ * Valid values are \c INPUT and \c OUTPUT. All pins begin as inputs by default.
+ *
+ * The value written will affect only the specified frame.
+ *
+ * \param context The I/O data structure which is passed by BeagleRT to render().
+ * \param frame Which frame (i.e. what time) to set the pin direction. Valid values range
+ * from 0 to (context->digitalFrames - 1).
+ * \param channel Which digital output to write. 16 pins across the P8 and P9 headers of the
+ * BeagleBone Black are available. See the constants P8_xx and P9_xx defined in
+ * digital_gpio_mapping.h.
+ * \param value Direction of the pin (\c INPUT or \c OUTPUT).
+ */
 void pinModeFrameOnce(BeagleRTContext *context, int frame, int channel, int mode);
 
 #else