LUFA Library  120219
Defines | Enumerations | Functions
TWI Peripheral Driver (AVR8)
TWI Driver - LUFA/Drivers/Peripheral/TWI.h

Defines

#define TWI_ADDRESS_READ   0x01
#define TWI_ADDRESS_WRITE   0x00
#define TWI_DEVICE_ADDRESS_MASK   0xFE
#define TWI_BIT_PRESCALE_1   ((0 << TWPS1) | (0 << TWPS0))
#define TWI_BIT_PRESCALE_4   ((0 << TWPS1) | (1 << TWPS0))
#define TWI_BIT_PRESCALE_16   ((1 << TWPS1) | (0 << TWPS0))
#define TWI_BIT_PRESCALE_64   ((1 << TWPS1) | (1 << TWPS0))
#define TWI_BITLENGTH_FROM_FREQ(Prescale, Frequency)   ((((F_CPU / (Prescale)) / (Frequency)) - 16) / 2)

Enumerations

enum  TWI_ErrorCodes_t {
  TWI_ERROR_NoError = 0,
  TWI_ERROR_BusFault = 1,
  TWI_ERROR_BusCaptureTimeout = 2,
  TWI_ERROR_SlaveResponseTimeout = 3,
  TWI_ERROR_SlaveNotReady = 4,
  TWI_ERROR_SlaveNAK = 5
}

Functions

static void TWI_Init (const uint8_t Prescale, const uint8_t BitLength) ATTR_ALWAYS_INLINE
static void TWI_Disable (void) ATTR_ALWAYS_INLINE
static void TWI_StopTransmission (void) ATTR_ALWAYS_INLINE
uint8_t TWI_StartTransmission (const uint8_t SlaveAddress, const uint8_t TimeoutMS)
bool TWI_SendByte (const uint8_t Byte)
bool TWI_ReceiveByte (uint8_t *const Byte, const bool LastByte) ATTR_NON_NULL_PTR_ARG(1)
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) ATTR_NON_NULL_PTR_ARG(3)
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) ATTR_NON_NULL_PTR_ARG(3)

Detailed Description

Module Description

Master mode TWI driver for the 8-bit AVR microcontrollers which contain a hardware TWI module.

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

The following snippet is an example of how this module may be used within a typical application.

Low Level API Example: 

      // Initialize the TWI driver before first use at 200KHz
      TWI_Init(TWI_BIT_PRESCALE_1, TWI_BITLENGTH_FROM_FREQ(1, 200000));

      // 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_ERROR_NoError)
      {
          TWI_SendByte(0xDC);

          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, internal address 0xDC with a 10ms timeout
      if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_WRITE, 10) == TWI_ERROR_NoError)
      {
          TWI_SendByte(0xDC);
          TWI_StopTransmission();

          if (TWI_StartTransmission(0xA0 | TWI_ADDRESS_READ, 10) == TWI_ERROR_NoError)
          {
              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();
          }
      }

High Level API Example: 

      // Initialize the TWI driver before first use at 200KHz
      TWI_Init(TWI_BIT_PRESCALE_1, TWI_BITLENGTH_FROM_FREQ(1, 200000));

      // 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);

Define Documentation

#define TWI_ADDRESS_READ   0x01

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_WRITE   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_BIT_PRESCALE_1   ((0 << TWPS1) | (0 << TWPS0))

Bit length prescaler for TWI_Init(). This mask multiplies the TWI bit length prescaler by 1.

#define TWI_BIT_PRESCALE_16   ((1 << TWPS1) | (0 << TWPS0))

Bit length prescaler for TWI_Init(). This mask multiplies the TWI bit length prescaler by 16.

#define TWI_BIT_PRESCALE_4   ((0 << TWPS1) | (1 << TWPS0))

Bit length prescaler for TWI_Init(). This mask multiplies the TWI bit length prescaler by 4.

#define TWI_BIT_PRESCALE_64   ((1 << TWPS1) | (1 << TWPS0))

Bit length prescaler for TWI_Init(). This mask multiplies the TWI bit length prescaler by 64.

#define TWI_BITLENGTH_FROM_FREQ (   Prescale,
  Frequency 
)    ((((F_CPU / (Prescale)) / (Frequency)) - 16) / 2)

Calculates the length of each bit on the TWI bus for a given target frequency. This may be used with the TWI_Init() function to convert a bus frequency to a number of clocks for the BitLength parameter.

Parameters:
[in]PrescalePrescaler set on the TWI bus.
[in]FrequencyDesired TWI bus frequency in Hz.
Returns:
Bit length in clocks for the given TWI bus frequency at the given prescaler value.
#define TWI_DEVICE_ADDRESS_MASK   0xFE

Mask to retrieve the base address for a TWI device, which can then be ORed with TWI_ADDRESS_READ or TWI_ADDRESS_WRITE to obtain the device's read and write address respectively.

Enumeration Type Documentation

enum TWI_ErrorCodes_t

Enum for the possible return codes of the TWI transfer start routine and other dependant TWI functions.

Enumerator:
TWI_ERROR_NoError 

Indicates that the command completed successfully.

TWI_ERROR_BusFault 

A TWI bus fault occurred while attempting to capture the bus.

TWI_ERROR_BusCaptureTimeout 

A timeout occurred whilst waiting for the bus to be ready.

TWI_ERROR_SlaveResponseTimeout 

No ACK received at the nominated slave address within the timeout period.

TWI_ERROR_SlaveNotReady 

Slave NAKed the TWI bus START condition.

TWI_ERROR_SlaveNAK 

Slave NAKed whilst attempting to send data to the device.

Function Documentation

static void TWI_Disable ( void  ) [inline, static]

Turns off the TWI driver hardware. If this is called, any further TWI operations will require a call to TWI_Init() before the TWI can be used again.

static void TWI_Init ( const uint8_t  Prescale,
const uint8_t  BitLength 
) [inline, static]

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 

F_CPU / (16 + 2 * BitLength + 4 ^ Prescale)

.

Note:
The value of the BitLength parameter should not be set below 10 or invalid bus conditions may occur, as indicated in the AVR8 microcontroller datasheet.
Parameters:
[in]PrescalePrescaler to use when determining the bus frequency, a TWI_BIT_PRESCALE_* value.
[in]BitLengthLength of the bits sent on the bus.
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 to the specified device.

Parameters:
[in]SlaveAddressBase address of the TWI slave device to communicate with.
[in]TimeoutMSTimeout for bus capture and slave START ACK, in milliseconds.
[in]InternalAddressPointer to a location where the internal slave read start address is stored.
[in]InternalAddressLenSize of the internal device address, in bytes.
[in]BufferPointer to a buffer where the read packet data is to be stored.
[in]LengthSize of the packet to read, in bytes.
Returns:
A value from the TWI_ErrorCodes_t enum.
bool TWI_ReceiveByte ( uint8_t *const  Byte,
const bool  LastByte 
)

Receives a byte from the currently addressed device on the TWI bus.

Parameters:
[in]ByteLocation where the read byte is to be stored.
[in]LastByteIndicates if the byte should be ACKed if false, NAKed if true.
Returns:
Boolean true if the byte reception successfully completed, false otherwise.
bool TWI_SendByte ( const uint8_t  Byte)

Sends a byte to the currently addressed device on the TWI bus.

Parameters:
[in]ByteByte to send to the currently addressed device
Returns:
Boolean true if the recipient ACKed the byte, false otherwise
uint8_t TWI_StartTransmission ( const uint8_t  SlaveAddress,
const uint8_t  TimeoutMS 
)

Begins a master mode TWI bus communication with the given slave device address.

Parameters:
[in]SlaveAddressAddress of the slave TWI device to communicate with.
[in]TimeoutMSTimeout period within which the slave must respond, in milliseconds.
Returns:
A value from the TWI_ErrorCodes_t enum.
static void TWI_StopTransmission ( void  ) [inline, static]

Sends a TWI STOP onto the TWI bus, terminating communication with the currently addressed device.

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 
)

High level function to perform a complete packet transfer over the TWI bus from the specified device.

Parameters:
[in]SlaveAddressBase address of the TWI slave device to communicate with
[in]TimeoutMSTimeout for bus capture and slave START ACK, in milliseconds
[in]InternalAddressPointer to a location where the internal slave write start address is stored
[in]InternalAddressLenSize of the internal device address, in bytes
[in]BufferPointer to a buffer where the packet data to send is stored
[in]LengthSize of the packet to send, in bytes
Returns:
A value from the TWI_ErrorCodes_t enum.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines