251 lines
6.2 KiB
Markdown
251 lines
6.2 KiB
Markdown
# NTAG424 綜合管理工具 v2.0
|
||
|
||
專業級 NTAG424 卡片管理解決方案，整合生產操作與品質測試功能。
|
||
|
||
## 🔧 重要修正記錄
|
||
|
||
### v2.2 - 新增 HTTP API 服務 (2024-01-XX)
|
||
- **新增功能**: CMAC 驗證 HTTP API 服務
|
||
- 提供 RESTful API 介面，支援遠端 CMAC 驗證
|
||
- 無需讀卡機硬體，純軟體驗證
|
||
- 支援多金鑰、多執行緒、CORS
|
||
- 適用場景：Web 應用、微服務、雲端部署
|
||
- 新增 API 文檔：`API_DOCUMENTATION.md`、`API_USAGE_GUIDE.md`
|
||
|
||
### v2.1 - 修正手動驗證模式 (2024-01-XX)
|
||
- **重要修正**: 手動驗證模式不再需要讀卡機
|
||
- 修正了手動驗證模式錯誤嘗試開啟讀卡機的問題
|
||
- 現在手動驗證完全基於軟體計算，支援離線驗證
|
||
- 適用場景：遠端驗證、批量驗證、測試環境、無硬體環境
|
||
- 新增專用測試腳本：`test_manual_verify.sh`
|
||
|
||
## 🚀 快速開始
|
||
|
||
```bash
|
||
# 啟動綜合管理工具
|
||
./ntag424_tool.sh
|
||
|
||
# 或直接使用 CLI 模式
|
||
./nt4h_c_example verify --key 1
|
||
./nt4h_c_example setsdm --url 1 --key 1
|
||
./nt4h_c_example getuid --key 1
|
||
```
|
||
|
||
## 📋 功能特色
|
||
|
||
### 🏭 **生產功能**
|
||
- **單卡操作模式**: 互動式單張卡片處理
|
||
- **批量操作模式**: 大量卡片自動化處理
|
||
- **質量檢測模式**: 完整的 6 項品質檢測
|
||
|
||
### 🌐 **API 服務**
|
||
- **HTTP API 服務**: RESTful CMAC 驗證 API
|
||
- **多平台支援**: Linux64、ARM64、ARM32
|
||
- **遠端驗證**: 無需讀卡機硬體的純軟體驗證
|
||
- **高併發支援**: 多執行緒處理，支援同時多個請求
|
||
|
||
### 🧪 **測試功能**
|
||
- **完整功能測試**: 21 項全面測試
|
||
- **新卡片處理測試**: 空白卡片處理流程
|
||
- **壓力測試**: 高頻操作穩定性測試
|
||
- **API 測試**: 自動化 API 功能測試
|
||
|
||
### 🔧 **工具功能**
|
||
- **操作日誌**: 自動記錄所有操作
|
||
- **操作報告**: 生成詳細的執行報告
|
||
- **系統狀態檢查**: 環境與設備狀態監控
|
||
|
||
## 💼 生產環境使用
|
||
|
||
### 批量卡片處理
|
||
```bash
|
||
# 啟動工具選擇 "2) 批量操作模式"
|
||
./ntag424_tool.sh
|
||
|
||
# 輸入參數：
|
||
# - 卡片數量: 100
|
||
# - 操作類型: setup (設定 SDM)
|
||
# - 靜默模式: y
|
||
```
|
||
|
||
### 質量檢測流程
|
||
```bash
|
||
# 啟動工具選擇 "3) 質量檢測模式"
|
||
./ntag424_tool.sh
|
||
|
||
# 自動執行 6 項檢測：
|
||
# 1. 讀卡機連接檢測
|
||
# 2. 卡片識別檢測
|
||
# 3. SDM 功能檢測
|
||
# 4. NDEF 格式檢測
|
||
# 5. MAC 驗證檢測
|
||
# 6. 手動驗證檢測
|
||
|
||
# 品質得分：
|
||
# 95%+ : 🏆 優秀品質
|
||
# 80%+ : ⚠️ 良好品質
|
||
# <80% : ❌ 品質不合格
|
||
```
|
||
|
||
## 🔄 CLI 自動化模式
|
||
|
||
### 基本操作
|
||
```bash
|
||
# 讀取 UID (安靜模式)
|
||
./nt4h_c_example getuid --quiet --key 1
|
||
|
||
# 設定 SDM (使用第1個URL和金鑰)
|
||
./nt4h_c_example setsdm --quiet --url 1 --key 1
|
||
|
||
# 驗證 CMAC (安靜模式)
|
||
./nt4h_c_example verify --quiet --key 1
|
||
|
||
# 手動驗證 (URL 模式)
|
||
./nt4h_c_example verify --manual --quiet --url "https://example.com/test?uid=...&ctr=...&cmac=..." --key 1
|
||
|
||
# 啟動 API 服務器
|
||
./cmac_api_server 8888
|
||
|
||
# API 驗證 (HTTP 請求)
|
||
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
|
||
```
|
||
|
||
### 高級操作
|
||
```bash
|
||
# 變更金鑰
|
||
./nt4h_c_example changekey --quiet --auth-key 1 --new-key 2 --old-key 1 --key-no 0
|
||
|
||
# 手動驗證 (參數模式)
|
||
./nt4h_c_example verify --manual --quiet --uid 0487715AD51F90 --ctr 000010 --cmac 8970E5C778F4234C --key 1
|
||
```
|
||
|
||
## 🌐 HTTP API 服務
|
||
|
||
### 快速開始
|
||
```bash
|
||
# 啟動 API 服務器
|
||
./cmac_api_server 8888
|
||
|
||
# 健康檢查
|
||
curl "http://localhost:8888/health"
|
||
|
||
# CMAC 驗證
|
||
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
|
||
```
|
||
|
||
### API 端點
|
||
- `GET /verify` - CMAC 驗證 (需要 uid, ctr, cmac, key 參數)
|
||
- `GET /health` - 健康檢查
|
||
- `GET /` - API 說明頁面
|
||
|
||
### 程式化呼叫範例
|
||
```javascript
|
||
// JavaScript 範例
|
||
const response = await fetch('http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1');
|
||
const result = await response.json();
|
||
console.log(result.success ? '✅ 驗證成功' : '❌ 驗證失敗');
|
||
```
|
||
|
||
### 詳細文檔
|
||
- `API_USAGE_GUIDE.md` - 簡潔使用說明
|
||
- `API_DOCUMENTATION.md` - 完整技術文檔
|
||
- `test_api.sh` - API 功能測試腳本
|
||
```
|
||
|
||
## 📁 配置檔案
|
||
|
||
### keys.txt
|
||
```
|
||
# AES 金鑰配置 (每行一個16進位金鑰)
|
||
00000000000000000000000000000000
|
||
11111111111111111111111111111111
|
||
22222222222222222222222222222222
|
||
...
|
||
```
|
||
|
||
### urls.txt
|
||
```
|
||
# URL 模板配置 (每行一個URL)
|
||
https://nodered.contree.app/test
|
||
https://example.com/nfc
|
||
https://myserver.com/verify
|
||
...
|
||
```
|
||
|
||
## 📊 監控與報告
|
||
|
||
### 即時監控
|
||
- 操作成功率統計
|
||
- 執行時間追蹤
|
||
- 錯誤詳細記錄
|
||
- 系統資源監控
|
||
|
||
### 自動報告
|
||
- 每次退出自動生成報告
|
||
- 包含操作統計與系統資訊
|
||
- 檔名格式: `ntag424_report_YYYYMMDD_HHMMSS.txt`
|
||
|
||
### 日誌系統
|
||
- 所有操作自動記錄到 `ntag424_operations.log`
|
||
- 時間戳記 + 操作類型 + 結果 + 詳細資訊
|
||
- 支援日誌查看與分析
|
||
|
||
## 🛠️ 新卡片處理
|
||
|
||
### 自動檢測
|
||
- 空白 NDEF 檔案自動識別
|
||
- 友善錯誤提示訊息
|
||
- 操作指引建議
|
||
|
||
### 處理流程
|
||
```bash
|
||
# 檢測新卡片時的建議流程：
|
||
1. ./nt4h_c_example setsdm --url 1 --key 1 # 先設定 SDM
|
||
2. ./nt4h_c_example verify --key 1 # 再進行驗證
|
||
```
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 常見問題
|
||
1. **讀卡機未檢測到**
|
||
- 檢查 USB 連接
|
||
- 執行 `lsusb | grep uFR`
|
||
|
||
2. **NDEF 格式驗證失敗**
|
||
- 使用新卡片處理測試
|
||
- 先執行 SDM 設定
|
||
|
||
3. **MAC 驗證失敗**
|
||
- 檢查金鑰是否正確
|
||
- 確認 SDM 已正確設定
|
||
|
||
### 系統需求
|
||
- Linux 64-bit
|
||
- uFR 讀卡機驅動
|
||
- NTAG424 DNA 卡片
|
||
- bash 4.0+
|
||
|
||
## 📈 性能指標
|
||
|
||
### 基準測試
|
||
- 單次讀取 UID: ~200ms
|
||
- 單次 SDM 設定: ~500ms
|
||
- 單次 CMAC 驗證: ~300ms
|
||
- 批量處理: ~1秒/卡
|
||
|
||
### 建議使用場景
|
||
- **小批量 (<50張)**: 單卡操作模式
|
||
- **中批量 (50-200張)**: 批量操作模式
|
||
- **大批量 (>200張)**: CLI 自動化腳本
|
||
- **品質控制**: 質量檢測模式
|
||
|
||
## 📞 技術支援
|
||
|
||
如需技術支援或功能建議，請檢查：
|
||
1. 系統狀態 (工具選項 9)
|
||
2. 操作日誌 (工具選項 7)
|
||
3. 操作報告 (工具選項 8)
|
||
|
||
---
|
||
|
||
**NTAG424 綜合管理工具 v2.0** - 專業、可靠、高效的 NTAG424 解決方案 |