i2c_master.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include "esp_err.h"
#include "driver/i2c_types.h"
#include "driver/gpio.h"

Go to the source code of this file.

Data Structures
struct	i2c_master_bus_config_t
	I2C master bus configuration. More...
struct	i2c_device_config_t
	Per-device configuration attached to a master bus. More...

Typedefs
typedef struct i2c_master_bus_t *	i2c_master_bus_handle_t
	Opaque handle for an I2C master bus.
typedef struct i2c_master_dev_t *	i2c_master_dev_handle_t
	Opaque handle for an I2C device attached to a master bus.

Functions
esp_err_t	i2c_new_master_bus (const i2c_master_bus_config_t *bus_config, i2c_master_bus_handle_t *ret_bus_handle)
	Create a new I2C master bus.
esp_err_t	i2c_del_master_bus (i2c_master_bus_handle_t bus_handle)
	Delete the I2C master bus and release the port.
esp_err_t	i2c_master_bus_add_device (i2c_master_bus_handle_t bus_handle, const i2c_device_config_t *dev_config, i2c_master_dev_handle_t *ret_handle)
	Attach a device to the master bus.
esp_err_t	i2c_master_bus_rm_device (i2c_master_dev_handle_t handle)
	Remove a device from the master bus.
esp_err_t	i2c_master_transmit (i2c_master_dev_handle_t i2c_dev, const uint8_t *write_buffer, size_t write_size, int xfer_timeout_ms)
	Master write (START + addr/W + data + STOP).
esp_err_t	i2c_master_receive (i2c_master_dev_handle_t i2c_dev, uint8_t *read_buffer, size_t read_size, int xfer_timeout_ms)
	Master read (START + addr/R + data + STOP).
esp_err_t	i2c_master_transmit_receive (i2c_master_dev_handle_t i2c_dev, const uint8_t *write_buffer, size_t write_size, uint8_t *read_buffer, size_t read_size, int xfer_timeout_ms)
	Combined write-then-read with repeated START.
esp_err_t	i2c_master_probe (i2c_master_bus_handle_t bus_handle, uint16_t address, int xfer_timeout_ms)
	Probe a device on the bus (write 0 bytes).
esp_err_t	i2c_master_bus_reset (i2c_master_bus_handle_t bus_handle)
	Reset the I2C bus (toggle SCL to release SDA).
esp_err_t	i2c_master_bus_wait_all_done (i2c_master_bus_handle_t bus_handle, int timeout_ms)
	Wait until all queued transfers are complete.

Typedef Documentation

i2c_master_bus_handle_t

typedef struct i2c_master_bus_t* i2c_master_bus_handle_t

Opaque handle for an I2C master bus.

i2c_master_dev_handle_t

typedef struct i2c_master_dev_t* i2c_master_dev_handle_t

Opaque handle for an I2C device attached to a master bus.

Function Documentation

i2c_new_master_bus()

esp_err_t i2c_new_master_bus ( const i2c_master_bus_config_t *  bus_config, i2c_master_bus_handle_t *  ret_bus_handle  )

extern

Create a new I2C master bus.

Allocates a bus handle from the injected pool. The underlying vsf_i2c_t is NOT initialised until the first transfer (lazy init on first device use), because the clock speed is a per-device property in this API.

Parameters

[in]	bus_config	Bus configuration.
[out]	ret_bus_handle	Returned bus handle on success.

Returns

ESP_OK / ESP_ERR_INVALID_ARG / ESP_ERR_NOT_FOUND / ESP_ERR_INVALID_STATE (port already in use).

i2c_del_master_bus()

esp_err_t i2c_del_master_bus ( i2c_master_bus_handle_t  bus_handle )

extern

Delete the I2C master bus and release the port.

All devices attached to this bus must be removed first via i2c_master_bus_rm_device(); otherwise ESP_ERR_INVALID_STATE is returned.

i2c_master_bus_add_device()

esp_err_t i2c_master_bus_add_device ( i2c_master_bus_handle_t  bus_handle, const i2c_device_config_t *  dev_config, i2c_master_dev_handle_t *  ret_handle  )

extern

Attach a device to the master bus.

The returned handle is used for all subsequent transfer calls. Multiple devices with different addresses / speeds may share one bus.

Parameters

[in]	bus_handle	Master bus handle.
[in]	dev_config	Per-device configuration.
[out]	ret_handle	Returned device handle on success.

i2c_master_bus_rm_device()

esp_err_t i2c_master_bus_rm_device ( i2c_master_dev_handle_t  handle )

extern

Remove a device from the master bus.

i2c_master_transmit()

esp_err_t i2c_master_transmit ( i2c_master_dev_handle_t  i2c_dev, const uint8_t *  write_buffer, size_t  write_size, int  xfer_timeout_ms  )

extern

Master write (START + addr/W + data + STOP).

Parameters

[in]	i2c_dev	Device handle.
[in]	write_buffer	Data to transmit.
[in]	write_size	Number of bytes to write.
[in]	xfer_timeout_ms	Timeout in ms (-1 = wait forever).

i2c_master_receive()

esp_err_t i2c_master_receive ( i2c_master_dev_handle_t  i2c_dev, uint8_t *  read_buffer, size_t  read_size, int  xfer_timeout_ms  )

extern

Master read (START + addr/R + data + STOP).

Parameters

[in]	i2c_dev	Device handle.
[out]	read_buffer	Receive buffer.
[in]	read_size	Number of bytes to read.
[in]	xfer_timeout_ms	Timeout in ms (-1 = wait forever).

i2c_master_transmit_receive()

esp_err_t i2c_master_transmit_receive ( i2c_master_dev_handle_t  i2c_dev, const uint8_t *  write_buffer, size_t  write_size, uint8_t *  read_buffer, size_t  read_size, int  xfer_timeout_ms  )

extern

Combined write-then-read with repeated START.

Sequence: START + addr/W + write_data + Sr + addr/R + read_data + STOP.

Parameters

[in]	i2c_dev	Device handle.
[in]	write_buffer	Data to transmit (register address, etc.).
[in]	write_size	Write byte count.
[out]	read_buffer	Receive buffer.
[in]	read_size	Read byte count.
[in]	xfer_timeout_ms	Timeout in ms (-1 = wait forever).

i2c_master_probe()

esp_err_t i2c_master_probe ( i2c_master_bus_handle_t  bus_handle, uint16_t  address, int  xfer_timeout_ms  )

extern

Probe a device on the bus (write 0 bytes).

Returns

ESP_OK if the device ACKed its address, ESP_ERR_NOT_FOUND if not.

i2c_master_bus_reset()

esp_err_t i2c_master_bus_reset ( i2c_master_bus_handle_t  bus_handle )

extern

Reset the I2C bus (toggle SCL to release SDA).

i2c_master_bus_wait_all_done()

esp_err_t i2c_master_bus_wait_all_done ( i2c_master_bus_handle_t  bus_handle, int  timeout_ms  )

extern

Wait until all queued transfers are complete.

Since all transfers in this shim are synchronous, this is always an immediate success.