The BOM gate claimed to stop BOMs from being stripped, but it only ever inspected files that were already tracked AND already had a BOM. A new file under a BOM-listed directory could be born without one and never be noticed, because the scan never returned it and, even if it had, the "no HEAD version" branch skipped it. Editing a listed file and losing its BOM is a real accident that already happened once; creating one without a BOM was the same accident with no safety net at all. Measured before and after on the same untracked file with no BOM: before: checked 101 files, no drift, exit 0 after: FAIL, names the file, exit 1 The count of 101 was itself the symptom: with one more file present the honest number is 102. The old code was not "silently passing a clean tree", it was not looking. The scan now includes untracked files, and a listed file with no HEAD version must carry a BOM. Files that are tracked without a BOM keep their historical pass so this does not flood existing code with failures; instead the two that were listed but had no BOM were given one so the list means what it says. That exposed a conflict nobody had hit yet. The font file is generated, and the generator rewrites it from scratch on every run, so a hand-added BOM survived until the next regeneration and then vanished. The BOM gate and the generated-fresh gate could not both pass. The generator now puts the BOM back as its last step, idempotently, so the two gates agree and the whole UI directory keeps its uniform encoding. Font content is untouched: everything after the first three bytes is byte-identical. The menu generator gains a real read-only mode. It previously had no options at all and always rewrote its outputs; the arrows it printed were accurate. That made it easy to mistake for a checker, since an unchanged tree produces identical bytes and looks untouched. --check now reports up to date or stale without writing anything, and the registration tables are checked the same way. Default behaviour and output are unchanged. The telemetry page header no longer restates the board's input hardware facts. They live in the IOBOARD README, which is where the board's electrical behaviour belongs; the page keeps only what it alone can say: that the output rows show the shadow register rather than contact feedback, why an invalid sample draws -- instead of 分, and that these twelve rows are not in the point table. One fact, one place. The team rule for experiments now requires the file hash, the located line number, and both runs. A report once cited a line number that did not exist in the final file, which left no way to confirm which version had actually been tested.
开入开出板 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 版本建模。
SH/LD= 低 → 异步并行装载(A..H 八个输入进寄存器),与时钟无关。SH/LD= 高 → 移位模式;每个CLK低到高沿使数据向QH方向移动一位。- 移位方向是 A → B → … → H → QH,即
H离输出最近。第一个时钟沿之前 QH 上已经是H, 第 8 个沿之前才是A。所以 8 次采样的顺序是 H,G,F,E,D,C,B,A,而接口要求A在 LSB。 - 手册明确要求:
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,不要 includeioboard.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」这条不是纸面推导。
- 上电后反复调用
ioboard_di_read(),记下基线 mask(无信号时通常全 0 或全 1,取决于板上端子接法)。 - 按板子的开入端子定义,把第 1 路(对应 A)短接到该板定义的"ON"电平(通常是 IN 与 COM 短接,或加 24 V),依次只改一路。
- 每次改一路,读一次 mask,期望只有对应的 bit 翻转:
- 第 1 路 → bit0 翻转;第 2 路 → bit1;……第 8 路 → bit7。
- 若发现整体错一位(比如第 1 路动 bit1),那不是软件位序问题(位序已被主机侧单测钉死), 而是板上 A..H 与端子的映射顺序与预期不同——查接线图,不要改软件。
没有万用表也能做:用一根杜邦线手动短接 PE3 到 GND/3V3 不能验证通道对应,只能验证数据线通路。 通道对应必须动真实端子。
第 2 步:验证开出极性与逐路动作(万用表 / 耳朵)
先验极性——这一步决定 IOBOARD_DO_LEVEL_ACTIVE 的取值是否正确:
ioboard_init()之后,4 路应全部释放:万用表量出口端子(常开触点)应为断开,继电器无声。- 调
ioboard_do_write(IOBOARD_DO_KO6)(只有第 0 路),期望只有出口 0 的继电器动作("嗒"一声)。- 同时用
ioboard_do_read_level()读引脚电平:第 0 路应为 1(与IOBOARD_DO_LEVEL_ACTIVE = 1U一致)。 - 若继电器不动、引脚电平也变了 → 极性反了,把
IOBOARD_DO_LEVEL_ACTIVE改成0U。 - 若继电器吸合了但初始化后不释放(上电就吸合)→ 同样说明极性反了,立即改宏后重测, 这属于安全问题,不要带着它继续做其它测试。
- 同时用
- 逐路验证 bit1/bit2/bit3 分别对应 TRIP/ERT/CLZ 三路,每次只有一路动作。
- 调
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. 已知限制
- 第二块 74HC165 读不到:两块级联但第二块的数据输出线在板上没接回 MCU,所以只能读 8 路开入。
软件侧适配点:
ioboard.c的ioboard_di_shift()—— 若飞线/改板后要读 16 位, 在那里把循环次数从IOBOARD_DI_COUNT(8)改为 16,并相应调整ioboard_bits.c的组装与IOBOARD_DI_MASK_ALL。不是现在该做的事,记在此处以免将来重复推导。 - 4 路开出分属两个端口(GPIOC×1、GPIOF×3),所以是两次 BSRR 写,两次之间约 10 ns 量级。 每次写内部原子,两次之间只会看到「旧态 → 新态」的跃迁,不会出现目标态以外的组合。 若将来业务要求 4 路严格同一时刻,需要硬件把它们挪到同一端口。
- 极性未经原理图核对:
IOBOARD_DO_LEVEL_ACTIVE = 1U目前只有「用户口径 + 上电初值为 RESET」两条间接依据, 必须按 §5 第 2 步实测确认。 - 硬件无辅助触点回读:
ioboard_do_get()读的是软件影子寄存器(「我上次让它是什么」), 不是「继电器现在真的动没动」。后者只能靠辅助触点或万用表。 - PE2 / PE4 是命名残留:硬件无信号,本驱动不配置、不读取。若 CubeMX 里还留着它们,
那是
IN_D4/IN_E4的旧配置,不影响本驱动。 - 开入位序仅部分验证:8 路开入与板级丝印
DI_A7 条),不再复述。DI_H的对应关系按移位顺序推定, 2026-11-16 已在 C 通道上实测确认(信号接入 C 路 → 屏上只有DI_C显示「合」, 其余 7 路不动),即 A 在 LSB、H 在 MSB 的位序与通道隔离都正确。 其余 7 路尚未逐路验证;若某一路接反,症状是「该路动作时屏上亮的是另一路」。 UI 侧的遥信页Drivers/BSP/UI/ui_page_yx.c文件头已改为引用本节(引第 3、6 - 开入是电平检测,不是通断检测(用户口径,2026-11-16):
本板开入测量的是输入信号有没有 24V 高电平,「导通」本身是测不出来的——
外部信号必须提供 24V,仅仅把回路接通而没有电平,开入不会动作。
板上是反相链路:有 24V 输入 → 光耦导通 → 74HC165 的 A..H 引脚被拉低。
这个反相由
ioboard.h的IOBOARD_DI_LEVEL_ACTIVE(当前0U= 低电平有效)在ioboard_di_read()返回前转换,所以上层看到的 mask 里 1 恒表示「有信号」, 消费者不需要各自记住「0 才是有信号」。 实测依据:IOBOARD_DI_LEVEL_ACTIVE取1U时屏上全灭、取0U时对应那一路亮。
7. 修改记录
| 日期 | 作者 | 变更 |
|---|---|---|
| 2026-11-16 | 王建锋 | 创建:74HC165 装载/移位时序、4 路光耦继电器整组写、位序纯逻辑拆分 |