I2C Library

I²C Library

The I²C full master I²C module is available with a number of the dsPIC30/33 and PIC24 MCU models. The mikroC PRO for dsPIC30/33 and PIC24 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 1 to 3.
Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

Generic Routines

I2C_Start
I2C_Restart
I2C_Is_Idle
I2C_Read
I2C_Write
I2C_Stop

I2Cx_Init

Prototype	void I2Cx_Init(unsigned long scl);
Description	Configures and initializes the desired I²C module with default settings. This function enables the I²C module by setting the I2CEN bit. The rest of the bits in I²C control register remains unchanged. Default initialization (after reset) of I²C module is: continue operation in IDLE mode IPMI mode disabled 7-bit slave address slew rate control enabled general call address disabled software or receive clock stretching disabled
Parameters	`scl:` requested serial clock rate.
Returns	Nothing.
Requires	MCU with the I²C module.
Example	// Initialize the I2C1 module with clock_rate of 100000 I2C1_Init(100000);
Notes	Refer to the MCU's datasheet for correct values of the `scl` in respect with Fosc. 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 1 to 3. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2Cx_Start

Prototype	void I2Cx_Start();
Description	Determines if the I²C bus is free and issues START signal.
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 routine.
Example	// Issue START signal 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 1 to 3. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2Cx_Restart

Prototype	void I2Cx_Restart();
Description	Issues repeated START signal.
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 routine.
Example	// Issue RESTART signal I2C1_Restart();
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 1 to 3. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2Cx_Is_Idle

Prototype	unsigned I2Cx_Is_Idle();
Description	Waits for the I²C bus to become free. This is a blocking function.
Parameters	None.
Returns	`0` if I²C bus is free. `1` if I²C bus is not free.
Requires	MCU with at least one I²C module. Used I²C module must be initialized before using this function. See I2Cx_Init routine.
Example	unsigned char data_; ... if (!I2C1_Is_Idle) I2C1_Write(data_); ...
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 1 to 3. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2Cx_Read

Prototype	unsigned char I2Cx_Read(unsigned ack);
Description	Reads a byte from the I²C bus.
Parameters	`ack:` acknowledge signal parameter. If the `ack = 0`, acknowledge signal will be sent after reading, otherwise the not acknowledge signal will be sent.
Returns	Received data.
Requires	MCU with at least one I²C module. Used I²C module must be initialized before using this function. See I2Cx_Init routine. Also, START signal needs to be issued in order to use this function. See I2Cx_Start.
Example	unsigned char take; ... // Read data and send the not_acknowledge signal take = I2C1_Read(1);
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 1 to 3. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2Cx_Write

Prototype	unsigned I2Cx_Write(unsigned char data_);
Description	Sends data byte via the I²C bus.
Parameters	`data_:` data to be sent
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 routine. Also, START signal needs to be issued in order to use this function. See I2Cx_Start.
Example	unsigned char data_; unsigned error; ... error = I2C1_Write(data_); error = I2C1_Write(0xA3);
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 1 to 3. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2Cx_Stop

Prototype	void I2Cx_Stop();
Description	Issues STOP signal.
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 routine.
Example	// Issue STOP signal I2C1_Stop();
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 1 to 3. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2C_Set_Active

Prototype	void I2C_Set_Active(unsigned (start_ptr)(), unsigned* (restart_ptr)(), unsigned char* (read_ptr)(unsigned), unsigned* (write_ptr)(unsigned char), void* (stop_ptr)(), unsigned* (*is_idle_ptr)());
Description	Sets the active I²C module which will be used by the I²C routines.
Parameters	`start_ptr:` I2Cx_Start handler `restart_ptr:` I2Cx_Restart handler `read_ptr:` I2Cx_Read handler `write_ptr:` I2Cx_Write handler `stop_ptr:` I2Cx_Stop handler `is_idle_ptr:` I2Cx_Is_Idle handler
Returns	Nothing.
Requires	Used I²C module must be initialized before using this function. See the I2Cx_Init routines.
Example	I2C_Set_Active(&I2C1_Start, &I2C1_Restart, &I2C1_Read, &I2C1_Write, &I2C1_Stop, &I2C1_Is_Idle); // Sets the I2C1 module active
Notes	Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2C_Start

Prototype	unsigned I2C_Start();
Description	Determines if the I²C bus is free and issues START signal. This is a generic routine which uses the active I²C module previously activated by the I2C_Set_Active routine.
Parameters	None.
Returns	`0` if I²C bus was successfully started. `0xFFFF` if I²C bus was not successfully started.
Requires	MCU with at least one I²C module. Used I²C module must be initialized before using this function. See I2Cx_Init routine.
Example	I2C_Set_Active(&I2C1_Start, &I2C1_Restart, &I2C1_Read, &I2C1_Write, &I2C1_Stop, &I2C1_Is_Idle); // Sets the I2C1 module active // Issue START signal I2C1_Start();
Notes	None.

I2C_Restart

Prototype	unsigned I2C_Restart();
Description	Issues repeated START signal. This is a generic routine which uses the active I²C module previously activated by the I2C_Set_Active routine.
Parameters	None.
Returns	`0` if I²C bus was successfully restarted. `0xFFFF` if I²C bus was not successfully restarted.
Requires	MCU with at least one I²C module. Used I²C module must be initialized before using this function. See I2Cx_Init routine.
Example	I2C_Set_Active(&I2C1_Start, &I2C1_Restart, &I2C1_Read, &I2C1_Write, &I2C1_Stop, &I2C1_Is_Idle); // Sets the I2C1 module active ... // Issue RESTART signal I2C_Restart();
Notes	None.

I2C_Is_Idle

Prototype	unsigned I2C_Is_Idle();
Description	Waits for the I²C bus to become free. This is a blocking function. This is a generic routine which uses the active I²C module previously activated by the I2C_Set_Active routine.
Parameters	None.
Returns	`0` if I²C bus is free. `1` if I²C bus is not free.
Requires	MCU with at least one I²C module. Used I²C module must be initialized before using this function. See I2Cx_Init routine.
Example	unsigned char data_; ... I2C_Set_Active(&I2C1_Start, &I2C1_Restart, &I2C1_Read, &I2C1_Write, &I2C1_Stop, &I2C1_Is_Idle); // Sets the I2C1 module active if !(I2C_Is_Idle) I2C_Write(data_); ...
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 1 to 5. Number of I²C modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.

I2C_Read

Prototype	unsigned char I2C_Read(unsigned ack);
Description	Reads a byte from the I²C bus. This is a generic routine which uses the active I²C module previously activated by the I2C_Set_Active routine.
Parameters	`ack:` acknowledge signal parameter. If this parameter is `_I2C_ACK`, acknowledge signal will be sent after reading, if its value is `_I2C_NACK`, not acknowledge signal will be sent after reading.
Returns	Received data.
Requires	MCU with at least one I²C module. Used I²C module must be initialized before using this function. See I2Cx_Init routine. Also, START signal needs to be issued in order to use this function. See I2Cx_Start.
Example	unsigned char take; ... I2C_Set_Active(&I2C1_Start, &I2C1_Restart, &I2C1_Read, &I2C1_Write, &I2C1_Stop, &I2C1_Is_Idle); // Sets the I2C1 module active // Read data and send the not_acknowledge signal take = I2C_Read(_I2C_NACK);
Notes	None.

I2C_Write

Prototype	unsigned I2C_Write(unsigned char data_);
Description	Sends data byte via the I²C bus. This is a generic routine which uses the active I²C module previously activated by the I2C_Set_Active routine.
Parameters	`data_:` data to be sent
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 routine. Also, START signal needs to be issued in order to use this function. See I2Cx_Start.
Example	unsigned char data_; unsigned error; ... I2C_Set_Active(&I2C1_Start, &I2C1_Restart, &I2C1_Read, &I2C1_Write, &I2C1_Stop, &I2C1_Is_Idle); // Sets the I2C1 module active error = I2C_Write(data_); error = I2C_Write(0xA3);
Notes	None.

I2C_Stop

Prototype	void I2C_Stop();
Description	Issues STOP signal. This is a generic routine which uses the active I²C module previously activated by the I2C_Set_Active routine.
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 routine.
Example	I2C_Set_Active(&I2C1_Start, &I2C1_Restart, &I2C1_Read, &I2C1_Write, &I2C1_Stop, &I2C1_Is_Idle); // Sets the I2C1 module active // Issue STOP signal I2C_Stop();
Notes	None.

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 PORTB for visual check. See the figure below how to interface the 24C02 to dsPIC30/33 and PIC24.

Copy Code To Clipboard

void main(){
  ADPCFG = 0xFFFF;           // initialize AN pins as digital

  LATB = 0;
  TRISB = 0;                 // Configure PORTB as output

  I2C1_Init(100000);         // initialize I2C communication
  I2C1_Start();              // issue I2C start signal
  I2C1_Write(0xA2);          // send byte via I2C  (device address + W)
  I2C1_Write(2);             // send byte (address of EEPROM location)
  I2C1_Write(0xF0);          // send data (data to be written)
  I2C1_Stop();               // issue I2C stop signal

  Delay_100ms();

  I2C1_Start();              // issue I2C start signal
  I2C1_Write(0xA2);          // send byte via I2C  (device address + W)
  I2C1_Write(2);             // send byte (data address)
  I2C1_Restart();            // issue I2C signal repeated start
  I2C1_Write(0xA3);          // send byte (device address + R)
  LATB = I2C1_Read(1u);      // Read the data (NO acknowledge)
  I2C1_Stop();               // issue I2C stop signal
}

HW Connection

Interfacing 24c02 to dsPIC30/33 and PIC24 via I²C

Want more examples and libraries?
Find them on