YA-Wiegand：轻量级事件驱动Wiegand协议解析库
1. 项目概述
Yet Another Arduino Wiegand Library（以下简称 YA-Wiegand）是一个专为嵌入式平台设计的轻量级、事件驱动型 Wiegand 协议解析库。它并非简单封装硬件抽象层，而是聚焦于协议语义层的健壮性实现——在不依赖特定 MCU 外设（如输入捕获单元）的前提下，将原始电平跳变转化为结构化数据帧，并提供可预测的回调通知机制。该库面向实际工业与安防场景中广泛部署的 Wiegand RFID 读卡器（如 HID ProxCard II、Indala、EM-Marin 等主流型号），其核心价值在于：解耦硬件检测逻辑与协议解析逻辑，支持动态消息长度识别，并严格遵循 Wiegand 物理层时序约束与常见数据格式规范。
Wiegand 接口虽因“简单可靠”被长期沿用，但其标准化缺失导致工程实践充满陷阱：厂商自定义位宽（26/34/37/44/50 位等）、奇偶校验策略（前半段偶校验 + 后半段奇校验）、字段语义（Facility Code / Card ID / Site Code）各不相同；物理层上，D0/D1 线空闲态为高电平，有效脉冲宽度仅 20–100 μs，相邻脉冲间隔达 200 μs 至 20 ms，对边沿检测精度与抗干扰能力提出严苛要求。YA-Wiegand 库的设计哲学正是直面这些挑战——它不假设用户使用中断或轮询，不强制绑定特定 GPIO 配置，而是将“状态采集”与“协议解析”划分为清晰边界，使开发者能根据硬件资源（如是否具备低功耗唤醒中断、是否需多路复用同一引脚）灵活选择底层驱动策略。
2. Wiegand 协议深度解析
2.1 物理层时序与电气特性
Wiegand 接口采用双线差分思想（非真正差分，无共模抑制），通过 D0（Data 0）和 D1（Data 1）两根独立信号线传输二进制数据。其电气行为定义如下：
- 空闲态：D0 与 D1 均被外部上拉电阻（通常 4.7 kΩ）拉至高电平（VCC），此时读卡器输出开漏/开集电极结构，呈高阻态。
- 数据脉冲：
- 若发送比特
0：D0 线被读卡器主动拉低，持续时间tPULSE ∈ [20, 100] μs，D1 保持高电平； - 若发送比特
1：D1 线被读卡器主动拉低，持续时间tPULSE ∈ [20, 100] μs，D0 保持高电平；
- 若发送比特
- 位间隔：相邻两个脉冲的下降沿之间的时间
tINTERBIT ∈ [200, 20000] μs（即 0.2 ms 至 20 ms）。此宽泛范围是自动长度检测的关键依据。 - 非法状态：D0 与 D1 同时为低电平（
D0=0 ∧ D1=0）被视为设备断连或故障标志；D0 与 D1 同时为高电平（D0=1 ∧ D1=1）为空闲态，亦为合法状态。
工程要点：MCU 的 GPIO 中断触发方式必须设置为
CHANGE（电平变化触发），而非RISING或FALLING。因为脉冲宽度极窄（最短仅 20 μs），若仅捕获下降沿，可能因中断响应延迟（典型 Cortex-M0+ 为 12–15 个周期）而错过后续脉冲；而CHANGE模式确保每次电平翻转（高→低或低→高）均被捕获，库内部通过采样当前电平值判断是脉冲起始还是结束。
2.2 数据帧格式与校验机制
Wiegand 数据帧无起始位、停止位，纯靠脉冲序列编码。其格式由厂商定义，但存在事实标准：
| 字段 | 位宽（示例） | 说明 |
|---|---|---|
| Leading Parity | 1 bit | 第 1 位，对第 2 至中间位（含）进行偶校验（EVEN parity） |
| Facility Code | 8–16 bits | 厂商自定义，常表示门禁系统分区编号 |
| Card Number | 16–24 bits | 唯一卡片 ID |
| Trailing Parity | 1 bit | 最后 1 位，对中间位（含）至倒数第 2 位进行奇校验（ODD parity） |
以最常见的26-bit 格式为例（HID 标准）：
Bit: 0 1-8 9-24 25 Field: Parity Fac.Code Card.No. Parity Value: ? XXXXXXXX YYYYYYYY ?- Bit 0（Leading Parity）：校验 Bit 1–13（Facility Code 的 8 位 + Card Number 的前 5 位），要求
∑(Bit1..13) % 2 == 0 - Bit 25（Trailing Parity）：校验 Bit 13–25（Card Number 的后 11 位 + Bit 25 自身？），实际应校验 Bit 13–24，要求
∑(Bit13..24) % 2 == 1
YA-Wiegand 的校验策略：
- 仅实现上述“前半段偶校验 + 后半段奇校验”的通用模式；
- 对奇数位宽（如 37-bit），中心位（bit
(n-1)/2）同时参与前后两段校验； - 校验失败的数据帧被静默丢弃，不触发
onReceive()回调，这是库的明确设计决策——避免向应用层传递不可信数据。
2.3 自动长度检测原理
当调用wiegand.begin(WIEGAND_LENGTH_AUTO)时，库启用自动长度检测。其核心逻辑基于 Wiegand 协议的tINTERBIT特性：
- 脉冲计时启动：首次检测到 D0 或 D1 下降沿（即
setPin0State(LOW)或setPin1State(LOW)）时，启动内部定时器lastBitTime记录此刻微秒级时间戳。 - 位间隔监控：每次新脉冲到达，计算
currentTime - lastBitTime。若该值≥ WIEGAND_TIMEOUT（默认 5000 μs = 5 ms），则判定前一脉冲为当前帧的最后一位。 - 帧完整性确认：
flush()被调用时，库检查lastBitTime是否已超时。若超时，则将已缓存的位序列组装为完整帧，执行校验并触发回调；否则视为帧未结束，继续等待。
关键参数
WIEGAND_TIMEOUT：
其值必须满足WIEGAND_TIMEOUT > max(tINTERBIT)且WIEGAND_TIMEOUT < min(tINTERFRAME)（帧间最小间隔）。实践中，5000 μs 是安全折中值——覆盖绝大多数读卡器的tINTERBIT上限（20 ms 是理论最大值，实际设备多为 2–5 ms），同时远小于典型帧间间隔（> 50 ms）。若遇特殊设备，可在Wiegand.h中修改宏定义。
3. API 接口详解与工程化使用
3.1 核心类与构造函数
class Wiegand { public: Wiegand(); // 默认构造，内部初始化缓冲区与状态机 // ... 其他方法声明 };- 无参数构造：所有状态变量（
bitBuffer,bitCount,lastBitTime,pin0State,pin1State）均初始化为 0 或false，确保对象处于确定初始态。
3.2 初始化与配置接口
| 函数签名 | 参数说明 | 工程意义 |
|---|---|---|
void begin(uint8_t expectedLength = WIEGAND_LENGTH_AUTO) | expectedLength: 预期位宽（如26,34）或WIEGAND_LENGTH_AUTO（自动检测） | 决定协议解析模式：固定长度模式下，setPin*State()在接收完第expectedLength位后立即触发回调；自动模式下，依赖flush()和超时机制。建议新项目首选AUTO，兼容性最佳。 |
void onReceive(void (*callback)(uint8_t*, uint8_t, const char*), const char* userData = nullptr) | callback: 三参数函数指针，(dataPtr, bitCount, userData)；userData: 透传给回调的任意指针 | 事件注册核心：dataPtr指向内部缓冲区（大端序，不含校验位），bitCount为有效数据位数（26/34 等）。userData是 C++ 成员函数回调的关键——通过static_cast将this指针传入，实现面向对象风格。 |
void onStateChange(void (*callback)(bool, const char*), const char* userData = nullptr) | callback:(plugged, userData)，plugged=true表示 D0/D1 不再同时为高（设备连接） | 设备在线检测：依赖硬件设计——D0/D1 必须接下拉电阻（10 kΩ）。当读卡器断开，两线均被下拉为低，setPin*State(LOW)被连续调用，库识别D0=0 && D1=0并触发plugged=false。 |
3.3 硬件状态注入接口（关键！）
| 函数签名 | 参数说明 | 使用约束 |
|---|---|---|
void setPin0State(bool state) | state:digitalRead(PIN_D0)返回值（HIGH/LOW） | 必须在中断服务程序（ISR）或轮询循环中高频调用。库不读取 GPIO，完全依赖用户注入。state必须为true(LOW) 或false(HIGH)，严禁传入HIGH/LOW常量（Arduino 定义为0/1，与布尔逻辑冲突）。 |
void setPin1State(bool state) | state:digitalRead(PIN_D1)返回值 | 同上。 |
为何不直接读取？
这是库“硬件无关性”的基石。例如：STM32 可用 EXTI 中断；ESP32 可用 GPIO 中断 +portMUX_TYPE保护；而资源受限的 ATtiny 可能只能轮询。若库内部读取，将强制绑定digitalRead()，丧失移植性。用户可根据平台选择最优方案：
- 中断方案：
attachInterrupt(digitalPinToInterrupt(pin), isr, CHANGE)，ISR 中仅调用setPin*State(digitalRead(pin))；- 轮询方案：主循环中
if (digitalRead(PIN_D0) != lastD0) { setPin0State(digitalRead(PIN_D0)); lastD0 = !lastD0; }，需保证轮询频率 >1/(2*tPULSE)（即 > 10 kHz）。
3.4 协议处理与同步接口
| 函数签名 | 参数说明 | 关键注意事项 |
|---|---|---|
void flush() | 无参数 | 线程不安全！必须在noInterrupts()保护下调用。此函数完成三件事：(1) 检查lastBitTime是否超时；(2) 若超时，拷贝bitBuffer到临时缓冲区，重置bitCount；(3) 执行校验，成功则调用onReceive()。若在中断中调用，可能导致数据竞争。 |
uint8_t getBitCount() | 无参数 | 返回当前缓存的位数（调试用），非线程安全。 |
4. 典型应用场景与代码增强
4.1 中断驱动方案（推荐）
以下为 STM32 HAL 库适配示例（替换 ArduinoattachInterrupt）：
#include "Wiegand.h" #include "main.h" // HAL 初始化头文件 #define PIN_D0_GPIO_PORT GPIOA #define PIN_D0_GPIO_PIN GPIO_PIN_0 #define PIN_D1_GPIO_PORT GPIOA #define PIN_D1_GPIO_PIN GPIO_PIN_1 Wiegand wiegand; // 外部中断回调（HAL 自动生成） void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) { if (GPIO_Pin == PIN_D0_GPIO_PIN) { wiegand.setPin0State(HAL_GPIO_ReadPin(PIN_D0_GPIO_PORT, PIN_D0_GPIO_PIN) == GPIO_PIN_RESET); } else if (GPIO_Pin == PIN_D1_GPIO_PIN) { wiegand.setPin1State(HAL_GPIO_ReadPin(PIN_D1_GPIO_PORT, PIN_D1_GPIO_PIN) == GPIO_PIN_RESET); } } void wiegand_init(void) { // 1. 配置 GPIO 为浮空输入（外部已有上拉） GPIO_InitTypeDef GPIO_InitStruct = {0}; GPIO_InitStruct.Pin = PIN_D0_GPIO_PIN | PIN_D1_GPIO_PIN; GPIO_InitStruct.Mode = GPIO_MODE_IT_RISING_FALLING; GPIO_InitStruct.Pull = GPIO_NOPULL; HAL_GPIO_Init(PIN_D0_GPIO_PORT, &GPIO_InitStruct); // 2. 使能中断（优先级需高于其他外设） HAL_NVIC_SetPriority(EXTI0_IRQn, 1, 0); HAL_NVIC_EnableIRQ(EXTI0_IRQn); HAL_NVIC_SetPriority(EXTI1_IRQn, 1, 0); HAL_NVIC_EnableIRQ(EXTI1_IRQn); // 3. 初始化 Wiegand 库 wiegand.onReceive(receivedData, "CARD:"); wiegand.onStateChange(stateChanged, "READER:"); wiegand.begin(WIEGAND_LENGTH_AUTO); } // 主循环 void loop(void) { noInterrupts(); // 关闭全局中断 wiegand.flush(); // 安全处理帧 interrupts(); // 恢复中断 HAL_Delay(100); // 降低 CPU 占用 }4.2 FreeRTOS 任务集成方案
在 RTOS 环境中，可将flush()封装为独立任务，避免阻塞高优先级任务：
QueueHandle_t xWiegandQueue; void wiegand_task(void *pvParameters) { uint8_t dataBuffer[6]; // 支持最大 44-bit → 6 bytes uint8_t bits; TickType_t xLastWakeTime = xTaskGetTickCount(); while (1) { // 每 50ms 检查一次（比 timeout 略长，确保帧完整） vTaskDelayUntil(&xLastWakeTime, pdMS_TO_TICKS(50)); noInterrupts(); // flush() 内部会调用 onReceive，若需队列通信，可在此处修改回调 wiegand.flush(); interrupts(); } } // 修改后的 receivedData 回调，向队列发送数据 void receivedData(uint8_t* data, uint8_t bits, const char* msg) { uint8_t bytes = (bits + 7) / 8; memcpy(dataBuffer, data, bytes); // 发送 {dataBuffer, bits} 结构体到队列 xQueueSend(xWiegandQueue, &dataBuffer, 0); }4.3 多读卡器复用 GPIO 方案
当 MCU GPIO 资源紧张时，可复用同一组中断引脚监测多个读卡器（需硬件支持）：
// 硬件：每个读卡器 D0/D1 经 OR 门汇总至 MCU 的 INT0/INT1 // 软件：在 ISR 中读取所有读卡器状态，分别调用 setPin*State void multi_reader_isr(void) { // 读取读卡器1状态 wiegand1.setPin0State(digitalRead(D0_1)); wiegand1.setPin1State(digitalRead(D1_1)); // 读取读卡器2状态 wiegand2.setPin0State(digitalRead(D0_2)); wiegand2.setPin1State(digitalRead(D1_2)); }5. 硬件设计与调试指南
5.1 关键电路设计
- 上拉电阻：D0/D1 线必须接
4.7 kΩ上拉至 VCC（3.3V/5V），确保空闲态稳定高电平。阻值过大会导致上升沿缓慢，影响高速读卡；过小则增加功耗。 - 下拉电阻（设备检测必需）：在 D0/D1 线各自对地加
10 kΩ下拉电阻。当读卡器断开，两线被下拉为低，库识别D0=0 && D1=0触发onStateChange(false)。此设计是设备热插拔检测的物理基础。 - ESD 保护：Wiegand 线缆易受静电干扰，在 MCU GPIO 前添加 TVS 二极管（如 PESD5V0S1BA）。
5.2 常见问题诊断
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
onReceive从不触发 | 1.flush()未被调用或未在noInterrupts()下调用2. setPin*State()未被正确注入（如 ISR 未使能）3. 上拉电阻缺失或阻值过大 | 用示波器观察 D0/D1 波形，确认有符合时序的脉冲；检查flush()调用位置；验证 ISR 是否执行。 |
onStateChange(false)频繁触发 | 下拉电阻未焊接或虚焊；读卡器电源不稳导致输出异常 | 万用表测量 D0/D1 对地电压，空闲态应为 0V（被下拉），连接态应为 VCC（被上拉）。 |
| 接收数据错乱（如 Card ID 高低位颠倒） | data缓冲区被其他任务覆盖；flush()调用过于频繁（< 5ms） | 确保onReceive回调中立即拷贝data到安全缓冲区；增大loop()中delay()时间。 |
| 自动长度检测失败（始终返回 0 位） | WIEGAND_TIMEOUT设置过小；读卡器tINTERBIT异常大 | 示波器测量实际tINTERBIT，将WIEGAND_TIMEOUT设为实测值的 1.5 倍。 |
6. 性能与资源占用分析
- RAM 占用：
Wiegand对象静态分配bitBuffer[6]（支持 ≤48-bit），加上状态变量，总 RAM ≤ 12 字节。无动态内存分配，适合资源受限 MCU。 - Flash 占用：编译后约 1.2 KB（ARM GCC），核心算法精简，无浮点运算。
- CPU 开销：
- 中断服务程序（ISR）：仅 2–3 条指令（读 GPIO + 调用
setPin*State），执行时间 < 100 ns； flush()：最坏情况（处理 44-bit 帧）约 5 μs，可安全在 100 Hz 循环中调用。
- 中断服务程序（ISR）：仅 2–3 条指令（读 GPIO + 调用
该库的设计证明：在嵌入式领域，“少即是多”。它放弃对硬件外设的依赖，换取极致的可移植性；牺牲部分自动化（需用户管理中断），赢得对时序的完全掌控。对于需要稳定接入传统门禁系统的工业控制器、楼宇自动化网关或 DIY 安防终端，YA-Wiegand 提供了一条经过验证的、低风险的技术路径——它不试图重新发明 Wiegand，而是成为连接混乱物理世界与确定数字逻辑之间最可靠的翻译官。