MFRC522 RFID 射频卡读取器

MFRC522 使用独立外设类型 RFID_MFRC522（54），不是通用传感器 38。固件需编入 FASTBEE_ENABLE_RFID，在功能配置开启 rfid，并通过预算与引脚预检。当前管理一个读卡器实例。

SPI 接线与配置

以下是经典 ESP32 的示例。逐板核对 SPI 引脚、片选、复位和 3.3V 电平，不能套用到所有 C3/C6/S3 或带 PSRAM 板卡。MFRC522 模块 SDA/SS 是 SPI 片选，不是 I2C SDA。

模块端子	示例 GPIO	配置顺序
SCK	18	pins[0]
MOSI	23	pins[1]
MISO	19	pins[2]
SDA / SS	5	pins[3]
RST	4	pins[4]
VCC / GND	3.3V / GND	按实际模块确认供电并共地

在 Web 外设配置中选择 MFRC522 RFID，填写上述五个 GPIO。下例是 peripherals 数组条目，先保持禁用：

{
  "id": "rfid1",
  "name": "RFID读卡器",
  "type": 54,
  "enabled": false,
  "pinCount": 5,
  "pins": [18, 23, 19, 5, 4],
  "params": {}
}

不用填写 driver=MFRC522、ssPin、rstPin 或 interval。驱动轮询间隔固定 200ms，卡移除判定使用超过 1000ms 未重新检测到的状态。SPI 共享须通过租约与资源检查，独立 CS 本身不能证明其他客户端兼容。

读取与事件

确认接线后启用外设，使用 GET /api/peripherals/read?id=rfid1 查看初始化、UID、卡类型、卡存在状态和驱动错误。首次卡扫描与周期检查受实际 SPI 可用性影响；只查询状态不证明卡片仍在感应范围。

事件 ID	编号	载荷示例
rfid_card_detected	120	{"uid":"A1B2C3D4","size":4}
rfid_card_removed	121	{"uid":"A1B2C3D4"}

驱动在释放 SPI 锁后派发事件；事件载荷没有外设 ID，目前不能按 triggerPeriphId=rfid1 区分多个读卡器。驱动没有自动生成 uid:... 格式的 MQTT 属性消息，也没有 ${rfid1.uid} 传感器缓存模板；上报和输出应使用已配置规则的实际事件数据处理路径。

下面是一条禁用的 LED 事件规则片段，先配置并验证数字输出 led1：

{
  "id": "rfid_led",
  "name": "刷卡点亮指示灯",
  "enabled": false,
  "triggers": [
    {"triggerType": 4, "eventId": "rfid_card_detected"}
  ],
  "actions": [
    {"actionType": 0, "targetPeriphId": "led1", "actionValue": ""}
  ]
}

该规则会响应检测到的卡片，不能作为授权 UID 的门禁验证。舵机动作 4 使用 raw duty，180 不表示 180°，动作 10 则要求 CALL 的结构化参数；角度和脉宽映射见舵机。

MIFARE Classic 数据块操作

登录并开启开发者模式后，现有 POST /api/peripherals/write 支持如下表单请求体：

action	必要参数	结果
read-block	id、block、key	认证后读取 16 字节，响应返回 hex、UID 和卡类型
write-block	id、block、key、data、confirm=WRITE_BLOCK	写 16 字节后回读比较

key 必须恰好 6 字节的十六进制；data 必须恰好 16 字节。只允许 MIFARE Classic 的数据块 1～62，块 0 和每个扇区尾块均拒绝；不提供制造商块、密钥块或任意卡型号的通用写入。请在明确授权的测试卡上操作，备份所需数据。

写入失败可能已经改变卡内容，不能自动重试或把回读不一致当作未写入。完整回读校验只证明此次卡通信与数据相符，不能证明门锁动作或 UID 安全身份。

失败与恢复

总线繁忙会跳过周期检查或拒绝本次操作。租约丢失、旧读卡器清理未完成时保留对象与引脚，不允许新配置覆盖；先处理原因再按外设停用、重启初始化流程恢复。停止未确认不等于资源已释放。

实际读取距离、连续贴卡的检测/移除事件、多种 UID 长度、断线恢复、数据块权限和长期运行须在对应卡片、模块和板卡上验证。UID 可复制或重复，不应作为唯一安全凭据。

相关文档：外设配置指南、事件触发。