OpenHarmony（鸿蒙南向）——平台驱动指南【I2C】

概述

功能简介

I2C（Inter Integrated Circuit）总线是由Philips公司开发的一种简单、双向二线制同步串行总线。由于其硬件连接简单、成本低廉，因此被广泛应用于各种短距离通信的场景。

运作机制

I2C以主从方式工作，通常有一个主设备和一个或者多个从设备，主从设备通过SDA（SerialData）串行数据线以及SCL（SerialClock）串行时钟线两根线相连（如图1）。

I2C数据的传输必须以一个起始信号作为开始条件，以一个结束信号作为传输的停止条件。数据传输以字节为单位，高位在前，逐个bit进行传输。

I2C总线上的每一个设备都可以作为主设备或者从设备，而且每一个设备都会对应一个唯一的地址，当主设备需要和某一个从设备通信时，通过广播的方式，将从设备地址写到总线上，如果某个从设备符合此地址，将会发出应答信号，建立传输。

I2C接口定义了完成I2C传输的通用方法集合，包括：

• I2C控制器管理：打开或关闭I2C控制器

• I2C消息传输：通过消息传输结构体数组进行自定义传输

图 1 I2C物理连线示意图

使用指导

场景介绍

I2C通常用于与各类支持I2C协议的传感器、执行器或输入输出设备进行通信。

接口说明

I2C模块提供的主要接口如表1所示，具体API详见//drivers/hdf_core/framework/include/platform/i2c_if.h。

表 1 I2C驱动API接口功能介绍

接口名	接口描述
DevHandle I2cOpen(int16_t number)	打开I2C控制器
void I2cClose(DevHandle handle)	关闭I2C控制器
int32_t I2cTransfer(DevHandle handle, struct I2cMsg *msgs, int16_t count)	自定义传输

使用流程

使用I2C设备的一般流程如下图所示。

图 2 I2C设备使用流程图

打开I2C控制器

在进行I2C通信前，首先要调用I2cOpen打开I2C控制器。

DevHandle I2cOpen(int16_t number);

表 2 I2cOpen参数和返回值描述

参数	参数描述
number	int16_t类型，I2C控制器号
返回值	返回值描述
NULL	打开I2C控制器失败
设备句柄	打开的I2C控制器设备句柄

假设系统中存在8个I2C控制器，编号从0到7，以下代码示例为获取3号控制器：

DevHandle i2cHandle = NULL;  // I2C控制器句柄

// 打开I2C控制器
i2cHandle = I2cOpen(3);
if (i2cHandle == NULL) {
   
    HDF_LOGE("I2cOpen: i2c open fail.\n");
    return NULL;
}

进行I2C通信

消息传输

int32_t I2cTransfer(DevHandle handle, struct I2cMsg *msgs, int16_t count);

表 3 I2cTransfer参数和返回值描述

参数	参数描述
handle	DevHandle类型，I2C控制器设备句柄
msgs	结构体指针，待传输数据的消息结构体数组
count	int16_t类型，消息数组长度
返回值	返回值描述
正整数	成功传输的消息结构体数目
负数	执行失败

I2C传输消息类型为I2cMsg，每个传输消息结构体表示一次读或写，通过一个消息数组，可以执行若干次的读写组合操作。组合读写示例：

int32_t ret;
uint8_t wbuff[2] = {
    0x12, 0x13 };
uint8_t rbuff[2] = {
    0 };
struct I2cMsg msgs[2];        // 自定义传输的消息结构体数组
msgs[0].buf = wbuff;          // 写入的数据
msgs[0].len = 2;              // 写入数据长度为2
msgs[0].addr = 0x5A;          // 写入设备地址为0x5A
msgs[0].flags = 0;            // 传输标记为0，默认为写
msgs[1].buf = rbuff;          // 要读取的数据
msgs[1].len = 2;              // 读取数据长度为2
msgs[1].addr = 0x5A;          // 读取设备地址为0x5A
msgs[1].flags = I2C_FLAG_READ // I2C_FLAG_READ置位
// 进行一次自定义传输，传输的消息个数为2 
ret = I2cTransfer(i2cHandle, msgs, 2)