I2C Library
  mikroC PRO for ARM Libraries > Hardware Libraries > 
  

I²C Library

The I²C full master I²C module is available with a number of the ARM MCU models. The mikroC PRO for ARM provides a library which supports the master I²C mode.


  Important :

Library Routines

I2Cx_Init

Prototype

void I2Cx_Init();
Description

This function configures and initializes the desired I²C module with the standard 100kbps bitrate.
Parameters

None.
Returns

Nothing.
Requires

MCU with the I²C module.
Example 
// Initialize the I2C1 module with the standard bitrate of 100000
I2C1_Init();
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

Stellaris

  • For MCUs with alternative PORT functions on GPIO pins, I2C0_Init is set on GPIO_PORTB pins 2 and 3, while the I2C1_Init is set on GPIO_PORTA pins 0 and 1.
  • Refer to the table below for correct values of the bit rate in respect with system clock :
    System Clock Standard Mode
    4 MHz 100 Kbps
    6 MHz 100 Kbps
    12.5 MHz 89 Kbps
    16.7 MHz 93 Kbps
    20 MHz 100 Kbps
    25 MHz 96.2 Kbps
    33 MHz 97.1 Kbps
    40 MHz 100 Kbps
    50MHz 100 Kbps
    80 MHz 100 Kbps

STM32

  • I2C1_Init is set on PORTB pins 6 and 7,
  • I2C2_Init is set on PORTB pins 10 and 11,
  • I2C3_Init is set on PORTH pins 7 and 8.

The peripheral input clock frequency must be at least :

  • 2 MHz in Standard mode (100 Kbps)
  • 4 MHz in Fast mode (400 Kbps)

I2Cx_Init_Advanced

Prototype // for Stellaris MCUs :

void I2Cx_Init_Advanced(unsigned long bitrate);

// for Stellaris MCUs with alternative PORT functions on GPIO pins :

void I2Cx_Init_Advanced(unsigned long bitrate, const Module_Struct *module);

// for ST MCUs :

void I2Cx_Init_Advanced(unsigned long : I2C_ClockSpeed, const Module_Struct *module);
Description

This function configures and initializes the desired I²C module using custom bitrate setting.
Parameters

Stellaris

  • bitrate: requested serial clock rate :
    Value Description
    _I2C_BITRATE_STANDARD_MODE 100 kbps bit rate.
    _I2C_BITRATE_FAST_MODE 400 kbps bit rate.
    _I2C_BITRATE_FAST_MODE_PLUS Fast-mode plus, 1 Mbps (available only for Stellaris Cortex M4 devices).
    _I2C_BITRATE_HIGH_SPEED_MODE High-speed mode, 3.33 Mbps (available only for Stellaris Cortex M4 devices).

  • module: appropriate module pinout, see the following table :
    I2C Module Pinouts for Stellaris Cortex M3
    I2C0 _GPIO_MODULE_I2C0_B23
    I2C1 _GPIO_MODULE_I2C1_A01 _GPIO_MODULE_I2C1_A67 _GPIO_MODULE_I2C1_G01 _GPIO_MODULE_I2C1_J01

    I2C Module Pinouts for Stellaris Cortex M4
    I2C0 _GPIO_MODULE_I2C0_B23_AHB
    I2C1 _GPIO_MODULE_I2C1_A67_AHB _GPIO_MODULE_I2C1_G45_AHB
    I2C2 _GPIO_MODULE_I2C2_E45_AHB _GPIO_MODULE_I2C2_F67_AHB
    I2C3 _GPIO_MODULE_I2C3_D01_AHB _GPIO_MODULE_I2C3_G01_AHB
    I2C4 _GPIO_MODULE_I2C4_G23_AHB
    I2C5 _GPIO_MODULE_I2C5_B67_AHB _GPIO_MODULE_I2C5_G67_AHB

STM32

  • I2C_ClockSpeed: requested serial clock rate. The peripheral input clock frequency must be at least :

    • 2 MHz in Standard mode (100 Kbps)
    • 4 MHz in Fast mode (400 Kbps)

  • module: appropriate module pinout, see the following table :

    I2C Module Pinouts for ST
    I2C1 _GPIO_MODULE_I2C1_PB67 _GPIO_MODULE_I2C1_PB89
    I2C2 _GPIO_MODULE_I2C2_PB10_11 _GPIO_MODULE_I2C2_PF01 _GPIO_MODULE_I2C2_PH45
    I2C3 _GPIO_MODULE_I2C3_PH78 _GPIO_MODULE_I2C2_F67_AHB
Returns

Nothing.
Requires

MCU with the I²C module.
Example

Stellaris

// Initialize the I2C1 module with in fast mode
I2C1_Init_Advanced(_I2C_BITRATE_FAST_MODE);

// Initialize the I2C1 module with in fast mode on GPIO_PORTJ
I2C1_Init_Advanced(_I2C_BITRATE_FAST_MODE, &_GPIO_MODULE_I2C1_J01);

STM32

// Initialize the I2C1 module with 100Kbps speed on PORTB
I2C1_Init_Advanced(100000, &_GPIO_MODULE_I2C1_PB67);
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • For available working modes for a specific MCU please read the appropriate datasheet.

Stellaris

  • Refer to the table below for correct values of the bit rate in respect with system clock :
    System Clock Standard Mode Fast Mode Fast Mode Plus High-Speed Mode
    4 MHz 100 Kbps - - -
    6 MHz 100 Kbps - - -
    12.5 MHz 89 Kbps 312 Kbps - -
    16.7 MHz 93 Kbps 278 Kbps - -
    20 MHz 100 Kbps 333 Kbps - -
    25 MHz 96.2 Kbps 312 Kbps - -
    33 MHz 97.1 Kbps 330 Kbps - -
    40 MHz 100 Kbps 400 Kbps 1000 Kbps 3.33 Mbps
    50MHz 100 Kbps 357 Kbps 833 Kbps 2.77 Mbps
    80 MHz 100 Kbps 400 Kbps 1000 Kbps 3.33 Mbps

STM32


The peripheral input clock frequency must be at least :

  • 2 MHz in Standard mode (100 Kbps)
  • 4 MHz in Fast mode (400 Kbps)

I2Cx_Enable

Prototype

void I2Cx_Enable();
Description

This routine enables I²C Master block.

This routine is valid only for Stellaris devices.
Parameters

None.
Returns

Nothing.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
// Enable I2C1 Master block
I2C1_Enable();
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for Stellaris devices.

I2Cx_Disable

Prototype

void I2Cx_Disable();
Description

This routine disables I²C Master block.

This routine is valid only for Stellaris devices.
Parameters

None.
Returns

Nothing.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
// Disable I2C1 Master block
I2C1_Disable();
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for Stellaris devices.

I2Cx_Start

Prototype

void I2Cx_Start();
Description

Determines if I²C bus is free and issues START signal.

This routine is valid only for ST devices.
Parameters

None.
Returns

If there is no error, routine returns 0.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
// Start I2C1 module
I2C1_Start();
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for ST devices.

I2Cx_Get_Status

Prototype

function I2Cx_Get_Status() : dword;
Description

This routine returns the values of both I²C status registers, SR1 and SR2, combined in one 32-bit value.

This routine is valid only for ST devices.
Parameters

None.
Returns

Values of both I²C status registers.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
// Get Status for I2C1 module
unsigned long stat;

stat = I2C1_Get_Status();
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for ST devices.

I2Cx_Is_Idle

Prototype

unsigned I2Cx_Is_Idle();
Description

Tests if I²C bus is free.

This routine is valid only for ST devices.
Parameters

None.
Returns

Returns 1 if I²C bus is free, otherwise returns 0.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
if (I2C1_Is_Idle() {
...
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for ST devices.

I2Cx_Master_Slave_Addr_Set

Prototype

void I2Cx_Master_Slave_Addr_Set(char slave_addr, char dir);
Description

Sets the address that the I²C Master will place on the bus, i.e. Slave address.

This routine is valid only for Stellaris devices.
Parameters
  • slave_addr: I²C slave address.
  • dir: I²C Master transceiver direction :
    Value Description
    _I2C_DIR_MASTER_RECEIVE Master receive.
    _I2C_DIR_MASTER_TRANSMIT Master transmit.
Returns

Nothing.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
// Set address which will be used by Master to transmit data to
I2C1_Master_Slave_Addr_Set(0x0A, _I2C_DIR_MASTER_TRANSMIT);
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for Stellaris devices.

I2Cx_Master_Bus_Busy

Prototype

char I2Cx_Master_Bus_Busy();
Description

Indicates whether or not the I²C bus is busy.

This routine is valid only for Stellaris devices.
Parameters

None.
Returns
  • 1 - if the I²C bus is busy,
  • 0 - otherwise.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
// If I2C bus is free :
if (!I2C1_Master_Bus_Busy) {
...
}
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for Stellaris devices.

I2Cx_Master_Busy

Prototype

char I2Cx_Master_Busy();
Description

Indicates whether or not the I²C Master is busy.

This routine is valid only for Stellaris devices.
Parameters

None.
Returns
  • 1 - if the I²C Master is busy,
  • 0 - otherwise.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example 
// If I2C Master is free :
if (!I2C1_Master__Busy) {
...
}
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
  • This routine is valid only for Stellaris devices.

I2Cx_Read

Prototype // for Stellaris MCUs :

char I2Cx_Read(char *dat, char mode);

// for ST MCUs :

void I2Cx_Read(char slave_address, char : ^ptrdata, unsigned long count, unsigned long END_mode);
Description

Receives a byte from the I²C bus.
Parameters

Stellaris

  • dat: received data.
  • mode: mode parameter. Available modes :
    Value Description
    _I2C_MASTER_MODE_SINGLE_RECEIVE Single byte receive.
    _I2C_MASTER_MODE_BURST_RECEIVE_START Start receiving burst of data (used when receiving first byte of data burst).
    _I2C_MASTER_MODE_BURST_RECEIVE_CONT Continue receiving burst of data (used when receiving data burst bytes other than first and last).
    _I2C_MASTER_MODE_BURST_RECEIVE_FINISH End of data burst reception (used when receiving last byte of data burst).

STM32

  • slave_address: slave address.
  • ptrdata: pointer to the received data.
  • count: number of bytes to be received.
  • END_mode: mode in which the I²C module will be set after the reading. Available modes :
    Value Description
    END_MODE_RESTART I²C bus will issue a restart.
    END_MODE_STOP I²C bus will issue a stop.
Returns
  • 0 if there were no errors.
  • 1 if write collision was detected on the I²C bus.
Requires
  • MCU with at least one I²C module.
  • Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example

Stellaris

I2C0_Master_Slave_Addr_Set(0x50, _I2C_DIR_MASTER_RECEIVE); // set slave address, and read operation
I2C0_Read(res, _I2C_MASTER_MODE_SINGLE_RECEIVE);       // issue I2C start, and read byte.

STM32

// Example for ST :
I2C1_Read(0x50, data_, num_bytes, END_MODE_STOP);          // receive num_bytes, store it to data_, and issue a stop condition .
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2Cx_Write

Prototype // for Stellaris MCUs :

unsigned I2Cx_Write(char dat, char mode);

// for ST MCUs :

unsigned I2Cx_Write(unsigned char slave_address, unsigned char *buf, unsigned long count, unsigned long END_mode)
Description

Sends data byte via the I²C bus.
Parameters

Stellaris

  • dat: data to be sent.
  • mode: mode parameter. Available modes :
    Value Description
    _I2C_MASTER_MODE_SINGLE_RECEIVE Single byte transmit.
    _I2C_MASTER_MODE_BURST_RECEIVE_START Start transmitting burst of data (used when transmitting first byte of data burst).
    _I2C_MASTER_MODE_BURST_RECEIVE_CONT Continue transmitting burst of data (used when transmitting data burst bytes other than first and last).
    _I2C_MASTER_MODE_BURST_RECEIVE_FINISH End of data burst transmission (used when transmitting last byte of data burst).

STM32

  • slave_address: slave address.
  • buf: pointer to the received data.
  • count: number of bytes to be received.
  • END_mode: mode in which the I²C module will be set after the writing. Available modes :
    Value Description
    END_MODE_RESTART I²C bus will issue a restart.
    END_MODE_STOP I²C bus will issue a stop.
Returns
  • 0 if there were no errors.
  • 1 if write collision was detected on the I²C bus.
Requires

MCU with at least one I²C module.

Used I²C module must be initialized before using this function. See I2Cx_Init and I2Cx_Init_Advanced routines.
Example

Stellaris

I2C0_Master_Slave_Addr_Set(0x50, _I2C_DIR_MASTER_TRANSMIT); // set slave address, and write operation
I2C0_Write(rAddr, _I2C_MASTER_MODE_SINGLE_SEND);    // issue I2C start, and send byte (address of EEPROM location)

STM32

I2C1_Write(0x50, data_, num_bytes, END_MODE_STOP);          // write num_bytes, stored in data_, and issue a stop condition.
Notes
  • I²C library routines require you to specify the module you want to use. To select the desired I²C module, simply change the letter x in the routine prototype for a number from 0 to 5.
  • Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

Library Example

This code demonstrates working with the I²C library. Program sends data to EEPROM (data is written at the address 2). After that, program reads data from the same EEPROM address and displays it on GPIO_PORTE for visual check. See the figure below how to interface the 24C02 to ARM.

Stellaris

Copy Code To ClipboardCopy Code To Clipboard 
char data_[256];


//--------------- Writes data to 24C02 EEPROM - signle location
void EEPROM_24C02_WrSingle(unsigned short wAddr, unsigned short wData) {
  data_[0] = wAddr;
  data_[1] = wData;
  I2C1_Start();
  // issue I2C start signal
  I2C1_Write(0x50,data_,2,END_MODE_STOP);
}//~

//--------------- Reads data from 24C02 EEPROM - single location (random)
unsigned short EEPROM_24C02_RdSingle(unsigned short rAddr) {
  data_[0] = rAddr;
  I2C1_Start();              // issue I2C start signal
  I2C1_Write(0x50,data_,1,END_MODE_RESTART);
  I2C1_Read(0x50,data_,1,END_MODE_STOP);

  return data_[0];
}

void main(){
  unsigned short i;

  GPIO_Digital_Output(&GPIOD_BASE, _GPIO_PINMASK_ALL);

  I2C1_Init();        // performs I2C initialization

  GPIOD_ODR = 0xFFFF;
  Delay_ms(1000);

  for(i = 0; i<0x80; i++) {
    EEPROM_24C02_WrSingle(i,i);
    GPIOD_ODR++;
    delay_ms(5);
  }

  Delay_ms(500);
  GPIOD_ODR = 0xFFFF;
  Delay_ms(1000);

  for(i = 0x00; i < 0x80; i++){
    GPIOD_ODR = EEPROM_24C02_RdSingle(i);
    delay_ms(100);
  }

}

STM32

Copy Code To ClipboardCopy Code To Clipboard 
void EEPROM_24C02_Init() {
  I2C0_Init();
}

//--------------- Writes data to 24C02 EEPROM - signle location
void EEPROM_24C02_WrSingle(unsigned short wAddr, unsigned short wData) {
  
  I2C0_Master_Slave_Addr_Set(0x50, _I2C_DIR_MASTER_TRANSMIT); // set slave address, and write operation
  I2C0_Write(wAddr, _I2C_MASTER_MODE_BURST_SEND_START);  // issue I2C start, and send byte (address of EEPROM location)
  I2C0_Write(wData, _I2C_MASTER_MODE_BURST_SEND_FINISH); // send data (data to be written), and finish transmit
}

//--------------- Reads data from 24C02 EEPROM - single location (random)
unsigned short EEPROM_24C02_RdSingle(unsigned short rAddr) {
  unsigned short reslt;
  
  I2C0_Master_Slave_Addr_Set(0x50, _I2C_DIR_MASTER_TRANSMIT); // set slave address, and write operation
  I2C0_Write(rAddr, _I2C_MASTER_MODE_SINGLE_SEND);       // issue I2C start, and send byte (address of EEPROM location)

  I2C0_Master_Slave_Addr_Set(0x50, _I2C_DIR_MASTER_RECEIVE); // set slave address, and read operation
  I2C0_Read(&reslt, _I2C_MASTER_MODE_SINGLE_RECEIVE);    // issue I2C start, and read byte.
  return reslt;
}

unsigned short i;
char b;
void main(){

  GPIO_Digital_Output(&GPIO_PORTD_DATA_BITS, _GPIO_PINMASK_ALL);  // Configure GPIO_PORTD as output
  GPIO_PORTD_DATA = 0;                                            // Set GPIO_PORTD value to zero
  GPIO_Digital_Output(&GPIO_PORTE_DATA_BITS, _GPIO_PINMASK_ALL);  // Configure GPIO_PORTE as output
  GPIO_PORTE_DATA = 0;                                            // Set GPIO_PORTE value to zero

  EEPROM_24C02_Init();        // performs I2C initialization
  b = 0x00;
  for(i = 0x00; i<0x80; i++) {
    EEPROM_24C02_WrSingle(i,b);
    b++;
    delay_ms(5);
  }
  for(i = 0x00; i < 0x80; i++){
    GPIO_PORTD_DATA = i;
    GPIO_PORTE_DATA = EEPROM_24C02_RdSingle(i);
    delay_ms(50);
  }
}
Copyright (c) 2002-2012 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