🔧 NFC 生產工具

📋 專案概述

這是一個整合式的 NFC 生產工具，結合了 C 語言核心程式與 Flask Web 介面，提供完整的 NFC 卡片生產、認證和管理功能。支援 SDM 加密、CMAC 認證、API 整合等進階功能。

🎯 主要功能

• 📝 生產新SDM：完整的 SDM 生產流程（變更金鑰 → 設定SDM → CMAC認證 → API上傳）
• 🔍 檢驗NFC：本地認證成功後自動POST到檢驗API
• 🔐 本地CMAC認證：本地認證 + 遠端線上認證
• 🧪 完整測試NFC：預處理 + 完整功能測試
• 📖 讀取UID：批次讀取所有NFC卡片
• Web 管理介面：直觀的網頁操作介面
• URL 管理：線上編輯和管理 URLs.txt
• 即時監控：WebSocket 即時顯示執行狀態
• API 整合：支援 Bearer Token 認證的 API 通訊

🚀 快速開始

1. 系統需求

• 作業系統：Ubuntu 18.04+ / CentOS 7+ / Debian 9+
• Python：3.7 或以上版本
• 硬體：uFR NFC 讀卡機
• 網路：用於 API 通訊和遠端認證

2. 一鍵安裝

# 下載專案
git clone <repository-url>
cd ufr_zero_nt4h(WEB)

# 執行安裝腳本
chmod +x install.sh
./install.sh

安裝腳本功能：

• 🔍 自動檢測作業系統（Ubuntu/Debian/CentOS/RHEL）
• 📦 自動安裝系統依賴套件
• 🔌 設定 USB 裝置權限（uFR 讀卡機）
• 🐍 創建 Python 虛擬環境
• 📁 設定檔案權限
• ⚙️ 可選創建 systemd 服務
• 🧹 自動清理現有服務配置

3. 手動安裝

# 1. 安裝 Python 依賴
pip install -r requirements.txt

# 2. 設定執行權限
chmod +x linux64_release/nt4h_c_example
chmod +x start.sh

# 3. 啟動應用程式
./start.sh

4. 啟動方式

方式一：直接啟動

./start.sh

方式二：背景執行

nohup ./start.sh > app.log 2>&1 &

方式三：systemd 服務（推薦）

# 啟動服務
sudo systemctl start NFCapp.service

# 啟用開機自啟
sudo systemctl enable NFCapp.service

# 查看服務狀態
sudo systemctl status NFCapp.service

# 查看服務日誌
sudo journalctl -u NFCapp.service -f

5. 訪問應用程式

開啟瀏覽器訪問：http://localhost:5000

🔧 安裝腳本詳解

install.sh 功能說明

安裝腳本 install.sh 提供完整的自動化安裝流程：

🔍 系統檢測

• 自動檢測作業系統類型（Ubuntu/Debian/CentOS/RHEL）
• 檢查 Python 版本（需要 3.7+）
• 驗證必要檔案存在

📦 依賴安裝

• Ubuntu/Debian：安裝 python3, python3-pip, python3-venv, gcc, make, curl, wget
• CentOS/RHEL：安裝 python3, python3-pip, gcc, make, curl, wget

🔌 USB 權限設定

• 創建 udev 規則檔案 /etc/udev/rules.d/99-ufr.rules
• 支援多種 uFR 讀卡機型號（6001, 6014, 6015）
• 自動將使用者加入 dialout 群組
• 重新載入 udev 規則

🐍 Python 環境

• 檢查並重新創建虛擬環境（如果已存在）
• 升級 pip 到最新版本
• 安裝 requirements.txt 中的所有依賴

📁 檔案權限

• 設定執行檔權限
• 設定設定檔權限（keys.txt, urls.txt）

⚙️ systemd 服務管理

• 自動清理：檢查並刪除現有的 NFCapp.service
• 服務停止：停止正在運行的服務
• 服務禁用：禁用已啟用的服務
• 檔案刪除：刪除舊的服務檔案
• 配置重載：重新載入 systemd 配置
• 可選創建：詢問使用者是否創建新的 systemd 服務

🎨 使用者體驗

• 彩色日誌輸出（INFO, SUCCESS, WARNING, ERROR）
• 詳細的安裝進度顯示
• 完整的安裝完成資訊
• 服務管理指令說明

🎮 使用說明

主要操作

📝 生產新SDM

完整的 SDM 生產流程：

1. 自動尋找可用的 oldkey
2. 變更金鑰到選擇的 KEY
3. 設定 SDM 功能
4. 執行 CMAC 認證
5. 自動 POST 到生產 API

API 端點：{API_URL}/nfc/insertForProduction
POST 格式：

{
    "uid": "04296A5AD51F90",
    "ctr": "00000A",
    "key": "1"
}

🔍 檢驗NFC

檢驗現有 NFC 卡片：

1. 執行本地 CMAC 認證
2. 解析 UID
3. 自動 POST 到檢驗 API

API 端點：{API_URL}/nfc/verifyForProduction
POST 格式：

{
    "uid": "04296A5AD51F90"
}

🔐 本地CMAC認證

雙重認證流程：

1. 本地 CMAC 認證
2. 遠端線上認證（https://verify.contree.app/verify）

🧪 完整測試NFC

預處理 + 完整測試：

1. 讀取 UID 尋找可用 KEY
2. 強制更換到 key 1
3. 執行完整測試腳本

📖 讀取UID

批次讀取所有 NFC 卡片，找到第一個可讀取的卡片後停止。

設定選項

• 選擇 Key：選擇要使用的金鑰（從 keys.txt）
• 選擇 URL：選擇要寫入的 URL（從 urls.txt）
• 選擇 NFC 名稱：選擇或新增 NFC 卡片名稱
• 資料API URL：設定 API 伺服器位址
• API Token：設定 Bearer Token 認證

工具操作

• 🔄 重新整理選項：重新載入 keys.txt 和 urls.txt
• 🗑️ 清除執行結果：清除輸出區域內容
• ✏️ 編輯URL：開啟 URL 編輯視窗
• ⬇️ 到底部：自動滾動到輸出底部
• ⬆️ 到頂部：自動滾動到輸出頂部

📁 檔案結構

ufr_zero_nt4h(WEB)/
├── app.py                 # Flask Web 應用程式主檔
├── start.sh              # Linux 啟動腳本
├── requirements.txt      # Python 依賴套件
├── config.json          # 應用程式設定檔
├── templates/
│   ├── index.html       # 主頁面
│   └── manual_test.html # 手動測試頁面
├── linux64_release/     # Linux 64位執行檔目錄
│   ├── nt4h_c_example   # 核心 NFC 程式
│   ├── keys.txt         # 金鑰檔案
│   ├── urls.txt         # URL 設定檔
│   └── libnt4h_c.so     # uFR 函式庫
└── src/                 # C 語言原始碼
    ├── main.c          # 主程式
    ├── uFR.c           # uFR 介面
    └── utils.c         # 工具函式

⚙️ 設定說明

config.json

{
  "api_url": "https://your-api-server.com",
  "api_token": "Bearer eyJhbGciOiJIUzI1NiJ9...",
  "name": "default-name",
  "names": ["name1", "name2"]
}

API 設定

• 資料API URL：設定 API 伺服器基礎位址
• API Token：設定 Bearer Token 用於 API 認證
• 自動認證：所有 API 請求都會自動包含 Bearer Token

keys.txt

每行一個 AES 金鑰，用於 NFC 卡片加密。

urls.txt

每行一個 URL，前三行為系統保留，從第四行開始可編輯。

🔧 手動測試

訪問 http://localhost:5000/manual_test 進行手動測試：

• 快速 SDM 設定
• NDEF 操作
• 變更 AES 金鑰
• 讀取 UID
• 自定義指令執行
• 手動 CMAC 認證
• 手動 API 驗證

🌐 API 整合

支援的 API 端點

生產 API

• 端點：POST {API_URL}/nfc/insertForProduction
• 用途：新增生產的 NFC 卡片資料
• 認證：Bearer Token
• 資料格式：JSON

檢驗 API

• 端點：POST {API_URL}/nfc/verifyForProduction
• 用途：檢驗現有 NFC 卡片
• 認證：Bearer Token
• 資料格式：JSON

遠端認證 API

• 端點：GET https://verify.contree.app/verify
• 用途：線上 CMAC 認證
• 認證：無需認證
• 回應格式：JSON

API 回應範例

成功回應

{
  "success": true,
  "message": "Operation completed successfully",
  "timestamp": "2025-01-24T12:52:18Z"
}

錯誤回應

{
  "success": false,
  "message": "Error description",
  "error_code": "ERROR_CODE"
}

🐛 故障排除

常見問題

1. 讀卡機無法連接：檢查 uFR 讀卡機是否正確連接
2. 權限錯誤：確保執行檔有執行權限
3. 依賴缺失：執行 pip install -r requirements.txt
4. WebSocket 連接問題：檢查防火牆設定，確保 5000 端口開放
5. API 認證失敗：檢查 API Token 是否正確設定
6. 本地認證失敗：檢查 keys.txt 中的金鑰是否正確
7. 遠端認證失敗：檢查網路連接和遠端認證服務狀態
8. USB 權限問題：重新載入 udev 規則

   sudo udevadm control --reload-rules
   sudo udevadm trigger
   

9. systemd 服務問題：檢查服務狀態和日誌

   sudo systemctl status NFCapp.service
   sudo journalctl -u NFCapp.service -f
   

日誌查看

應用程式會即時顯示執行日誌，包含顏色標示和詳細錯誤訊息。

功能特色

• 即時輸出：WebSocket 即時顯示執行過程
• 顏色標示：支援 ANSI 顏色代碼顯示
• 自動重連：WebSocket 自動重連機制
• 錯誤處理：完整的錯誤處理和提示
• API 整合：自動 API 認證和資料上傳
• 雙重認證：本地 + 遠端認證機制
• 智能檢測：自動檢測可用金鑰和錯誤碼
• JSON 格式：標準化的 API 通訊格式

📞 技術支援

如有問題，請檢查：

1. 硬體連接是否正常
2. 設定檔是否正確
3. 執行日誌中的錯誤訊息

📋 更新日誌

v2.1.0 (2025-01-24)

• ✅ 改進安裝腳本功能
• ✅ 新增自動作業系統檢測
• ✅ 新增 USB 裝置權限自動設定
• ✅ 新增 systemd 服務自動管理
• ✅ 新增現有服務自動清理功能
• ✅ 改進錯誤處理和日誌顯示
• ✅ 新增多種啟動方式說明

v2.0.0 (2025-01-24)

• ✅ 新增「生產新SDM」完整流程
• ✅ 新增「檢驗NFC」功能
• ✅ 新增「本地CMAC認證」雙重認證
• ✅ 更新「完整測試NFC」預處理流程
• ✅ 整合 API 通訊功能
• ✅ 支援 Bearer Token 認證
• ✅ 新增 JSON 格式 API 通訊
• ✅ 改進錯誤處理和狀態檢測
• ✅ 新增遠端認證整合

v1.0.0 (2024-01)

• ✅ 基礎 NFC 生產工具
• ✅ Web 介面
• ✅ 手動測試功能

---

版本：2.1.0
更新日期：2025年1月24日