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 根钩子全通过。
This commit is contained in:
2026-11-16 18:30:31 +08:00
parent d9f8dbfd90
commit fd767d1dcd
35 changed files with 3646 additions and 249 deletions
+58
View File
@@ -0,0 +1,58 @@
#ifndef IOBOARD_BITS_H
#define IOBOARD_BITS_H
/*
* 模块名称:开入开出板的纯逻辑层(位序组装)
* 模块功能:把「74HC165 按手册时序串行读出的 8 个比特」组装成「A 在 LSB」的开入 mask。
* 适用平台:只依赖 <stdint.h>,不 include HAL / CMSIS / FreeRTOS / main.h。
* 主机侧(MSVC)单测直接 include ioboard_bits.c 即可,无需任何桩目录。
* 作者:王建锋
* 创建日期:2026-11-16
* 修改记录:
* 2026-11-16 王建锋 创建:从 ioboard.c 拆出。位序是**静默错误**(错了不报错,只是
* 数据差一位),只能靠主机侧单测钉住——台架上「位序错一位」与
* 「线接错一位」完全同形,无法归因。
*/
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
/* ======================== 常量 ======================== */
/* 开入路数:74HC165 一片 8 位(两块级联,V0.1 只接回一块的数据线,见 README 已知限制) */
#define IOBOARD_DI_COUNT 8
/* 开出路数:4 路光耦驱动继电器 */
#define IOBOARD_DO_COUNT 4
/* 开入 mask 有效位:bit0..bit7 */
#define IOBOARD_DI_MASK_ALL ((uint8_t)((1U << IOBOARD_DI_COUNT) - 1U))
/* 开出 mask 有效位:bit0..bit3(bit4..bit7 无对应硬件) */
#define IOBOARD_DO_MASK_ALL ((uint8_t)((1U << IOBOARD_DO_COUNT) - 1U))
/* ======================== 纯函数 ======================== */
/*
* 函数功能:把 74HC165 串行读出的 8 个比特组装成开入 mask(A 通道落在 bit0)
* 入口参数:bits - 长度为 IOBOARD_DI_COUNT 的数组,bits[i] 为**第 i+1 个时钟沿之前**
* 从 QH(PE3)读到的电平;非 0 即视为高电平(传 0/1 亦可)
* 返回值:8 位开入 mask,bit0 = A 通道 … bit7 = H 通道
* 限定条件:纯函数,无寄存器/无全局状态,任意上下文可调(主机侧可测)
* 函数说明:依据 TI SN74HC165 数据手册(SNx4HC165 Rev.H,第 7.3 节 Functional Modes
* 真值表Shift 行:数据向 QH 方向移动,每个 CLK 低到高沿推出当前最靠前的比特):
* 第一个时钟沿**之前** QH 上已经是 H,第 8 个沿之前是 A。
* 即 reads = [H,G,F,E,D,C,B,A],组装时必须把 reads[0] 放到 bit7、reads[7] 放到 bit0,
* 等价于逐位从 LSB 往里塞:bit(7-i) = reads[i]。
* 算例(README 同款):只有 A 与 H 为 1 → reads=[1,0,0,0,0,0,0,1] → 0x81。
*/
uint8_t ioboard_di_assemble(const uint8_t bits[IOBOARD_DI_COUNT]);
#ifdef __cplusplus
}
#endif
#endif /* IOBOARD_BITS_H */