文档中心
I2c 接口文档
更新时间： 2026/03/04
在Gitcode上查看源码

I2c接口文档 ​

init函数 ​

函数形式

  • int32_t I2c::init(uint32_t bus_id, uint32_t speed, uint32_t mode, uint32_t addr)

描述

  • I2C初始化接口，实现对指定I2C总线初始化。

参数

参数类型描述
bus_iduint32_tI2C控制器的编号，取值范围为0~15
speeduint32_tspeed，I2C传输速率设置(100或400)，分别代表100K和400K
modeuint32_t是否为从模式(主从只能为一种)，0表示主模式，1表示从模式
addruint32_t从模式的地址 ，当作为主模式时，这个地址可以不配,当作为从模式时,取值范围:<=127

返回

  • 0，初始化成功
  • 其他，初始化失败

示例

c++
I2c i2c;
try {
    int32_t result = i2c.init(0, 100, 0, 0x50); // 初始化 I2C 总线 0，速度 100 kHz，主设备模式，地址 0x50
    if (result == 0) {
        std::cout << "I2C 初始化成功" << std::endl;
    } else {
        std::cout << "I2C 初始化失败，错误码：" << result << std::endl;
    }
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}

read函数 ​

函数形式

  • std::tuple<int32_t, std::optional<std::string>> I2c::read(I2C_READ_S *read_data, const std::string_view &in_data)

描述

  • I2C读接口，实现对指定I2C总线设备读操作

参数

参数类型描述
read_dataI2C_READ_S*包含读请求参数的结构体指针
in_datastring_view&读请求发送的数据

I2C_READ_S结构体介绍如下：

c++
using I2C_READ_S = struct tag_i2c_read_s {
    uint32_t       rv_id;         /* I2C控制器的编号，取值范围为0~15 */
    const uint8_t *tx_buffer;     /* 读操作发送的数据 (地址(1byte高7位) + 其他数据),其他数据可以没有 */
    uint32_t       tx_len;        /* 发送命令中数据长度( 地址+其他数据的字节数 ) ，< =64byte */
    uint8_t       *read_buf;      /* 回传数据buffer */
    uint32_t       length;        /* 读出数据的长度，数据长度大于0，小于等于2048 */
    uint32_t       time_out_cnt;  /* 读超时时间 ms */
    uint32_t       re_read_cnt;   /* 重读次数 默认为3，失败时重读三次 */
};

返回

  • tuple中第一个元素为错误码，0表示成功，负值表示失败。第二个元素为读取到的数据，如果读失败则为std::nullopt。

示例

c++
// 该data数据的含义代表：1.slave器件地址addr为0x30 2.器件偏移为4个字节为 0x00, 0x00, 0x00, 0x10
const uint8_t data[] = {0x30, 0x00, 0x00, 0x00, 0x10};
const size_t data_length = sizeof(data) / sizeof(data[0]);
std::string_view in_data_str(reinterpret_cast<const char *>(data), data_length);

// 调用 read 函数
I2c i2c;
I2C_READ_S read_config = {0};
read_config.rv_id = 0;
read_config.length = 10;
read_config.time_out_cnt = 3000
read_config.re_read_cnt = 3

try {
    auto result = i2c.read(&read_config, in_data_str);
    if (std::get<0>(result) == 0) {
        std::string read_str = std::get<1>(result).value();
        std::cout << "读取到的数据：" << read_str << std::endl;
    } else {
        std::cout << "读取失败，错误码：" << std::get<0>(result) << std::endl;
    }
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}

write函数 ​

函数形式

  • int32_t I2c::write(uint32_t drv_id, const std::string_view &in_data, uint32_t time_out_cnt, uint8_t write_delay)

描述

  • I2C写接口，实现对指定I2C总线设备写操作。I2C写最长等待响应时间由time_out_cnt设置，如果I2C等待发送数据到对端器件超过time_out_cnt毫秒，则判断失败，如果time_out_cnt未配置时，timeout时间默认配置为3秒。

参数

参数类型描述
drv_iduint32_tI2C控制器的编号，取值范围为0-15
in_datastring_view&待写入的数据
time_out_cntuint32_t写超时时间，单位：ms
write_delayuint8_t写入操作后的延迟时间，单位：ms

返回

  • 0，写入成功
  • 其他，写入失败

示例

c++
// 该data数据的含义代表：
// 1.slave器件地址addr为0x30 
// 2.器件偏移为4个字节为 0x00, 0x00, 0x00, 0x10 
// 3.实际待写入内容为4个字节0x01, 0x02, 0x03, 0x04
const uint8_t data[] = {0x30, 0x00, 0x00, 0x00, 0x10, 0x01, 0x02, 0x03, 0x04};
const size_t data_length = sizeof(data) / sizeof(data[0]);
std::string_view in_data_str(reinterpret_cast<const char *>(data), data_length);
I2c i2c;
try {
    int32_t result = i2c.write(0, in_data_str, 3000, 10); 
    if (result == 0) {
        std::cout << "写入成功" << std::endl;
    } else {
        std::cout << "写入失败，错误码：" << result << std::endl;
    }
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}

reset函数 ​

函数形式

  • void I2c::reset(uint8_t bus_id)

描述

  • I2C复位接口，实现对指定I2C总线复位

参数

参数类型描述
bus_iduint8_t指定总线id，取值范围为0-15

返回

  • 成功时无返回值，失败时通过错误引擎抛错

示例

c++
I2c i2c;
try {
    i2c.reset(0); 
    std::cout << "I2C 总线重置成功" << std::endl;
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}

slave_cache_write函数 ​

函数形式

  • void I2c::slave_cache_write(uint32_t drv_id, uint32_t offset, const std::string_view &val)

描述

  • 该接口实现在指定的I2C控制器作为slave时，写I2C Slave的缓存。

参数

参数类型描述
drv_iduint32_t驱动ID，与总线ID保持一致，取值范围为0-15
offsetuint32_t读写偏移，slave为eeprom时需要配置，slave为smbus时为0
valstring_view&写入的数据

返回

  • 成功时无返回值，失败时通过错误引擎抛错

示例

c++
I2c i2c;
try {
    i2c.slave_cache_write(0, 0, "test");
    std::cout << "缓存写入成功" << std::endl;
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}

slave_cache_read函数 ​

函数形式

  • std::string I2c::slave_cache_read(uint32_t drv_id, uint32_t offset, uint32_t size)

描述

  • 该接口实现在指定的I2C控制器作为slave时，读I2C Slave的缓存。

参数

参数类型描述
drv_iduint32_t驱动ID，与总线ID保持一致，取值范围为0-15
offsetuint32_t读写偏移，slave为eeprom时需要配置，slave为smbus时为0
sizeuint32_t读取数据的长度

返回

  • 成功时无返回值，失败时通过错误引擎抛错

示例

c++
I2c i2c;
try {
    std::string read_data = i2c.slave_cache_read(0, 0, 4); 
    std::cout << "读取到的数据：" << read_data << std::endl;
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}

deploy函数 ​

函数形式

  • int32_t I2c::deploy(const DEV_I2C_DEPLOY *deploy)

描述

  • I2C/SMBus初始化统一新接口，实现对指定I2C总线初始化，该接口兼容I2C/SMBus总线的初始化。

参数

参数类型描述
deployDEV_I2C_DEPLOY *包含请求信息的结构体指针

DEV_I2C_DEPLOY结构体介绍如下：

c++
struct i2c_depl {
    uint32_t drv_id;             /* 驱动ID, 与总线ID保持一致 */
    uint32_t flags;              /* 初始化属性 */
    uint32_t sda_hold;           /* SDA信号hold延迟周期数 */
    uint32_t scl_high;           /* SCL 高电平周期数 */
    uint32_t scl_low;            /* SCL 低电平周期数 */
    uint32_t scl_low_timeout;    /* SCL 低电平超时周期数 */
    uint32_t sda_low_timeout;    /* SDL 低电平超时周期数 */
    uint16_t slave_address;      /* 总线初始化为slave时，控制器的地址 */
    uint16_t clk_strech_timeout; /* slave时钟延展最长时间 单位ms */
    uint64_t slave_dlen;         /* 总线初始化为slave时，控制器使用的内存的长度，单位字节，必须是8的整数倍 */
    uint64_t extension;          /* 保留扩展字段 */
} __attribute__((aligned(sizeof(uint32_t))));

using DEV_I2C_DEPLOY = struct i2c_depl;

返回

  • 0，成功
  • 其他值，失败

示例

c++
I2c i2c;
try {
    DEV_I2C_DEPLOY deploy_config = {0};
    deploy_config.drv_id = 0;
    deploy_config.flags = 0x30A;
    deploy_config.slave_dlen = 256;
    deploy_config.slave_address = 0x50;
    
    int32_t result = i2c.deploy(&deploy_config);
    if (result == 0) {
        std::cout << "成功" << std::endl;
    } else {
        std::cout << "失败，错误码：" << result << std::endl;
    }
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}

msg_xfer函数 ​

函数形式

  • std::string I2c::msg_xfer(DEV_I2C_MSG *msg, const std::string_view &in_val)

描述

  • I2C消息收发接口，该接口实现对指定的I2C消息进行消息收发，该接口兼容I2C/SMBus消息的收发。

参数

参数类型描述
msgDEV_I2C_MSG*包含请求信息的结构体指针
in_valstring_view&需要发送的消息

DEV_I2C_MSG结构体介绍如下：

c++
struct i2c_msg {
    uint32_t drv_id;         /* 驱动ID, 与总线ID保持一致 */
    uint16_t addr;           /* 消息目的地址 */
    uint16_t flags;          /* 消息属性 */
    uint8_t  smbus_protocol; /* SMBus消息协议号，仅smbus消息时该字段有效 */
    uint8_t  rsvd[3];        /* 保留扩展字段3个字节 */
    uint32_t wlen;           /* 消息发送长度 */
    uint8_t *wbuf;           /* 消息发送缓存 */
    uint32_t rlen;           /* 消息属性具有I2C_KMSG_RECV_LEN标识时表示消息接收buffer长度，否则表示想要接收的消息的长度 */
    uint8_t *rbuf;           /* 消息接收缓存 */
    uint32_t timeout;        /* 消息收发超时时间，以ms为单位 */
    uint32_t retries;        /* 通信失败后，若具备重传条件，重传次数 */
    uint64_t extension;      /* 保留扩展字段 */
} __attribute__((aligned(sizeof(uint32_t))));

using DEV_I2C_MSG = struct i2c_msg;

返回

  • 读取到的数据，类型为string

示例

c++
// 该data数据的含义代表：1.slave器件地址addr为0x70 2.器件偏移为4个字节为 0x00, 0x00, 0x00, 0x10
const uint8_t data[] = {0x70, 0x00, 0x00, 0x00, 0x10};
const size_t data_length = sizeof(data) / sizeof(data[0]);
std::string_view in_data_str(reinterpret_cast<const char *>(data), data_length);

I2c i2c;
DEV_I2C_MSG i2c_msg_config = {0};
i2c_msg_config.drv_id = 0;
i2c_msg_config.addr = 0x70;
i2c_msg_config.flags = 0x3;
i2c_msg_config.smbus_protocol = 0x0;
i2c_msg_config.timeout = 3000;
i2c_msg_config.retries = 3;

try {
    std::string read_result = i2c.msg_xfer(&i2c_msg_config, in_data_str);
    std::cout << "读取到的数据：" << read_result << std::endl;
} catch (const std::runtime_error& e) {
    std::cout << "异常：" << e.what() << std::endl;
}
上一篇hisport接口文档
下一篇ORM提供的task机制