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 根钩子全通过。
181 lines
9.5 KiB
C
181 lines
9.5 KiB
C
/*
|
||
* 模块名称:开入(DI)去抖与快照——纯逻辑层
|
||
* 模块功能:把「每拍读一次 8 路开入」拆成两个与硬件无关的部件——
|
||
* ① 通道去抖:每个通道独立计时,电平连续稳定满 DI_DEBOUNCE_WINDOW_MS 才翻转;
|
||
* ② 双区快照:消费者拿到的 mask 与 seq 永远来自同一份已稳定的副本。
|
||
* 读引脚在 App/util/ioboard_di.c 的 .c 部分(本 .c 就是那一半,属于同一模块的
|
||
* 可测部分);本头文件**不 include** HAL / FreeRTOS / ioboard.h / main.h,
|
||
* 可被主机侧 MSVC 单测直接编译。
|
||
*
|
||
* 为什么去抖不放进 ioboard.c:BSP 只回答"让硬件动起来并如实汇报",去抖与
|
||
* 失败语义是上报层的事;而且 ioboard.c 依赖 HAL/FreeRTOS,主机侧编不过。
|
||
* 为什么不做成通用 di_debounce 工具:去抖的具体语义(20 ms、8 路、失败拍
|
||
* 推时间戳)是开入业务的一部分,抽成泛化工具会造出第二个真相源。
|
||
* 适用平台:任何 C99(ARMCC v5 / MSVC / GCC);仅 <stdint.h>。
|
||
* 作者:王建锋
|
||
* 创建日期:2026-11-16
|
||
* 修改记录:
|
||
* 2026-11-16 王建锋 创建
|
||
*
|
||
* 失败语义(本模块最重要的一条,单测与调用方都依赖它):
|
||
* 本项目铁律是「读失败不得把开入当全 0 上报」。本模块的落点有三处:
|
||
* · 快照 mask **只**由成功读更新:失败拍喂进去的是"上一有效值",绝不自行产生 0;
|
||
* · 但失败拍**照样推进**去抖计时并更新候选值——否则一次跨过整段失败窗口的真实
|
||
* 变位会被永久吞掉,104/UI 上看到的仍是旧值且无痕迹;
|
||
* · 有效性下降沿 / 恢复沿各记一次(fail_edges / valid),由调用方决定是否留痕;
|
||
* 本模块本身不碰文件系统、不依赖 CMSIS,所以能在 PC 上跑。
|
||
*/
|
||
|
||
#ifndef IOBOARD_DI_H
|
||
#define IOBOARD_DI_H
|
||
|
||
#include <stdint.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* ======================== 常量 ======================== */
|
||
|
||
/* 去抖窗口(ms):某通道电平须连续稳定这么久,快照才允许翻转。
|
||
* 取 20 ms:现场开关与继电器辅助触点抖动在 5~10 ms 量级,20 ms 是常见两倍余量;
|
||
* 且 20 ms < defaultTask 的 50 ms 基准拍(最快两拍后翻转)、
|
||
* 远小于 100 ms 喂狗判定,不影响任何既有节拍。 */
|
||
#define IOBOARD_DI_DEBOUNCE_MS 20u
|
||
|
||
/* 开入路数。**刻意不复用 IOBOARD_DI_COUNT**:IOBOARD 头里的 HC165 引脚宏会展开成
|
||
* main.h 的符号,一旦被 .c 真正使用就把 MCU 头拉进本纯逻辑单元,主机侧编不过。
|
||
* 两者的一致性由主机侧测试在编译期静态断言(test/host/ioboard/ioboard_test.c)。 */
|
||
#define IOBOARD_DI_CH_NUM 8u
|
||
|
||
/* 读失败累计上界:到顶后不再增加,防止长时间断线把 int32 计数绕成负数,
|
||
* 让"一直失败"看起来像"从未失败" */
|
||
#define IOBOARD_DI_FAIL_COUNT_CAP 0x7FFFFFFFL
|
||
|
||
/* 读侧重试上限:写者一次发布是十几条指令,正常第二遍必一致;
|
||
* 20 次仍不一致 = 被持续抢占,返回 0 让调用方本次不用这个值 */
|
||
#define IOBOARD_DI_SNAP_RETRY 20u
|
||
|
||
/* ======================== 通道去抖 ======================== */
|
||
|
||
/*
|
||
* 单通道去抖状态。结构体公开是为了让调用方放进静态存储(本仓禁用 C 库堆分配)。
|
||
* 字段语义(一律走下面的函数读改写,别直接写):
|
||
* t_ms - raw 最近一次变化的时刻
|
||
* raw - 最近一拍读到的电平(0/1)
|
||
* stable - 已确认稳定的电平(就是快照里那一位)
|
||
* started - 是否已收到第一拍(0 = 尚未确立)
|
||
*/
|
||
typedef struct {
|
||
uint32_t t_ms;
|
||
uint8_t raw;
|
||
uint8_t stable;
|
||
uint8_t started;
|
||
} ioboard_di_ch_t;
|
||
|
||
/*
|
||
* 函数功能:把一组通道复位成"下一拍即整组确立"
|
||
* 入口参数:ch - 通道数组
|
||
* n - 数组长度(可小于 IOBOARD_DI_CH_NUM,便于单测只用一个通道)
|
||
* now_ms - 复位时刻(沿用调用方时间基准,通常是 HAL_GetTick)
|
||
* 返回值:无
|
||
* 限定条件:任意上下文;纯内存写,不加锁
|
||
* 函数说明:复位后**第一拍**无论读到什么都整组确立——这是 run 期"重新武装"语义:
|
||
* 调用方先让快照失效、再复位,下一拍重新建立基准,不必区分设备是上电起来
|
||
* 还是从故障恢复起来。
|
||
*/
|
||
void ioboard_di_ch_reset(ioboard_di_ch_t *ch, uint8_t n, uint32_t now_ms);
|
||
|
||
/*
|
||
* 函数功能:喂一拍采样给单个通道
|
||
* 入口参数:c - 通道状态(已复位或已初始化)
|
||
* level - 本拍电平(非 0 即 1;传更宽的值也安全)
|
||
* now_ms - 本拍时刻(ms,任意起点、允许 32 位回绕)
|
||
* window_ms - 去抖窗口(ms;0 = 不滤波,下一拍立即跟随)
|
||
* 返回值:1 = 稳定电平在本拍翻转;0 = 未翻转
|
||
* 限定条件:相邻两拍间隔须 < 2^32 ms(49 天)——本项目 50 ms 节拍天然满足
|
||
* 函数说明:
|
||
* 一、首个样本直接确立(否则上电后要空等一个窗口才有开入值)。
|
||
* 二、raw 变化 → 记新 raw 与时刻、计时重开始(抖动不断推迟翻转,这就是去抖)。
|
||
* 三、raw 未变、已稳定、且 (now - t_ms) **>=** window → stable 跟随 raw。
|
||
* 用无符号减法而不是 `now >= t + window`:后者在 tick 回绕附近会错误地
|
||
* "永久成立"或"永久不成立"(单测"回绕"一条扫这个窗口)。边界取 >=:满 20 ms 即翻。
|
||
*/
|
||
uint8_t ioboard_di_ch_feed(ioboard_di_ch_t *c, uint8_t level, uint32_t now_ms,
|
||
uint32_t window_ms);
|
||
|
||
/* ======================== 双区快照 ======================== */
|
||
|
||
/*
|
||
* 快照。**单写者**(run 期 = defaultTask;同一时刻只有一个写者),**多读者**
|
||
* (任意上下文、无锁)。读者按"序号偶数且前后一致"取一致值;写者按"奇-写-偶"发布。
|
||
*/
|
||
typedef struct {
|
||
volatile uint32_t seq; /* 偶数 = 稳定;奇数 = 正在写 */
|
||
volatile uint8_t mask; /* 去抖后的 8 路开入(bit0 = A … bit7 = H) */
|
||
volatile uint8_t valid; /* 1 = 至少成功读过一次、且当前不在失败态 */
|
||
volatile int32_t fail_count; /* **连续**读失败拍数(成功一拍即归零;饱和于 CAP) */
|
||
volatile uint32_t fail_edges; /* 有效 → 失效 的下降沿次数(= 故障次数) */
|
||
volatile uint32_t change_seq; /* 去抖后 mask 翻转次数 */
|
||
} ioboard_di_snapshot_t;
|
||
|
||
/*
|
||
* 函数功能:写者发布一拍
|
||
* 入口参数:s - 快照对象
|
||
* mask - 本拍去抖结果(读失败时**必须**传上一有效值)
|
||
* valid - 本拍之后是否有效(0/1)
|
||
* is_fail - 本拍是否读失败(0 = 失败;非 0 = 成功)
|
||
* 返回值:去抖后 mask 相对上一拍是否翻转(1 = 翻转,change_seq 已加一)
|
||
* 限定条件:单写者;不加锁;可在临界区内调用
|
||
* 函数说明:第一次发布(change_seq == 0)也返回 1,让上位机区分"还没有任何值"与
|
||
* "已建立基线"。本函数**从不自行生成 0**:mask 就是调用方传进来的值,
|
||
* 失败拍传的是上一有效值——这就是"失败不当全 0"的落点。
|
||
*/
|
||
uint8_t ioboard_di_snap_publish(ioboard_di_snapshot_t *s, uint8_t mask, uint8_t valid,
|
||
uint8_t is_fail);
|
||
|
||
/*
|
||
* 函数功能:读者取一致的一组值
|
||
* 入口参数:s - 快照对象
|
||
* out_mask - 输出,去抖后开入(可为 NULL)
|
||
* out_seq - 输出,change_seq(可为 NULL)
|
||
* 返回值:1 = 读到一致且有效的快照;0 = 快照尚无效 / 读取期间持续被打断
|
||
* 限定条件:任意上下文、无锁、不阻塞
|
||
* 函数说明:返回 0 时 out_mask 仍被写为"最近一次发布值",但**不得**当新数据用——
|
||
* 消费者按"本次无新数据"处理(保留自己上一次保存的值)。
|
||
*/
|
||
uint8_t ioboard_di_snap_read(const ioboard_di_snapshot_t *s, uint8_t *out_mask,
|
||
uint32_t *out_seq);
|
||
|
||
/*
|
||
* 函数功能:把快照清成"从未成功读过"的初始态
|
||
* 入口参数:s - 快照对象
|
||
* 返回值:无
|
||
* 限定条件:单写者(初始化期 / 尚无读者)
|
||
* 函数说明:全字段清零。**mask = 0 此时不表示"开入全 0"**——消费者必须看 valid 与
|
||
* change_seq。
|
||
*/
|
||
void ioboard_di_snap_reset(ioboard_di_snapshot_t *s);
|
||
|
||
/* 诊断副本:不保证一致性,仅供自检/串口打印 */
|
||
void ioboard_di_snap_copy(const ioboard_di_snapshot_t *s, ioboard_di_snapshot_t *out);
|
||
|
||
/*
|
||
* 函数功能:读"有效 → 失效 下降沿"累计次数与"连续失败拍数"
|
||
* 入口参数:s - 快照对象
|
||
* out_edges - 输出,fail_edges(可为 NULL)
|
||
* out_fails - 输出,fail_count(可为 NULL)
|
||
* 返回值:无
|
||
* 限定条件:任意上下文;单字读,值可能来自相邻两拍(诊断用途够用)
|
||
* 函数说明:调用方(defaultTask)用它把"开入读失败"这一事实经 syslog 留痕——
|
||
* 本模块自己不碰文件系统,留痕点只有调用方知道该写哪个日志、写多频。
|
||
*/
|
||
void ioboard_di_snap_faults(const ioboard_di_snapshot_t *s, uint32_t *out_edges,
|
||
int32_t *out_fails);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* IOBOARD_DI_H */
|