类: I2C

约 3982 字大约 13 分钟

2024-05-04

构建固件和导入到JS

该类没有直接导出, 只能从 serial 模块导入该类的实例:

import { i2c0 } from "serial"

简介

I2C 总线类

用于配置和管理 ESP32 的 I2C 总线。I2C 是一种两线串行通信协议，常用于连接传感器、显示屏、EEPROM 等外设。

ESP32 通常有 2 个 I2C 总线（I2C0、I2C1），部分型号还有低功耗 I2C（I2C LP）。 serial 模块会自动创建 I2C 实例并通过 i2c0, i2c1 等导出。用户直接通过 serial 模块访问这些实例，无需手动创建。

不同芯片型号导出的 I2C 对象不同：

ESP32/ESP32-S2/S3/H2/P4：i2c0, i2c1（2 个 I2C）
ESP32-C2/C3/C6：i2c0（只有 1 个 I2C）

示例：

import * as serial from "serial"

// 访问 I2C0 总线实例（推荐）
const i2c = serial.i2c0

// 配置 I2C 总线
i2c.setup({
    sda: 21,  // SDA 引脚
    scl: 22,  // SCL 引脚
    freq: 400000  // 时钟频率 400kHz
})

// 扫描总线上的设备
i2c.scan()

// 添加设备配置
i2c.addDevice({
    addr: 0x68,  // 设备地址（如 MPU6050）
    freq: 100000
})

// 读写寄存器
i2c.write8(0x68, 0x6B, 0x00)  // 向地址 0x68 的寄存器 0x6B 写入 0x00
const data = i2c.readU8(0x68, 0x75)  // 从寄存器 0x75 读取数据
console.log("Who am I:", data)

该类的构造函数没有绑定给 JS , 无法从 JS 创建实例。

模块 serial 创建了和硬件对应的 I2C 实例，import serial 即可。

类方法

方法 setup

原型: setup (options:object)

配置并启动 I2C 总线。

初始化 I2C 总线，配置 SDA/SCL 引脚、主从模式等参数。当前仅支持主模式（master mode），从模式尚未实现。

options 参数说明：

{
    sda: number,              // SDA 引脚 GPIO 编号（必需）
    scl: number,              // SCL 引脚 GPIO 编号（必需）
    mode: number = 1,         // 模式：0=从机, 1=主机（默认主机）
    core: number = 0,         // 运行 I2C 驱动的 CPU 核心编号
    clk_source: number,       // 时钟源（默认 I2C_CLK_SRC_DEFAULT）
    glitch_ignore_cnt: number = 7,  // 毛刺过滤计数
    internal_pullup: bool = true,   // 使能内部上拉
    allow_pd: bool = false,         // 允许断电
    intr_priority: number = 0,      // 中断优先级
    trans_queue_depth: number = 0,  // 事务队列深度
    dev: [                      // 预配置设备数组（可选）
        {
            addr: number,           // 设备地址（必需）
            addrBit10: bool = false,    // 是否使用 10 位地址
            regAddrBits: number = 8,    // 寄存器地址位数（8/16/32）
            regBits: number = 8,        // 寄存器值位数（8/16/32）
            freq: number = 100000,      // 时钟频率（Hz）
            timeout: number = 1000,     // 超时时间（微秒）
            ackCheck: bool = true       // 是否启用 ACK 检查
        }
    ]
}

参数:

options
类型object
参数说明配置选项对象

异常:

缺少 sda 或 scl 配置
I2C 总线初始化失败
添加预配置设备失败
从模式不受支持

返回值:

类型undefined

方法 addDevice

原型: addDevice (options:object)

向 I2C 总线添加一个设备。

将设备配置添加到总线，用于后续的读写操作。如果设备已存在，则更新其配置信息。

options 参数说明：

{
    addr: number,               // 设备地址（必需）
    addrBit10: bool = false,    // 是否使用 10 位地址（默认 7 位）
    regAddrBits: number = 8,    // 寄存器地址位数（8/16/32，默认 8）
    regBits: number = 8,        // 寄存器值位数（8/16/32，默认与 regAddrBits 相同）
    freq: number = 100000,      // 时钟频率（Hz，默认 100kHz）
    timeout: number = 1000,     // 超时时间（微秒，默认 1000）
    ackCheck: bool = true       // 是否启用 ACK 检查（默认启用）
}