树莓派 I2C 传感器开发实战指南

一、GPIO 引脚速查表（多来源核对）

Raspberry Pi 4B / Zero / Zero 2 W / 3B+ 均采用 40-pin GPIO Header，引脚布局完全兼容。 引脚编号规则：USB 口朝下时，Pin 1 在左上角（方焊盘），按书页顺序编号。

来源核对：Raspberry Pi 官方文档 raspberrypi.com、 pinout.xyz、Wevolver Pi 4 Pinout Guide、 Electronics for You GPIO 指南

1.1 通信接口引脚（I2C / SPI / UART）

1.2 电源与通用 GPIO 引脚

1.3 电气特性（必须遵守）

• 3.3V 逻辑电平：所有 GPIO 通信引脚（SDA/SCL/MOSI/MISO/TX/RX）均为 3.3V，不兼容 5V。直接接 5V 会烧毁 GPIO。
• GPIO2/GPIO3 固定上拉：这两个引脚有 ~1.8kΩ 板载上拉电阻 到 3.3V，因此：
  • 不能配置为下拉或浮空输入
  • 非常适合 I2C（I2C 规范要求 SDA/SCL 上拉）
  • 如果当普通 GPIO 用，默认就是高电平
• 3.3V 电源限制：总输出电流约 800mA，5V 引脚直通 USB 供电。
• Zero 系列：Zero / Zero W / Zero 2 W 出厂 不焊排针，需自行焊接或使用带排针版本（WH）。

二、I2C 总线选型：标准 I2C vs 软件 I2C

2.1 标准 I2C（/dev/i2c-1）

使用硬件 I2C 控制器，驱动由 Linux 内核管理。

# 启用
sudo raspi-config  # -> Interface Options -> I2C -> Enable
# 或修改 /boot/config.txt 添加：
# dtparam=i2c_arm=on

2.2 软件 I2C（Bit-Banging）

通过 GPIO 手动翻转电平模拟 I2C 时序，可使用任意 GPIO。

适用场景：

• 标准 I2C-1 已被其他设备占用
• 传感器需要接到非标准引脚（如 GPIO8/9）
• 需要与 SPI 引脚复用（GPIO8/9 同时也是 SPI0 CE0/MISO）

两种实现方式：

内核 overlay 陷阱：i2c-gpio 设备树叠加层无法启用 SoC 内部上拉电阻。如果外接传感器没有外部上拉，I2C 总线会处于浮空状态，导致设备扫描不到、通信失败。必须用 gpiod 库在用户态实现。

2.3 性能对比（实测数据）

以 BMI270 读取 12 字节（accel + gyro）为例：

关键结论：

• C 并不比 Python 快多少，瓶颈在 Linux I2C 内核层（系统调用 + 调度）
• Bit-banging 的瓶颈是 GPIO 翻转延时（微秒级 sleep），C 和 Python 性能接近
• 要达到 200Hz 连续采集，必须用标准 I2C（/dev/i2c-1）+ 块读取，且 BMI270 必须接在 pin3/5

三、gpiod 库使用指南

3.1 安装

# Python
pip3 install gpiod

# C
sudo apt install libgpiod-dev

3.2 Python：SMBus 兼容层

用 gpiod 实现一个与 smbus2.SMBus 接口兼容的类，可 monkey-patch 替换原驱动中的 SMBus：

import gpiod
from gpiod.line import Direction, Value, Bias

class SMBus:
    """gpiod-based bit-banging I2C compatible with smbus2.SMBus"""
    def __init__(self, bus=None):
        self.chip = gpiod.Chip('/dev/gpiochip0')
        self.scl_pin = 9   # GPIO9 (物理 pin21)
        self.sda_pin = 8   # GPIO8 (物理 pin24)
        self.addr = 0

    def _delay(self):
        import time
        time.sleep(0.00001)  # 10us = ~50kHz

    def _start(self):
        # SCL=1 时 SDA 从高变低
        ...

    def _stop(self):
        # SCL=1 时 SDA 从低变高
        ...

    def write_byte_data(self, addr, reg, value):
        self.addr = addr
        self._start()
        self._write_raw(addr \x3C\x3C 1)      # ADDR + W
        self._write_raw(reg)
        self._write_raw(value)
        self._stop()

    def read_i2c_block_data(self, addr, reg, length):
        self.addr = addr
        self._start()
        self._write_raw(addr \x3C\x3C 1)      # ADDR + W
        self._write_raw(reg)
        self._start()                   # Repeated START
        self._write_raw((addr \x3C\x3C 1) | 1)  # ADDR + R
        data = [self._read_raw(ack=1) for _ in range(length-1)]
        data.append(self._read_raw(ack=0))  # 最后字节发 NACK
        self._stop()
        return data

    def write_i2c_block_data(self, addr, reg, data):
        self.addr = addr
        self._start()
        self._write_raw(addr \x3C\x3C 1)
        self._write_raw(reg)
        for b in data:
            self._write_raw(b)
        self._stop()

关键技巧：

• SDA 引脚需要在 输出模式（带内部上拉）和 输入模式（带内部上拉）之间切换
• 输出模式用 GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP
• 输入模式也用 GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP
• 不要共用输入/输出 line 对象，release 后再 re-request

3.3 C：libgpiod 接口

#include \x3Cgpiod.h>

#define SDA_GPIO  8
#define SCL_GPIO  9

struct gpiod_chip *chip = gpiod_chip_open("/dev/gpiochip0");
struct gpiod_line *scl = gpiod_chip_get_line(chip, SCL_GPIO);

// SCL 固定为输出（带上拉）
gpiod_line_request_output_flags(scl, "i2c_driver",
    GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP, 1);

// SDA 读时切为输入（带上拉）
gpiod_line_request_input_flags(sda_in, "i2c_driver",
    GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP);

// SDA 写时切为输出（带上拉）
gpiod_line_request_output_flags(sda_out, "i2c_driver",
    GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP, 1);

四、BMI270 6轴 IMU 专项

4.1 基本信息

4.2 初始化流程（关键！必须严格遵循）

BMI270 每次上电或软复位后必须加载 8KB config 文件，否则无法工作。

1. 读 CHIP_ID (0x00) -> 应返回 0x24
2. 写 PWR_CONF (0x7C) = 0x00     # 禁用高级省电模式
3. 延时 1ms
4. 写 INIT_CTRL (0x59) = 0x00    # 准备加载 config
5. 延时 1ms
6. 【循环 256 次】每次写 32 字节到 INIT_DATA (0x5E)
   - 写 INIT_ADDR_0 (0x5B) = 0x00
   - 写 INIT_ADDR_1 (0x5C) = page (0~255)
   - burst write: 0x5E + 32 bytes config data
   - 每页延时 30us
7. 写 INIT_CTRL (0x59) = 0x01    # 完成加载
8. 延时 30ms
9. 轮询 INTERNAL_STATUS (0x21) 直到 == 0x01（最多等 2 秒）
10. 写 PWR_CTRL (0x7D) = 0x07   # 启用 Accel + Gyro + Temp
11. 配置 ODR 和量程

4.3 Config 文件加载技巧

• Config 文件为二进制 .bin，8192 字节，由 Bosch 官方提供
• 不能 byte-by-byte 写入，太慢且不可靠。应使用 块写入（burst write）
• 标准 I2C 下：直接用 write(i2c_fd, buf, 33)，buf[0]=0x5E, buf[1..32]=config data
• 块写入时序：START -> ADDR+W -> REG(0x5E) -> 32 bytes data -> STOP
• 每页（32 字节）写完后延时 30us，全部 256 页约需 200ms+

4.4 数据读取与转换

寄存器布局（从 0x0C 开始连续读取 12 字节）：

转换公式：

// Accel (量程 ±16g, REG_ACC_RANGE=0x03)
float scale = 16.0f / 32768.0f;  // ≈ 0.000488 g/LSB

// Gyro (量程 ±2000 dps, REG_GYR_RANGE=0x00)
float scale = 2000.0f / 32768.0f;  // ≈ 0.061 dps/LSB

// 温度 (寄存器 0x22, 2字节)
// 实际驱动中常用简化公式：23.0 + (raw * 0.5f / 512.0f)

4.5 配置寄存器参考

五、MAX30205 温度传感器专项

5.1 基本信息

5.2 温度读取

import smbus
bus = smbus.SMBus(1)
data = bus.read_i2c_block_data(0x48, 0x00, 2)  # 从寄存器 0x00 读 2 字节
raw = (data[0] \x3C\x3C 8) | data[1]
if raw > 0x7FFF:
    raw -= 0x10000
temp_c = raw / 256.0

C 语言版本：

int fd = open("/dev/i2c-1", O_RDWR);
ioctl(fd, I2C_SLAVE, 0x48);
uint8_t reg = 0x00;
write(fd, &reg, 1);
uint8_t data[2];
read(fd, data, 2);
int16_t raw = (data[0] \x3C\x3C 8) | data[1];
if (raw > 0x7FFF) raw -= 0x10000;
float temp = raw / 256.0f;

5.3 关键寄存器

六、常见问题排查清单

6.1 I2C 设备扫描不到

6.2 BMI270 初始化失败

6.3 GPIO Bit-Banging 问题

6.4 Flask / Python 特定问题

七、实战接线对照表

本项目实际接线（BMI270 + MAX30205 共存）：

注意：GPIO8/9 同时也是 SPI0 的 CE0/MISO。如果同时使用 SPI 设备，需避免冲突。

八、性能优化建议

1. 块读取优先：BMI270 的 accel+gyro 共 12 字节连续寄存器，用一次 read_i2c_block_data(0x0C, 12) 比 6 次单字节读取快 5 倍以上
2. 温度读取可降频：BMI270 内部温度变化慢，不需要每帧都读
3. C 语言不等于高性能：如果瓶颈在 I2C 总线或 OS 调度，改用 C 提升有限
4. 如需 200Hz+：BMI270 必须接标准 I2C-1（pin3/5），且用 C + 块读取
5. config 只加载一次：BMI270 初始化后不要重复加载 8KB config，耗时 200ms+

九、参考资源

• Raspberry Pi 官方 GPIO 文档
• pinout.xyz 交互式引脚图
• BMI270 数据手册 (Bosch)
• BMI270 官方 GitHub 驱动
• MAX30205 数据手册 (Analog Devices/Maxim)
• libgpiod 文档