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

15 KiB
Raw Blame History

开入开出板 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:

#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 路光耦继电器整组写、位序纯逻辑拆分