Files
STM32F4-Base/Drivers/BSP/IOBOARD/README.md
T
wandering1 fd767d1dcd feat(ioboard): 开入开出板驱动、去抖快照与主机侧单测接入
74HC165 开入 + 光耦继电器开出的完整硬件抽象层,接进 defaultTask
的 50ms 节拍。开入 8 路(第二块 165 数据线板上未接,故只有 8 位),
开出 4 路(高电平吸合)。

驱动 BSP drivers:
- IOBOARD/ioboard.c 装载与移位时序,每步注明数据手册依据;
  SH/LD 拉高前先拉低 CLK,否则装载瞬间多移一位;
  单次读取上界 26us(延时按最慢列 VCC 2V 全温区取值)。
- IOBOARD/ioboard_bits.c 位序组装纯函数,只依赖 stdint.h,
  主机侧可直接 include 做单测:读 8 次为 H,G,F,E,D,C,B,A,
  A 放 bit0(bit(7-i) = reads[i])。
- 极性集中在 IOBOARD_DO_LEVEL_ACTIVE 一处,接口语义统一为
  mask 的 1 = 吸合。

业务接线:
- App/util/ioboard_di.c 通道去抖与双区快照,纯逻辑;
  刻意不 include ioboard.h(其引脚宏会牵入 main.h),
  两处路数常量由测试的编译期静态断言钉住。
- default_task.c 的 default_task_di_poll():读失败不喂去抖、
  不写发布值,只把上一有效值加 valid=0 发布出去,
  避免"全 0"被现场读成开入全部复归。
- 去抖实际粒度 50ms(每个轮询周期喂一拍),最坏上报约 100ms;
  想要真 20ms 需另建定时器,本次不做。
- Src/main.c 在 app_main_init 之前调 ioboard_init(),
  上电即把 4 路出口钉在全释放并确认 165 静止态。

测试:
- test/host/ioboard/ 100 条断言。位序主判据为单比特两端
  (只有 A 得 0x01、只有 H 得 0x80)加八点双射穷举;
  混合图样降级为辅助,因该图样曾先后被算成 0xA5、0x5A、0xAA。
- 去抖覆盖 20ms 边界、抖动不翻、跨 49.7 天回绕。
- 失败语义覆盖"失败保留上次有效值"与"失败窗口内的真实变位不丢"。

文档:
- 新增 docs/硬件平台/开入开出实施说明.md。
- 硬件规格与能力边界 §5 的能力边界现状改写:出口继电器与
  开入回路已具备、业务层未接入;4 路开出只可台架验证,
  不得用于真实跳闸。
- 修正 docs/文档规范.md §3.1:原文要求所有互链用仓库根相对,
  与 check_doc_links.py 的实际解析基准矛盾(markdown 链接按
  当前文档目录解析,反引号路径才按仓库根)。改为区分两类,
  并补 §3.1b 写明对应校验器。
- 清理 docs/任务规划/登记簿.md 改名为硬件改版登记.md 后
  遗留的 9 处旧名引用。

门禁: keil-build 0 Error 0 Warning;主机侧单测 ioboard 100/100、
sb_proto 45/45;pre-commit 48 根钩子全通过。
2026-11-16 18:30:31 +08:00

254 lines
15 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` 的旧配置,不影响本驱动。
---
## 7. 修改记录
| 日期 | 作者 | 变更 |
|---|---|---|
| 2026-11-16 | 王建锋 | 创建:74HC165 装载/移位时序、4 路光耦继电器整组写、位序纯逻辑拆分 |