# RC522 任务接入说明 (CubeMX 友好)

你要求不要直接改自动生成任务代码，避免下次 CubeMX 重新生成被覆盖。下面是推荐接入方式。

## 1. 已新增驱动文件

- `Core/Bsp/bsp_rc522.h`
- `Core/Bsp/bsp_rc522.c`

核心接口：

```c
rc522_status_t rc522_init(void);
rc522_status_t rc522_poll(rc522_card_info_t *out_card);
rc522_status_t rc522_service(rc522_card_info_t *out_card);
uint8_t rc522_get_last_card(rc522_card_info_t *out_card);
uint8_t rc522_has_valid_card(void);
uint8_t rc522_get_new_card(rc522_card_info_t *out_card);
void rc522_clear_last_card(void);
uint8_t rc522_uid_to_string(const rc522_card_info_t *card, char *out_str, uint16_t out_len);
void rc522_irq_callback(uint16_t GPIO_Pin);
```

RUN 灯提示（已内置在驱动里）：

- 成功读到卡后自动点亮 `RUN_LED`
- 保持 `RC522_RUN_LED_HOLD_MS` 毫秒后自动熄灭
- 默认低电平点亮，可在 `bsp_rc522.h` 里改：

```c
#define RC522_RUN_LED_ENABLE 1U
#define RC522_RUN_LED_HOLD_MS 300U
#define RC522_RUN_LED_ON_LEVEL GPIO_PIN_RESET
#define RC522_CACHE_EXPIRE_MS 1500U
#define RC522_USE_IRQ_TRIGGER 0U
```

## 2. 硬件连接确认

按你现在配置：

- `SDA (CS)` -> `PC4` (输出)
- `RST` -> `PB0` (输出)
- `IOR (IRQ)` -> `PC5` (EXTI，可选)
- `SPI1` -> `PA5/PA6/PA7`

> 注意：默认是 **轮询模式**（`RC522_USE_IRQ_TRIGGER=0`），最稳。
> 如果你想改为中断触发读卡：设为 `1`，并确保 EXTI 回调里调用 `rc522_irq_callback(GPIO_Pin)`。

## 3. 在 CubeMX 的 freertos.c 用户区接入

### 3.1 头文件包含 (`USER CODE BEGIN Includes`)

```c
#include "bsp_rc522.h"
```

### 3.2 在初始化阶段调用 (`USER CODE BEGIN Init`)

```c
rc522_init();
```

### 3.3 新建一个低优先级任务（推荐 50~100ms）

任务函数示例（你可以放在用户代码区）：

```c
void rc522_task(void *argument)
{
    rc522_card_info_t card;
    char uid_str[3 * RC522_UID_MAX_LEN] = {0};

    for (;;) {
        rc522_status_t st = rc522_service(&card);
        if (st == RC522_OK) {
            if (rc522_uid_to_string(&card, uid_str, sizeof(uid_str))) {
                printf("RFID UID: %s, SAK:0x%02X, ATQA:0x%04X\r\n",
                       uid_str, card.sak, card.atqa);
            }
        }
        osDelay(100);
    }
}
```

如果你只希望“新卡刷入时”触发一次业务，不重复触发：

```c
rc522_card_info_t new_card;
if (rc522_get_new_card(&new_card)) {
    // 仅在识别到新 UID 时进入
}
```

## 4. 在业务代码中获取“最近一次卡片信息”

驱动会自动缓存最近一次成功读到的卡，可在任意位置读取：

```c
rc522_card_info_t last_card;
if (rc522_get_last_card(&last_card)) {
    // last_card 有效
} else {
    // 当前没有有效卡缓存
}
```

## 5. 常见问题

1. 一直读不到卡：
   - 检查 RC522 供电是否 3.3V（不要 5V）
   - 检查 `SDA(PC4)` 是否被其他器件复用
   - 确认 SPI1 时钟极性/相位为 `CPOL=0, CPHA=1Edge`

2. UID 偶发错误：
   - 降低 SPI 速率（在 CubeMX 调大分频，例如 Prescaler=8）
   - 线长尽量短，地线要可靠

3. 任务被覆盖：
   - 只在 `USER CODE BEGIN ... END` 区域放代码
   - 或者把任务函数放到 `Core/Bsp` 内，由 `freertos.c` 用户区仅调用