i2cdev - I2C master thread-safe functions for communication with I2C slave

group i2cdev

ESP-IDF I2C master thread-safe functions for communication with I2C slave.

Copyright (c) 2018 Ruslan V. Uss unclerus@gmail.com

MIT Licensed as described in the file LICENSE

Defines

I2CDEV_MAX_STRETCH_TIME
I2C_DEV_TAKE_MUTEX(dev)
I2C_DEV_GIVE_MUTEX(dev)
I2C_DEV_CHECK(dev, X)
I2C_DEV_CHECK_LOGE(dev, X, msg, ...)

Enums

enum i2c_dev_type_t

I2C transaction type.

Values:

enumerator I2C_DEV_WRITE

Write operation.

enumerator I2C_DEV_READ

Read operation.

Functions

esp_err_t i2cdev_init()

Init library.

The function must be called before any other functions of this library.

Returns:

ESP_OK on success

esp_err_t i2cdev_done()

Finish work with library.

Uninstall i2c drivers.

Returns:

ESP_OK on success

esp_err_t i2c_dev_create_mutex(i2c_dev_t *dev)

Create mutex for device descriptor.

This function does nothing if option CONFIG_I2CDEV_NOLOCK is enabled.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t i2c_dev_delete_mutex(i2c_dev_t *dev)

Delete mutex for device descriptor.

This function does nothing if option CONFIG_I2CDEV_NOLOCK is enabled.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t i2c_dev_take_mutex(i2c_dev_t *dev)

Take device mutex.

This function does nothing if option CONFIG_I2CDEV_NOLOCK is enabled.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t i2c_dev_give_mutex(i2c_dev_t *dev)

Give device mutex.

This function does nothing if option CONFIG_I2CDEV_NOLOCK is enabled.

Parameters:

dev – Device descriptor

Returns:

ESP_OK on success

esp_err_t i2c_dev_probe(const i2c_dev_t *dev, i2c_dev_type_t operation_type)

Check the availability of the device.

Issue an operation of operation_type to the I2C device then stops.

Parameters:
  • dev – Device descriptor

  • operation_type – Operation type

Returns:

ESP_OK if device is available

esp_err_t i2c_dev_read(const i2c_dev_t *dev, const void *out_data, size_t out_size, void *in_data, size_t in_size)

Read from slave device.

Issue a send operation of out_data register address, followed by reading in_size bytes from slave into in_data . Function is thread-safe.

Parameters:
  • dev – Device descriptor

  • out_data – Pointer to data to send if non-null

  • out_size – Size of data to send

  • in_data[out] Pointer to input data buffer

  • in_size – Number of byte to read

Returns:

ESP_OK on success

esp_err_t i2c_dev_write(const i2c_dev_t *dev, const void *out_reg, size_t out_reg_size, const void *out_data, size_t out_size)

Write to slave device.

Write out_size bytes from out_data to slave into out_reg register address. Function is thread-safe.

Parameters:
  • dev – Device descriptor

  • out_reg – Pointer to register address to send if non-null

  • out_reg_size – Size of register address

  • out_data – Pointer to data to send

  • out_size – Size of data to send

Returns:

ESP_OK on success

esp_err_t i2c_dev_read_reg(const i2c_dev_t *dev, uint8_t reg, void *in_data, size_t in_size)

Read from register with an 8-bit address.

Shortcut to i2c_dev_read().

Parameters:
  • dev – Device descriptor

  • reg – Register address

  • in_data[out] Pointer to input data buffer

  • in_size – Number of byte to read

Returns:

ESP_OK on success

esp_err_t i2c_dev_write_reg(const i2c_dev_t *dev, uint8_t reg, const void *out_data, size_t out_size)

Write to register with an 8-bit address.

Shortcut to i2c_dev_write().

Parameters:
  • dev – Device descriptor

  • reg – Register address

  • out_data – Pointer to data to send

  • out_size – Size of data to send

Returns:

ESP_OK on success

struct i2c_dev_t
#include <i2cdev.h>

I2C device descriptor.

Public Members

i2c_port_t port

I2C port number.

i2c_config_t cfg

I2C driver configuration.

uint8_t addr

Unshifted address.

SemaphoreHandle_t mutex

Device mutex.

uint32_t timeout_ticks

HW I2C bus timeout (stretch time), in ticks.

80MHz APB clock ticks for ESP-IDF, CPU ticks for ESP8266. When this value is 0, I2CDEV_MAX_STRETCH_TIME will be used