Description

Driver to communicate with I2C slaves.

File(s):

The driver must be configured by supplying a project specific "px_i2c_cfg.h". "px_i2c_cfg_template.h" can be copied, renamed and modified to supply compile time options.

Example:: #include "px_i2c.h"

#include "px_board.h"

// Bosch BMP280 I2C Slave Address

#define I2C_SLA_ADR 0x76

// Create I2C Slave handle object

px_i2c_handle_t px_i2c_handle;

int main(void)

{

uint8_t data[1];

// Initialise board

px_board_init();

// Initialise I2C driver

px_i2c_init();

// Open handle to I2C slave device

px_i2c_open(&px_i2c_handle, PX_I2C_NR_1, I2C_SLA_ADR);

// START I2C write transaction and write register address

data[0] = 0xd0;

px_i2c_wr(&px_i2c_handle, data, 1, PX_I2C_FLAG_START_AND_END);

// REPEATED START I2C read transaction and read register value

px_i2c_rd(&px_i2c_handle, data, 1, PX_I2C_FLAG_REP_START_AND_STOP);

// Close I2C Handle

px_i2c_close(&px_i2c_handle);

}

px_board_init
void px_board_init(void)
Initialise the board hardware.
Definition: px_board.c:168

px_i2c_close
bool px_i2c_close(px_i2c_handle_t *handle)
Close specified handle.
Definition: px_i2c.c:184

px_i2c_init
void px_i2c_init(void)
Initialise I2C driver.
Definition: px_i2c.c:107

px_i2c_open
bool px_i2c_open(px_i2c_handle_t *handle, px_i2c_nr_t i2c_nr, uint8_t slave_adr)
Open I2C slave handle.
Definition: px_i2c.c:118

px_i2c_rd
bool px_i2c_rd(px_i2c_handle_t *handle, void *data, size_t nr_of_bytes, uint8_t flags)
Perform an I2C read transaction with an I2C slave.
Definition: px_i2c.c:430

PX_I2C_FLAG_REP_START_AND_STOP
#define PX_I2C_FLAG_REP_START_AND_STOP
Begin and finish an I2C transaction with a REP START and STOP condition.
Definition: px_i2c.h:97

PX_I2C_FLAG_START_AND_END
#define PX_I2C_FLAG_START_AND_END
Begin and finish an I2C transaction with a START and END condition.
Definition: px_i2c.h:95

px_i2c_wr
bool px_i2c_wr(px_i2c_handle_t *handle, const void *data, size_t nr_of_bytes, uint8_t flags)
Perform an I2C write transaction with an I2C slave.
Definition: px_i2c.c:240

px_i2c_handle_t
Define I2C handle for a slave.
Definition: px_i2c.h:104

Data Structures
struct	px_i2c_handle_t
	Define I2C handle for a slave. More...

Macros
#define	PX_I2C_CFG_PER_COUNT
	Number of enabled peripherals. More...

#define	PX_I2C_CFG_I2C1_EN 1
	Enable/disable support for I2C1 peripheral. More...

#define	PX_I2C_CFG_I2C2_EN 0
	Enable/disable support for I2C2 peripheral. More...

#define	PX_I2C_CFG_TIMINGR 0x20302e37
	I2C peripheral timing register value Calculated using STM32CubeMX graphical tool: More...

Enumerations
enum	px_i2c_nr_t
	Specify I2C peripheral. More...

Functions
void	px_i2c_init (void)
	Initialise I2C driver. More...

bool	px_i2c_open (px_i2c_handle_t *handle, px_i2c_nr_t i2c_nr, uint8_t slave_adr)
	Open I2C slave handle. More...

bool	px_i2c_close (px_i2c_handle_t *handle)
	Close specified handle. More...

bool	px_i2c_wr (px_i2c_handle_t handle, const void data, size_t nr_of_bytes, uint8_t flags)
	Perform an I2C write transaction with an I2C slave. More...

bool	px_i2c_rd (px_i2c_handle_t handle, void data, size_t nr_of_bytes, uint8_t flags)
	Perform an I2C read transaction with an I2C slave. More...

void	px_i2c_change_slave_adr (px_i2c_handle_t *handle, uint8_t slave_adr)
	Change I2C slave address. More...

I2C bit flags to demarcate the start and end of a transaction
#define	PX_I2C_FLAG_START (1 << 0)
	Begin I2C transaction with a START condition. More...

#define	PX_I2C_FLAG_STOP (1 << 1)
	Finish I2C transaction with a STOP condition. More...

#define	PX_I2C_FLAG_END (1 << 2)
	Signal END of current I2C transaction for REP_START to follow. More...

#define	PX_I2C_FLAG_REP_START (1 << 3)
	Begin I2C transaction with a REPEATED START condition. More...

#define	PX_I2C_FLAG_START_AND_STOP (PX_I2C_FLAG_START + PX_I2C_FLAG_STOP)
	Begin and finish an I2C transaction with a START and STOP condition. More...

#define	PX_I2C_FLAG_START_AND_END (PX_I2C_FLAG_START + PX_I2C_FLAG_END)
	Begin and finish an I2C transaction with a START and END condition. More...

#define	PX_I2C_FLAG_REP_START_AND_STOP (PX_I2C_FLAG_REP_START + PX_I2C_FLAG_STOP)
	Begin and finish an I2C transaction with a REP START and STOP condition. More...

#define	PX_I2C_FLAG_REP_START_AND_END (PX_I2C_FLAG_REP_START + PX_I2C_FLAG_END)
	Begin and finish an I2C transaction with a REP START and END condition. More...

Data Structure Documentation

◆ px_i2c_handle_t

struct px_i2c_handle_t

Define I2C handle for a slave.

Definition at line 103 of file px_i2c.h.

Data Fields
struct px_i2c_per_s *	i2c_per	I2C peripheral data.
uint8_t	slave_adr	7-bit I2C slave address

Macro Definition Documentation

◆ PX_I2C_CFG_PER_COUNT

#define PX_I2C_CFG_PER_COUNT

Value:

( PX_I2C_CFG_I2C1_EN \

+ PX_I2C_CFG_I2C2_EN )

PX_I2C_CFG_I2C1_EN

#define PX_I2C_CFG_I2C1_EN

Enable/disable support for I2C1 peripheral.

Definition: px_i2c_cfg_template.h:36

PX_I2C_CFG_I2C2_EN

#define PX_I2C_CFG_I2C2_EN

Enable/disable support for I2C2 peripheral.

Definition: px_i2c_cfg_template.h:39

Number of enabled peripherals.

Definition at line 62 of file px_i2c.h.

◆ PX_I2C_FLAG_START

#define PX_I2C_FLAG_START (1 << 0)

Begin I2C transaction with a START condition.

Definition at line 85 of file px_i2c.h.

◆ PX_I2C_FLAG_STOP

#define PX_I2C_FLAG_STOP (1 << 1)

Finish I2C transaction with a STOP condition.

Definition at line 87 of file px_i2c.h.

◆ PX_I2C_FLAG_END

#define PX_I2C_FLAG_END (1 << 2)

Signal END of current I2C transaction for REP_START to follow.

Definition at line 89 of file px_i2c.h.

◆ PX_I2C_FLAG_REP_START

#define PX_I2C_FLAG_REP_START (1 << 3)

Begin I2C transaction with a REPEATED START condition.

Definition at line 91 of file px_i2c.h.

◆ PX_I2C_FLAG_START_AND_STOP

#define PX_I2C_FLAG_START_AND_STOP (PX_I2C_FLAG_START + PX_I2C_FLAG_STOP)

Begin and finish an I2C transaction with a START and STOP condition.

Definition at line 93 of file px_i2c.h.

◆ PX_I2C_FLAG_START_AND_END

#define PX_I2C_FLAG_START_AND_END (PX_I2C_FLAG_START + PX_I2C_FLAG_END)

Begin and finish an I2C transaction with a START and END condition.

Definition at line 95 of file px_i2c.h.

◆ PX_I2C_FLAG_REP_START_AND_STOP

#define PX_I2C_FLAG_REP_START_AND_STOP (PX_I2C_FLAG_REP_START + PX_I2C_FLAG_STOP)

Begin and finish an I2C transaction with a REP START and STOP condition.

Definition at line 97 of file px_i2c.h.

◆ PX_I2C_FLAG_REP_START_AND_END

#define PX_I2C_FLAG_REP_START_AND_END (PX_I2C_FLAG_REP_START + PX_I2C_FLAG_END)

Begin and finish an I2C transaction with a REP START and END condition.

Definition at line 99 of file px_i2c.h.

◆ PX_I2C_CFG_I2C1_EN

#define PX_I2C_CFG_I2C1_EN 1

Enable/disable support for I2C1 peripheral.

Definition at line 36 of file px_i2c_cfg_template.h.

◆ PX_I2C_CFG_I2C2_EN

#define PX_I2C_CFG_I2C2_EN 0

Enable/disable support for I2C2 peripheral.

Definition at line 39 of file px_i2c_cfg_template.h.

◆ PX_I2C_CFG_TIMINGR

#define PX_I2C_CFG_TIMINGR 0x20302e37

I2C peripheral timing register value Calculated using STM32CubeMX graphical tool:

Speed Frequency = 100 kHz
Rise Time = 100 ns
Fall Time = 10 ns
Analog Filter = Enabled

Definition at line 49 of file px_i2c_cfg_template.h.

Enumeration Type Documentation

◆ px_i2c_nr_t

enum px_i2c_nr_t

Specify I2C peripheral.

Definition at line 75 of file px_i2c.h.

Function Documentation

◆ px_i2c_init()

void px_i2c_init ( void )

Initialise I2C driver.

Definition at line 107 of file px_i2c.c.

◆ px_i2c_open()

bool px_i2c_open	(	px_i2c_handle_t *	handle,
		px_i2c_nr_t	i2c_nr,
		uint8_t	slave_adr
	)

Open I2C slave handle.

Parameters

handle	Pointer to handle data structure
i2c_nr	I2C peripheral number
slave_adr	7-bit I2C slave address

Return values

false	Error - handle was not opened
true	Success - handle was opened

Definition at line 118 of file px_i2c.c.

◆ px_i2c_close()

bool px_i2c_close ( px_i2c_handle_t * handle )

Close specified handle.

Parameters

handle Pointer to handle data structure

Return values

true	Success
false	Specified handle was already closed (or not opened)

Definition at line 184 of file px_i2c.c.

◆ px_i2c_wr()

bool px_i2c_wr	(	px_i2c_handle_t *	handle,
		const void *	data,
		size_t	nr_of_bytes,
		uint8_t	flags
	)

Perform an I2C write transaction with an I2C slave.

With the use of flags this function allows concatenation of one or more writes to an I2C slave to form one big write transaction. It is also possible to generate a REPEATED START (RESTART) condition by not generating an intervening STOP condition.

If the PX_I2C_FLAG_START flag is specified, a START condition is generated and the 7-bit slave address and WRITE bit is sent on the bus (SLA+W). If a NAK is received, a STOP condition is generated to return the I2C bus to idle state.

The specified number of bytes is sent with the slave supposed to ACK each byte. If a NAK is received, a STOP condition is generated to return the I2C bus to idle state.

If the PX_I2C_FLAG_STOP flag is specified, a STOP condition is generated to complete the transaction and return the I2C bus to the idle state.

More than one I2C transaction may be concatenated without releasing the I2C bus by using a REPEATED START condition. This is acheived by signalling the end of the current transaction with the PX_I2C_FLAG_END flag and starting the next transaction with a PX_I2C_FLAG_REP_START flag.

Parameters

handle	Pointer to handle data structure
data	Buffer containing data to write
nr_of_bytes	Number of bytes to write to the slave
flags	Bit combination of PX_I2C_FLAG_START, PX_I2C_FLAG_STOP, PX_I2C_FLAG_REP_START, PX_I2C_FLAG_END or nothing (0)

Return values

true	Slave ACK'd all bytes written to it
false	Received a NAK or bus error

Definition at line 240 of file px_i2c.c.

◆ px_i2c_rd()

bool px_i2c_rd	(	px_i2c_handle_t *	handle,
		void *	data,
		size_t	nr_of_bytes,
		uint8_t	flags
	)

Perform an I2C read transaction with an I2C slave.

With the use of flags this function allows concatenation of one or more reads from an I2C slave to form one big read transaction. It is also possible to generate a REPEATED START (RESTART) condition by not generating an intervening STOP condition.

If the PX_I2C_FLAG_START flag is specified, A START condition is generated and the 7-bit slave address and READ bit is sent on the bus (SLA+R). If a NAK is received, a STOP condition is generated to return the I2C bus to idle state.

The specified number of bytes is read from the slave and each byte is ACKed, except the last one. If the PX_I2C_FLAG_STOP or PX_I2C_FLAG_END flag is specified, the last byte is NAKed to indicate to the I2C slave that this is the end of the read transaction, otherwise it is also ACKed to allow the read transaction to continue.

If the PX_I2C_FLAG_STOP flag is specified, a STOP condition is generated to complete the transaction and return the I2C bus to the idle state.

More than one I2C transaction may be concatenated without releasing the I2C bus by using a REPEATED START condition. This is acheived by signalling the end of the current transaction with the PX_I2C_FLAG_END flag and starting the next transaction with a PX_I2C_FLAG_REP_START flag.

Parameters

handle	Pointer to handle data structure
data	Pointer to a buffer where the received data must be stored
nr_of_bytes	Number of bytes to read from slave
flags	Bit combination of PX_I2C_FLAG_START, PX_I2C_FLAG_STOP, PX_I2C_FLAG_REP_START, PX_I2C_FLAG_END or nothing (0)

Return values

true	Byte(s) succesfully read
false	Received NAK or bus error

Definition at line 430 of file px_i2c.c.

◆ px_i2c_change_slave_adr()

void px_i2c_change_slave_adr	(	px_i2c_handle_t *	handle,
		uint8_t	slave_adr
	)

Change I2C slave address.

Parameters

handle	Pointer to handle data structure
slave_adr	New 7-bit I2C slave address

Definition at line 615 of file px_i2c.c.

Description

Data Structures

Macros

Enumerations

Functions

I2C bit flags to demarcate the start and end of a transaction

Data Structure Documentation

◆ px_i2c_handle_t

Macro Definition Documentation

◆ PX_I2C_CFG_PER_COUNT

◆ PX_I2C_FLAG_START

◆ PX_I2C_FLAG_STOP

◆ PX_I2C_FLAG_END

◆ PX_I2C_FLAG_REP_START

◆ PX_I2C_FLAG_START_AND_STOP

◆ PX_I2C_FLAG_START_AND_END

◆ PX_I2C_FLAG_REP_START_AND_STOP

◆ PX_I2C_FLAG_REP_START_AND_END

◆ PX_I2C_CFG_I2C1_EN

◆ PX_I2C_CFG_I2C2_EN

◆ PX_I2C_CFG_TIMINGR

Enumeration Type Documentation

◆ px_i2c_nr_t

Function Documentation

◆ px_i2c_init()

◆ px_i2c_open()

◆ px_i2c_close()

◆ px_i2c_wr()

◆ px_i2c_rd()

◆ px_i2c_change_slave_adr()