fd767d1dcd
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 根钩子全通过。
254 lines
15 KiB
Markdown
254 lines
15 KiB
Markdown
# 开入开出板 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 路光耦继电器整组写、位序纯逻辑拆分 |
|