Mistake on this page?
Report an issue in GitHub or email us
Modules | Functions
I2C Configuration Functions

Defined behavior

More...

Modules

 I2C hal tests
 The I2C HAL tests ensure driver conformance to defined behaviour.
 

Functions

void i2c_get_capabilities (i2c_capabilities_t *capabilities)
 Fills structure indicating supported features and frequencies on the current platform. More...
 
void i2c_init (i2c_t *obj, PinName sda, PinName scl, bool is_slave)
 Initialize the I2C peripheral. More...
 
void i2c_free (i2c_t *obj)
 Release the I2C object. More...
 
uint32_t i2c_frequency (i2c_t *obj, uint32_t frequency)
 Configure the frequency in Hz at which the I2C peripheral should operate. More...
 
void i2c_set_clock_stretching (i2c_t *obj, bool enabled)
 Enable or disable clock stretching for the I2C peripheral. More...
 
void i2c_timeout (i2c_t *obj, uint32_t timeout)
 Configure the timeout duration in microseconds for blocking transmission. More...
 
void i2c_start (i2c_t *obj)
 Send START command. More...
 
void i2c_stop (i2c_t *obj)
 Send STOP command. More...
 
int32_t i2c_write (i2c_t *obj, uint16_t address, const uint8_t *data, uint32_t length, bool stop)
 Blocking sending data. More...
 
int32_t i2c_read (i2c_t *obj, uint16_t address, uint8_t *data, uint32_t length, bool stop)
 Blocking reading data. More...
 
const PinMapi2c_master_sda_pinmap (void)
 Get the pins that support I2C SDA. More...
 
const PinMapi2c_master_scl_pinmap (void)
 Get the pins that support I2C SCL. More...
 
const PinMapi2c_slave_sda_pinmap (void)
 Get the pins that support I2C SDA. More...
 
const PinMapi2c_slave_scl_pinmap (void)
 Get the pins that support I2C SCL. More...
 

Detailed Description

Defined behavior

Undefined behavior

Function Documentation

void i2c_free ( i2c_t obj)

Release the I2C object.

Parameters
objThe I2C object to deinitialize
uint32_t i2c_frequency ( i2c_t obj,
uint32_t  frequency 
)

Configure the frequency in Hz at which the I2C peripheral should operate.

Parameters
objThe I2C object
frequencyFrequency in Hz
Returns
The actual frequency that the peripheral generates to allow a user to adjust its strategy in case the target cannot be reached.
void i2c_get_capabilities ( i2c_capabilities_t capabilities)

Fills structure indicating supported features and frequencies on the current platform.

Parameters
[out]capabilitiesCapabilities structure filled with supported configurations.
void i2c_init ( i2c_t obj,
PinName  sda,
PinName  scl,
bool  is_slave 
)

Initialize the I2C peripheral.

It sets the default parameters for the I2C peripheral and configures its pins.

Parameters
objThe I2C object
sdaThe sda pin
sclThe scl pin
is_slaveChoose whether the peripheral is initialized as master or slave.
const PinMap* i2c_master_scl_pinmap ( void  )

Get the pins that support I2C SCL.

Return a PinMap array of pins that support I2C SCL in master mode. The array is terminated with {NC, NC, 0}.

Returns
PinMap array
const PinMap* i2c_master_sda_pinmap ( void  )

Get the pins that support I2C SDA.

Return a PinMap array of pins that support I2C SDA in master mode. The array is terminated with {NC, NC, 0}.

Returns
PinMap array
int32_t i2c_read ( i2c_t obj,
uint16_t  address,
uint8_t *  data,
uint32_t  length,
bool  stop 
)

Blocking reading data.

This function receives data when the peripheral is configured as Master from the selected slave and when configured as Slave from the Master.

This function is blocking; it returns when the transfer is complete or a timeout event is triggered. The number of bytes received is returned by the function after the operation is completed. Receive operation cannot be canceled or aborted.

When in master mode, the operation consists of:

  • Addressing the slave as a Master receiver.
  • Receiving data from the addressed slave.
  • Generating a STOP condition if the specified stop field is true.
Parameters
objThe I2C object
address7/10-bit address (last bit is 1)
dataThe buffer for receiving
lengthNumber of bytes to read
stopIf true, stop is generated after the transfer is done
Note
If the current platform supports multimaster operation, the peripheral performs arbitration automatically when detecting collisions and completes the transfer or returns I2C_ERROR_ARBITRATION_LOST when it loses arbitration.

Additional time for arbitration or clock stretching should by count by setting appropriate timeout value.

When no transmision timeout is set by the user, the default timeout value is used. It counts one additional byte for addressing stage: default_timeout = (length + 1) * byte_timeout.

Returns
zero or nonzero - Number of written bytes negative - I2C_ERROR_XXX status
void i2c_set_clock_stretching ( i2c_t obj,
bool  enabled 
)

Enable or disable clock stretching for the I2C peripheral.

Parameters
objThe I2C object
enabledIf 'true', enable clock stretching on the given I2C peripheral; otherwise, disable it.
const PinMap* i2c_slave_scl_pinmap ( void  )

Get the pins that support I2C SCL.

Return a PinMap array of pins that support I2C SCL in slave mode. The array is terminated with {NC, NC, 0}.

Returns
PinMap array
const PinMap* i2c_slave_sda_pinmap ( void  )

Get the pins that support I2C SDA.

Return a PinMap array of pins that support I2C SDA in slave mode. The array is terminated with {NC, NC, 0}.

Returns
PinMap array
void i2c_start ( i2c_t obj)

Send START command.

Parameters
objThe I2C object.
void i2c_stop ( i2c_t obj)

Send STOP command.

Parameters
objThe I2C object
void i2c_timeout ( i2c_t obj,
uint32_t  timeout 
)

Configure the timeout duration in microseconds for blocking transmission.

Parameters
objThe I2C object
timeoutTransmission timeout in microseconds.
Note
If no timeout is set, the default timeout is used. Default timeout value is based on I2C frequency. Byte timeout is computed as triple amount of time it would take to send 10 bit over I2C and is expressed by the formula: byte_timeout = 3 * (1/frequency * 10 * 1000000)
int32_t i2c_write ( i2c_t obj,
uint16_t  address,
const uint8_t *  data,
uint32_t  length,
bool  stop 
)

Blocking sending data.

This function transmits data when the peripheral is configured as Master to the selected slave and when configured as Slave transmits data to the Master.

This function is blocking; it returns when the transfer is complete or a timeout event is triggered. The number of bytes transmitted is returned by the function after the operation is completed. Transmit operation cannot be canceled or aborted.

The data buffer must stay allocated during the duration of the transfer, and the contents must not be modified. The value of the specified address is ignored when configured in slave mode. In master mode, it contains the address of the target peripheral. This is a 7-bit value unless 10-bit addressing is configured, and the target supports it.

When in master mode, the operation consists of:

  • Addressing the slave as a Master transmitter.
  • Transmitting data to the addressed slave.
  • Generating a STOP condition if the specified stop field is true.
Parameters
objThe I2C object
address7/10-bit address (last bit is 0)
dataThe buffer for sending
lengthNumber of bytes to write
stopIf true, stop is generated after the transfer is done
Note
If the current platform supports multimaster operation, the peripheral performs arbitration automatically when detecting collisions and completes the transfer or returns I2C_ERROR_ARBITRATION_LOST when it loses arbitration.

Additional time for arbitration or clock stretching should by count by setting appropriate timeout value.

When no transmision timeout is set by the user, the default timeout value is used. It counts one additional byte for addressing stage: default_timeout = (length + 1) * byte_timeout.

Returns
zero or nonzero - Number of written bytes negative - I2C_ERROR_XXX status
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.