TWI Library
  mikroC PRO for AVR Libraries > Hardware Libraries > 
  

TWI Library

TWI full master MSSP module is available with a number of AVR MCU models. mikroC PRO for AVR provides library which supports the master TWI mode.

Library Routines

Generic Routines

TWI_Init

Prototype

void TWI_Init(unsigned long clock);

// for XMEGA family of MCUs

void TWIx_Init(unsigned long clock);
Returns

Nothing.
Description

Initializes TWI with desired clock (refer to device data sheet for correct values in respect with Fosc). Needs to be called before using other functions of TWI Library.

You don’t need to configure ports manually for using the module; library will take care of the initialization.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

Library requires MCU with TWI module.
Example 
TWI_Init(100000);

TWI_Busy

Prototype

char TWI_Busy();

// for XMEGA family of MCUs

char TWIx_Busy();
Returns
  • 0 - if TWI bus is not busy
  • 1 - if TWI bus is busy
Description

Signalizes the status of TWI bus.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
if (TWI_Busy == 1) { 
...

TWI_Start

Prototype

char TWI_Start();

// for XMEGA family of MCUs

char TWIx_Start();
Returns
  • 0 - if TWI start sequence is finished
  • 1 - if TWI start sequence is not finished
Description

Determines if TWI bus is free and issues START signal.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
if (TWI_Start == 1) { 
...

TWI_Read

Prototype

char TWI_Read(char ack);

// for XMEGA family of MCUs

char TWIx_Read(char ack);
Returns

Returns one byte from the slave.
Description

Reads one byte from the slave, and sends not acknowledge signal if parameter ack is 0, otherwise it sends acknowledge.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

TWI must be configured before using this function. See TWI_Init.

Also, START signal needs to be issued in order to use this function. See TWI_Start.
Example

Read data and send not acknowledge signal:

tmp = TWI_Read(0);

TWI_Write

Prototype

void TWI_Write(char data_);

// for XMEGA family of MCUs

void TWIx_Write(char data_);
Returns

Nothing.
Description

Sends data byte (parameter data_) via TWI bus.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

TWI must be configured before using this function. See TWI_Init.

Also, START signal needs to be issued in order to use this function. See TWI_Start.
Example 
TWI_Write(0xA3);

TWI_Stop

Prototype

void TWI_Stop();

// for XMEGA family of MCUs

void TWIx_Stop();
Returns

Nothing.
Description

Issues STOP signal to TWI operation.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
TWI_Stop();

TWI_Status

Prototype

char TWI_Status();

// for XMEGA family of MCUs

char TWIx_Status();
Returns

Returns value of status register (TWSR), the highest 5 bits.
Description

Returns status of TWI.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
status = TWI_Status();

TWI_Close

Prototype

void TWI_Close();

// for XMEGA family of MCUs

void TWIx_Close();
Returns

Nothing.
Description

Closes TWI connection.

For XMEGA family of MCUs change the X in the routine prototype with C, D, E or F.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
TWI_Close();

TWI_SetTimeoutCallback

Prototype

void TWI_SetTimeoutCallback(unsigned long timeout, void (*twi_timeout)(char));
Returns

Nothing.
Description

This function checks for a TWI timeout condition in a user defined time period, after which it jumps to a callback function if this condition is met.
Different TWI operations can cause a timeout (read, write, start and repeated start) so user may test which one caused it, as in the example below.

Parameters :
  • timeout: Represents a number of while loops in which the TWI timeout condition is checked.
    Depending on the MCU family, the generated code (i.e. the execution time) may vary for the same value of this parameter.

  • twi_timeout: pointer to the callback function. Callback function must be written according to this function prototype : 
    void TWI_TimeoutCallback(char errorCode) {

}
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
// define callback function
void TWI_TimeoutCallback(char errorCode) {

   if (errorCode == _TWI_TIMEOUT_RD) {
     // do something if timeout is caused during read
   }
   
   if (errorCode == _TWI_TIMEOUT_WR) {
     // do something if timeout is caused during write
   }
   
   if (errorCode == _TWI_TIMEOUT_START) {
     // do something if timeout is caused during start
   } 
}	

// initialize TWI module
TWI_Init();

// set timeout period and callback function
TWI_SetTimeoutCallback(1000, I2C1_TimeoutCallback);

TWI_Set_Active

Prototype

void TWI_Set_Active(char (*start_ptr)(), char (*read_ptr)(char ack), void (*write_ptr)(char data_), void (*stop_ptr)(), void (*close_ptr)(), char (*busy_ptr)(), char (*status_ptr)());
Description

Sets the active TWI module which will be used by the TWI library routines.
Parameters
Returns

Nothing.
Requires

Used TWI module must be initialized before using this function. See the TWI_Init routines.
Example 
TWI_Set_Active(&TWIC_Start, &TWIC_Read, &TWIC_Write, &TWIC_Stop, &TWI_Close, &TWIC_Busy, &TWIC_Status); // Sets the TWIC module active
Notes

Number of TWI modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

TWI_Busy

Prototype

char TWI_Busy();
Returns
  • 0 - if TWI bus is not busy
  • 1 - if TWI bus is busy
Description

Signalizes the status of TWI bus.

This is a generic routine which uses the active TWI module previously activated by the TWI_Set_Active routine.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
if (TWI_Busy() == 1) { 
...

TWI_Start

Prototype

char TWI_Start();
Returns
  • 0 - if TWI start sequence is finished
  • 1 - if TWI start sequence is not finished
Description

Determines if TWI bus is free and issues START signal.

This is a generic routine which uses the active TWI module previously activated by the TWI_Set_Active routine.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
if (TWI_Start() == 1) { 
...

TWI_Read

Prototype

char TWI_Read(char ack);
Returns

Returns one byte from the slave.
Description

Reads one byte from the slave, and sends not acknowledge signal if parameter ack is 0, otherwise it sends acknowledge.

This is a generic routine which uses the active TWI module previously activated by the TWI_Set_Active routine.
Requires

TWI must be configured before using this function. See TWI_Init.

Also, START signal needs to be issued in order to use this function. See TWI_Start.
Example

Read data and send not acknowledge signal:

tmp = TWI_Read(0);

TWI_Write

Prototype

void TWI_Write(char data_);
Returns

Nothing.
Description

Sends data byte (parameter data_) via TWI bus.

This is a generic routine which uses the active TWI module previously activated by the TWI_Set_Active routine.
Requires

TWI must be configured before using this function. See TWI_Init.

Also, START signal needs to be issued in order to use this function. See TWI_Start.
Example 
TWI_Write(0xA3);

TWI_Stop

Prototype

void TWI_Stop();
Returns

Nothing.
Description

Issues STOP signal to TWI operation.

This is a generic routine which uses the active TWI module previously activated by the TWI_Set_Active routine.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
TWI_Stop();

TWI_Status

Prototype

char TWI_Status();
Returns

Returns value of status register (TWSR), the highest 5 bits.
Description

Returns status of TWI.

This is a generic routine which uses the active TWI module previously activated by the TWI_Set_Active routine.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
status = TWI_Status();

TWI_Close

Prototype

void TWI_Close();
Returns

Nothing.
Description

Closes TWI connection.

This is a generic routine which uses the active TWI module previously activated by the TWI_Set_Active routine.
Requires

TWI must be configured before using this function. See TWI_Init.
Example 
TWI_Close();

Library Example

This code demonstrates use of TWI Library procedures and functions. AVR MCU is connected (SCL, SDA pins ) to 24c02 EEPROM. Program sends data to EEPROM (data is written at address 2). Then, we read data via TWI from EEPROM and send its value to PORTA, to check if the cycle was successful. Check the figure below.

Copy Code To ClipboardCopy Code To Clipboard 
void main(){
  DDRA = 0xFF;              // configure PORTA as output

  TWI_Init(100000);         // initialize TWI communication
  TWI_Start();              // issue TWI start signal
  TWI_Write(0xA2);          // send byte via TWI (device address + W)
  TWI_Write(2);             // send byte (address of EEPROM location)
  TWI_Write(0xAA);          // send data (data to be written)
  TWI_Stop();               // issue TWI stop signal

  Delay_100ms();

  TWI_Start();              // issue TWI start signal
  TWI_Write(0xA2);          // send byte via TWI (device address + W)
  TWI_Write(2);             // send byte (data address)
  TWI_Start();              // issue TWI signal repeated start
  TWI_Write(0xA3);          // send byte (device address + R)
  PORTA = TWI_Read(0u);     // read data (NO acknowledge)
  TWI_Stop();               // issue TWI stop signal
}

HW Connection

Interfacing 24c02 to AVR via I²C

Interfacing 24c02 to AVR via TWI

Copyright (c) 2002-2017 mikroElektronika. All rights reserved.
What do you think about this topic ? Send us feedback!
Want more examples and libraries? 
Find them on LibStock - A place for the code