# android-nfc

**Repository Path**: ssy_kr/android-nfc

## Basic Information

- **Project Name**: android-nfc
- **Description**: Android 二维码与 NFC 工具箱：文本生成二维码、NFC NDEF 贴纸模拟、NFC 标签读取，可以直接照搬实现案例
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-17
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# guanyun-test

<img src="docs/images/app-icon.svg" width="88" alt="二维码与 NFC 波纹应用图标" />

Android 二维码与 NFC 工具箱：文本生成二维码、NFC NDEF 贴纸模拟、NFC 标签读取。

## 功能

| 功能 | 内容 |
| --- | --- |
| 二维码生成 | 输入文本或链接，使用 ZXing 生成二维码 |
| NFC 贴纸模拟 | 通过 HCE 模拟只读 NDEF Type 4 Tag，支持文本、URI、URI + AAR 三种记录 |
| NFC 读取 | 展示协议类型、UID、完整 NDEF 消息的十六进制字节；结果可长按选择复制 |

读取页不会自动打开卡片里的链接。进入页面开启 Reader Mode，暂停或退出时释放，避免影响卡模拟功能。

## 运行截图

截图来自 Xiaomi / HyperOS / Android 16 真机（2026-09-17）。

| 二维码生成 | NFC 贴纸模拟 | NFC 读取 |
| --- | --- | --- |
| <img src="docs/images/qr.png" width="260" alt="示例编号生成二维码" /> | <img src="docs/images/nfc-simulate.png" width="260" alt="URI 记录贴纸模拟已激活" /> | <img src="docs/images/nfc-read.png" width="260" alt="MIFARE Classic 门禁卡协议和 UID，无 NDEF 消息" /> |

图中的门禁卡被识别为 `MifareClassic`、`NFC-A / ISO 14443-3A` 和 `NdefFormatable`，UID 已读出；系统没有检测到 NDEF 消息，因此显示“无可展示的 NDEF 数据”，符合当前功能范围。`NdefFormatable` 表示系统提供 NDEF 格式化接口，不表示卡内已有 NDEF，也不表示可以无条件格式化成功。本应用不会格式化卡片。

当前读取功能不读取门禁卡的受保护扇区，也不包含密钥认证、卡片克隆或全部存储区转储。读取 MIFARE Classic 扇区需要相应密钥与认证流程，参见 [Android MifareClassic API](https://developer.android.com/reference/android/nfc/tech/MifareClassic)。没有 NDEF 消息不代表卡片没有门禁数据。

## 使用

### 二维码

打开“二维码生成”，输入文本或链接即可生成。

### NFC 贴纸模拟与读取

1. 设备 A 开启 NFC，进入“NFC 贴纸模拟”，填写内容并激活，保持亮屏且页面在前台。
2. 设备 B 开启 NFC，进入“NFC 读取”，将两台设备的 NFC 感应区贴近。
3. B 展示识别到的协议、UID，以及可读取的 NDEF 消息十六进制数据。
4. 普通实体 NDEF 标签也可直接用读取页扫描；非 NDEF 卡片目前仅识别协议和 UID。

模拟端需要 HCE 支持；二维码功能不依赖 NFC。HCE 模拟的是 NDEF Type 4 Tag，不是 MIFARE Classic 门禁卡或固定 UID。

`应用直达` 模式写入 URI + AAR。系统或其他读取应用是否打开链接取决于其分发行为；本应用的读取页只展示数据。

## 开发环境与构建

- JDK 17、Android SDK 34
- Kotlin 1.9.0、Jetpack Compose / Material 3、ZXing 3.5.3
- minSdk 28、targetSdk / compileSdk 34
- Android Gradle Plugin 8.4.0、Gradle Wrapper 8.6

Windows PowerShell：

```powershell
.\gradlew.bat :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
.\gradlew.bat :app:connectedDebugAndroidTest
```

macOS / Linux 使用 `./gradlew`。SDK 路径配置在本机 `local.properties` 中。
`gradle.properties` 当前含本机 `127.0.0.1:7890` 代理配置；未运行对应代理时，请删除或调整该段。

Deep link：

```powershell
adb shell am start -a android.intent.action.VIEW -d "guanyun-test://checkin?point=A-001"
```

## 实现要点

- Manifest 申请 `android.permission.NFC`；HCE 服务用 `BIND_NFC_SERVICE` 限制绑定方，两者不可替代。
- 标准 AID：`D2760000850101`；CC 文件：`E103`；NDEF 文件：`E104`。
- T4T 2.0 NDEF 文件为 `[NLEN（2 字节大端）][NDEF message]`，不加入 `0x03` TLV 包装。
- 文件容量 4096 字节，完整 NDEF 消息最多 4094 字节；按编码后的字节数校验，包含记录头和 AAR。
- 空输入、非法 URI、超容量更新会停止模拟并提示；UPDATE BINARY 请求被拒绝。
- 前台优先使用公开 `CardEmulation.setPreferredService(activity, component)`，检查返回值，暂停时释放、恢复时重新申请。

## 验证状态

已在连接的 Xiaomi / Android 16 上验证：

- 调试 APK 构建、安装；HCE 注册、前台优先服务的激活 / 暂停 / 恢复 / 停止。
- 4 项仪器测试通过：应用上下文，以及三种 NDEF 记录回环、容量边界、UTF-8 / URI 校验。
- NFC 读取页进入 / 退出正确切换 Reader Mode。
- 实体 MIFARE Classic 门禁卡协议和 UID 识别，结果见上图。

双机完整 NDEF 无线读取尚未在本轮验证；上述测试不等同于所有标签与设备的兼容性保证。

## 目录

```text
app/src/main/java/com/example/guanyun_test/
├── MainActivity.kt
├── nfc/
│   ├── NdefTagSimulator.kt
│   ├── SimulatedNdefApduService.kt
│   └── NfcTagReader.kt
├── ui/
│   ├── HomeScreen.kt
│   ├── QrScreen.kt
│   ├── NfcScreen.kt
│   └── NfcReaderScreen.kt
└── util/QrCodeGenerator.kt

app/src/androidTest/   # 保留可重复运行的测试源码
scripts/verify_preferred.ps1  # 前台优先服务验证
docs/images/           # 三张真机截图与图标设计
```

临时构建日志、NFC dumpsys / logcat、UI dump、旧排查截图已清理；测试源码和验证脚本保留。运行验证脚本需连接已解锁且开启 NFC 的调试手机：

```powershell
.\scripts\verify_preferred.ps1
```

## English

An Android toolkit for text-to-QR, HCE NDEF Type 4 Tag emulation, and NFC reading. The reader displays tag technologies, UID and available NDEF message bytes in hexadecimal. Non-NDEF access cards are identified without reading authenticated sectors. The screenshots above show all three features, including a real MIFARE Classic access card result. End-to-end wireless NDEF transfer still needs two-device validation.

## License

MIT — see [LICENSE](LICENSE).