# QCard_esp32

**Repository Path**: japyvi/qcard_esp32

## Basic Information

- **Project Name**: QCard_esp32
- **Description**: esp32-c3读卡器代码（接ws1830读卡芯片）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32-C3 NFC 读卡器（上位机驱动版）

基于 ESP-IDF 的 ESP32-C3 Super Mini + SPI 接口 WS1830T（MFRC522 兼容）NFC 读卡器。
设备通过 **USB 调试串口** 接收上位机的 ASCII 命令，执行读卡、写卡等操作后返回结果。

## 功能
- 通过 USB 串口接收上位机命令（115200/8/N/1）
- 检测 ISO14443-A 卡片并返回 UID / ATQA
- 选卡、认证、MIFARE Classic 块读取 / 块写入
- 所有二进制数据使用十六进制字符串传输，便于串口调试

## 硬件接线

| WS1830T 引脚 | ESP32-C3 引脚 | 说明 |
|--------------|---------------|------|
| VCC          | 3.3V          | 必须为 3.3V，不可接 5V |
| GND          | GND           |      |
| RST          | GPIO10        | 可在 menuconfig 修改 |
| NSS (CS)     | GPIO7         | 可在 menuconfig 修改 |
| MISO         | GPIO5         | 可在 menuconfig 修改 |
| MOSI         | GPIO4         | 可在 menuconfig 修改 |
| SCK          | GPIO6         | 可在 menuconfig 修改 |

> 默认使用 `SPI2_HOST`，SPI 模式 0，MSB First，默认时钟 4 MHz。

### 指示灯与蜂鸣器（可选）

| 外设 | GPIO | 默认有效电平 | 说明 |
|------|------|--------------|------|
| LED  | GPIO2 | 低电平点亮 | 读卡/写卡过程中常亮 |
| 有源蜂鸣器 | GPIO3 | 高电平响 | 读卡/写卡成功时蜂鸣 100ms |

可在 `idf.py menuconfig → NFC Reader Configuration → Indicator Configuration` 中修改引脚和有效电平。

## 软件依赖

- ESP-IDF v4.4 或更高版本
- 组件：`esp_driver_spi`、`esp_driver_gpio`

## 配置

```bash
idf.py menuconfig
```

进入 `NFC Reader Configuration` 菜单，可修改引脚、SPI 主机、SPI 时钟。

## 编译与烧录

```bash
idf.py build
idf.py -p PORT flash monitor
```

将 `PORT` 替换为实际串口号，例如 `COM3` 或 `/dev/ttyUSB0`。

## 人机交互指示

- **LED**：执行 `READ`、`SELECT`、`AUTH`、`READ_BLOCK`、`WRITE_BLOCK` 等涉及卡片的命令时点亮，命令结束后熄灭。
- **蜂鸣器**：上述命令执行成功时发出约 100ms 的“嘀”声；失败时不蜂鸣。
- 这样设计方便现场操作：刷卡时看到 LED 亮，听到蜂鸣声即表示成功。

## 通信协议

### 基本规则
- **物理层**：ESP32-C3 USB 调试串口（USB-Serial-JTAG）。
- **帧格式**：以 `\n` 结尾的可打印 ASCII 行（兼容 `\r\n`）。
- **编码**：命令和响应均为 ASCII；二进制数据用 **小写十六进制字符串** 表示。
- **大小写**：命令关键字不区分大小写；十六进制数据大小写均可。
- **无主动上报**：读卡器仅在收到命令后返回一行响应。

### 命令列表

| 命令 | 参数 | 说明 | 示例 |
|------|------|------|------|
| `PING` | 无 | 心跳/握手 | `PING` |
| `VERSION` | 无 | 获取版本 | `VERSION` |
| `READ` | 无 | 寻卡、防冲突、选卡并返回 UID / ATQA | `READ` |
| `SELECT` | `<uid_hex>` | 选择指定 UID 的卡片 | `SELECT a1b2c3d4` |
| `AUTH` | `<block> <a\|b> <key_hex>` | 认证指定块所在扇区 | `AUTH 4 a ffffffffffff` |
| `READ_BLOCK` | `<block> [a\|b] [key_hex]` | 读 16 字节块数据 | `READ_BLOCK 4` |
| `WRITE_BLOCK` | `<block> <data_hex> [a\|b] [key_hex]` | 写 16 字节块数据 | `WRITE_BLOCK 4 000102030405060708090a0b0c0d0e0f` |
| `HALT` | 无 | 停止 RF 场 | `HALT` |

- 默认密钥：`ffffffffffff`（MIFARE Classic 默认 Key A/B）。
- 默认 Key 类型：`a`（Key A）。
- `READ_BLOCK` / `WRITE_BLOCK` 会自动认证目标块所在扇区的尾块（trailer block）。

### 响应格式

```
OK [key=value ...]
ERR <code> <message>
```

### 响应示例

```
> PING
OK pong
> VERSION
OK ver=1.0.0 board=esp32c3_nfc
> READ
OK uid=a1b2c3d4 atqa=0400
> READ_BLOCK 4
OK data=000102030405060708090a0b0c0d0e0f
> WRITE_BLOCK 4 000102030405060708090a0b0c0d0e0f
OK written=4
> HALT
OK halted
> READ
ERR NO_CARD no card detected
```

### 错误码

| 错误码 | 含义 |
|--------|------|
| `NO_CARD` | 未检测到卡片 |
| `ANTICOLL_FAIL` | 防冲突失败 |
| `SELECT_FAIL` | 选卡失败 |
| `AUTH_FAIL` | 认证失败 |
| `READ_FAIL` | 读块失败 |
| `WRITE_FAIL` | 写块失败 |
| `INVALID_ARG` | 参数非法 |
| `UNKNOWN_CMD` | 未知命令 |
| `INTERNAL` | 内部错误 |

### 典型上位机交互流程

```
PING                    -> OK pong
READ                    -> OK uid=a1b2c3d4 atqa=0400
AUTH 4 a ffffffffffff   -> OK authenticated=4
READ_BLOCK 4            -> OK data=000102030405060708090a0b0c0d0e0f
HALT                    -> OK halted
```

## 文件说明

| 文件 | 说明 |
|------|------|
| `main/ws1830t.h/c` | WS1830T 底层 SPI 驱动，移植自 `ref/drv_ws1830t.c` |
| `main/nfc_card.h/c` | 卡片抽象层，移植自 `ref/nfc_fx2.c` |
| `main/serial_cmd.h/c` | USB 串口命令解析与分发 |
| `main/main.c` | 应用主程序，初始化 SPI/NFC 后启动命令任务 |

## 参考

- `ref/drv_ws1830t.c` / `ref/drv_ws1830t.h`：原始 RT-Thread 驱动
- `ref/nfc_fx2.c`：原始卡片抽象层

## 注意事项

- 若 `READ` 返回 `ERR NO_CARD`，请检查卡片是否贴近天线、供电是否稳定。
- MIFARE Classic 块读写前必须先认证对应扇区的尾块；`READ_BLOCK` / `WRITE_BLOCK` 已自动处理。
- 写卡操作具有破坏性，请谨慎使用，尤其不要覆盖扇区尾块，否则可能锁死卡片。
- 默认密钥 `ffffffffffff` 仅适用于未修改密钥的空白卡或测试卡。