IIC
函数列表
简要说明
I2C (Inter-Integrated Circuit,或IIC) 是一种串行的同步通信总线。 I2C串行总线有两根信号线,一根是双向的数据线SDA,另一根是时钟线SCL。所有接到I2C总线设备上的串行数据SDA都接到总线的SDA上,各设备的时钟线SCL接到总线的SCL上。IIC典型接线方式如下:
总线的通信由主机控制,即主机是数据的传送(发出启动信号)、发出时钟信号以及传送结束时发出停止信号的设备。被主机寻访的设备称为从机。每个接到I2C总线的设备都有一个唯一的地址,以便于主机寻访。主机和从机的数据传送,可以由主机发送数据到从机,也可以由从机发到主机。I2C 支持7位或者10位从设备地址模式。I2C总线在开始条件后的首字节决定哪个被控器将被主控器选择,当主机输出一地址时,系统中的每一从设备都将开始条件后的地址和自己的地址进行比较,如果相同,该从机即认为自己被主机寻址。
接口描述
csi_iic_initialize
iic_handle_t csi_iic_initialize(int32_t idx, iic_event_cb_t cb_event)
功能描述:
- 通过设备号初始化对应的iic实例,返回iic实例的句柄 。
参数:
idx
: 设备号。cb_event
: iic实例的事件回调函数(一般在中断上下文执行)。回调函数原型定义见iic_event_cb_t。
回调函数类型iic_event_cb_t定义如下:
typedef void (*iic_event_cb_t)(int32_t idx, iic_event_e event);
其中idx为设备号,event 为传给回调函数的事件类型。
返回值:
- NULL: 初始化失败。
- 其它: 实例句柄。
IIC回调事件枚举类型iic_event_e定义如下:
名字 | 定义 | 备注 |
---|---|---|
IIC_EVENT_TRANSFER_DONE | 传输完成事件 | |
IIC_EVENT_TRANSFER_INCOMPLETE | 传输未完成事件 | |
IIC_EVENT_SLAVE_TRANSMIT | 从设备发送操作请求事件 | |
IIC_EVENT_SLAVE_RECEIVE | 从设备接收操作请求事件 | |
IIC_EVENT_ADDRESS_NACK | 地址未应答事件 | |
IIC_EVENT_GENERAL_CALL | 指示收到general call(地址为0)事件 | |
IIC_EVENT_ARBITRATION_LOST | 主机仲裁丢失事件 | |
IIC_EVENT_BUS_ERROR | 总线错误事件 | |
IIC_EVENT_BUS_CLEAR | 总线清除完成事件 |
csi_iic_uninitialize
int32_t csi_iic_uninitialize(iic_handle_t handle)
功能描述:
- usart实例反初始化。该接口会停止usart
- 实例正在进行的传输(如果有),并且释放相关的软硬件资源。
参数:
handle
: 实例句柄。
返回值:
- 错误码。
csi_iic_get_capabilities
iic_capabilities_t csi_iic_get_capabilities(int32_t idx)
功能描述:
- 获取iic实例支持的能力。
参数:
idx
: 设备号。
返回值:
- 描述iic 能力的结构体。
csi_iic_master_send
int32_t csi_iic_master_send(iic_handle_t handle, uint32_t devaddr, const void *data, uint32_t num, bool xfer_pending)
功能描述:
- iic 作为主机时启动数据发送。
参数:
handle
: 实例句柄。devaddr
: Slave设备地址。data
: 待发送数据的缓冲区地址。num
: 待发送数据的长度。xfer_pending
:- 发送完成后是否发送停止位。1-不发送停止位,0-发送停止位。
返回值:
- 错误码。
csi_iic_master_receive
int32_t csi_iic_master_receive(iic_handle_t handle, uint32_t devaddr, void *data, uint32_t num, bool xfer_pending)
功能描述:
参数:
handle
: 实例句柄。devaddr
: Slave设备地址。data
: 待接收数据的缓冲区地址。num
: 待接收数据的长度。xfer_pending
:- 接收完成后是否发送停止位。1-不发送停止位,0-发送停止位。
返回值:
- 错误码。
csi_iic_slave_send
int32_t csi_iic_slave_send(iic_handle_t handle, const void *data, uint32_t num)
功能描述:
- iic 作为从机时启动数据发送。
参数:
handle
: 实例句柄。data
: 待发送数据的缓冲区地址。num
: 待发送数据的长度。
返回值:
- 错误码。
csi_iic_slave_receive
int32_t csi_iic_slave_receive(iic_handle_t handle, void *data, uint32_t num)
功能描述:
- iic 作为从机时启动数据接收。
参数:
handle
: 实例句柄。data
: 待接收数据的缓冲区地址。num
: 待接收数据的长度。
返回值:
- 错误码。
csi_iic_abort_transfer
int32_t csi_iic_abort_transfer(iic_handle_t handle)
功能描述:
- 停止正在执行的传输,包括发送和接收。若iic设备处于空闲状态时,不做任何操作。
参数:
handle
: 实例句柄。
返回值:
- 错误码。
csi_iic_get_status
iic_status_t csi_iic_get_status(iic_handle_t handle)
功能描述:
- 获取当前时刻IIC 的状态。
参数:
handle
: 实例句柄。
返回值:
- iic 状态的结构体。iic 的状态定义见 iic_status_t
- 定义。
iic_status_t:
名字 | 定义 | 备注 |
---|---|---|
busy : 1 | 传输或发送忙状态位 | |
mode : 1 | 模式位。1-主,0-从 | |
direction : 1 | 传输方向:1-接收,0-发送 | |
general_call : 1 | general call 指示 | |
arbitration_lost : 1 | 主机失去仲裁 | |
bus_error : 1 | 总线错误 |
csi_iic_power_control
int32_t csi_iic_power_control(iic_handle_t handle, csi_power_stat_e state)
功能描述:
- 配置iic 实例的功耗模式。
参数:
handle
: 实例句柄。state
: iic的功耗模式,参看- csi_power_stat_e 的定义。
返回值:
- 错误码。
csi_iic_config_mode
int32_t csi_iic_config_mode(iic_handle_t handle, iic_mode_e mode)
功能描述:
- 配置iic 实例的主从工作模式。
参数:
handle
: 实例句柄。mode
: iic的主、从工作模式,参见 iic_mode_e 的定义。
返回值:
- 错误码。
iic_mode_e:
名字 | 定义 | 备注 |
---|---|---|
IIC_MODE_MASTER | IIC主机模式 | |
IIC_MODE_SLAVE | IIC从机模式 |
csi_iic_config_speed
int32_t csi_iic_config_speed(iic_handle_t handle, iic_speed_e speed)
功能描述:
- 配置iic 实例的工作速度。
参数:
handle
: 实例句柄。speed
: iic的速度,参看 iic_speed_e的定义。
返回值:
- 错误码。
iic_speed_e:
名字 | 定义 | 备注 |
---|---|---|
I2C_BUS_SPEED_STANDARD | iic标准速度(100KHz) | |
I2C_BUS_SPEED_FAST | iic快速速度(400KHz) | |
I2C_BUS_SPEED_FAST_PLUS | iic标准+速度(1MHz) | |
I2C_BUS_SPEED_HIGH | iic高速速度(3.4MHz) |
csi_iic_config_addr_mode
int32_t csi_iic_config_addr_mode(iic_handle_t handle, iic_address_mode_e addr_mode)
功能描述:
- 配置iic 实例的地址模式。
参数:
handle
: 实例句柄。addr_mode
: iic的地址模式,参看iic_address_mode_e的定义。
返回值:
- 错误码。
iic_address_mode_e:
名字 | 定义 | 备注 |
---|---|---|
I2C_ADDRESS_7BIT | 7bit 地址模式 | |
I2C_ADDRESS_10BIT | 10bit 地址模式 |
csi_iic_config_slave_addr
int32_t csi_iic_config_slave_addr(iic_handle_t handle, int32_t slave_addr)
功能描述:
- 配置iic 实例的从设备地址。
参数:
handle
: 实例句柄。slave_addr
: iic 从设备通信地址。
返回值:
- 错误码。
csi_iic_get_data_count
uint32_t csi_iic_get_data_count(iic_handle_t handle)
功能描述:
- 获取iic 实例的已传输的数据个数。
参数:
handle
: 实例句柄。
返回值:
- 已传输的数据个数。
csi_iic_send_start
int32_t csi_iic_send_start(iic_handle_t handle)
功能描述:
- 发送START命令。
参数:
handle
: 实例句柄。
返回值:
- 错误码。
csi_iic_send_stop
int32_t csi_iic_send_stop(iic_handle_t handle)
功能描述:
- 发送STOP 命令。
参数:
handle
: 实例句柄。
返回值:
- 错误码。
csi_iic_reset
int32_t csi_iic_reset(iic_handle_t handle)
功能描述:
- 复位IIC。
参数:
handle
: 实例句柄。
返回值:
- 错误码。
示例
IIC示例1
static iic_handle_t iic_handle;
static uint8_t cb_transfer_flag = 0xff;
static void iic_event_cb_fun(int32_t idx, iic_event_e event)
{
cb_transfer_flag = event;
}
void example_main(void)
{
iic_capabilities_t cap;
int32_t ret;
//receive buffer
char rcv_buf[10] ;
//data to send
char send_buf[10] = {0,1,2,3,4,5,6,7,8,9};
//get iic capabilities
cap = csi_iic_get_capabilities(0);
printf("iic %s 10bit address\n",cap.address_10_bit==1 ? "support":"not support");
iic_handle = csi_iic_initialize(0, iic_event_cb_fun);
if (iic_handle == NULL) {
//fail
return;
}
ret = csi_iic_power_control(iic_handle, DRV_POWER_FULL);
if (ret < 0) {
// power control failed
return;
}
//config iic as master-standard speed-7bit address-slave addr=0x57
csi_iic_config_mode(iic_handle, IIC_MODE_MASTER);
csi_iic_config_speed(iic_handle, I2C_BUS_SPEED_STANDARD);
csi_iic_config_addr_mode(iic_handle, I2C_ADDRESS_7BIT);
csi_iic_config_slave_addr(iic_handle, 0x57);
ret = csi_iic_master_send(iic_handle, 0x57, send_buf, sizeof(send_buf), 0);
if (ret < 0) {
//failed
}
while (cb_transfer_flag == 0xff);
//check transfer result
if (cb_transfer_flag == I2C_EVENT_TRANSFER_DONE) {
//transmit done
} else {
//failed
}
cb_transfer_flag = 0xff;
ret = csi_iic_master_receive(iic_handle, 0x57, rcv_buf, sizeof(rcv_buf), 0);
if (ret < 0) {
//failed
}
while (cb_transfer_flag == 0xff);
//check transfer result
if (cb_transfer_flag == I2C_EVENT_TRANSFER_DONE) {
//transmit done
} else {
//failed
}
ret = csi_iic_power_control(iic_handle, DRV_POWER_OFF);
if (ret < 0) {
// power control failed
return;
}
//uninitialize iic
ret = csi_iic_uninitialize(iic_handle);
if (ret != 0) {
//failed
}
}
IIC示例2
static iic_handle_t iic_handle;
//event callback for iic
static void iic_event_cb_fun(int32_t idx, iic_event_e event)
{
//...
}
static void example_main(void)
{
int32_t ret;
iic_status_t st;
//data to send
char send_buf[10] = {0,1,2,3,4,5,6,7,8,9};
//receive buffer
char rcv_buf[10] ;
iic_handle = csi_iic_initialize(0, iic_event_cb_fun);
if (iic_handle == NULL) {
return;
}
ret = csi_iic_power_control(iic_handle, DRV_POWER_FULL);
if (ret < 0) {
// power control failed
return;
}
//config iic as slave-standard speed-7bit address-slave addr=0x57
csi_iic_config_mode(iic_handle, IIC_MODE_SLAVE);
csi_iic_config_speed(iic_handle, I2C_BUS_SPEED_STANDARD);
csi_iic_config_addr_mode(iic_handle, I2C_ADDRESS_7BIT);
csi_iic_config_slave_addr(iic_handle, 0x57);
ret = csi_iic_slave_send(iic_handle, send_buf, sizeof(send_buf));
if (ret < 0) {
//failed
}
//wait send done, waiting for 100 ms max
int32_t cnt = 100;
while(cnt--) {
mdelay(1);
//check status
st = csi_iic_get_status(iic_handle);
//transmit done
if (st.busy == 0){
break;
}
}
//abort transmit when timeout
if (cnt == 0) {
csi_iic_abort_transfer(iic_handle);
}
st.busy = 0;
ret = csi_iic_slave_receive(iic_handle, rcv_buf, sizeof(rcv_buf));
if (ret < 0) {
//failed
}
//wait receive done, waiting for 100 ms max
cnt = 100;
while(cnt--) {
mdelay(1);
//check status
st = csi_iic_get_status(iic_handle);
//transmit done
if (st.busy == 0){
break;
}
}
//abort transmit when timeout
if (cnt == 0) {
csi_iic_abort_transfer(iic_handle);
}
ret = csi_iic_power_control(iic_handle, DRV_POWER_OFF);
if (ret < 0) {
// power control failed
return;
}
//uninitialize iic
ret = csi_iic_uninitialize(iic_handle);
if (ret != 0) {
//failed
}
}