| LUFA Library 140302 |

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Enumerations | Functions
TWI Peripheral Driver (XMEGA)
TWI Driver - LUFA/Drivers/Peripheral/TWI.h

## Macros
#define | TWI_ADDRESS_READ 0x01
#define | TWI_ADDRESS_WRITE 0x00
#define | TWI_BAUD_FROM_FREQ(Frequency) ((F_CPU / (2 * Frequency)) - 5)
#define | TWI_DEVICE_ADDRESS_MASK 0xFE

## 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, 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_Disable (TWI_t *const TWI) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1)
static void | TWI_Init (TWI_t *const TWI, const uint8_t Baud) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1)
uint8_t | TWI_ReadPacket (TWI_t *const TWI, 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(1) ATTR_NON_NULL_PTR_ARG(4)
bool | TWI_ReceiveByte (TWI_t *const TWI, uint8_t *const Byte, const bool LastByte) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2)
bool | TWI_SendByte (TWI_t *const TWI, const uint8_t Byte) ATTR_NON_NULL_PTR_ARG(1)
uint8_t | TWI_StartTransmission (TWI_t *const TWI, const uint8_t SlaveAddress, const uint8_t TimeoutMS) ATTR_NON_NULL_PTR_ARG(1)
static void | TWI_StopTransmission (TWI_t *const TWI) ATTR_ALWAYS_INLINE ATTR_NON_NULL_PTR_ARG(1)
uint8_t | TWI_WritePacket (TWI_t *const TWI, 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(1) ATTR_NON_NULL_PTR_ARG(4)

## 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(&TWIC, TWI_BAUD_FROM_FREQ(200000));
// Start a write session to device at device address 0xA0, internal address 0xDC with a 10ms timeout
if (TWI_StartTransmission(&TWIC, 0xA0 | TWI_ADDRESS_WRITE, 10) == TWI_ERROR_NoError)
{
TWI_SendByte(&TWIC, 0xDC);
TWI_SendByte(&TWIC, 0x01);
TWI_SendByte(&TWIC, 0x02);
TWI_SendByte(&TWIC, 0x03);
// Must stop transmission afterwards to release the bus
TWI_StopTransmission(&TWIC);
}
// Start a read session to device at address 0xA0, internal address 0xDC with a 10ms timeout
if (TWI_StartTransmission(&TWIC, 0xA0 | TWI_ADDRESS_WRITE, 10) == TWI_ERROR_NoError)
{
TWI_SendByte(&TWIC, 0xDC);
TWI_StopTransmission(&TWIC);
if (TWI_StartTransmission(&TWIC, 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(&TWIC, &Byte1, false);
TWI_ReceiveByte(&TWIC, &Byte2, false);
TWI_ReceiveByte(&TWIC, &Byte3, true);
// Must stop transmission afterwards to release the bus
TWI_StopTransmission(&TWIC);
}
}

High Level API Example:

// Initialize the TWI driver before first use at 200KHz
TWI_Init(&TWIC, TWI_BAUD_FROM_FREQ(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(&TWIC, 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(&TWIC, 0xA0, 10, &InternalReadAddress, sizeof(InternalReadAddress),
&ReadPacket, sizeof(ReadPacket);

## Macro Definition 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_BAUD_FROM_FREQ | ( |  | Frequency | ) | ((F_CPU / (2 * Frequency)) - 5)

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] | Frequency | Desired 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.
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 | ( | TWI_t *const | TWI | ) |
| 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.

Parameters

  [in] | TWI | Pointer to the base of the TWI peripheral within the device.

static void TWI_Init | ( | TWI_t *const | TWI,
|  | const uint8_t | Baud
| ) |  |
| 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 / (2 * (5 + (BAUD)))

.

Attention
  The value of the `BitLength` parameter should not be set below 10 or invalid bus conditions may occur, as indicated in the XMEGA microcontroller datasheet.

Parameters

  [in] | TWI | Pointer to the base of the TWI peripheral within the device.
  [in] | Baud | Value of the BAUD register of the TWI Master.

uint8_t TWI_ReadPacket | ( | TWI_t *const | TWI,
|  | 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] | TWI | Pointer to the base of the TWI peripheral within the device.
  [in] | SlaveAddress | Base address of the TWI slave device to communicate with.
  [in] | TimeoutMS | Timeout for bus capture and slave START ACK, in milliseconds.
  [in] | InternalAddress | Pointer to a location where the internal slave read start address is stored.
  [in] | InternalAddressLen | Size of the internal device address, in bytes.
  [in] | Buffer | Pointer to a buffer where the read packet data is to be stored.
  [in] | Length | Size of the packet to read, in bytes.

Returns
  A value from the TWI_ErrorCodes_t enum.

bool TWI_ReceiveByte | ( | TWI_t *const | TWI,
|  | uint8_t *const | Byte,
|  | const bool | LastByte
| ) |  |

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

Parameters

  [in] | TWI | Pointer to the base of the TWI peripheral within the device.
  [in] | Byte | Location where the read byte is to be stored.
  [in] | LastByte | Indicates 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 | ( | TWI_t *const | TWI,
|  | const uint8_t | Byte
| ) |  |

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

Parameters

  [in] | TWI | Pointer to the base of the TWI peripheral within the device.
  [in] | Byte | Byte to send to the currently addressed device

Returns
  Boolean `true` if the recipient ACKed the byte, `false` otherwise

uint8_t TWI_StartTransmission | ( | TWI_t *const | TWI,
|  | const uint8_t | SlaveAddress,
|  | const uint8_t | TimeoutMS
| ) |  |

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

Parameters

  [in] | TWI | Pointer to the base of the TWI peripheral within the device.
  [in] | SlaveAddress | Address of the slave TWI device to communicate with.
  [in] | TimeoutMS | Timeout period within which the slave must respond, in milliseconds.

Returns
  A value from the TWI_ErrorCodes_t enum.

static void TWI_StopTransmission | ( | TWI_t *const | TWI | ) |
| inline static

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

Parameters

  [in] | TWI | Pointer to the base of the TWI peripheral within the device.

uint8_t TWI_WritePacket | ( | TWI_t *const | TWI,
|  | 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] | TWI | Pointer to the base of the TWI peripheral within the device.
  [in] | SlaveAddress | Base address of the TWI slave device to communicate with
  [in] | TimeoutMS | Timeout for bus capture and slave START ACK, in milliseconds
  [in] | InternalAddress | Pointer to a location where the internal slave write start address is stored
  [in] | InternalAddressLen | Size of the internal device address, in bytes
  [in] | Buffer | Pointer to a buffer where the packet data to send is stored
  [in] | Length | Size of the packet to send, in bytes

Returns
  A value from the TWI_ErrorCodes_t enum.