WAVESHARE 适配器配置
Waveshare USB TO UART/I2C/SPI/JTAG 适配器（主控 CH347T）在平台上以「通用总线适配器」接入：一块板按拨码模式暴露 I2C / SPI / UART / JTAG 四类协议，日常工作重心是在仪器指令库中 「编辑读取指令 / 编辑设置指令」 创建指令——平台把 I2C:R:0x08:1 这样的模板翻译成总线事务，读回后还能用 ;BIT: / ;EXPR: / ;FMT: 把一次读回的字节拆成多条测试指标、并指定显示进制；PMBus 器件可以直接用 PMBUS:READ: / PMBUS:WRITE:（见第 8 节）。
本文以一款锂电池充电管理芯片为例（I2C 接口），配合空总线 SPI/UART 通路贯穿全文，要建哪条指令直接对照第 9 节全量填写速查复制即可。适配器本身也能下发几条临时配置指令（改速率、开关 I2C 扫描、读拨码），见第 12 节。
相关页面：ATEBOX 485 连接说明、PMBus 设备配置、UDS 设备配置、PLC 设备配置、Modbus 设备配置。
1. 先懂适配器：拨码模式决定能用哪些协议
拨码必须先拨好再插 USB，软件不能改拨码：
| 模式 | S1 | S2 | 可用接口 |
|---|---|---|---|
| M0 | OFF | OFF | UART0 + UART1 |
| M1 | ON | OFF | UART1 + I2C + SPI |
| M2 | OFF | ON | UART1 + I2C + SPI |
| M3 | ON | ON | UART1 + JTAG（+ I2C） |
| 拨码 | I2C 模板 | SPI 模板 | UART 模板 | JTAG 模板 |
|---|---|---|---|---|
| M1 | 可用 | 可用 | 可用 | 不可用 |
| M2 | 可用 | 可用 | 可用 | 不可用 |
| M3 | 可用 | 不可用 | 可用 | 可用 |
| M0 | 不可用 | 不可用 | 可用 | 不可用 |
适配器外观与关键部件（正面为四类总线接口与指示灯，背面为工作模式拨码开关、USB 电源接口与电平切换开关）：
- 连接器打开后自动按拨码模式识别可用协议，协议与拨码不符会中文报错——例如 Mode1 下绑 JTAG 会被拒。
- 打开后可以用
MODE读回当前生效的模式（0 ～ 3），见第 12 节。 - 板载 5V / 3V3 电平拨动开关必须与被测芯片一致，接错可能损坏芯片。
2. 页面上要填什么
页面分三块：基本信息、测试参数、测试指标。
| 页面位置 | 作用 | 填写要点 |
|---|---|---|
| 指令名称 | 在流程里显示的中文名 | 读用「读取…」，写用「设置…」，例如「读取REG08」 |
| 指令编码 | 本仪器内唯一编号 | 读用 get_…，写用 set_…，例如 get_reg08 |
| 指令模板 | 实际执行的指令内容 | 总线指令以 I2C: / SPI: / UART: / JTAG: / PMBUS: 开头，适配器自身指令以 RATE: / SCAN: / MODE 开头，不要写成指令编码 |
| 指令说明 | 给同事看的备注 | 可写用途，例如「充电状态寄存器」 |
| 测试参数 | 执行时要填的输入 | 只有模板里出现 {{参数编码}} 时才需要 |
| 测试指标 | 读回来的结果 | 读取指令必须有，条数 = 模板解析段数 |
| 解析规则 | 如何得到指标值 | 选「直接取返回值」，换算写在 EXPR 段里；要按十六进制 / 二进制显示，加 FMT 段并把指标类型选「字符串」 |
| 模拟数据 | 离线调试时的假数据 | 可照抄第 9 章速查表中对应指令的模拟值；未给出时可留空 |
三条铁律：
- 模板里出现
{{xxx}}，「测试参数」必须有编码为xxx的参数。 - 读取指令的测试指标条数 = 模板解析段数（协议段与
FMT段不占指标），顺序一一对应。 - I2C 从机地址、UART 串口路径、SPI 片选与 SPI 模式 / 时钟 / 位序、I2C 速率默认值都不在指令页填，由工位绑定（资源）决定。
3. I2C 指令
3.1 模板格式
| 操作 | 模板 |
|---|---|
| 写单寄存器 | I2C:W:<reg>:<data_hex> |
| 连续写 | I2C:WS:<start_reg>:<data_hex> |
| 读单寄存器 | I2C:R:<reg>:<nbytes> |
| 连续读 | I2C:RS:<start_reg>:<nbytes> |
| 指定速率读 / 写 | I2C:RATE:<档>:R:<reg>:<nbytes>（W / WS / RS 同理） |
3.2 从机地址与速率
- 从机地址来自绑定资源（如
ch347::i2c:0x50），工位不单独填写；扫描到的资源列表里就能直接选到地址。 - 资源名里的地址就是协议 7 位地址（也就是手册上印的那个）：手册写 7 位
0x6B，资源里就是0x6B，程序访问时会自己左移 1 位拼成 8 位读 / 写地址——不要再手动左移。 - 速率档：模板
RATE与工位绑定里的rate共用同一套取值。
| 档 | 速率 | 档 | 速率 |
|---|---|---|---|
| 0 | 20 kHz | 4 | 50 kHz |
| 1 | 100 kHz（默认） | 5 | 200 kHz |
| 2 | 400 kHz | 6 | 1 MHz |
| 3 | 750 kHz |
覆盖与生效规则：
- 优先级：模板
RATE→ 适配器覆盖值（RATE:I2C:，见第 12 节）→ 工位绑定rate。只有0～6的整数才采用模板速率；写成9、abc这类无效值时，读写照常进行，改用适配器覆盖值或绑定的rate。绑定rate不填才算「没有」，填0是 20 kHz。 - 模板里的
I2C:RATE:只影响这一次读写，不会改掉后续指令用的速率。 - 工位保存该从机的速率、或下发
RATE:I2C:，都会立刻把新速率下发到适配器，谁后执行谁生效；之后在工位对这台从机再保存一次会清掉覆盖值，回到绑定速率。 - 覆盖值只在内存里：重启后按已保存的绑定速率工作。
旧填法迁移：以前按「8 位写地址」填的地址要改成 7 位。大于
0x7F的偶数旧地址会被自动右移一次；0x7F及以下的旧地址无法自动判断，请在工位上重新选或直接改成手册的 7 位地址。
3.3 读回值长什么样
成功时指标值是按字节空格分隔的大写十六进制串，如 AB CD、17 1A B4 AA 58。指标类型选「字符串」时原样展示；要取数值或位域，用第 7 节的 BIT / EXPR 段，想整体换成十进制或二进制显示则用同节的 FMT 段。
3.4 配置示例：读 REG08（1 字节）
| 项目 | 填写 |
|---|---|
| 指令名称 | 读取REG08 |
| 指令编码 | get_reg08 |
| 指令模板 | I2C:R:0x08:1 |
| 指令说明 | 充电状态寄存器 |
| 指标名称 / 编码 | REG08 / reg08 |
| 指标类型 / 分类 / 单位 | 字符串 / 数字 / / |
| 模拟数据 | 54 |
| 解析规则 | 直接取返回值 |
3.5 配置示例：写寄存器（安全位回写）
| 项目 | 填写 |
|---|---|
| 指令名称 | 写REG0A |
| 指令编码 | set_reg0a |
| 指令模板 | I2C:W:0x0A:{{data}} |
| 指令说明 | 置位/恢复 INT mask |
测试参数（点「添加参数」）：
| 字段 | 填写 |
|---|---|
| 参数名称 | 寄存器值 |
| 参数编码 | data（必须与模板占位符一致） |
| 参数类型 / 分类 | 字符串 / 数字 |
| 参数形式 | 自定义，说明：81 = 置位最低位，80 = 恢复 |
设置指令一般不添加测试指标。
4. SPI 指令
| 操作 | 模板 | 说明 |
|---|---|---|
| 写 | SPI:W:<data_hex> | 只发不收 |
| 读 | SPI:R:<nbytes> | 读操作必须是 R 或 XFER |
| 全双工 | SPI:XFER:<data_hex> | 发多少收多少，MOSI 上就是模板里的字节 |
- 片选
cs取0或1，在工位绑定里选，不写在模板里（同一块板支持 cs0 / cs1 两路）。 - SPI 的模式（
0～3，0= Mode 0：时钟空闲低、上升沿采样）、时钟档（0= 60 MHz、1= 30 MHz、2= 15 MHz、3= 7.5 MHz、4= 3.75 MHz、5= 1.875 MHz、6= 937.5 kHz、7= 468.75 kHz）与位序（msb高位先发 / 低位先发）都在工位绑定里按设备选择，指令页不填；某个字段没选时用平台默认。适配器执行过RATE:SPI:后时钟档用该覆盖值，模式与位序仍按绑定。 - 工位保存
clock/mode/msb、或下发RATE:SPI:，都会立刻把新时钟下发到适配器，谁后执行谁生效；在工位对这台从机再保存一次会清掉RATE:SPI:覆盖。覆盖只在内存，重启后按已保存的绑定初始化。 - 无从机（空总线）时读回
00/FF属正常，不要当读值。
示例：读 JEDEC ID 用 SPI:XFER:0x9F000000（发 1 字节指令 + 3 个 dummy），指标 raw 选「字符串」、模拟值空总线为 FFFFFFFF。
5. UART 指令
| 操作 | 模板 |
|---|---|
| 写（十六进制 / 十进制 / 二进制字节） | UART:W:<data> |
| 写（ASCII 文本） | UART:W:ascii:hello |
| 读固定字节 | UART:R:<nbytes> |
| 读到分隔符 | UART:RUNTIL:<hex_delim>:<timeout_ms> |
- 串口路径来自绑定资源（如
ch347::uart:/dev/ttyACM0），工位不手填。 - 写入数据的写法见第 10 节：按空格或逗号分成单元，每个单元可以是
0x十六进制、0b二进制字节，或无前缀十进制（0 ～ 255）。 - 绑定可选
baud（默认115200）、bytesize/parity/stopbits（CH347 编码，默认 8N1）。适配器执行过RATE:UART:后波特率用该覆盖值，数据位 / 校验 / 停止位不变。 - 示例：
UART:W:ascii:ATE→ 线上发出41 54 45；UART:R:8读 8 字节；UART:RUNTIL:0x0A:200读到0x0A或 200 ms 超时（超时会报「未遇到分隔符」）。
6. JTAG 指令（需 Mode3）
| 操作 | 模板 | 说明 |
|---|---|---|
| 初始化 | JTAG:INIT:<0-5> | 给了档位时优先于适配器 RATE:JTAG: |
| 切 TAP 状态 | JTAG:TAP:<state> | 0 = Test-Logic-Reset，与 IEEE 1149.1 状态编码一致 |
| 送 IR | JTAG:IR:<bitlen>:<hex> | 指令寄存器 |
| 送 / 收 DR | JTAG:DR:<bitlen>:<hex> | 数据寄存器 |
| 读 IDCODE | JTAG:IDCODE | 复位后读 32 位 DR |
不做 OpenOCD / 固件下载。Mode1 / Mode2 下绑定 JTAG 业务码会返回「JTAG 需要 Mode3」。
7. 一条指令解析多个指标
对齐 PMBus 设备配置 第 6 节：一次总线读回，用分号分段解析到多条测试指标。解析段数必须与测试指标（replys）条数严格相等；协议段与 FMT 段本身不占指标（只负责读回原始字节 / 指定显示进制）。
<协议读模板>[;FMT:<10|16|2>];BIT:<hi>[:<lo>][:<编码>=<值>[,...]][;BIT:...][;EXPR:<expression>]| 段 | 含义 | 指标值 |
|---|---|---|
FMT:10 | 十进制（缺省） | 有 BIT / EXPR 时与不写 FMT 相同 |
FMT:16 | 大写十六进制，不带 0x，按位域宽度补到整半字节 | 8 位读值 0x17 显示为 17 |
FMT:2 | 二进制，不带 0b，按位域宽度左侧补零 | D[7:0] 的 0x17 显示为 00010111，D[4:0] 的 23 显示为 10111 |
BIT:<n> | 取第 n 位（LSB = 0） | 0 或 1 |
BIT:<hi>:<lo> | 取闭区间位域 D[hi:lo]，与手册 D[7:5] 写法一致 | 无符号整数 |
BIT:<hi>[:<lo>]:<编码>=<值>[,...] | 取位后按对照表替换；只取一位时，第二段含 = 即视为对照表 | 表中的数值或文字 |
EXPR:<expression> | 以前面各指标 key 为变量的安全表达式 | 计算结果 |
进制显示（FMT）：FMT 一条模板最多一段，可以写在任意解析段的位置；写了之后，没带对照表的指标都用同一种进制，带对照表的指标用表中的值、不再按 FMT 重排。不写就是十进制。写了两段 FMT，或取值不是 10 / 16 / 2，读操作失败。
- 十六进制为大写且不带
0x，二进制不带0b，都按位域宽度补零：BIT:7:0读到0x17时FMT:16得17、FMT:2得00010111；BIT:4:0得23时FMT:2得10111。 - 只写
FMT、没有BIT/EXPR时，FMT直接作用在整段读回字节上：把字节按大端拼成一个整数（宽度 = 字节数 × 8），再按该进制填入每条指标。例如I2C:R:0x00:1;FMT:2读到0x17，指标值是00010111。 FMT:16/FMT:2时，EXPR的计算结果必须是非负整数，否则读操作失败；十进制仍按指标的缩放与小数位显示。- 指标类型：十进制选「数值」；十六进制与二进制请选「字符串」，选「数值」时平台会把
00010111当十进制数，值就不对了。
位编号规则：把读回字节按 先收到的为高字节（大端） 拼成整数后再取位。单字节 I2C:R:0x08:1 的 D[7:0] 与手册一致；多字节如 I2C:R:0x00:2 得到 17 1A 时，BIT:15:8 = 0x17、BIT:7:0 = 0x1A。一次最多 8 字节。
EXPR 运算符与 PMBus 相同：+ - * / % **、括号、一元负号，以及 abs / round / min / max / sqrt。
仪器库填写时：指标类型选「数值」，解析规则选「直接取返回值」——不要再写换算，换算请写在
EXPR里；写了FMT:16/FMT:2的指标类型改选「字符串」。
无 BIT / EXPR 段时行为不变：整段十六进制填入指标（可配多条指标，值相同）；想换成十进制或二进制显示，加一段 FMT 即可。
7.1 示例：读 REG08 状态位
手册 REG08（地址 0x08，只读）：D[7:5] = VBUS_STAT、D[4:3] = CHRG_STAT、D[2] = PG_STAT、D[1] = THERM_STAT、D[0] = VSYS_STAT。
| 项目 | 填写 |
|---|---|
| 指令名称 | 读REG08状态位 |
| 指令编码 | get_reg08_status |
| 指令模板 | I2C:R:0x08:1;BIT:7:5;BIT:4:3;BIT:2;BIT:1;BIT:0 |
| 测试参数 | 不添加 |
测试指标（5 条，顺序与 BIT 段一一对应）：
| 顺序 | 指标名称 | 指标编码 | 指标类型 | 指标分类 |
|---|---|---|---|---|
| 1 | VBUS状态 | vbus_stat | 数值 | 数字 |
| 2 | 充电状态 | chrg_stat | 数值 | 数字 |
| 3 | 输入电源状态 | pg_stat | 数值 | 数字 |
| 4 | 热调节状态 | therm_stat | 数值 | 数字 |
| 5 | 系统电压调节状态 | vsys_stat | 数值 | 数字 |
- 手册举例：读回
0x2C（0010_1100）时vbus_stat=1、chrg_stat=1、pg_stat=1、therm_stat=0、vsys_stat=0。 - 实测：REG08 读回
0x54，对应 VBUS = Adaptor 2.4A、CHRG = Fast charging、PG = 1、THERM = 0、VSYS = 0。
7.2 位域取出后再换算
I2C:R:0x08:1;BIT:7:5;EXPR:vbus_stat*10对应 2 条指标，编码分别为 vbus_stat、scaled。
7.3 示例：按二进制显示整字节
I2C:R:0x08:1;FMT:2 读回 0x54（REG08 = 0101_0100）：
| 项目 | 填写 |
|---|---|
| 指令名称 | 读REG08二进制 |
| 指令编码 | get_reg08_bin |
| 指令模板 | I2C:R:0x08:1;FMT:2 |
| 测试参数 | 不添加 |
| 指标名称 / 编码 | REG08 / reg08 |
| 指标类型 / 解析规则 | 字符串 / 直接取返回值 |
| 预期指标值 | 01010100 |
换成 FMT:16 时同一读值显示为 54（不带 0x 的大写十六进制）。
7.4 示例：位域按二进制铺开
I2C:R:0x08:1;BIT:7:5;FMT:2 读回 0x54（0101_0100）时，D[7:5] 取出 2（010），指标值显示为 010——FMT 对 BIT 位域同样按位域宽度补零。
7.5 示例：位域按十六进制显示
I2C:R:0x00:2;BIT:15:8;BIT:7:0;FMT:16 读回 17 1A 时，两条指标分别显示为 17、1A。
7.6 用对照表把编码翻成数值或文字
有些寄存器编码不是一个算式能算出来的（例如「档位 0 → 0.5 A，档位 1 → 1 A」），这时把对照表写在 BIT 段末尾，仍然只占一条指标：
<协议读模板>;BIT:<hi>[:<lo>]:<编码>=<值>[,<编码>=<值>...]- 程序找到模板里第一个
=，再取它左边最近的冒号：冒号左边是位域，右边是编码=值列表，多项用逗号分开。 - 编码的写法和指令里的标量一致：
0、00、0b00是同一个编码。值里可以带冒号，例如USB:SDP。 - 数值指标：把表中的值当数，再按指标的缩放 / 小数位格式化，并且不再按
FMT重排。有对照表时不要再用缩放去做编码换算。 - 字符串指标：原样写入表中的文字。
- 表里要覆盖实际可能出现的每个编码——编码不在表中、编码重复、表为空、或某项没有
=，读操作都会失败。 - 后面的
EXPR引用这条指标时，数值指标用映射后的数，文字指标用原来的编码。
7.7 示例：电流档位与状态文字
读 REG02 的 D[1:0]，按对照表把档位翻成电流（0 → 0.5 A、1 → 1 A）：
| 项目 | 填写 |
|---|---|
| 指令名称 | 读REG02电流档 |
| 指令编码 | get_ich |
| 指令模板 | I2C:R:0x02:1;BIT:1:0:0=0.5,1=1 |
| 指标名称 / 编码 | ICH / ich |
| 指标类型 / 单位 / 小数位 | 数值 / A / 1 |
读回 0x00 时指标值是 0.5，读回 0x01 时是 1.0——名称与单位来自指标设置，结果不是字符串 ICH=0.5A。
要显示文字，把指标类型选「字符串」：BIT:4:3:0=USB:SDP,1=主机 读到的指标值就是 USB:SDP 或 主机。
8. PMBus 指令
PMBus 器件走 I2C 总线（工位绑定选 I2C 资源，拨码需在 M1 / M2），指令模板以 PMBUS: 开头。它按 PMBus 格式解码，不参与上一节的 BIT 大端拼接；EXPR 规则与 I2C 相同，解析段数同样必须等于测试指标条数。地址取自绑定资源（用它的 8 位写地址）。
读取：
PMBUS:READ:<命令>:<格式>[:<参数>][;<命令>:<格式>[:<参数>]][;EXPR:<expression>]| 格式 | 读取 | 指标值 |
|---|---|---|
LINEAR11 | 2 字节，低字节在前 | 尾数 × 2^指数 |
LINEAR16 | 2 字节无符号尾数 | 尾数 × 2^N，N 取该从机缓存的 VOUT_MODE（0x20） |
LINEAR16:<指数> | 同上 | 指数用模板里的 -16 ～ 15，不去读 0x20 |
BYTE | 1 字节 | 字符串形式 0x16 |
WORD | 2 字节，低字节在前 | 字符串形式 0x0043 |
RAW / RAW:N | 默认 2 字节，N 为 1 ～ 32 | 0x + 连续十六进制，不看长度头 |
BLOCK / BLOCK:N | 默认预读 33 字节，N 为 1 ～ 256 | 按首字节长度裁切，载荷 1 ～ 255 字节 |
FLOAT | 预读 5 字节 | 长度头之后的 4 字节小端单精度；全 0 为 0 |
FLOAT:4 | 4 字节 | 没有长度头的小端单精度 |
VOUT_MODE在该从机第一次使用不带指数的LINEAR16时读取并缓存；这次读失败时指数按 0，读写仍可继续；重新绑定后缓存清空。- 数值指标照常用缩放与小数位；想看原始字节（
BYTE/WORD/RAW/BLOCK）把指标类型选「字符串」。
写入：
PMBUS:WRITE:<命令>
PMBUS:WRITE:<命令>:<值>
PMBUS:WRITE:<命令>:LINEAR11:<物理值>
PMBUS:WRITE:<命令>:BLOCK:<hex>- 省略
<值>时只发命令字（Send Byte）。 0x开头或含A～F的值按十六进制解析、多字节低字节先发；纯十进制值按 2 字节小端编码，范围 0 ～ 65535。LINEAR11把物理值编码后再低字节先发；BLOCK的 hex 是数据区，程序会在前面加 1 字节长度，数据区不能为空、也不能超过 255 字节。
示例：
| 项目 | 填写 |
|---|---|
| 指令名称 | 读输入电压 |
| 指令编码 | get_vin |
| 指令模板 | PMBUS:READ:0x88:LINEAR11 |
| 指标名称 / 编码 | 输入电压 / vin |
| 指标类型 / 单位 / 小数位 | 数值 / V / 3 |
- 输出电压指数固定为 -3 的电源：
PMBUS:READ:0x8B:LINEAR16:-3。 - 器件块读带长度字节用
PMBUS:READ:0xF1:FLOAT；只有 4 字节浮点用PMBUS:READ:0xF1:FLOAT:4。
PMBus 的基础概念与适用范围见 PMBus 设备配置。
9. 全量填写速查
- 同一条命令既能读又能写时，表中拆成两行，分别在「编辑读取指令」「编辑设置指令」页面创建。
- 读取指令：测试指标必填；设置指令：不添加测试指标，写入值用测试参数开放。
- 指令模板请原样复制，不要改写成指令编码。
- 适配器自身的
RATE:/SCAN:/MODE指令不在本节，见第 12 节。
9.1 通用 I2C（照抄建指令）
| 界面 | 指令名称 | 指令编码 | 指令模板 | 测试指标 / 参数 |
|---|---|---|---|---|
| 读取指令 | 读单寄存器 | get_i2c_reg | I2C:R:0x08:1 | data / 寄存器 / 字符串 / / |
| 读取指令 | 二进制读单寄存器 | get_i2c_reg_bin | I2C:R:0x08:1;FMT:2 | reg08 / 寄存器 / 字符串 / / |
| 读取指令 | 连续读多字节 | get_i2c_regs | I2C:RS:0x00:8 | data / 寄存器组 / 字符串 / / |
| 读取指令 | 指定速率读 | get_i2c_reg_fast | I2C:RATE:2:R:0x08:1 | 同上（400 kHz） |
| 读取指令 | 位域查对照表 | get_i2c_code | I2C:R:0x02:1;BIT:1:0:0=0.5,1=1 | code / 档位 / 数值 / / |
| 设置指令 | 写单寄存器 | set_i2c_reg | I2C:W:{{reg}}:{{data}} | reg、data（字符串） |
| 设置指令 | 连续写 | set_i2c_regs | I2C:WS:0x00:{{data}} | data（多字节 hex） |
| 设置指令 | 指定速率写 | set_i2c_reg_rate | I2C:RATE:{{rate}}:W:{{reg}}:{{data}} | rate（0 ～ 6）、reg、data |
9.2 通用 SPI（照抄建指令）
| 界面 | 指令名称 | 指令编码 | 指令模板 | 测试指标 / 参数 |
|---|---|---|---|---|
| 读取指令 | 读 N 字节 | get_spi_read | SPI:R:4 | data / 读数 / 字符串 / / |
| 读取指令 | 全双工收发 | get_spi_xfer | SPI:XFER:0x9F000000 | data / 读数 / 字符串 / / |
| 设置指令 | 写数据 | set_spi_write | SPI:W:{{data}} | data（hex） |
9.3 通用 UART（照抄建指令）
| 界面 | 指令名称 | 指令编码 | 指令模板 | 测试指标 / 参数 |
|---|---|---|---|---|
| 读取指令 | 读固定字节 | get_uart_read | UART:R:8 | data / 读数 / 字符串 / / |
| 读取指令 | 读到分隔符 | get_uart_runtil | UART:RUNTIL:0x0A:200 | data / 一行 / 字符串 / / |
| 设置指令 | 写 ASCII | set_uart_ascii | UART:W:ascii:{{text}} | text（字符串） |
| 设置指令 | 写十六进制 | set_uart_hex | UART:W:{{data}} | data（hex） |
9.4 通用 JTAG（照抄建指令）
| 界面 | 指令名称 | 指令编码 | 指令模板 | 测试指标 / 参数 |
|---|---|---|---|---|
| 读取指令 | 读 IDCODE | get_jtag_idcode | JTAG:IDCODE | idcode / IDCODE / 字符串 / / |
| 设置指令 | 初始化 | set_jtag_init | JTAG:INIT:0 | 无 |
| 设置指令 | 送 IR | set_jtag_ir | JTAG:IR:{{bitlen}}:{{data}} | bitlen、data |
| 设置指令 | 送 DR | set_jtag_dr | JTAG:DR:{{bitlen}}:{{data}} | bitlen、data |
9.5 寄存器读写示例（已实测，I2C）
绑定：Mode1、速率 100 kHz、资源按3.2 节填手册的 7 位从机地址。下表「模拟值」为现场实测一致的读数：
| 界面 | 指令名称 | 指令编码 | 指令模板 | 测试指标（编码 / 类型 / 模拟值） |
|---|---|---|---|---|
| 读取指令 | 读REG00 | get_reg00 | I2C:R:0x00:1 | reg00 / 字符串 / 17 |
| 读取指令 | 读REG01 | get_reg01 | I2C:R:0x01:1 | reg01 / 字符串 / 1A |
| 读取指令 | 读REG02 | get_reg02 | I2C:R:0x02:1 | reg02 / 字符串 / A2 |
| 读取指令 | 读REG03 | get_reg03 | I2C:R:0x03:1 | reg03 / 字符串 / 22 |
| 读取指令 | 读REG04 | get_reg04 | I2C:R:0x04:1 | reg04 / 字符串 / 58 |
| 读取指令 | 读REG05 | get_reg05 | I2C:R:0x05:1 | reg05 / 字符串 / 9F |
| 读取指令 | 读REG06 | get_reg06 | I2C:R:0x06:1 | reg06 / 字符串 / 66 |
| 读取指令 | 读REG07 | get_reg07 | I2C:R:0x07:1 | reg07 / 字符串 / 4C |
| 读取指令 | 读REG08 | get_reg08 | I2C:R:0x08:1 | reg08 / 字符串 / 54 |
| 读取指令 | 读REG08二进制 | get_reg08_bin | I2C:R:0x08:1;FMT:2 | reg08 / 字符串 / 01010100 |
| 读取指令 | 读REG09 | get_reg09 | I2C:R:0x09:1 | reg09 / 字符串 / 80 |
| 读取指令 | 读REG0A | get_reg0a | I2C:R:0x0A:1 | reg0a / 字符串 / 80 |
| 读取指令 | 读REG0B | get_reg0b | I2C:R:0x0B:1 | reg0b / 字符串 / 14 |
| 读取指令 | 读REG08状态位 | get_reg08_status | I2C:R:0x08:1;BIT:7:5;BIT:4:3;BIT:2;BIT:1;BIT:0 | 5 条数值指标（见 7.1 节） |
| 读取指令 | 读REG0B身份位 | get_reg0b_pn | I2C:R:0x0B:1;BIT:3:0 | pn / 数值 / 2（= 0010） |
| 读取指令 | 连续读REG00–0B | get_regs_0_11 | I2C:RS:0x00:12 | regs / 字符串 / 171AA222589F664C54808014 |
| 设置指令 | 写REG0A | set_reg0a | I2C:W:0x0A:{{data}} | 参数 data（81 置位 / 80 恢复） |
读
0x0C及更高地址会统一返回FF，这是该芯片「读超范围返回 0xFF」的行为，可用来验证通路。安全约束：不要为了「看能不能写」而置位
EN_HIZ、BATFET_DIS、REG_RST、OTG_CONFIG、ICHG=0。可做只读 REG00–0B、对照 PORV、读0x0C期望0xFF、安全位（如 REG0A INT mask）翻转后恢复。
9.6 无从机时的期望值（通路自检）
| 协议 | 指令模板 | 空总线期望 |
|---|---|---|
| SPI | SPI:R:4 | 00000000 |
| SPI | SPI:XFER:0x9F000000 | FFFFFFFF |
| UART | UART:R:8 | 0000000000000000 |
| UART | UART:RUNTIL:0x0A:200 | 报「读超时，未遇到分隔符」 |
没有从机时软件回 00 / FF 是正常的，不要当对照值。
9.7 通用 PMBus（照抄建指令）
| 界面 | 指令名称 | 指令编码 | 指令模板 | 测试指标 / 参数 |
|---|---|---|---|---|
| 读取指令 | 读 LINEAR11 | get_pmbus_lin11 | PMBUS:READ:0x88:LINEAR11 | value / 读数 / 数值 / / |
| 读取指令 | 读 LINEAR16 | get_pmbus_lin16 | PMBUS:READ:0x8B:LINEAR16:-3 | value / 读数 / 数值 / / |
| 读取指令 | 读原始字节 | get_pmbus_raw | PMBUS:READ:0xF1:BLOCK | data / 原始字节 / 字符串 / / |
| 设置指令 | 只发命令字 | set_pmbus_cmd | PMBUS:WRITE:0x01 | 无 |
| 设置指令 | 写线性值 | set_pmbus_linear | PMBUS:WRITE:0x21:LINEAR11:{{value}} | value（物理值） |
10. 数值与字节写法
10.1 标量数值
指令里的标量（寄存器地址、读取长度、超时、位长、BIT 位号等）同时支持三种写法：
| 写法 | 示例 | 说明 |
|---|---|---|
0x / 0X 十六进制 | 0x10 | 常见写法 |
| 无前缀十进制 | 16 | |
0b / 0B 二进制 | 0b00010000 | 8 位以内 |
- 三者等价：寄存器
0x10=16=0b00010000。 - 无前缀且含
A–F（如A0）仍按十六进制解析。
10.2 写入数据的字节串
写指令的载荷（I2C:W / I2C:WS / SPI:W / SPI:XFER / UART:W / JTAG:IR / JTAG:DR 的 data）按空格或逗号分成一个个单元，每个单元可以按不同进制写：
| 单元写法 | 例 | 含义 |
|---|---|---|
0x / 0X 十六进制 | 0x17、0x171A | 一个或多个字节，连续写 |
0b / 0B 二进制 | 0b00010001 | 一个字节（超过 8 位会失败） |
| 无前缀十进制 | 23 | 一个字节，范围 0 ～ 255 |
无前缀且含 A ～ F | 1A、171A | 按十六进制字节串 |
- 同一个字节的三种写法对照：
17（无前缀）是十进制 17，实际发出字节0x11；0x17是十六进制，发出0x17；0b00010001也是字节0x11。所以想表达0x17就必须写0x17。 - 大于 255 的纯数字会失败；要写多字节只能靠
0x前缀或含A–F的写法（如0x0102）。 - UART 写另行支持
ascii:文本。
10.3 不走上面这套的地方
- 读回后的
BIT/FMT只按十六进制字节解析：读到的17就是0x17。 UART:RUNTIL的分隔符只按十六进制解析。- I2C 从机地址来自绑定资源，不走这套规则。
11. 填错了怎么办
指令执行失败时，优先看返回的提示信息：
| 现象 / 提示关键词 | 可能原因 | 处理建议 |
|---|---|---|
SPI 读操作必须是 R 或 XFER | 模板写了别的操作码 | 读改用 SPI:R 或 SPI:XFER |
UART 读操作必须是 R 或 RUNTIL | 同上 | 读改用 UART:R 或 UART:RUNTIL |
UART 读超时，未遇到分隔符 | 对端没发数据 / 分隔符不对 / 超时太短 | 核对波特率与接线；加大超时；先用 UART:R:<n> 看原始字节 |
当前为 Mode1（UART1+I2C+SPI），JTAG 需要 Mode3 | 拨码与协议不符 | 拨到 M3 后重新插 USB，再重启连接器 |
I2C 读取失败（addr=0x..） | 从机无应答、地址不对、缺上拉、芯片未上电 | 核对资源里的 7 位从机地址（手册上印的那个，不要再左移）；确认 10 kΩ 上拉与供电；扫总线看有无 ACK |
模板段数与 replys 数量不匹配 | 解析段数与测试指标条数不一致 | 每段一条指标，顺序一一对应 |
FMT 写了两段 / 值不是 10、16、2 | FMT 段不合法 | 一条模板只留一段 FMT，取值只能是 10 / 16 / 2 |
| 二进制 / 十六进制指标显示成十进制数 | 指标类型选成了「数值」 | 这两种进制的指标类型改成「字符串」 |
RATE:I2C: / SCAN:I2C:ON 失败 | 当前拨码模式不支持 I2C | 拨到 M1 / M2 后重新插 USB，再重启连接器；RATE: 失败时原有覆盖值不变 |
MODE 读失败 | 适配器尚未完成打开、模式未确定 | 稍后重读；确认适配器已正常识别 |
| 写进去的字节不是想要的 | 写入值的进制写法不对 | 0x 开头或含 A ～ F 是十六进制；无前缀纯数字是十进制（17 发出 0x11）；二进制加 0b；ascii: 是文本 |
| 多字节写报错 / 提示大于 255 | 多字节写成了纯十进制 | 多字节写成 0x0102 这类带 0x 的形式 |
| 对照表报错（编码不在表中 / 键重复 / 表为空） | BIT 对照表没覆盖实际读到的编码 | 按 BIT:<位>:<编码>=<值>,... 把所有可能的编码补齐 |
PMBUS: 指令报错 | 拨码不在 M1 / M2（没有 I2C），或命令字 / 格式不被从机支持 | 确认拨码与从机手册；先用 BYTE / WORD 读原始字节定位 |
读回全 FF / 全 00 | 空总线（无从机），或从机未上电 | 属正常现象，先确认从机在总线上 |
提示缺少参数 xxx | 模板里有 {{xxx}}，但测试参数没有同名编码 | 补一个编码 xxx 的参数，或删掉模板里的占位符 |
值格式错误 | 写入值的写法不对 | 十六进制用 0x 或空格分隔；无前缀纯数字按十进制；文本加 ascii: 前缀 |
| 指标全是 0 / 值不对 | 位号或位域写错 | 先整字节读确认原始值，再核对 BIT 段 |
| 拨码是 M1 / M3 但 SPI / I2C 全部失败 | 适配器未被平台识别 | 重新插拔 USB 后重试；仍失败请联系技术支持 |
自查顺序（建议）
- 拨码模式与指令协议是否匹配（M1 / M2 才有 I2C + SPI，JTAG 必须 M3）
- 工位绑定的资源是否对（I2C 的 7 位地址、UART 路径、SPI 片选）
- 用最简单的单点读验证通路（
I2C:R:0x00:1、SPI:R:4、UART:W:ascii:ATE） - 空总线时读回
00/FF是正常现象，先接从机或先看波形 - 再上
BIT/EXPR/FMT/ 对照表多指标 - 想临时改速率、关 I2C 扫描，或确认当前拨码模式，用适配器指令（第 12 节）
- 仍失败请记录拨码模式、绑定资源、指令模板与报错原文，联系技术支持
12. 适配器自身的指令
适配器（转接卡）打开后会作为一台独立的在线仪器登记到平台（序列号 CH347、型号 WAVESHARE）。它不出现在工位可绑定的资源列表里，也不能像普通仪器那样被删除或修改；它不接受发给从机的 I2C: / SPI: / UART: / JTAG: / PMBUS: 模板，只认下面这套指令——用来临时改速率、开关 I2C 资源扫描、读回当前拨码模式。
速率覆盖与扫描开关只在本次运行内有效：进程重启后，速率回到工位绑定值，I2C 扫描恢复开启。
| 操作 | 类型 | 指令模板 |
|---|---|---|
| I2C 速率档 0 ～ 6 | 写 | RATE:I2C:<档> |
| SPI 时钟档 0 ～ 7 | 写 | RATE:SPI:<档> |
| UART 波特率 | 写 | RATE:UART:<波特率> |
| JTAG 时钟档 0 ～ 5 | 写 | RATE:JTAG:<档> |
| 关闭 I2C 资源扫描 | 写 | SCAN:I2C:OFF |
| 开启 I2C 资源扫描 | 写 | SCAN:I2C:ON |
| 读取拨码模式 | 读 | MODE |
- 速率覆盖：对某协议下发过
RATE:后，该协议已绑定设备的后续读写都用这个覆盖值（例如RATE:UART:9600把波特率临时改成 9600）。指令模板里的I2C:RATE:优先级更高，仍会盖过覆盖值。当前拨码不支持该协议时对应的RATE指令失败，之前生效的覆盖值保持不变。 - 谁后执行谁生效：工位保存 I2C 速率 / SPI 时钟、或下发
RATE:I2C:/RATE:SPI:，都会立刻把新值下发到适配器；之后在工位对这台仪器再保存一次会清掉对应的覆盖值。 - 扫描开关：
SCAN:I2C:OFF之后，平台资源列表里不再出现ch347::i2c:*，已绑定的 I2C 仪器不受影响；SCAN:I2C:ON会立刻重新扫描一次。当前拨码模式没有 I2C 时，ON会失败。 - 读拨码模式：
MODE的指标值是0、1、2、3，与打开适配器时的拨码一致——0= Mode0（双 UART）、1= Mode1（UART1 + I2C + SPI）、2= Mode2（UART1 + I2C + SPI）、3= Mode3（UART1 + JTAG）。模式尚未确定时读操作失败；对适配器写MODE会失败。
这几条指令同样在仪器指令库里创建：MODE 建在「读取指令」页（1 条指标，类型选「数值」），RATE: / SCAN: 建在「设置指令」页（不添加测试指标；档位用测试参数开放，例如 RATE:I2C:{{rate}}）。
13. 配置流程速览
确认拨码模式（M1=I2C+SPI / M3=JTAG）与电平 5V/3V3
↓
工位绑定：选协议 + 资源（ch347::i2c:0x50 这类 7 位地址 / ch347::spi:cs0 / ch347::uart:/dev/ttyACM0）
↓
编辑读取指令：I2C:R / SPI:R / UART:R / JTAG:IDCODE / PMBUS:READ + 测试指标
或编辑设置指令：I2C:W / SPI:W / UART:W / JTAG:IR|DR / PMBUS:WRITE（+ 测试参数）
↓
一次读回要拆多个量 / 换进制 / 查编码表？
→ `;` 分段 + BIT / EXPR / FMT / 对照表（段数 = 指标数；十进制指标选数值，十六 / 二进制选字符串）
↓
临时改速率 / 关 I2C 扫描 / 读拨码？
→ 对「适配器」这台在线仪器下发 RATE / SCAN / MODE（第 12 节）
↓
读回 FF/00 → 空总线（正常）；值不对 → 查位号 / 地址 / 速率
失败 → 按第 11 章排查（拨码 → 绑定 → 通路 → BIT）