I2C Library

I²C Library

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

Important :

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 routine prototypes may vary from family to family, so please pay attention to the desired routine section.

I2Cx_Init

Prototype

sub procedure 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 :

sub procedure I2Cx_Init_Advanced(dim bitrate as longword)

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

sub procedure I2Cx_Init_Advanced(dim bitrate as longword, dim module as ^const Module_Struct)

' for ST MCUs :

sub procedure I2Cx_Init_Advanced(dim I2C_ClockSpeed as longword, dim module as ^const Module_Struct)

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 in fast mode
I2C1_Init_Advanced(_I2C_BITRATE_FAST_MODE)

' Initialize the I2C1 module 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	sub procedure 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	sub procedure I2Cx_Restart()
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	sub procedure 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	sub function I2Cx_Get_Status() as longword
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 dim stat as longword 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	sub function I2Cx_Is_Idle() as word
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() then ...
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

sub procedure I2Cx_Master_Slave_Addr_Set(dim slave_addr as byte, dim dir as byte)

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	sub function I2Cx_Master_Bus_Busy() as byte
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 = 0) then ... end if
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	sub function I2Cx_Master_Busy() as byte
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 = 0) then ... end if
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 :

sub function I2Cx_Read(dim byref dat as byte, dim mode as byte) as byte

' for ST MCUs :

sub procedure I2Cx_Read(dim slave_address as byte, dim ptrdata as ^byte, dim count as longword, dim END_mode as longword)

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 :

sub function I2Cx_Write(dim dat as byte, dim mode as byte) as byte

' for ST MCUs :

sub function I2Cx_Write(dim slave_address as byte, dim ptrdata as ^byte, dim count as longword, dim END_mode as longword) as word

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_PORTB for visual check. See the figure below how to interface the 24C02 to ARM.

Stellaris

Copy Code To Clipboard

program I2C_Simple

dim i, b as char
    atest as word

sub procedure EEPROM_24C02_Init()
  I2C0_Init()
end sub

'--------------- Writes data to 24C02 EEPROM - signle location
sub procedure EEPROM_24C02_WrSingle(dim wAddr as byte, dim wData as byte)
  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
end sub

'--------------- Reads data from 24C02 EEPROM - single location (random)
sub function EEPROM_24C02_RdSingle(dim rAddr as byte) as byte
dim
  res as char
  
  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(res, _I2C_MASTER_MODE_SINGLE_RECEIVE)       ' issue I2C start, and read byte.
  result = res
end sub

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 to 0x7F
    EEPROM_24C02_WrSingle(i,b)
    Inc(b)
    Delay_ms(5)
  next i

  for i = 0x00 to 0x7F
    GPIO_PORTD_DATA = i
    GPIO_PORTE_DATA = EEPROM_24C02_RdSingle(i)
    Delay_ms(50)
  next i
end.

STM32

Copy Code To Clipboard

program I2C_Simple

dim i as char
dim data_ as byte[256]

'--------------- Writes data to 24C02 EEPROM - signle location
sub procedure EEPROM_24C02_WrSingle(dim wAddr as byte, dim wData as byte)
  data_[0] = wAddr
  data_[1] = wData
  I2C1_Start()
  ' issue I2C start signal
  I2C1_Write(0x50,@data_,2,END_MODE_STOP)
end sub

'--------------- Reads data from 24C02 EEPROM - single location (random)
sub function EEPROM_24C02_RdSingle(dim rAddr as byte) as byte
  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)

  result = data_[0]
end sub

main:

  GPIO_Digital_Output(@GPIOD_BASE, _GPIO_PINMASK_ALL)

  I2C1_Init()              ' performs I2C initialization

  GPIOD_ODR = 0xFFFF
  Delay_ms(1000)

  for i = 0x00 to 0x7F
    EEPROM_24C02_WrSingle(i,i)
    Inc(GPIOD_ODR)
    Delay_ms(5)
  next i

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

  for i = 0x00 to 0x7F
    GPIOD_ODR = EEPROM_24C02_RdSingle(i)
    Delay_ms(50)
  next i

end.

Want more examples and libraries?
Find them on