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 接口采用双线差分思想非真正差分无共模抑制通过 D0Data 0和 D1Data 1两根独立信号线传输二进制数据。其电气行为定义如下空闲态D0 与 D1 均被外部上拉电阻通常 4.7 kΩ拉至高电平VCC此时读卡器输出开漏/开集电极结构呈高阻态。数据脉冲若发送比特0D0 线被读卡器主动拉低持续时间tPULSE ∈ [20, 100] μsD1 保持高电平若发送比特1D1 线被读卡器主动拉低持续时间tPULSE ∈ [20, 100] μsD0 保持高电平位间隔相邻两个脉冲的下降沿之间的时间tINTERBIT ∈ [200, 20000] μs即 0.2 ms 至 20 ms。此宽泛范围是自动长度检测的关键依据。非法状态D0 与 D1 同时为低电平D00 ∧ D10被视为设备断连或故障标志D0 与 D1 同时为高电平D01 ∧ D11为空闲态亦为合法状态。工程要点MCU 的 GPIO 中断触发方式必须设置为CHANGE电平变化触发而非RISING或FALLING。因为脉冲宽度极窄最短仅 20 μs若仅捕获下降沿可能因中断响应延迟典型 Cortex-M0 为 12–15 个周期而错过后续脉冲而CHANGE模式确保每次电平翻转高→低或低→高均被捕获库内部通过采样当前电平值判断是脉冲起始还是结束。2.2 数据帧格式与校验机制Wiegand 数据帧无起始位、停止位纯靠脉冲序列编码。其格式由厂商定义但存在事实标准字段位宽示例说明Leading Parity1 bit第 1 位对第 2 至中间位含进行偶校验EVEN parityFacility Code8–16 bits厂商自定义常表示门禁系统分区编号Card Number16–24 bits唯一卡片 IDTrailing Parity1 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 0Leading Parity校验 Bit 1–13Facility Code 的 8 位 Card Number 的前 5 位要求∑(Bit1..13) % 2 0Bit 25Trailing Parity校验 Bit 13–25Card Number 的后 11 位 Bit 25 自身实际应校验 Bit 13–24要求∑(Bit13..24) % 2 1YA-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)pluggedtrue表示 D0/D1 不再同时为高设备连接设备在线检测依赖硬件设计——D0/D1 必须接下拉电阻10 kΩ。当读卡器断开两线均被下拉为低setPin*State(LOW)被连续调用库识别D00 D10并触发pluggedfalse。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Ω上拉至 VCC3.3V/5V确保空闲态稳定高电平。阻值过大会导致上升沿缓慢影响高速读卡过小则增加功耗。下拉电阻设备检测必需在 D0/D1 线各自对地加10 kΩ下拉电阻。当读卡器断开两线被下拉为低库识别D00 D10触发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 KBARM GCC核心算法精简无浮点运算。CPU 开销中断服务程序ISR仅 2–3 条指令读 GPIO 调用setPin*State执行时间 100 nsflush()最坏情况处理 44-bit 帧约 5 μs可安全在 100 Hz 循环中调用。该库的设计证明在嵌入式领域“少即是多”。它放弃对硬件外设的依赖换取极致的可移植性牺牲部分自动化需用户管理中断赢得对时序的完全掌控。对于需要稳定接入传统门禁系统的工业控制器、楼宇自动化网关或 DIY 安防终端YA-Wiegand 提供了一条经过验证的、低风险的技术路径——它不试图重新发明 Wiegand而是成为连接混乱物理世界与确定数字逻辑之间最可靠的翻译官。