Added basic driver example use code to the library documentation.

Made the USARTStream global public and documented in the SerialStream module, allowing for the serial USART stream to be accessed via its handle rather than via the implicit stdout and stdin streams.

LUFA/Common/Common.h

@@ -95,10 +95,12 @@
 			#define JTAG_DEBUG_BREAK()      __asm__ __volatile__ ("BREAK" ::)
 
 			/** Macro for testing condition "x" and breaking via JTAG_DEBUG_BREAK() if the condition is false.
+			 *
+			 *  \param[in] Condition  Condition that will be evaluated,
 			 *
 			 *  \ingroup Group_Debugging
 			*/
-			#define JTAG_DEBUG_ASSERT(x)    MACROS{ if (!(x)) { JTAG_DEBUG_BREAK(); } }MACROE
+			#define JTAG_DEBUG_ASSERT(Condition)    MACROS{ if (!(Condition)) { JTAG_DEBUG_BREAK(); } }MACROE
 
 			/** Macro for testing condition "x" and writing debug data to the stdout stream if false. The stdout stream
 			 *  must be pre-initialized before this macro is run and linked to an output device, such as the AVR's USART
@@ -106,11 +108,13 @@
 			 *
 			 *  The output takes the form "{FILENAME}: Function {FUNCTION NAME}, Line {LINE NUMBER}: Assertion {x} failed."
 			 *
+			 *  \param[in] Condition  Condition that will be evaluated,
+			 *
 			 *  \ingroup Group_Debugging
 			 */
-			#define STDOUT_ASSERT(x)        MACROS{ if (!(x)) { printf_P(PSTR("%s: Function \"%s\", Line %d: "   \
+			#define STDOUT_ASSERT(Condition)        MACROS{ if (!(x)) { printf_P(PSTR("%s: Function \"%s\", Line %d: "   \
-			                                             "Assertion \"%s\" failed.\r\n"),     \
+			                                                "Assertion \"%s\" failed.\r\n"),     \
-			                                             __FILE__, __func__, __LINE__, #x); } }MACROE
+			                                                __FILE__, __func__, __LINE__, #x); } }MACROE
 			
 			/** Forces GCC to use pointer indirection (via the AVR's pointer register pairs) when accessing the given
 			 *  struct pointer. In some cases GCC will emit non-optimal assembly code when accessing a structure through

LUFA/Drivers/Board/Buttons.h

@@ -60,6 +60,21 @@
  *
  *  For possible BOARD makefile values, see \ref Group_BoardTypes.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the button driver before first use
+ *      Buttons_Init();
+ *
+ *      printf("Waiting for button press...\r\n");
+ *
+ *      // Loop until a board button has been pressed
+ *      uint8_t ButtonPress;
+ *      while (!(ButtonPress = Buttons_GetStatus())) {};
+ *
+ *      // Display which button was pressed (assuming two board buttons)
+ *      printf("Button pressed: %s\r\n", (ButtonPress == BUTTONS_BUTTON1) ? "Button 1" : "Button 2");
+ *  \endcode
+ * 
  *  @{
  */
 

LUFA/Drivers/Board/Dataflash.h

@@ -59,6 +59,54 @@
  *
  *  For possible BOARD makefile values, see \ref Group_BoardTypes.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the SPI and board Dataflash drivers before first use
+ *      SPI_Init(SPI_SPEED_FCPU_DIV_2 | SPI_ORDER_MSB_FIRST | SPI_SCK_LEAD_FALLING |
+ *               SPI_SAMPLE_TRAILING | SPI_MODE_MASTER);
+ *      Dataflash_Init();
+ *
+ *      uint8_t WriteBuffer[DATAFLASH_PAGE_SIZE];
+ *      uint8_t ReadBuffer[DATAFLASH_PAGE_SIZE];
+ *
+ *      // Fill page write buffer with a repeating pattern
+ *      for (uint16_t i = 0; i < DATAFLASH_PAGE_SIZE; i++)
+ *        WriteBuffer[i] = (i & 0xFF);
+ *
+ *      // Must select the chip of interest first before operating on it
+ *      Dataflash_SelectChip(DATAFLASH_CHIP1);
+ *
+ *      // Write to the Dataflash's first internal memory buffer
+ *      printf("Writing data to first dataflash buffer:\r\n");
+ *      Dataflash_SendByte(DF_CMD_BUFF1WRITE);
+ *      Dataflash_SendAddressBytes(0, 0);
+ *
+ *      for (uint16_t i = 0; i < DATAFLASH_PAGE_SIZE; i++)
+ *        Dataflash_SendByte(WriteBuffer[i]);
+ *
+ *      // Commit the Dataflash's first memory buffer to the non-voltatile FLASH memory
+ *      printf("Committing page to non-volatile memory page index 5:\r\n");
+ *      Dataflash_SendByte(DF_CMD_BUFF1TOMAINMEMWITHERASE);
+ *      Dataflash_SendAddressBytes(5, 0);
+ *      Dataflash_WaitWhileBusy();
+ *
+ *      // Read the page from non-voltatile FLASH memory into the Dataflash's second memory buffer
+ *      printf("Reading data into second dataflash buffer:\r\n");
+ *      Dataflash_SendByte(DF_CMD_MAINMEMTOBUFF2);
+ *      Dataflash_SendAddressBytes(5, 0);
+ *      Dataflash_WaitWhileBusy();
+ *
+ *      // Read the Dataflash's second internal memory buffer
+ *      Dataflash_SendByte(DF_CMD_BUFF2READ);
+ *      Dataflash_SendAddressBytes(0, 0);
+ *
+ *      for (uint16_t i = 0; i < DATAFLASH_PAGE_SIZE; i++)
+ *        ReadBuffer[i] = Dataflash_ReceiveByte();
+ *
+ *      // Deselect the chip after use
+ *      Dataflash_DeselectChip();
+ *  \endcode
+ *
  *  @{
  */
 
@@ -97,7 +145,8 @@
 
 		/* Inline Functions: */
 			/** Initialises the dataflash driver so that commands and data may be sent to an attached dataflash IC.
-			 *  The AVR's SPI driver MUST be initialized before any of the dataflash commands are used.
+			 *
+			 *  \note The AVR's SPI driver must be initialized before any of the dataflash commands are used.
 			 */
 			static inline void Dataflash_Init(void);
 

LUFA/Drivers/Board/Joystick.h

@@ -59,6 +59,30 @@
  *
  *  For possible BOARD makefile values, see \ref Group_BoardTypes.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the board Joystick driver before first use
+ *      Joystick_Init();
+ *
+ *      printf("Waiting for joystick movement...\r\n");
+ *
+ *      // Loop until a the joystick has been moved
+ *      uint8_t JoystickMovement;
+ *      while (!(JoystickMovement = Joystick_GetStatus())) {};
+ *
+ *      // Display which direction the joystick was moved in
+ *      printf("Joystick moved:\r\n");
+ *      
+ *      if (JoystickMovement & (JOY_UP | JOY_DOWN))
+ *        printf("%s ", (JoystickMovement & JOY_UP) ? "Up" : "Down");
+ *
+ *      if (JoystickMovement & (JOY_LEFT | JOY_RIGHT))
+ *        printf("%s ", (JoystickMovement & JOY_LEFT) ? "Left" : "Right");
+ *
+ *      if (JoystickMovement & JOY_PRESSED)
+ *        printf("Pressed");
+ *  \endcode
+ *
  *  @{
  */
 

LUFA/Drivers/Board/LEDs.h

@@ -68,6 +68,29 @@
  *        compatible code for a board with no LEDs by making a board LED driver (see \ref Page_WritingBoardDrivers)
  *        which contains only stub functions and defines no LEDs.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the board LED driver before first use
+ *      LEDs_Init();
+ *
+ *      // Turn on each of the four LEDs in turn
+ *      LEDs_SetAllLEDs(LEDS_LED1); 
+ *      _delay_ms(500);
+ *      LEDs_SetAllLEDs(LEDS_LED1); 
+ *      _delay_ms(500);
+ *      LEDs_SetAllLEDs(LEDS_LED1); 
+ *      _delay_ms(500);
+ *      LEDs_SetAllLEDs(LEDS_LED1); 
+ *      _delay_ms(500);
+ *
+ *      // Turn on all LEDs
+ *      LEDs_SetAllLEDs(LEDS_ALL_LEDS);
+ *      _delay_ms(1000);
+ *
+ *      // Turn on LED 1, turn off LED 2, leaving LEDs 3 and 4 in their current state
+ *      LEDs_ChangeLEDs((LEDS_LED1 | LEDS_LED2), LEDS_LED1);
+ *  \endcode
+ *
  *  @{
  */
 

LUFA/Drivers/Board/Temperature.c

@@ -50,10 +50,10 @@ int8_t Temperature_GetTemperature(void)
 	if (Temp_ADC > pgm_read_word(&Temperature_Lookup[0]))
 	  return TEMP_MIN_TEMP;
 
-	for (uint16_t Index = 0; Index < TEMP_TABLE_SIZE; Index++)
+	for (uint16_t Index = 0; Index < (sizeof(Temperature_Lookup) / sizeof(Temperature_Lookup[0])); Index++)
 	{
 		if (Temp_ADC > pgm_read_word(&Temperature_Lookup[Index]))
-		  return (Index + TEMP_TABLE_OFFSET);
+		  return (Index + TEMP_TABLE_OFFSET_DEGREES);
 	}
 
 	return TEMP_MAX_TEMP;

LUFA/Drivers/Board/Temperature.h

@@ -47,6 +47,16 @@
  *  current temperature in degrees C. It is designed for and will only work with the temperature sensor located on the
  *  official Atmel USB AVR boards, as each sensor has different characteristics.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the ADC and board temperature sensor drivers before first use
+ *      ADC_Init(ADC_FREE_RUNNING | ADC_PRESCALE_128);
+ *      Temperature_Init();
+ *
+ *      // Display converted temperature in degrees Celcius
+ *      printf("Current Temperature: %d Degrees\r\n", Temperature_GetTemperature());
+ *  \endcode
+ * 
  *  @{
  */
 
@@ -110,8 +120,7 @@
 	/* Private Interface - For use in library only: */
 	#if !defined(__DOXYGEN__)
 		/* Macros: */
-			#define TEMP_TABLE_SIZE   (sizeof(Temperature_Lookup) / sizeof(Temperature_Lookup[0]))
+			#define TEMP_TABLE_OFFSET_DEGREES   -21
-			#define TEMP_TABLE_OFFSET -21
 	#endif
 
 	/* Disable C linkage for C++ Compilers: */

LUFA/Drivers/Misc/RingBuffer.h

@@ -56,7 +56,7 @@
  *  or deletions) must not overlap. If there is possibility of two or more of the same kind of
  *  operating occuring at the same point in time, atomic (mutex) locking should be used.
  *
- *  Example Usage:
+ *  <b>Example Usage:</b>
  *  \code
  *      // Create the buffer structure and its underlying storage array
  *      RingBuff_t Buffer;
@@ -76,7 +76,7 @@
  *      uint16_t BufferCount = RingBuffer_GetCount(&Buffer);
  *
  *      // Printer stored data length
- *      printf("Buffer Length: %d, Buffer Data:\r\n", BufferCount);
+ *      printf("Buffer Length: %d, Buffer Data: \r\n", BufferCount);
  *
  *      // Print contents of the buffer one character at a time
  *      while (BufferCount--)

LUFA/Drivers/Misc/TerminalCodes.h

@@ -49,7 +49,7 @@
  *        compiler via the -D switch to disable the terminal codes without modifying the source, for use with non
  *        compatible terminals (any terminal codes then equate to empty strings).
  *
- *  Example Usage:
+ *  <b>Example Usage:</b>
  *  \code
  *      printf("Some String, " ESC_BOLD_ON " Some bold string");
  *  \endcode

LUFA/Drivers/Peripheral/ADC.h

@@ -48,6 +48,9 @@
  *  Hardware ADC driver. This module provides an easy to use driver for the hardware
  *  ADC present on many AVR models, for the conversion of analogue signals into the
  *  digital domain.
+ *
+ *  \note The exact API for this driver may vary depending on the target used - see
+ *        individual target module documentation for the API specific to your target processor.
  */
 
 #ifndef __ADC_H__

LUFA/Drivers/Peripheral/AVRU4U6U7/ADC.h

@@ -47,6 +47,24 @@
  *  \note This file should not be included directly. It is automatically included as needed by the ADC driver
  *        dispatch header located in LUFA/Drivers/Peripheral/ADC.h.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the ADC driver before first use
+ *      ADC_Init(ADC_FREE_RUNNING | ADC_PRESCALE_32);
+ *
+ *      // Must setup the ADC channel to read beforehand
+ *      ADC_SetupChannel(1);
+ *
+ *      // Perform a single conversion of the ADC channel 1
+ *      ADC_GetChannelReading(ADC_REFERENCE_AVCC | ADC_RIGHT_ADJUSTED | ADC_CHANNEL1);
+ *      printf("Conversion Result: %d\r\n", ADC_GetResult());
+ *
+ *      // Start reading ADC channel 1 in free running (continuous conversion) mode
+ *      ADC_StartReading(ADC_REFERENCE_AVCC | ADC_RIGHT_ADJUSTED | ADC_CHANNEL1);
+ *      while (!(ADC_IsReadingComplete())) {};
+ *      printf("Conversion Result: %d\r\n", ADC_GetResult());
+ *  \endcode
+ *
  *  @{
  */
 

LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h

@@ -45,6 +45,37 @@
  *  \note This file should not be included directly. It is automatically included as needed by the TWI driver
  *        dispatch header located in LUFA/Drivers/Peripheral/TWI.h.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the TWI driver before first use
+ *      TWI_Init();
+ *
+ *      // Start a write session to device at address 0xA0 with a 10ms timeout
+ *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
+ *      {
+ *          TWI_SendByte(0x01);
+ *          TWI_SendByte(0x02);
+ *          TWI_SendByte(0x03);
+ *
+ *          // Must stop transmission afterwards to release the bus
+ *          TWI_StopTransmission();
+ *      }
+ *
+ *      // Start a read session to device at address 0xA0 with a 10ms timeout
+ *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10))
+ *      {
+ *          uint8_t Byte1, Byte2, Byte3;
+ *
+ *          // Read three bytes, acknowledge after the third byte is received
+ *          TWI_ReceiveByte(&Byte1, false);
+ *          TWI_ReceiveByte(&Byte2, false);
+ *          TWI_ReceiveByte(&Byte3, true);
+ *
+ *          // Must stop transmission afterwards to release the bus
+ *          TWI_StopTransmission();
+ *      }
+ *  \endcode
+ * 
  *  @{
  */
 
@@ -70,6 +101,17 @@
 		#endif
 
 	/* Public Interface - May be used in end-application: */
+		/* Macros: */
+			/** TWI slave device address mask for a read session. Mask with a slave device base address to obtain
+			 *  the correct TWI bus address for the slave device when reading data from it.
+			 */
+			#define TWI_ADDRESS_READ        0x00
+
+			/** TWI slave device address mask for a write session. Mask with a slave device base address to obtain
+			 *  the correct TWI bus address for the slave device when writing data to it.
+			 */
+			#define TWI_ADDRESS_WRITE       0x01
+	
 		/* Inline Functions: */
 			/** Initialises the TWI hardware into master mode, ready for data transmission and reception. This must be
 			 *  before any other TWI operations.

LUFA/Drivers/Peripheral/SPI.h

@@ -45,6 +45,26 @@
  *  Driver for the hardware SPI port available on most AVR models. This module provides
  *  an easy to use driver for the setup of and transfer of data over the AVR's SPI port.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the SPI driver before first use
+ *      SPI_Init(SPI_SPEED_FCPU_DIV_2 | SPI_ORDER_MSB_FIRST | SPI_SCK_LEAD_FALLING |
+ *               SPI_SAMPLE_TRAILING | SPI_MODE_MASTER);
+ *
+ *      // Send several bytes, ignoring the returned data
+ *      SPI_SendByte(0x01);
+ *      SPI_SendByte(0x02);
+ *      SPI_SendByte(0x03);
+ *
+ *      // Receive several bytes, sending a dummy 0x00 byte each time
+ *      uint8_t Byte1 = SPI_ReceiveByte();
+ *      uint8_t Byte2 = SPI_ReceiveByte();
+ *      uint8_t Byte3 = SPI_ReceiveByte();
+ *
+ *      // Send a byte, and store the received byte from the same transaction
+ *      uint8_t ResponseByte = SPI_TransferByte(0xDC);
+ *  \endcode
+ * 
  *  @{
  */
 

LUFA/Drivers/Peripheral/Serial.h

@@ -45,6 +45,18 @@
  *  Hardware serial USART driver. This module provides an easy to use driver for
  *  the setup of and transfer of data over the AVR's USART port.
  *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the serial USART driver before first use, with 9600 baud (and no double-speed mode)
+ *      Serial_Init(9600, false);
+ *
+ *      // Send a string through the USART
+ *      Serial_TxString("Test String\r\n");
+ *
+ *      // Receive a byte through the USART
+ *      uint8_t DataByte = Serial_RxByte();
+ *  \endcode
+ *
  *  @{
  */
 

LUFA/Drivers/Peripheral/SerialStream.h

@@ -47,8 +47,24 @@
  *  \section Module Description
  *  Serial stream driver for the USART subsystem on supported USB AVRs. This makes use of the functions in the
  *  regular USART driver (see \ref Group_Serial), but allows the avr-libc standard stream functions (printf,
- *  puts, etc.) to work with the
+ *  puts, etc.) to work with the USART. Upon configuration, this will redirect the standard input and output
- *  USART.
+ *  streams to the USART.
+ *
+ *  <b>Example Usage:</b>
+ *  \code
+ *      // Initialise the Serial Stream driver before first use, with 9600 baud (and no double-speed mode)
+ *      SerialStream_Init(9600, false);
+ *
+ *      // Write a string to the USART via the implicit stdout stream
+ *      printf("Test String using stdout\r\n");
+ *
+ *      // Write a string to the USART via the explicit USART stream
+ *      fprintf(&USARTStream, "Test String using explicit stream handle\r\n");
+ * 
+ *      // Read in an integer from the USART using the implicit stdin stream
+ *      uint16_t TestValue;
+ *      scanf("%d", &TestValue);
+ *  \endcode
  *
  *  @{
  */
@@ -69,9 +85,6 @@
 
 	/* Private Interface - For use in library only: */
 	#if !defined(__DOXYGEN__)
-		/* External Variables: */
-			extern FILE USARTStream;
-
 		/* Function Prototypes: */
 		#if defined(__INCLUDE_FROM_SERIALSTREAM_C)
 			static int SerialStream_TxByte(char DataByte,
@@ -105,6 +118,13 @@
 				Serial_ShutDown();
 			}
 
+		/* External Variables: */
+			/** Named stream for the USART, once \ref SerialStream_Init() has been called. This may be used with the
+			 *  file based stream functions (fprintf, fscanf, etc.) that require a handle to the stream rather than
+			 *  using the stdin and stdout named streams.
+			 */
+			extern FILE USARTStream;
+
 	/* Disable C linkage for C++ Compilers: */
 		#if defined(__cplusplus)
 			}

LUFA/Drivers/Peripheral/TWI.h

@@ -48,6 +48,9 @@
  *  \section Module Description
  *  Master Mode Hardware TWI driver. This module provides an easy to use driver for the hardware
  *  TWI present on many AVR models, for the transmission and reception of data on a TWI bus.
+ *
+ *  \note The exact API for this driver may vary depending on the target used - see
+ *        individual target module documentation for the API specific to your target processor.
  */
 
 #ifndef __TWI_H__

LUFA/ManPages/ChangeLog.txt

@@ -14,18 +14,19 @@
   *     in exchange for a smaller compiled program binary size
   *   - Added a new general RingBuff.h miscellaneous ring buffer library driver header
   *   - Added new GCC_FORCE_POINTER_ACCESS() macro to correct GCC's mishandling of struct pointer accesses
+  *   - Added basic driver example use code to the library documentation
   *  - Library Applications:
-  *   - Added new incomplete MIDIToneGenerator project
   *   - Added ability to write protect Mass Storage disk write operations from the host OS
-  *   - Added new RingBuffer_Peek() function to the lightweight ring buffer headers
   *
   *  <b>Changed:</b>
   *  - Core:
-  *   - Unordered Endpoint/Pipe configuration is now allowed once again via the previous reconfig workaround
+  *   - Unordered Endpoint/Pipe configuration is now allowed once again by default via the previous reconfig workaround
   *   - Refactored Host mode Class Driver *_Host_ConfigurePipes() routines to be more space efficient when compiled
   *   - Added new *_ENUMERROR_PipeConfigurationFailed error codes for the *_Host_ConfigurePipes() routines
+  *   - The USARTStream global is now public and documented in the SerialStream module, allowing for the serial USART
+  *     stream to be accessed via its handle rather than via the implicit stdout and stdin streams
   *  - Library Applications:
-  *   - Changed the XPLAINBridge software UART to use the regular CTC mode instead of the alternative CTC mode
+  *   - Changed the XPLAINBridge software UART to use the regular timer CTC mode instead of the alternative CTC mode
   *     via the Input Capture register, to reduce user confusion
   *   - Combined page and word ISP programming mode code in the AVRISP-MKII clone project to reduce compiled size and
   *     increase maintainability of the code

Projects/TempDataLogger/Lib/DS1307.h

@@ -96,8 +96,8 @@
 		#define DS1307_TIMEREG_START  0x00
 		#define DS1307_DATEREG_START  0x04
 
-		#define DS1307_ADDRESS_READ   0b11010001
+		#define DS1307_ADDRESS_READ   (0xD0 | TWI_ADDRESS_READ)
-		#define DS1307_ADDRESS_WRITE  0b11010000
+		#define DS1307_ADDRESS_WRITE  (0xD0 | TWI_ADDRESS_WRITE)
 
 	/* Function Prototypes: */
 		void DS1307_SetDate(const uint8_t Day,