mirror of
https://github.com/espressif/ESP8266_RTOS_SDK.git
synced 2025-06-05 13:16:37 +08:00
Merge branch 'feature/refactor_i2c_driver' into 'master'
refactor(i2c): Refactor i2c driver for esp8266 idf See merge request sdk/ESP8266_RTOS_SDK!247
This commit is contained in:
Wu Jian Gang
268
components/esp8266/include/driver/i2c.h
Normal file
268
components/esp8266/include/driver/i2c.h
Normal file
@ -0,0 +1,268 @@
|
||||
// Copyright 2018-2025 Espressif Systems (Shanghai) PTE LTD
|
||||
//
|
||||
// Licensed under the Apache License, Version 2.0 (the "License");
|
||||
// you may not use this file except in compliance with the License.
|
||||
// You may obtain a copy of the License at
|
||||
//
|
||||
// http://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// Unless required by applicable law or agreed to in writing, software
|
||||
// distributed under the License is distributed on an "AS IS" BASIS,
|
||||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
// See the License for the specific language governing permissions and
|
||||
// limitations under the License.
|
||||
|
||||
#pragma once
|
||||
|
||||
#include <stdint.h>
|
||||
|
||||
#include "FreeRTOS.h"
|
||||
|
||||
#include "esp_err.h"
|
||||
|
||||
#include "gpio.h"
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
typedef enum {
|
||||
I2C_MODE_MASTER, /*!< I2C master mode */
|
||||
I2C_MODE_MAX,
|
||||
} i2c_mode_t;
|
||||
|
||||
typedef enum {
|
||||
I2C_MASTER_WRITE = 0, /*!< I2C write data */
|
||||
I2C_MASTER_READ, /*!< I2C read data */
|
||||
} i2c_rw_t;
|
||||
|
||||
typedef enum {
|
||||
I2C_CMD_RESTART = 0, /*!< I2C restart command */
|
||||
I2C_CMD_WRITE, /*!< I2C write command */
|
||||
I2C_CMD_READ, /*!< I2C read command */
|
||||
I2C_CMD_STOP, /*!< I2C stop command */
|
||||
} i2c_opmode_t;
|
||||
|
||||
typedef enum {
|
||||
I2C_NUM_0 = 0, /*!< I2C port 0 */
|
||||
I2C_NUM_MAX
|
||||
} i2c_port_t;
|
||||
|
||||
typedef enum {
|
||||
I2C_MASTER_ACK = 0x0, /*!< I2C ack for each byte read */
|
||||
I2C_MASTER_NACK = 0x1, /*!< I2C nack for each byte read */
|
||||
I2C_MASTER_LAST_NACK = 0x2, /*!< I2C nack for the last byte*/
|
||||
I2C_MASTER_ACK_MAX,
|
||||
} i2c_ack_type_t;
|
||||
|
||||
/**
|
||||
* @brief I2C initialization parameters
|
||||
*/
|
||||
typedef struct {
|
||||
i2c_mode_t mode; /*!< I2C mode */
|
||||
gpio_num_t sda_io_num; /*!< GPIO number for I2C sda signal */
|
||||
gpio_pullup_t sda_pullup_en; /*!< Internal GPIO pull mode for I2C sda signal*/
|
||||
gpio_num_t scl_io_num; /*!< GPIO number for I2C scl signal */
|
||||
gpio_pullup_t scl_pullup_en; /*!< Internal GPIO pull mode for I2C scl signal*/
|
||||
} i2c_config_t;
|
||||
|
||||
typedef void *i2c_cmd_handle_t; /*!< I2C command handle */
|
||||
|
||||
/**
|
||||
* @brief I2C driver install
|
||||
*
|
||||
* @param i2c_num I2C port number
|
||||
* @param mode I2C mode( master or slave )
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_FAIL Driver install error
|
||||
*/
|
||||
esp_err_t i2c_driver_install(i2c_port_t i2c_num, i2c_mode_t mode);
|
||||
|
||||
/**
|
||||
* @brief I2C driver delete
|
||||
*
|
||||
* @param i2c_num I2C port number
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_driver_delete(i2c_port_t i2c_num);
|
||||
|
||||
/**
|
||||
* @brief I2C parameter initialization
|
||||
*
|
||||
* @note It must be used after calling i2c_driver_install
|
||||
*
|
||||
* @param i2c_num I2C port number
|
||||
* @param i2c_conf pointer to I2C parameter settings
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_param_config(i2c_port_t i2c_num, const i2c_config_t *i2c_conf);
|
||||
|
||||
/**
|
||||
* @brief Configure GPIO signal for I2C sck and sda
|
||||
*
|
||||
* @param i2c_num I2C port number
|
||||
* @param sda_io_num GPIO number for I2C sda signal
|
||||
* @param scl_io_num GPIO number for I2C scl signal
|
||||
* @param sda_pullup_en Whether to enable the internal pullup for sda pin
|
||||
* @param scl_pullup_en Whether to enable the internal pullup for scl pin
|
||||
* @param mode I2C mode
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_set_pin(i2c_port_t i2c_num, int sda_io_num, int scl_io_num,
|
||||
gpio_pullup_t sda_pullup_en, gpio_pullup_t scl_pullup_en, i2c_mode_t mode);
|
||||
|
||||
/**
|
||||
* @brief Create and init I2C command link
|
||||
* @note
|
||||
* Before we build I2C command link, we need to call i2c_cmd_link_create() to create
|
||||
* a command link.
|
||||
* After we finish sending the commands, we need to call i2c_cmd_link_delete() to
|
||||
* release and return the resources.
|
||||
*
|
||||
* @return i2c command link handler
|
||||
*/
|
||||
i2c_cmd_handle_t i2c_cmd_link_create();
|
||||
|
||||
/**
|
||||
* @brief Free I2C command link
|
||||
* @note
|
||||
* Before we build I2C command link, we need to call i2c_cmd_link_create() to create
|
||||
* a command link.
|
||||
* After we finish sending the commands, we need to call i2c_cmd_link_delete() to
|
||||
* release and return the resources.
|
||||
*
|
||||
* @param cmd_handle I2C command handle
|
||||
*/
|
||||
void i2c_cmd_link_delete(i2c_cmd_handle_t cmd_handle);
|
||||
|
||||
/**
|
||||
* @brief Queue command for I2C master to generate a start signal
|
||||
* @note
|
||||
* Only call this function in I2C master mode
|
||||
* Call i2c_master_cmd_begin() to send all queued commands
|
||||
*
|
||||
* @param cmd_handle I2C cmd link
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_master_start(i2c_cmd_handle_t cmd_handle);
|
||||
|
||||
/**
|
||||
* @brief Queue command for I2C master to write one byte to I2C bus
|
||||
* @note
|
||||
* Only call this function in I2C master mode
|
||||
* Call i2c_master_cmd_begin() to send all queued commands
|
||||
*
|
||||
* @param cmd_handle I2C cmd link
|
||||
* @param data I2C one byte command to write to bus
|
||||
* @param ack_en enable ack check for master
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_master_write_byte(i2c_cmd_handle_t cmd_handle, uint8_t data, bool ack_en);
|
||||
|
||||
/**
|
||||
* @brief Queue command for I2C master to write buffer to I2C bus
|
||||
* @note
|
||||
* Only call this function in I2C master mode
|
||||
* Call i2c_master_cmd_begin() to send all queued commands
|
||||
*
|
||||
* @param cmd_handle I2C cmd link
|
||||
* @param data data to send
|
||||
* @param data_len data length
|
||||
* @param ack_en enable ack check for master
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_master_write(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len, bool ack_en);
|
||||
|
||||
/**
|
||||
* @brief Queue command for I2C master to read one byte from I2C bus
|
||||
* @note
|
||||
* Only call this function in I2C master mode
|
||||
* Call i2c_master_cmd_begin() to send all queued commands
|
||||
*
|
||||
* @param cmd_handle I2C cmd link
|
||||
* @param data pointer accept the data byte
|
||||
* @param ack ack value for read command
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_master_read_byte(i2c_cmd_handle_t cmd_handle, uint8_t *data, i2c_ack_type_t ack);
|
||||
|
||||
/**
|
||||
* @brief Queue command for I2C master to read data from I2C bus
|
||||
* @note
|
||||
* Only call this function in I2C master mode
|
||||
* Call i2c_master_cmd_begin() to send all queued commands
|
||||
*
|
||||
* @param cmd_handle I2C cmd link
|
||||
* @param data data buffer to accept the data from bus
|
||||
* @param data_len read data length
|
||||
* @param ack ack value for read command
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_master_read(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len, i2c_ack_type_t ack);
|
||||
|
||||
/**
|
||||
* @brief Queue command for I2C master to generate a stop signal
|
||||
* @note
|
||||
* Only call this function in I2C master mode
|
||||
* Call i2c_master_cmd_begin() to send all queued commands
|
||||
*
|
||||
* @param cmd_handle I2C cmd link
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
*/
|
||||
esp_err_t i2c_master_stop(i2c_cmd_handle_t cmd_handle);
|
||||
|
||||
/**
|
||||
* @brief I2C master send queued commands.
|
||||
* This function will trigger sending all queued commands.
|
||||
* The task will be blocked until all the commands have been sent out.
|
||||
* The I2C APIs are not thread-safe, if you want to use one I2C port in different tasks,
|
||||
* you need to take care of the multi-thread issue.
|
||||
* @note
|
||||
* Only call this function in I2C master mode
|
||||
*
|
||||
* @param i2c_num I2C port number
|
||||
* @param cmd_handle I2C command handler
|
||||
* @param ticks_to_wait maximum wait ticks.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK Success
|
||||
* - ESP_ERR_INVALID_ARG Parameter error
|
||||
* - ESP_FAIL Sending command error, slave doesn't ACK the transfer.
|
||||
* - ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode.
|
||||
* - ESP_ERR_TIMEOUT Operation timeout because the bus is busy.
|
||||
*/
|
||||
esp_err_t i2c_master_cmd_begin(i2c_port_t i2c_num, i2c_cmd_handle_t cmd_handle, TickType_t ticks_to_wait);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
Reference in New Issue
Block a user