Files
STM32F4-Base/Drivers/BSP/IOBOARD/README.md
T
wandering1 2b466b85f0 feat(ui): add DI/DO status page showing 8 inputs and 4 outputs
New read-only content page under 实时数据 → 开入开出 showing the board's
8 opto inputs (DI_A..DI_H, 合/分) and 4 relay outputs (KO6/TRIP/ERT/CLZ,
吸合/释放) as a 12-row list, 8 rows per page, 2 pages.

Data path reuses the existing de-bounced input poll instead of adding a
second hardware reader:

  defaultTask (50 ms) → ioboard_di_snap_publish() → de-bounced snapshot
    → ioboard_di_snap_lookup()  [new registration channel]
    → ui_data_feed_tick() (uiTask, 200 ms)
    → ui_data_rt_t.dio_di_* / dio_do_*

No new critical sections, no new hardware access on the UI path. Outputs
come from the volatile shadow register (a memory read, no lock).

Semantic honesty, recorded in ui_page_di_do.c and README §6:
  · Output state is the software shadow register (ODR mirror), NOT a
    mechanical contact feedback — this platform has no auxiliary contact
    readback path. ioboard_do_read_level() also reads ODR, so comparing
    the two is tautological.
  · IOBOARD_DO_LEVEL_ACTIVE polarity has not been checked against the
    schematic.
  · Input bit order has not been verified by manual shorting. The
    2026-11-16 run read 0x00 eight times because the operator had no time
    to short each channel — the data path itself was fine.
  · Board-level inputs are deliberately kept out of the 33-point telemetry
    bitmap (IEC 104 point-table semantics); the two have no mapping.

Invalid snapshots render "--", never 合/分 or 吸合/释放: painting "no data"
as "all inputs released" would tell the field the inputs are open when we
simply failed to read them.

Board-verified 2026-11-16: page 1 shows 分 on all 8 inputs, page 2 shows
释放 on all 4 outputs, page footer and paging correct. Input bit order
still pending manual shorting.

Also: regenerate ui_font_cn_12 for 吸/释, add golden references for both
pages, align check_menu_rows.py L2 geometry with the now-4-item submenu,
and register the new source file in both the Keil project and CMake.

Reviewed independently; zero blocking findings.
2026-11-16 21:45:08 +08:00

260 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 开入开出板 BSP(IOBOARD)
**一句话**:这个驱动让板上的 74HC165 移位寄存器能够被读出 8 路开入,让 4 路光耦继电器能够被整组写入;它只做引脚与时序,不做任何业务判断。
---
## 1. 器件与接线
### 1.1 MCU 侧引脚(来源:`STM32F407-Demo.ioc` → `Inc/main.h` → `Src/gpio.c`)
| 功能 | 引脚 | `main.h` 宏 | 模式 | CubeMX 初值 | 速度 |
|---|---|---|---|---|---|
| 74HC165 装载 `SH/LD` | PC2 | `HC165_LD_Pin` | 推挽输出 | **SET**(移位模式) | VERY_HIGH |
| 74HC165 时钟 `CLK` | PC3 | `HC165_CLK_Pin` | 推挽输出 | **RESET**(时钟低) | LOW |
| 74HC165 数据 `QH` | PE3 | `HC165_IN2_Pin` | 输入 | — | — |
| 出口 0(KO6) | PC14 | `KO6_Pin` | 推挽输出 | RESET | LOW |
| 出口 1(TRIP) | PF0 | `TRIP_LED_Pin` | 推挽输出 | RESET | LOW |
| 出口 2(ERT) | PF1 | `ERT_LED_Pin` | 推挽输出 | RESET | LOW |
| 出口 3(CLZ) | PF6 | `CLZ_LED_Pin` | 推挽输出 | RESET | LOW |
PE2(旧名 `IN_D4`)与 PE4(旧名 `IN_E4`)是命名残留,**硬件上没有对应信号**,本驱动完全不碰。
> ⚠ **改动引脚只能走 CubeMX**(改 `.ioc` 后重生成)。`Src/gpio.c` 是生成文件,手改会在下次重生成时被覆盖。
> 引脚换脚/换端口时,软件侧唯一要动的地方是 `ioboard.c` 顶部的「引脚绑定」区;`ioboard.h` 不用动。
### 1.2 74HC165 侧接法
- 两块 74HC165 **级联**,共用 `CLK`(PC3)与 `SH/LD`(PC2)。
- **但只有一块芯片的 QH 回到了 MCU**(PE3)。第二块的 QH → 第一块的 SER 链路或引出线在板上缺失,
所以本驱动把一次 8 拍读到的数据当作**一块芯片的 8 位开入**(A..H 通道)。
- 这就是「已知限制」第一条的来源,见 §5。
---
## 2. 时序原理与数据手册依据
### 2.1 四条从数据手册直接得到的事实
出处:TI **SNx4HC165 Rev.H**(`SN74HC165` / `SN54HC165`)第 7 节 Detailed Description 与 7.3 节 Functional Modes 真值表;
ST **M74HC165** 与 Nexperia **74HC165** 的功能表与之相同。本驱动按 TI 版本建模。
1. `SH/LD` = **低** → 异步并行装载(A..H 八个输入进寄存器),与时钟无关。
2. `SH/LD` = **高** → 移位模式;每个 `CLK` **低到高沿**使数据向 `QH` 方向移动一位。
3. 移位方向是 **A → B → … → H → QH**,即 `H` 离输出最近。**第一个时钟沿之前** QH 上已经是 `H`,
第 8 个沿之前才是 `A`。所以 8 次采样的顺序是 **H,G,F,E,D,C,B,A**,而接口要求 `A` 在 LSB。
4. 手册明确要求:`CLK` 与 `CLK INH` 在 `SH/LD` 由低升高**之前**必须已经是低电平
(原文:"...CLK and CLK INH should be LOW before the LOW-to-HIGH transition of SH/LD to prevent shifting the data when SH/LD goes HIGH.")。
违反它的症状不是报错,而是整串数据**偏一位**。
### 2.2 为什么是这个顺序
```
CLK ‾‾|____|‾‾‾‾|____|‾‾‾‾|____|‾‾‾‾|____|‾‾‾‾ ... 共 8 个上升沿
LD ‾‾‾‾‾‾‾\________________________/‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
QH ======X= 装载后先是 H ====== 上升沿后 G ==== F ==== ... ==== A
↑采样点(每次上升沿之前读)
```
- **先让 CLK 低**:满足上面第 4 条。代码里这一步由 `ioboard_check_idle()` 保证,并在时序函数里再显式写一次,
使「CLK 低」与「LD 拉低」在代码顺序上紧邻。
- **LD 拉低 → 短暂延时 → LD 拉高**:装载是异步的,延时只为满足最小脉宽 `tw(SH/LD low)`。
- **每次先读 QH,再打上升沿**:手册时序图里数据在上升沿**之前**已稳定;上升沿后 QH 要过一个 `tpd` 才变成新值。
若改成「先打沿再读」,第 8 个沿之后读到的会是 `SER` 端的内容而不是 `A`——这是最经典的「多读一位」错误。
### 2.3 延时取值与出处(`ioboard.h` 的 `IOBOARD_HC165_*_US`)
| 宏 | 取值 | 手册原值(最慢列:VCC 2 V / −40…85 °C) | 余量 |
|---|---|---|---|
| `IOBOARD_HC165_LOAD_PULSE_US` | 1 µs | `tw(SH/LD low)` 120 ns | 8× |
| `IOBOARD_HC165_LOAD_SETTLE_US` | 1 µs | `tpd(SH/LD → QH)` 225 ns | 4× |
| `IOBOARD_HC165_CLK_PHASE_US` | 1 µs | `tw(CLK high or low)` 120 ns | 8× |
| `IOBOARD_HC165_QH_SETTLE_US` | 1 µs | `tpd(CLK → QH)` 225 ns | 4× |
**按最慢电压/温度列取值**,所以换 VCC 或温区都不必重算。
一次完整读取的上界 `IOBOARD_DI_READ_MAX_US` = 1 + 1 + 8×(1+1+1) = **26 µs**。
#### 关于 `HC165_CLK` 的速度是 LOW(≈2 MHz 上限)
**这不是缺陷,也不需要改**。SPEED_FREQ_LOW 在 3.3 V / ~50 pF 负载下的边沿约 500 ns 量级,
驱动每一位的实际周期是 2 µs 以上(上升 1 µs + 下降 1 µs),带宽利用率不到 25%,边沿永远不会成为瓶颈。
若将来确实需要提速:**去 CubeMX 把 PC3 改成 MEDIUM/HIGH 再重生成**,不要改 `Src/gpio.c`;
然后重算上表四个宏,并复核 26 µs 这个上界仍满足调用方的节拍。
---
## 3. 位序算例(人工核对依据)
设只有 **A 与 H** 两路有信号,其余 6 路无信号:
- 第 1 次采样读到 **H = 1**,第 2..7 次读到 G..B = 0,第 8 次读到 **A = 1**;
- 于是读取序列 `bits = [1,0,0,0,0,0,0,1]`;
- 组装规则 `bit(7-i) = bits[i]`:`bits[0]`(H)→ bit7,`bits[7]`(A)→ bit0;
- 结果 **`mask = 0x81`**(bit7 与 bit0 为 1)。
另一条**非对称**算例(对称图样不含位序信息,不能用):
- `bits = [1,0,1,0,1,0,1,0]` → 为 1 的是第 1/3/5/7 次采样 = **H, F, D, B** → 落在 bit7/5/3/1 → **`0xAA`**;
- 其反序 `[0,1,0,1,0,1,0,1]` → **G, E, C, A** → 落在 bit6/4/2/0 → **`0x55`**。
> 历史教训:这组输入在评审中先后被算成 `0xA5`、`0x5A`、`0xAA`。
> 正确值是 `0xAA`;`0xA5`/`0x5A` **不是任何实现的输出**,引用前请手推。
> (顺带:`[1,0,1,0,1,0,1,0]` 是回文图样,反序不变,所以它**根本不含位序信息**——正因如此才要配上 0x55 那一条成对断言。)
---
## 4. 软件结构
### 4.1 分层
```
业务层(defaultTask / 未来 104 / UI) ← 判据、去抖、互锁,全在这里
│ 只看 ioboard.h 的 4 个函数 + 位宏
▼
ioboard.c ← 引脚 + 时序 + 极性转换 + 影子寄存器(唯一 include HAL/FreeRTOS 的文件)
│ 只调 ioboard_di_assemble()
▼
ioboard_bits.c ← 纯逻辑:位序组装。只依赖 <stdint.h>,主机侧可单测
```
**为什么位序要单独成文件**:位序错一位不会报错,只表现为「开入状态差一位」——
在台架上这与「线接错一位」完全同形,无法归因。把它剥离成纯函数,主机侧用假数据一条条钉住;
台架上剩下的就只可能是物理层问题。
### 4.2 接口
| 函数 | 一句话职责 | mask 语义 |
|---|---|---|
| `ioboard_init()` | 清影子、自检引脚模式、确认静止态、4 路全释放 | — |
| `ioboard_di_read(uint8_t *out_mask)` | 一次完整装载 + 8 拍移位;任意上下文 | **bit0 = A … bit7 = H** |
| `ioboard_di_read_from_isr(uint8_t *out_mask)` | 同上,强制 FROM_ISR 临界区 | 同上 |
| `ioboard_do_write(uint8_t mask)` | 整组原子写 4 路开出 | **bit0..bit3,1 = 吸合**;bit4..bit7 忽略 |
| `ioboard_do_get(uint8_t *out_mask)` | 读软件影子寄存器(上次写入值) | 同上 |
| `ioboard_do_read_level(uint8_t *out_level)` | 读 4 路引脚**实际输出电平**(调试用) | **bit n = 1 表示引脚高电平**,与吸合语义无关 |
- `ioboard_init()` **不调用 `HAL_GPIO_Init`**:引脚模式/速度/上下拉由 `MX_GPIO_Init()` 唯一负责。
在这里再初始化一遍只会让 CubeMX 显示的引脚状态与真相脱节,下次重生成还会被覆盖。
- 读失败时**不写** `*out_mask`——「读失败」与「读到全 0」必须可区分,判断权留给上层。
上层不能把失败当成「全 0」上报(否则故障会被伪装成「信号消失」)。
- `ioboard_di_read` 自动判别任务/ISR 上下文(读 `SCB->ICSR.VECTACTIVE`)。
调度器尚未启动时(初始化阶段)自动改用 `__disable_irq()`,因为 `taskENTER_CRITICAL()`
在 `taskSCHEDULER_NOT_STARTED` 时是空操作。
### 4.3 极性:唯一可改点
`ioboard.h`:
```c
#define IOBOARD_DO_LEVEL_ACTIVE (1U) /* 1 = 高电平吸合;若硬件实测相反改成 0U */
#define IOBOARD_DO_LEVEL_RELEASE ((IOBOARD_DO_LEVEL_ACTIVE) ? 0U : 1U)
```
**改极性只改 `IOBOARD_DO_LEVEL_ACTIVE` 这一行**:调用方永远只说「哪一路吸合」,
从不手写 HIGH/LOW;`ioboard_init()` 的「上电全释放」读的也是这个宏,所以不需要另改初始化。
当前取值依据:用户口径「高电平 = 继电器吸合」。若原理图显示相反,改这一行即可。
⚠ 这个取值**尚未经原理图核对、也尚未上板验证**,见 §5 第一条。
### 4.4 构建注册
- **`ioboard_bits.c` 与 `ioboard.c` 必须一起进构建**:前者提供 `ioboard_di_assemble()` 的定义,
后者调用它;缺任何一半都会链接失败(undefined symbol)。
- Keil 工程:`MDK-ARM/STM32F407-Demo.uvprojx` 的 `Drivers/BSP` 组已注册两个文件,
`IncludePath` 已加 `../Drivers/BSP/IOBOARD`。
- 模拟器端**不编驱动**:`simulator/CMakeLists.txt` 不加,理由与本仓既有硬件驱动(`CH395F` / `TPAFE5160` / `RS485`)一致——
它们已在 `scripts/check_registration.py` 的 `SIM_EXEMPT` 名单里逐个点名「模拟器无对应」。
本驱动的纯逻辑部分由 `test/host/ioboard` 的主机侧单测直接编译覆盖,所以不进模拟器不形成覆盖空窗。
- 只想要纯逻辑时(主机侧单测、上层去抖模块):**只 include `ioboard_bits.h`**,不要 include `ioboard.h`
——后者会拉进 `bsp_err.h`,而且不提供任何纯函数。
---
## 5. 上板验证步骤
### 第 0 步:先看驱动自己报什么
上电后立刻调用一次 `ioboard_init()`,**检查返回值**:
| 返回值 | 含义 | 先查什么 |
|---|---|---|
| `BSP_OK` | 引脚模式正确、静止态确认通过 | 继续第 1 步 |
| `BSP_ERR_STATE` | PC2/PC3/PE3 模式不对,或 DWT 不可用,或主频换算不符,或引脚电平与期望不符 | 用调试器读 `GPIOC->MODER` / `GPIOE->MODER`,确认 PC2=01、PC3=01、PE3=00;读 `DWT->CTRL` 确认 CYCCNTENA=1 |
### 第 1 步:验证开入逐路对应关系(不需要示波器)
目标:确认「bit0 = A」这条不是纸面推导。
1. 上电后反复调用 `ioboard_di_read()`,记下基线 mask(无信号时通常全 0 或全 1,取决于板上端子接法)。
2. 按板子的开入端子定义,把**第 1 路**(对应 A)短接到该板定义的"ON"电平(通常是 IN 与 COM 短接,或加 24 V),依次只改一路。
3. 每次改一路,读一次 mask,**期望只有对应的 bit 翻转**:
- 第 1 路 → bit0 翻转;第 2 路 → bit1;……第 8 路 → **bit7**。
4. 若发现**整体错一位**(比如第 1 路动 bit1),那不是软件位序问题(位序已被主机侧单测钉死),
而是板上 A..H 与端子的映射顺序与预期不同——查接线图,不要改软件。
> 没有万用表也能做:用一根杜邦线手动短接 PE3 到 GND/3V3 不能验证通道对应,只能验证数据线通路。
> 通道对应必须动真实端子。
### 第 2 步:验证开出极性与逐路动作(万用表 / 耳朵)
**先验极性**——这一步决定 `IOBOARD_DO_LEVEL_ACTIVE` 的取值是否正确:
1. `ioboard_init()` 之后,4 路应**全部释放**:万用表量出口端子(常开触点)应为断开,继电器无声。
2. 调 `ioboard_do_write(IOBOARD_DO_KO6)`(只有第 0 路),期望**只有出口 0 的继电器动作**("嗒"一声)。
- 同时用 `ioboard_do_read_level()` 读引脚电平:第 0 路应为 **1**(与 `IOBOARD_DO_LEVEL_ACTIVE = 1U` 一致)。
- 若**继电器不动**、引脚电平也变了 → 极性反了,把 `IOBOARD_DO_LEVEL_ACTIVE` 改成 `0U`。
- 若**继电器吸合了但初始化后不释放**(上电就吸合)→ 同样说明极性反了,**立即改宏后重测**,
这属于安全问题,不要带着它继续做其它测试。
3. 逐路验证 bit1/bit2/bit3 分别对应 TRIP/ERT/CLZ 三路,**每次只有一路动作**。
4. 调 `ioboard_do_write(0x0F)` 四路全吸合,再 `ioboard_do_write(0x00)` 全释放。
用 `ioboard_do_get()` 回读影子寄存器,应为刚写入的值;与 `ioboard_do_read_level()` 对照,
若两者不一致 = 有人在驱动之外写了这 4 根引脚的 ODR。
### 第 3 步:有示波器时看时序
把探头接 **PC2(LD)** 与 **PC3(CLK)**,触发在 LD 下降沿。期望看到:
- LD 先为高;出现一个**低脉冲**(宽 1 µs 量级),随后回到高并保持;
- LD 回到高之后,CLK 才开始**第一组 8 个脉冲**,每个高、低各 1 µs 量级;
- **LD 由低升高的那一刻,CLK 必须是低电平**(这是 §2.1 第 4 条),放大看 LD 上升沿处 CLK 应为 0;
- 整段从 LD 下降沿到第 8 个 CLK 下降沿约 26 µs。
同时把第三个探头接 **PE3(QH)**:第一个 CLK 上升沿之前 QH 上应是第 8 路(H)的电平;
每个上升沿之后约 30~225 ns 内 QH 翻转。
> ⚠ 本驱动在读取全过程持有 FreeRTOS 临界区(关 `configMAX_SYSCALL_INTERRUPT_PRIORITY` 以下中断),
> 所以示波器上会看到这段时序**连续、无中断插入**——这正是设计意图。若看到中间被插入了一段
> 别的波形,说明有人在临界区里做了长操作,去查那个地方。
---
## 6. 已知限制
1. **第二块 74HC165 读不到**:两块级联但第二块的数据输出线在板上没接回 MCU,所以只能读 8 路开入。
软件侧适配点:`ioboard.c` 的 `ioboard_di_shift()` —— 若飞线/改板后要读 16 位,
在那里把循环次数从 `IOBOARD_DI_COUNT`(8)改为 16,并相应调整 `ioboard_bits.c` 的组装与
`IOBOARD_DI_MASK_ALL`。**不是现在该做的事**,记在此处以免将来重复推导。
2. **4 路开出分属两个端口**(GPIOC×1、GPIOF×3),所以是**两次** BSRR 写,两次之间约 10 ns 量级。
每次写内部原子,两次之间只会看到「旧态 → 新态」的跃迁,不会出现目标态以外的组合。
若将来业务要求 4 路**严格同一时刻**,需要硬件把它们挪到同一端口。
3. **极性未经原理图核对**:`IOBOARD_DO_LEVEL_ACTIVE = 1U` 目前只有「用户口径 + 上电初值为 RESET」两条间接依据,
必须按 §5 第 2 步实测确认。
4. **硬件无辅助触点回读**:`ioboard_do_get()` 读的是**软件影子寄存器**(「我上次让它是什么」),
不是「继电器现在真的动没动」。后者只能靠辅助触点或万用表。
5. **PE2 / PE4 是命名残留**:硬件无信号,本驱动不配置、不读取。若 CubeMX 里还留着它们,
那是 `IN_D4` / `IN_E4` 的旧配置,不影响本驱动。
6. **开入位序未经人工验证**:8 路开入与板级丝印 `DI_A`~`DI_H` 的对应关系目前只是
**按移位顺序推定**,没有现场逐路短接核对过。2026-11-16 那一轮读过 8 次、`ok_reads` 全部正常、
但 `read` 恒为 `0x00`——原因是操作员来不及逐路短接,不是驱动故障:数据线通路本身是好的。
判定标准见 §5 第 1 步(短接某一路应读到对应位的 `0x01`/`0x80`)。
**在完成这一步之前,任何"第 n 路开入处于什么状态"的结论都只能算推定。**
UI 侧的状态页 `ui_page_di_do.c` 在文件头注释里做了同样的声明。
---
## 7. 修改记录
| 日期 | 作者 | 变更 |
|---|---|---|
| 2026-11-16 | 王建锋 | 创建:74HC165 装载/移位时序、4 路光耦继电器整组写、位序纯逻辑拆分 |