Added new high level TWI packet read/write commands, altered behaviour of the TWI_StartTransmission() function.

Spell check source code files.

2 files changed, 174 insertions, 25 deletions

diff --git a/LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h b/LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h
index 2408ad15f..499fc4d99 100644
--- a/LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h
+++ b/LUFA/Drivers/Peripheral/AVRU4U6U7/TWI.h
@@ -49,13 +49,16 @@
  *  The following snippet is an example of how this module may be used within a typical
  *  application.
  *
+ *  <b>Low Level API Example:</b>
  *  \code
  *      // Initialise the TWI driver before first use
  *      TWI_Init();
  *
- *      // Start a write session to device at address 0xA0 with a 10ms timeout
+ *      // Start a write session to device at device address 0xA0, internal address 0xDC with a 10ms timeout
  *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
  *      {
+ *          TWI_SendByte(0xDC);
+ *
  *          TWI_SendByte(0x01);
  *          TWI_SendByte(0x02);
  *          TWI_SendByte(0x03);
@@ -64,21 +67,47 @@
  *          TWI_StopTransmission();
  *      }
  *
- *      // Start a read session to device at address 0xA0 with a 10ms timeout
- *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10))
+ *      // Start a read session to device at address 0xA0, internal address 0xDC with a 10ms timeout
+ *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
  *      {
- *          uint8_t Byte1, Byte2, Byte3;
+ *          TWI_SendByte(0xDC);
+ *          TWI_StopTransmission();
  *
- *          // Read three bytes, acknowledge after the third byte is received
- *          TWI_ReceiveByte(&Byte1, false);
- *          TWI_ReceiveByte(&Byte2, false);
- *          TWI_ReceiveByte(&Byte3, true);
+ *          if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10))
+ *          {
+ *              uint8_t Byte1, Byte2, Byte3;
  *
- *          // Must stop transmission afterwards to release the bus
- *          TWI_StopTransmission();
+ *              // 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
  * 
+ *  <b>High Level API Example:</b>
+ *  \code
+ *      // Initialise the TWI driver before first use
+ *      TWI_Init();
+ *
+ *      // Start a write session to device at device address 0xA0, internal address 0xDC with a 10ms timeout
+ *      uint8_t InternalWriteAddress = 0xDC;
+ *      uint8_t WritePacket[3] = {0x01, 0x02, 0x03};
+ *
+ *      TWI_WritePacket(0xA0, 10, &InternalWriteAddress, sizeof(InternalWriteAddress),
+ *                      &WritePacket, sizeof(WritePacket);
+ *
+ *      // Start a read session to device at address 0xA0, internal address 0xDC with a 10ms timeout
+ *      uint8_t InternalReadAddress = 0xDC;
+ *      uint8_t ReadPacket[3];
+ *
+ *      TWI_ReadPacket(0xA0, 10, &InternalReadAddress, sizeof(InternalReadAddress),
+ *                     &ReadPacket, sizeof(ReadPacket);
+ *  \endcode
+ *
  *  @{
  */
 
@@ -90,6 +119,7 @@
 
 		#include <avr/io.h>
 		#include <stdbool.h>
+		#include <stdio.h>
 		#include <util/twi.h>
 		#include <util/delay.h>
 
@@ -108,12 +138,29 @@
 			/** 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
+			#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
+			#define TWI_ADDRESS_WRITE        0x01
+
+			/** Mask to retrieve the base address for a TWI device, which can then be ORed with \ref TWI_ADDRESS_READ
+			 *  or \ref TWI_ADDRESS_WRITE to obtain the device's read and write address respectively.
+			 */
+			#define TWI_DEVICE_ADDRESS_MASK  0xFE
+			
+		/* Enums: */
+			/** Enum for the possible return codes of the TWI transfer start routine and other dependant TWI functions. */
+			enum TWI_ErrorCodes_t
+			{
+				TWI_ERROR_NoError              = 0, /**< Indicates that the command completed sucessfully. */
+				TWI_ERROR_BusFault             = 1, /**< A TWI bus fault occurred while attempting to capture the bus. */
+				TWI_ERROR_BusCaptureTimeout    = 2, /**< A timeout occurred whilst waiting for the bus to be ready. */
+				TWI_ERROR_SlaveResponseTimeout = 3, /**< No ACK received at the nominated slave address within the timeout period. */
+				TWI_ERROR_SlaveNotReady        = 4, /**< Slave NAKed the TWI bus START condition. */
+				TWI_ERROR_SlaveNAK             = 5, /**< Slave NAKed whilst attempting to send data to the device. */
+			};
 	
 		/* Inline Functions: */
 			/** Initialises the TWI hardware into master mode, ready for data transmission and reception. This must be
@@ -163,8 +210,8 @@
 			 *
 			 *  \return Boolean \c true if the byte reception successfully completed, \c false otherwise
 			 */
-			static inline bool TWI_ReceiveByte(uint8_t* const Byte,
-			                                   const bool LastByte)
+			static inline uint8_t TWI_ReceiveByte(uint8_t* const Byte,
+			                                      const bool LastByte)
 			{
 				uint8_t TWCRMask = ((1 << TWINT) | (1 << TWEN));
 
@@ -184,10 +231,44 @@
 			 *  \param[in] SlaveAddress  Address of the slave TWI device to communicate with
 			 *  \param[in] TimeoutMS     Timeout period within which the slave must respond, in milliseconds
 			 *
-			 *  \return Boolean \c true if the device is ready for data, \c false otherwise
+			 *  \return A value from the \ref TWI_ErrorCodes_t enum
+			 */
+			uint8_t TWI_StartTransmission(const uint8_t SlaveAddress,
+			                              const uint8_t TimeoutMS);
+
+			/** High level function to perform a complete packet transfer over the TWI bus to the specified
+			 *  device.
+			 *
+			 *  \param[in] SlaveAddress        Base address of the TWI slave device to communicate with
+			 *  \param[in] TimeoutMS           Timeout for bus capture and slave START ACK, in milliseconds
+			 *  \param[in] InternalAddress     Pointer to a location where the internal slave read start address is stored
+			 *  \param[in] InternalAddressLen  Size of the internal device address, in bytes
+			 *  \param[in] Buffer              Pointer to a buffer where the read packet data is to be stored
+			 *  \param[in] Length              Size of the packet to read, in bytes
+			 */
+			uint8_t TWI_ReadPacket(const uint8_t SlaveAddress,
+			                       const uint8_t TimeoutMS,
+			                       const uint8_t* InternalAddress,
+			                       uint8_t InternalAddressLen,
+			                       uint8_t* Buffer,
+			                       uint8_t Length);
+
+			/** High level function to perform a complete packet transfer over the TWI bus from the specified
+			 *  device.
+			 *
+			 *  \param[in] SlaveAddress        Base address of the TWI slave device to communicate with
+			 *  \param[in] TimeoutMS           Timeout for bus capture and slave START ACK, in milliseconds
+			 *  \param[in] InternalAddress     Pointer to a location where the internal slave write start address is stored
+			 *  \param[in] InternalAddressLen  Size of the internal device address, in bytes
+			 *  \param[in] Buffer              Pointer to a buffer where the packet data to send is stored
+			 *  \param[in] Length              Size of the packet to send, in bytes
 			 */
-			bool TWI_StartTransmission(const uint8_t SlaveAddress,
-			                           const uint8_t TimeoutMS);
+			uint8_t TWI_WritePacket(const uint8_t SlaveAddress,
+			                        const uint8_t TimeoutMS,
+			                        const uint8_t* InternalAddress,
+			                        uint8_t InternalAddressLen,
+			                        const uint8_t* Buffer,
+			                        uint8_t Length);
 
 	/* Disable C linkage for C++ Compilers: */
 		#if defined(__cplusplus)
diff --git a/LUFA/Drivers/Peripheral/TWI.c b/LUFA/Drivers/Peripheral/TWI.c
index 6aaf19219..2f4e4ed42 100644
--- a/LUFA/Drivers/Peripheral/TWI.c
+++ b/LUFA/Drivers/Peripheral/TWI.c
@@ -7,8 +7,8 @@
 
 #include "TWI.h"
 
-bool TWI_StartTransmission(const uint8_t SlaveAddress,
-                           const uint8_t TimeoutMS)
+uint8_t TWI_StartTransmission(const uint8_t SlaveAddress,
+                              const uint8_t TimeoutMS)
 {
 	for (;;)
 	{
@@ -33,17 +33,17 @@ bool TWI_StartTransmission(const uint8_t SlaveAddress,
 						continue;
 					default:
 						TWCR = (1 << TWEN);
-						return false;
+						return TWI_ERROR_BusFault;
 				}
 			}
 
 			_delay_us(10);
 		}
 
-		if (!(BusCaptured))
+		if (!(TimeoutRemaining))
 		{
 			TWCR = (1 << TWEN);
-			return false;
+			return TWI_ERROR_BusCaptureTimeout;
 		}
 
 		TWDR = SlaveAddress;
@@ -59,17 +59,85 @@ bool TWI_StartTransmission(const uint8_t SlaveAddress,
 		}
 
 		if (!(TimeoutRemaining))
-		  return false;
+		  return TWI_ERROR_SlaveResponseTimeout;
 
 		switch (TWSR & TW_STATUS_MASK)
 		{
 			case TW_MT_SLA_ACK:
 			case TW_MR_SLA_ACK:
-				return true;
+				return TWI_ERROR_NoError;
 			default:
 				TWCR = ((1 << TWINT) | (1 << TWSTO) | (1 << TWEN));
-				return false;
+				return TWI_ERROR_SlaveNotReady;
+		}
+	}
+}
+
+uint8_t TWI_ReadPacket(const uint8_t SlaveAddress,
+                       const uint8_t TimeoutMS,
+                       const uint8_t* InternalAddress,
+                       uint8_t InternalAddressLen,
+                       uint8_t* Buffer,
+                       uint8_t Length)
+{
+	uint8_t ErrorCode;
+	
+	if ((ErrorCode = TWI_WritePacket(SlaveAddress, TimeoutMS, InternalAddress, InternalAddressLen,
+	                                 NULL, 0)) != TWI_ERROR_NoError)
+	{
+		return ErrorCode;
+	}
+
+	if ((ErrorCode = TWI_StartTransmission((SlaveAddress & TWI_DEVICE_ADDRESS_MASK) | TWI_ADDRESS_READ,
+										   TimeoutMS)) == TWI_ERROR_NoError)
+	{
+		while (Length--)
+		{
+			if (!(TWI_ReceiveByte(Buffer++, (Length == 0))))
+			{
+				ErrorCode = TWI_ERROR_SlaveNAK;
+				break;
+			}
 		}
+		
+		TWI_StopTransmission();
 	}
+	
+	return ErrorCode;
 }
 
+uint8_t TWI_WritePacket(const uint8_t SlaveAddress,
+                        const uint8_t TimeoutMS,
+                        const uint8_t* InternalAddress,
+                        uint8_t InternalAddressLen,
+                        const uint8_t* Buffer,
+                        uint8_t Length)
+{
+	uint8_t ErrorCode;
+
+	if ((ErrorCode = TWI_StartTransmission((SlaveAddress & TWI_DEVICE_ADDRESS_MASK) | TWI_ADDRESS_WRITE,
+	                                       TimeoutMS)) == TWI_ERROR_NoError)
+	{
+		while (InternalAddressLen--)
+		{
+			if (!(TWI_SendByte(*(InternalAddress++))))
+			{
+				ErrorCode = TWI_ERROR_SlaveNAK;
+				break;
+			}
+		}
+
+		while (Length--)
+		{
+			if (!(TWI_SendByte(*(Buffer++))))
+			{
+				ErrorCode = TWI_ERROR_SlaveNAK;
+				break;
+			}
+		}
+		
+		TWI_StopTransmission();
+	}
+	
+	return ErrorCode;
+}