X-Git-Url: http://git.linex4red.de/pub/lufa.git/blobdiff_plain/b6a3c78fa3e46fea1dd6f4b93352686837983dfd..3309c00a99cca6d4a903aed9ecd092346b767ea0:/LUFA/Drivers/Peripheral/AVR8/TWI_AVR8.h

diff --git a/LUFA/Drivers/Peripheral/AVR8/TWI_AVR8.h b/LUFA/Drivers/Peripheral/AVR8/TWI_AVR8.h
index e03423385..8ff38a16f 100644
--- a/LUFA/Drivers/Peripheral/AVR8/TWI_AVR8.h
+++ b/LUFA/Drivers/Peripheral/AVR8/TWI_AVR8.h
@@ -52,11 +52,11 @@
  *
  *  <b>Low Level API Example:</b>
  *  \code
- *      // Initialise the TWI driver before first use
- *      TWI_Init();
+ *      // Initialize the TWI driver before first use
+ *      TWI_Init(TWI_BIT_PRESCALE_1, 10);
  *
  *      // 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))
+ *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10) == TWI_ERROR_NoError)
  *      {
  *          TWI_SendByte(0xDC);
  *
@@ -69,12 +69,12 @@
  *      }
  *
  *      // Start a read session to device at address 0xA0, internal address 0xDC with a 10ms timeout
- *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10))
+ *      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10) == TWI_ERROR_NoError)
  *      {
  *          TWI_SendByte(0xDC);
  *          TWI_StopTransmission();
  *
- *          if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10))
+ *          if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10) == TWI_ERROR_NoError)
  *          {
  *              uint8_t Byte1, Byte2, Byte3;
  *
@@ -91,8 +91,8 @@
  * 
  *  <b>High Level API Example:</b>
  *  \code
- *      // Initialise the TWI driver before first use
- *      TWI_Init();
+ *      // Initialize the TWI driver before first use
+ *      TWI_Init(TWI_BIT_PRESCALE_1, 10);
  *
  *      // Start a write session to device at device address 0xA0, internal address 0xDC with a 10ms timeout
  *      uint8_t InternalWriteAddress = 0xDC;
@@ -155,11 +155,23 @@
 			 */
 			#define TWI_DEVICE_ADDRESS_MASK  0xFE
 			
+			/** Bit length prescaler for \ref TWI_Init(). This mask multiplies the TWI bit length prescaler by 1. */
+			#define TWI_BIT_PRESCALE_1       ((0 << TWPS1) | (0 << TWPS0))
+			
+			/** Bit length prescaler for \ref TWI_Init(). This mask multiplies the TWI bit length prescaler by 4. */
+			#define TWI_BIT_PRESCALE_4       ((0 << TWPS1) | (1 << TWPS0))
+
+			/** Bit length prescaler for \ref TWI_Init(). This mask multiplies the TWI bit length prescaler by 16. */
+			#define TWI_BIT_PRESCALE_16      ((1 << TWPS1) | (0 << TWPS0))
+
+			/** Bit length prescaler for \ref TWI_Init(). This mask multiplies the TWI bit length prescaler by 64. */
+			#define TWI_BIT_PRESCALE_64      ((1 << TWPS1) | (1 << TWPS0))
+			
 		/* 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_NoError              = 0, /**< Indicates that the command completed successfully. */
 				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. */
@@ -168,13 +180,23 @@
 			};
 	
 		/* Inline Functions: */
-			/** Initialises the TWI hardware into master mode, ready for data transmission and reception. This must be
+			/** Initializes the TWI hardware into master mode, ready for data transmission and reception. This must be
 			 *  before any other TWI operations.
+			 *
+			 *  The generated SCL frequency will be according to the formula <pre>F_CPU / (16 + 2 * BitLength + 4 ^ Prescale)</pre>.
+			 *
+			 *  \note The value of the \c BitLength parameter should not be set below 10 or invalid bus conditions may
+			 *        occur, as indicated in the AVR8 microcontroller datasheet.
+			 *
+			 *  \param[in] Prescale   Prescaler to use when determining the bus frequency, a \c TWI_BIT_PRESCALE_* value.
+			 *  \param[in] BitLength  Length of the bits sent on the bus.
 			 */
-			static inline void TWI_Init(void) ATTR_ALWAYS_INLINE;
-			static inline void TWI_Init(void)
+			static inline void TWI_Init(const uint8_t Prescale, const uint8_t BitLength) ATTR_ALWAYS_INLINE;
+			static inline void TWI_Init(const uint8_t Prescale, const uint8_t BitLength)
 			{
-				TWCR |=  (1 << TWEN);
+				TWCR |= (1 << TWEN);
+				TWSR  = Prescale;
+				TWBR  = BitLength;
 			}
 
 			/** Turns off the TWI driver hardware. If this is called, any further TWI operations will require a call to
@@ -254,7 +276,7 @@
 			uint8_t TWI_ReadPacket(const uint8_t SlaveAddress,
 			                       const uint8_t TimeoutMS,
 			                       const uint8_t* InternalAddress,
-			                       uint8_t InternalAddressLen,
+			                       const uint8_t InternalAddressLen,
 			                       uint8_t* Buffer,
 			                       uint8_t Length);