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.

15 files changed, 251 insertions, 13 deletions

diff --git a/LUFA/Drivers/Board/Buttons.h b/LUFA/Drivers/Board/Buttons.h
index d06781dbb..e112683a8 100644
--- a/LUFA/Drivers/Board/Buttons.h
+++ b/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
+ * 
  *  @{
  */
 
diff --git a/LUFA/Drivers/Board/Dataflash.h b/LUFA/Drivers/Board/Dataflash.h
index 31e311596..d443c8f5a 100644
--- a/LUFA/Drivers/Board/Dataflash.h
+++ b/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);
 
diff --git a/LUFA/Drivers/Board/Joystick.h b/LUFA/Drivers/Board/Joystick.h
index 6bf786947..f3c5c9d26 100644
--- a/LUFA/Drivers/Board/Joystick.h
+++ b/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
+ *
  *  @{
  */
 
diff --git a/LUFA/Drivers/Board/LEDs.h b/LUFA/Drivers/Board/LEDs.h
index a898be28b..b05d55cf8 100644
--- a/LUFA/Drivers/Board/LEDs.h
+++ b/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
+ *
  *  @{
  */
 
diff --git a/LUFA/Drivers/Board/Temperature.c b/LUFA/Drivers/Board/Temperature.c
index 67d105491..3c8028143 100644
--- a/LUFA/Drivers/Board/Temperature.c
+++ b/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;
diff --git a/LUFA/Drivers/Board/Temperature.h b/LUFA/Drivers/Board/Temperature.h
index 8832c0c66..c8b36f586 100644
--- a/LUFA/Drivers/Board/Temperature.h
+++ b/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 -21
+			#define TEMP_TABLE_OFFSET_DEGREES   -21
 	#endif
 
 	/* Disable C linkage for C++ Compilers: */
diff --git a/LUFA/Drivers/Misc/RingBuffer.h b/LUFA/Drivers/Misc/RingBuffer.h
index 30493e33a..af6a69f83 100644
--- a/LUFA/Drivers/Misc/RingBuffer.h
+++ b/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--)

diff --git a/LUFA/Drivers/Misc/TerminalCodes.h b/LUFA/Drivers/Misc/TerminalCodes.h
index f6673bc81..e1cba1674 100644
--- a/LUFA/Drivers/Misc/TerminalCodes.h
+++ b/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
diff --git a/LUFA/Drivers/Peripheral/ADC.h b/LUFA/Drivers/Peripheral/ADC.h
index b0c6f3731..0fba2d10e 100644
--- a/LUFA/Drivers/Peripheral/ADC.h
+++ b/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__
diff --git a/LUFA/Drivers/Peripheral/AVRU4U6U7/ADC.h b/LUFA/Drivers/Peripheral/AVRU4U6U7/ADC.h
index 4790668cd..3e736864c 100644
--- a/LUFA/Drivers/Peripheral/AVRU4U6U7/ADC.h
+++ b/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
+ *
  *  @{
  */
 
diff --git a/LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h b/LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h
index 67171b3f2..c6fb42009 100644
--- a/LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h
+++ b/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.
diff --git a/LUFA/Drivers/Peripheral/SPI.h b/LUFA/Drivers/Peripheral/SPI.h
index 4e1fd09ce..ff45bc3ae 100644
--- a/LUFA/Drivers/Peripheral/SPI.h
+++ b/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
+ * 
  *  @{
  */
 
diff --git a/LUFA/Drivers/Peripheral/Serial.h b/LUFA/Drivers/Peripheral/Serial.h
index 2fca02b96..f40201de5 100644
--- a/LUFA/Drivers/Peripheral/Serial.h
+++ b/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
+ *
  *  @{
  */
 
diff --git a/LUFA/Drivers/Peripheral/SerialStream.h b/LUFA/Drivers/Peripheral/SerialStream.h
index 87478ee2f..bef52ac9e 100644
--- a/LUFA/Drivers/Peripheral/SerialStream.h
+++ b/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
- *  USART.
+ *  puts, etc.) to work with the USART. Upon configuration, this will redirect the standard input and output
+ *  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)
 			}
diff --git a/LUFA/Drivers/Peripheral/TWI.h b/LUFA/Drivers/Peripheral/TWI.h
index c85440e44..e8cc834c8 100644
--- a/LUFA/Drivers/Peripheral/TWI.h
+++ b/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__