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.
开入开出板 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_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 路光耦继电器整组写、位序纯逻辑拆分 |