diff --git a/LUFA/Common/Common.h b/LUFA/Common/Common.h index f2e5e313dc..1e9e9663f5 100644 --- a/LUFA/Common/Common.h +++ b/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: " \ - "Assertion \"%s\" failed.\r\n"), \ - __FILE__, __func__, __LINE__, #x); } }MACROE + #define STDOUT_ASSERT(Condition) MACROS{ if (!(x)) { printf_P(PSTR("%s: Function \"%s\", Line %d: " \ + "Assertion \"%s\" failed.\r\n"), \ + __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 diff --git a/LUFA/Drivers/Board/Buttons.h b/LUFA/Drivers/Board/Buttons.h index d06781dbb9..e112683a84 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. * + * Example Usage: + * \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 31e3115960..d443c8f5ac 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. * + * Example Usage: + * \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 6bf7869473..f3c5c9d26e 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. * + * Example Usage: + * \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 a898be28bb..b05d55cf82 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. * + * Example Usage: + * \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 67d1054914..3c8028143c 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 8832c0c664..c8b36f5861 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. * + * Example Usage: + * \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 30493e33aa..af6a69f83f 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: + * Example Usage: * \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 f6673bc81b..e1cba16741 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: + * Example Usage: * \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 b0c6f3731a..0fba2d10eb 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 4790668cdb..3e736864ce 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. * + * Example Usage: + * \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 67171b3f27..c6fb420094 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. * + * Example Usage: + * \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 4e1fd09cea..ff45bc3ae4 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. * + * Example Usage: + * \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 2fca02b96c..f40201de50 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. * + * Example Usage: + * \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 87478ee2f2..bef52ac9ef 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. + * + * Example Usage: + * \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 c85440e449..e8cc834c83 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__ diff --git a/LUFA/ManPages/ChangeLog.txt b/LUFA/ManPages/ChangeLog.txt index 382e0ed4d3..106e7fef0f 100644 --- a/LUFA/ManPages/ChangeLog.txt +++ b/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 * * Changed: * - 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 diff --git a/Projects/TempDataLogger/Lib/DS1307.h b/Projects/TempDataLogger/Lib/DS1307.h index 87c6229f66..f069c2712a 100644 --- a/Projects/TempDataLogger/Lib/DS1307.h +++ b/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_WRITE 0b11010000 + #define DS1307_ADDRESS_READ (0xD0 | TWI_ADDRESS_READ) + #define DS1307_ADDRESS_WRITE (0xD0 | TWI_ADDRESS_WRITE) /* Function Prototypes: */ void DS1307_SetDate(const uint8_t Day,