CH341 StreamI2C字节流命令详解：从EEPROM读写到自定义I2C设备调试

CH341这块芯片在嵌入式调试圈子里算是老熟人了，USB转串口、转并口、转SPI、转I2C都靠它，关键是便宜、驱动全、Windows和Linux下都有官方库。但很多朋友一用到CH341的I2C流模式（StreamI2C）就开始懵，尤其是第一次拿它读写EEPROM的时候，API文档翻来覆去看不明白，示例代码又只有寥寥几行，照着抄都抄不出预期效果。我自己最初也是从AT24C02开始啃StreamI2C的，踩了一堆坑之后才把这套字节流命令的配置逻辑真正理顺。这篇文章就把我反复验证过的参数组织方式一次讲清楚，从EEPROM读写开始，再延伸到自定义I2C设备，保证你看完能直接开干。

1. 先搞清楚StreamI2C到底解决什么问题

1.1 不是所有I2C操作都能用“一键函数”搞定

CH341的驱动库里其实提供了两套I2C操作方式。一套是所谓的“易用模式”，调用CH341I2CWrite、CH341I2CRead这类接口，芯片自动处理START、STOP、地址、ACK这些时序细节，用法非常简单。但易用模式的问题也很明显：它把I2C通信过程给固化了，比如读EEPROM的时候只能按照“先写目标地址，再发重起始信号，然后读数据”这个固定模板来，遇到一些特殊时序要求、非标准从机地址、需要自定义控制位的设备，或者想自己控制每一笔操作的边界时，它就无能为力了。

还有一点容易被忽略，易用模式下每次操作都要经过一次USB请求的完整往返，如果反复做单字节读写，USB通信开销占比会非常高，实测下来大量小操作时吞吐量并不理想。

这个时候就要用到StreamI2C，也就是CH341的I2C流模式。它做的事其实很纯粹：把I2C总线上的每一个基础动作，比如产生起始位、产生停止位、输出一个字节、读取一个字节、发送ACK、发送NACK，都编码成字节流里的特定命令。你先在内存里拼好一串命令字节，再一次性交给驱动发送出去，CH341芯片就按照这串命令在I2C总线上逐步执行。

1.2 StreamI2C的核心优势：一次USB传输干完整笔事务

StreamI2C最大的价值不是“灵活”这两个字，而是把整笔I2C事务压缩进一次USB交互。拿EEPROM随机读举例，完整过程是：START、发送设备地址（写）、等待ACK、发送寄存器地址、等待ACK、重新START、发送设备地址（读）、等待ACK、读取数据字节、发送NACK、STOP。如果用易用模式，至少拆成两次函数调用，中间总线上会出现一次完整的停止信号，这对某些严格要求原子操作的设备来说是无法接受的。

而用StreamI2C，我把这11个动作全部编码成一串命令，一次CH341StreamI2C调用就全部搞定，中间不会产生多余的STOP，时序完全由我自己定义。所以在做自定义I2C设备调试、驱动验证、或者批量EEPROM读写的时候，StreamI2C才是真正好用的那把刀。理解这一点，就明白为什么它值得花时间研究。

2. 揭开StreamI2C的字节流命令格式

2.1 命令集其实不复杂，就十来个码

CH341的StreamI2C把I2C时序动作映射成一组单字节命令。官方文档里给出了完整定义，我记得关键命令如下：

实际用得最多的是前六个。0x74和0x75负责产生START和STOP条件，0x80负责写地址或写数据，0x81用于不需要ACK确认的场景，0xA0读一个字节并回ACK，0xA1读最后一个字节时回NACK。看到这里你应该已经悟了：所谓StreamI2C，本质上就是用字节流在模拟I2C时序。

2.2 参数配置逻辑的最关键一环：长度与缓冲区

StreamI2C的函数原型在不同系统、不同语言的封装下长得不一样，但核心参数万变不离其宗。以Windows下C语言接口为例，官方DLL提供的函数是这样的：

BOOL CH341StreamI2C( ULONG iIndex, // 设备序号 ULONG iRepeat, // 重复次数（通常填1） ULONG iSpeed, // 时钟频率档位，0低速/1标准/2高速 ULONG iSCL, // SCL引脚位（默认0） ULONG iSDA, // SDA引脚位（默认1） PUCHAR iWriteBuf, // 写缓冲区，放命令字节+数据字节 ULONG iWriteLength, // 写缓冲区长度 PUCHAR oReadBuf, // 读缓冲区，放读到的数据 ULONG oReadLength // 期望读取的字节数 );

这里有个非常容易踩坑的细节：iWriteBuf里放的不只是要写到I2C总线上的数据，而是“命令+数据”的混合流。很多新手直接把要写的字节丢进去，调用完发现总线上完全没有波形，问题就在这。命令字节和数据字节是一个整体，CH341按顺序解析执行，遇到0x80就知道后面跟的是要发送的数据字节，遇到0xA1就知道要把这时的SDA数据采回来。

oReadLength和读命令也有对应关系。如果你在命令流里放了两个0xA0、一个0xA1，那么oReadLength应该是3。如果你期望读3个字节，但命令流里只放了一个0xA1，实际只能读回1个字节，其余位置是垃圾数据。所以配置逻辑的底层规律是：写缓冲区的命令编排出什么节奏，读缓冲区就相应准备多大。这个对应关系理解透了，StreamI2C就算掌握了一半。

2.3 时钟速度档位和电气参数的关系

iSpeed参数决定SCL时钟频率，通常三档分别是低速（约20kHz）、标准（约100kHz）、高速（约400kHz）。但注意，这个频率是芯片内部粗略分频得到的，不是精确的I2C标准频率。实测下来，低速模式下SCL大概在十几到二十几kHz之间波动，标准模式接近100kHz，高速模式能到300kHz多，和芯片版本、USB负载都有关系。

对EEPROM这类慢速存储芯片，20kHz、100kHz都稳稳的。但如果你挂了一些对时序比较挑剔的传感器，比如某些需要严格400kHz的器件，CH341的高速档可能达不到标称值，甚至会有轻微抖动。我的习惯是：常规器件用标准档，调试时先用低速档排除信号完整性问题，最后再切高速档。这个顺序能帮你省掉很多莫名其妙的故障排查时间。

3. 从EEPROM读写实战开始

3.1 搭建一个最小验证环境

动手写代码之前，先确认手里的硬件连接。CH341的I2C引脚在不同封装下位置不太一样，典型的是DIP-16、SSOP-20这些封装，I2C的SCL和SDA引脚通常是专用的，具体看手册的引脚定义表。连接方式：

• SCL接EEPROM（以AT24C02为例）的SCL引脚
• SDA接EEPROM的SDA引脚
• EEPROM的A0/A1/A2接地（也可以根据你的地址需求配置）
• WP写保护引脚直接接地或悬空（AT24C02内部有下拉，一般悬空也能写，但稳妥起见接地）
• VCC接3.3V或5V，注意CH341的IO电平跟目标板一致，最好加2.2k到4.7k的上拉电阻到VCC

这里有个细节很多人会忽略：CH341的I2C引脚是开漏输出，所以外部必须接上拉电阻。有些开发板上没集成上拉，直接连EEPROM模块后波形就完全不对。我调试时习惯在SCL和SDA上各接一个4.7k的上拉电阻到3.3V，效果很稳定。如果目标设备是5V供电，就用5V上拉，但这时候要确认CH341引脚能承受5V电平，手册里一般会标“容忍5V”。

3.2 单字节写入：命令流的完整拆解

AT24C02内部有256个字节，分32页，每页8字节。随机写一个字节的标准I2C时序是：START -> 发送设备地址(写) -> 等待ACK -> 发送字节地址 -> 等待ACK -> 发送数据 -> 等待ACK -> STOP。

设备地址的构成是固定的，AT24C02的7位地址是1010加上A2/A1/A0三个引脚电平，如果三个引脚都接地，那么7位地址就是0x50，加上读写位之后变成0xA0（写）和0xA1（读）。

对应到StreamI2C命令流，写法如下：

UCHAR wbuf[10]; UCHAR rbuf[8]; int wlen = 0; // 步骤1: 起始位 wbuf[wlen++] = 0x74; // 步骤2: 发送设备地址(写), 0xA0, 并期望ACK wbuf[wlen++] = 0x80; wbuf[wlen++] = 0xA0; // 步骤3: 发送EEPROM内部字节地址, 比如0x00 wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x00; // 步骤4: 发送数据字节, 比如0x5A wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x5A; // 步骤5: 停止位 wbuf[wlen++] = 0x75; CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, rbuf, 0);

注意最后oReadLength填0，因为这笔操作完全不读数据。如果你填了非0值，一些版本的驱动反而会出问题。写完这5步，EEPROM就收到了一笔完整的单字节写事务。写完之后芯片内部进入编程状态，需要等大概5ms左右才能进行下一次操作，这是EEPROM的硬件特性，代码里记得加延时。

3.3 随机读与顺序读：读命令怎么编排

随机读一个字节，时序比写稍微绕一点，因为要先写地址再重新发起通信。命令流如下：

wlen = 0; wbuf[wlen++] = 0x74; // START wbuf[wlen++] = 0x80; // 设备地址(写) 0xA0 wbuf[wlen++] = 0xA0; wbuf[wlen++] = 0x80; // 字节地址 0x00 wbuf[wlen++] = 0x00; wbuf[wlen++] = 0x74; // 重新START (注意不是STOP+START) wbuf[wlen++] = 0x80; // 设备地址(读) 0xA1 wbuf[wlen++] = 0xA1; wbuf[wlen++] = 0xA1; // 读取一字节, 主机回NACK // 这里没有数据字节 // 读缓冲准备1个字节 UCHAR rbuf[2]; CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, rbuf, 1); // rbuf[0] 就是读回来的数据

这里的关键点是重新START用0x74而不是0x75+0x74。I2C规范里重复起始位（Restart）与独立的停止位有本质区别，有些设备对“先STOP再START”很宽容，但有些专用传感器就要求必须Restart，否则状态机就乱了。StreamI2C里连续两个0x74之间没有停止位，芯片会在总线上产生一个真正的Restart条件，这点设计得非常巧妙。

如果想连续读多个字节，就把0xA1（NACK）放到最后一个读动作。前面的读命令都用0xA0（ACK），模拟“主机告诉从机继续发”的过程。比如连续读4个字节：

wbuf[wlen++] = 0xA0; // 读第1字节, 回ACK wbuf[wlen++] = 0xA0; // 读第2字节, 回ACK wbuf[wlen++] = 0xA0; // 读第3字节, 回ACK wbuf[wlen++] = 0xA1; // 读第4字节, 回NACK CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, rbuf, 4);

3.4 页写操作与内置延时

AT24C02支持页写，一次最多写8个字节。页写时序跟单字节写几乎一样，只是地址后面连续跟多个数据字节。需要注意的是，页写的地址低3位必须是对齐到页边界的。如果你从页内偏移5开始写8个字节，EEPROM会回绕到页开头覆盖数据，这是芯片设计如此，不算逻辑错误但容易让人误以为程序有bug。

页写命令流：

wlen = 0; wbuf[wlen++] = 0x74; wbuf[wlen++] = 0x80; wbuf[wlen++] = 0xA0; // 设备地址写 wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x00; // 页起始地址, 页对齐 wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x01; // 数据1 wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x02; // 数据2 // ... 一直到数据8 wbuf[wlen++] = 0x75; CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, rbuf, 0); Sleep(10); // 等待内部写周期完成

不禁想多说一句，很多人在页写后立刻读数据发现读回来不对，第一反应是CH341的问题，其实是因为没有等EEPROM内部编程完成。AT24C02写周期典型值是5ms，上限有时到10ms，Sleep(10)是个保险值。如果你用的其他型号EEPROM，这个时间可能有差异，建议按数据手册来。

4. 从EEPROM扩展到自定义设备

4.1 寄存器型设备的通用访问模板

EEPROM算是“裸存储器”类设备，访问逻辑比较简单直接。但实际工程中更多的I2C设备是寄存器映射型，典型如传感器（SHT30、BMP280）、IO扩展芯片（PCF8574）、ADC芯片（ADS1115）等等。这类设备的访问模式可以抽象成两种：

• 写寄存器：START -> 设备地址(写) -> 寄存器地址 -> 数据... -> STOP
• 读寄存器：START -> 设备地址(写) -> 寄存器地址 -> Restart -> 设备地址(读) -> 数据... -> STOP

这不就是EEPROM的随机读和页写吗？本质完全一样。所以只要把EEPROM的代码稍作修改，就能通吃绝大多数I2C设备。

以PCF8574为例，它的器件地址是0x40（写方向），只有一个8位的IO寄存器，直接对这个地址发一个数据字节就能控制8个IO口输出高低电平。想读回当前IO状态，直接发设备地址(读)再读1字节。整个过程极短：

// 读PCF8574的8位IO状态 wlen = 0; wbuf[wlen++] = 0x74; wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x41; // 设备地址+读, 0x40|1 wbuf[wlen++] = 0xA1; // 读取电平状态, NACK结束 UCHAR ioState; CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, &ioState, 1);

4.2 带校验和与状态字节的复杂设备怎么拆解

有些传感器的读取流程没那么直白，比如SHT30温湿度传感器，它支持周期测量和单次测量。单次测量模式下，需要先向0x2C、0x06这两个命令字节发起“测量请求”，然后等待一定时间（实测约15ms），再发起数据读取。命令流如下：

// 发起单次测量 wlen = 0; wbuf[wlen++] = 0x74; wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x88; // 设备地址左移一位，写方向 wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x2C; // 命令高字节 wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x06; // 命令低字节 wbuf[wlen++] = 0x75; CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, rbuf, 0); Sleep(20); // 等待测量完成 // 读取6字节: 温度MSB, LSB, CRC, 湿度MSB, LSB, CRC wlen = 0; wbuf[wlen++] = 0x74; wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x89; // 设备地址+读 wbuf[wlen++] = 0xA0; // 第1字节 wbuf[wlen++] = 0xA0; // 第2字节 wbuf[wlen++] = 0xA0; // 第3字节 wbuf[wlen++] = 0xA0; // 第4字节 wbuf[wlen++] = 0xA0; // 第5字节 wbuf[wlen++] = 0xA1; // 第6字节, NACK wbuf[wlen++] = 0x75; UCHAR data[6]; CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, data, 6);

这种带CRC校验的数据流，正好发挥StreamI2C“整笔事务一次完成”的优势。如果用易用模式，读六字节时需要中间插两次函数调用，而且地址重发逻辑还得自己拼，代码丑且容易出错。用StreamI2C，直接一个buf搞定。

4.3 一次事务轮询多个不同从机地址

StreamI2C的另一大用法是在同一笔事务里访问多个从机。比如总线上挂了一颗EEPROM和一颗IO扩展芯片，你想先写EEPROM再读IO状态，完全可以把两个操作串到一串命令里，只调一次USB接口。这在需要“多设备同步采样”或“尽量降低单次USB交互延迟”的场景下非常实用。

实现方式很简单，第一个设备的操作结束后，不写STOP，直接再写一个START，然后接第二个设备的地址和操作。当然，你也可以在中间加STOP再START，这取决于总线上设备是否要求连续操作。我的经验是，如果设备手册没有特殊要求，优先使用Restart连接不同事务，时序更紧凑，效率更高。

wlen = 0; // EEPROM页写 wbuf[wlen++] = 0x74; wbuf[wlen++] = 0x80; wbuf[wlen++] = 0xA0; wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x10; wbuf[wlen++] = 0x80; wbuf[wlen++] = 0xAA; // 无缝切换到PCF8574 wbuf[wlen++] = 0x74; // 重新START wbuf[wlen++] = 0x80; wbuf[wlen++] = 0x41; // 读IO wbuf[wlen++] = 0xA1; wbuf[wlen++] = 0x75; CH341StreamI2C(0, 1, 1, 0, 1, wbuf, wlen, rbuf, 1);

不过要留意一点，某些从机在收到Restart后可能进入复位状态，这时同一笔事务里的操作就会出现意外。遇到这种怪问题，优先拆成两笔独立事务来排查。

5. 踩坑记录与排查技巧

5.1 常见错误速查表

我把自己和其他朋友在实际调试中遇到过的问题整理成了一张表，方便你对照排查：

5.2 用逻辑分析仪验证时序才是最高效的排错手段

代码写完先别急着接真实设备，最好用逻辑分析仪单独抓一下CH341发出的波形。不需要多高端的设备，那种几十块钱的8通道24MHz采样率的逻辑分析仪就够用了。把探头夹在SCL和SDA上，运行一次StreamI2C调用，观察波形是否符合I2C时序规范。

我提几个重点检查的波形特征：起始位是否满足“SCL为高时SDA由高变低”；停止位是否满足“SCL为高时SDA由低变高”；数据位是否满足“SDA在SCL为高时保持稳定”。这三个特征只要有一个不对，从机就不会正确响应。借助逻辑分析仪自带的I2C协议解码功能，甚至可以直观看到每一个地址字节、数据字节的ACK状态，排错效率完全不一样。

5.3 异步操作与状态位检测的配合

CH341的StreamI2C接口本身是同步阻塞的，调用返回时整笔事务已经发送完毕（或者超时）。但在Linux下使用libusb进行异步传输时，代码逻辑要稍加调整。libusb的异步批量传输回调会在完成时触发，此时才能安全释放缓冲区。

// libusb异步方式提交StreamI2C命令 struct libusb_transfer *tr = libusb_alloc_transfer(0); libusb_fill_bulk_transfer(tr, dev_handle, 0x02, wbuf, wlen, callback, NULL, 0); libusb_submit_transfer(tr);

在callback里再检查实际传输长度是否等于wlen，如果不一致，说明USB层面出了问题。这点很容易被忽视，因为CH341的USB端点描述符在不同驱动下可能略有区别，Windows下用系统HID或VCP驱动没这个问题，Linux下用libusb就要自己处理端点。

此外，如果你的宿主程序本身跑在RTOS或者异步框架里，要注意StreamI2C的同步调用可能会阻塞较长时间（尤其是在USB异常时，超时时间可能到几百毫秒）。这种情况下建议把I2C操作放到独立任务中，并加超时保护，避免拖垮整个系统调度。

5.4 频率与负载导致的信号完整性问题

很多人用CH341调通了EEPROM就以为万事大吉，结果挂上一个较长走线的传感器模块就开始随机出问题。这时候首要排查的不是代码，而是信号完整性。

I2C总线的上拉电阻值不是随便选的。总线上挂的设备越多、走线越长，寄生电容越大，需要的上拉电阻就越小（拉电流更强）。我在一条总线上挂了4个设备，走线大约30cm时，把上拉电阻从4.7k换成了2.2k，问题立刻消失。但同时也要注意，电阻太小会导致灌电流过大，某些从机可能承受不住。

一个实用的估算方法是：先以100kHz为目标，总线上拉电阻选4.7k起步；如果波形上升沿太缓（超过1微秒），再用2.2k或1k。CH341的高速档对上升沿要求更严，所以布线条件一般时不要轻易用高速档。

6. 把StreamI2C放进更大的工具链

6.1 上位机与MCU的调试协同

CH341很多时候不是最终产品里的I2C主控，而是PC端调试工具。你可能正在给STM32或STC32G写I2C驱动，但手上没有逻辑分析仪，又不想反复烧录固件来验证时序，这时候完全可以用CH341 StreamI2C模拟主机的行为，把目标设备当作被测对象，先把寄存器读写、数据格式全部在PC上跑通，再移植到MCU里，开发节奏会快很多。

反过来，你也可以用CH341作为上位机注入异常时序，比如中间故意不发送STOP，看目标设备会不会挂死，借此验证固件里是否有超时恢复机制。这些操作在StreamI2C模式下一串命令就能搞定，ESD防护、总线恢复、多主冲突这些边界场景都能模拟。

6.2 在Linux下通过libusb复用同一套逻辑

Windows平台有官方DLL，方便得很。Linux下CH341更多是通过libusb直接控制设备。CH341在Linux下通常枚举为自定义HID设备或并口设备，使用libusb控制时，命令流格式和Windows完全一致。也就是说，你只需要写一个底层发送函数，上层拼StreamI2C命令的逻辑完全复用。

int ch341_stream_i2c(libusb_device_handle *dev, unsigned char *cmd, int cmd_len, unsigned char *resp, int resp_len) { int transferred = 0; int ret = libusb_bulk_transfer(dev, 0x02, cmd, cmd_len, &transferred, 1000); if (ret != 0) return ret; if (resp_len > 0) { ret = libusb_bulk_transfer(dev, 0x82, resp, resp_len, &transferred, 1000); } return ret; }

注意0x02是输出端点，0x82是输入端点，不同CH341封装可能有差异，最好用lsusb -v确认一下端点号。Linux下没有官方DLL里那些对单次传输长度的隐藏限制，但也要注意libusb的单次批量传输缓冲区不要超过64KB，一般I2C命令流根本没有那么大。

6.3 在Verilog/FPGA调试中的参考价值

有些朋友在做FPGA上的I2C控制器，比如自己写Verilog版的I2C读写EEPROM逻辑，这时候CH341 StreamI2C可以当作一个参考主设备来使用。你不需要重新造轮子，首先用CH341把EEPROM的读写时序全部跑通并记录波形，然后在FPGA里实现同样的状态机，用逻辑分析仪将两边的波形对比，定位是起始位保持时间不够，还是数据建立时间不足。

我自己在调一个Verilog I2C控制器时，就是用CH341先抓了一版标准波形，然后在ModelSim里对着波形一点一点调状态机，最后在FPGA上跑出来的时序和CH341的几乎一致。这种跨工具链的调试方法，很多时候比闷头看代码高效得多。

7. 一个经常被忽略但很值得养成的习惯

StreamI2C用熟了以后，我非常推荐你为它建立一套自己的“命令模板库”。不要每次写代码都从0x74拼起，把常用的操作封装成函数，比如eeprom_write_byte、eeprom_page_write、eeprom_random_read、reg_write、reg_read这类，内部拼命令流，对外只暴露设备地址、寄存器地址、缓冲区指针和长度。这样一来，业务代码会变得非常干净，排查问题时也能很快定位到是拼命令流出错还是设备本身没响应。

封装的时候有一件事值得注意：每笔StreamI2C调用之后最好都检查一下错误码，尤其要区分“USB传输失败”和“从机NACK”这两种情况。USB传输失败是底层没发出去，多半是线缆、驱动问题；NACK是从机确实收到了但不认账，多半是地址或时序问题。这两个问题的排查方向完全不同，别混为一谈。

我个人在实际调试中还习惯在每条命令流的开头加一个0x74起始位，即使上一笔已经用STOP结束，也再发一次START。这个冗余看似多余，但它能保证状态机永远不会因为总线残留状态而错乱。代价只是一个字节的USB传输量，换来的是极佳的稳定性。这个小套路，我在量产测试程序里一直沿用，极少再碰到总线卡死的情况。