NFCcreate-web/linux64_release/DEVELOPER_MANUAL.md

# NTAG424 Linux64 Release 開發者操作手冊

## 📋 目錄
1. [概述](#概述)
2. [檔案結構](#檔案結構)
3. [快速開始](#快速開始)
4. [核心程式](#核心程式)
5. [API 服務](#api-服務)
6. [測試腳本](#測試腳本)
7. [配置檔案](#配置檔案)
8. [整合範例](#整合範例)
9. [故障排除](#故障排除)
10. [進階功能](#進階功能)

---

## 概述

`linux64_release` 資料夾包含完整的 NTAG424 卡片管理解決方案，提供：
- **硬體操作**：直接與 NTAG424 卡片互動
- **HTTP API**：遠端 CMAC 驗證服務
- **測試套件**：完整的自動化測試
- **生產工具**：批量處理和品質檢測

### 系統需求
- Linux 64-bit 系統
- uFR 讀卡機硬體
- NTAG424 DNA 卡片
- bash 4.0+

---

## 檔案結構

```
linux64_release/
├── 核心程式
│   ├── nt4h_c_example          # 主要 CLI 工具
│   ├── cmac_api_server         # HTTP API 服務器
│   └── libnt4h_c.so           # 動態函式庫
│
├── 配置檔案
│   ├── keys.txt               # AES 金鑰配置
│   └── urls.txt               # URL 模板配置
│
├── 測試腳本
│   ├── test_ntag424.sh        # 完整功能測試
│   ├── simple_test.sh         # 簡化測試
│   ├── test_api.sh            # API 功能測試
│   ├── test_manual_verify.sh  # 手動驗證測試
│   └── test_new_card.sh       # 新卡片處理測試
│
├── 生產工具
│   └── ntag424_tool.sh        # 綜合管理工具
│
├── 文檔
│   ├── README_API.md          # API 快速指南
│   ├── API_DOCUMENTATION.md   # 完整 API 文檔
│   ├── API_USAGE_GUIDE.md     # API 使用說明
│   └── README_PRODUCTION.md   # 生產環境指南
│
└── 日誌檔案
    └── ntag424_operations.log # 操作日誌
```

---

## 快速開始

### 1. 基本環境檢查
```bash
cd linux64_release

# 檢查必要檔案
ls -la nt4h_c_example keys.txt urls.txt

# 檢查讀卡機連接
lsusb | grep uFR
```

### 2. 基本操作
```bash
# 讀取卡片 UID
./nt4h_c_example getuid --key 1

# 設定 SDM 功能
./nt4h_c_example setsdm --url 1 --key 1

# 驗證 CMAC
./nt4h_c_example verify --key 1
```

### 3. 啟動 API 服務
```bash
# 啟動 API 服務器
./cmac_api_server 8888

# 測試 API
curl "http://localhost:8888/health"
```

---

## 核心程式

### nt4h_c_example - 主要 CLI 工具

#### 基本語法
```bash
./nt4h_c_example <command> [options]
```

#### 主要命令

##### 1. 讀取 UID
```bash
# 詳細模式
./nt4h_c_example getuid --key 1

# 安靜模式（僅輸出 UID）
./nt4h_c_example getuid --quiet --key 1
```

##### 2. 設定 SDM
```bash
# 使用 URL 索引 1 和金鑰 1
./nt4h_c_example setsdm --url 1 --key 1

# 安靜模式
./nt4h_c_example setsdm --quiet --url 1 --key 1
```

##### 3. CMAC 驗證
```bash
# 標準驗證（需要讀卡機）
./nt4h_c_example verify --key 1

# 手動驗證（無需讀卡機）
./nt4h_c_example verify --manual --uid 0456735AD51F90 --ctr 000028 --cmac 222ED1BA962F7F5C --key 1

# URL 方式手動驗證
./nt4h_c_example verify --manual --url "https://example.com/nfc?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C" --key 1
```

##### 4. NDEF 操作
```bash
# 寫入 NDEF
./nt4h_c_example writendef --url "https://example.com"

# 從檔案寫入
./nt4h_c_example writendef --url-index 1

# 讀取 NDEF
./nt4h_c_example readndef

# 安靜模式讀取
./nt4h_c_example readndef --quiet
```

##### 5. 金鑰管理
```bash
# 變更金鑰
./nt4h_c_example changekey --auth-key 1 --new-key 2 --old-key 1 --key-no 0
```

#### 參數說明
- `--key <index>`: 指定金鑰索引 (1-10)
- `--url <index>`: 指定 URL 索引 (1-4)
- `--quiet`: 安靜模式，僅輸出結果
- `--manual`: 手動驗證模式
- `--uid <uid>`: 手動指定 UID
- `--ctr <counter>`: 手動指定計數器
- `--cmac <cmac>`: 手動指定 CMAC

---

## API 服務

### cmac_api_server - HTTP API 服務器

#### 啟動服務
```bash
# 預設端口 8080
./cmac_api_server

# 指定端口
./cmac_api_server 8888
```

#### API 端點

##### 1. 健康檢查
```bash
curl "http://localhost:8888/health"
```

回應：
```json
{
  "success": true,
  "message": "CMAC Verification API is running",
  "timestamp": "2025-01-XX T15:30:14Z",
  "version": "1.0"
}
```

##### 2. CMAC 驗證
```bash
curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"
```

成功回應：
```json
{
  "success": true,
  "message": "CMAC verification successful",
  "timestamp": "2025-01-XX T15:30:14Z",
  "details": {
    "uid": "0456735AD51F90",
    "counter": "000028",
    "cmac": "222ED1BA962F7F5C",
    "key_index": 1
  }
}
```

失敗回應：
```json
{
  "success": false,
  "message": "CMAC verification failed (status: 0x000000CA)",
  "timestamp": "2025-01-XX T15:30:14Z"
}
```

##### 3. API 說明頁面
```bash
curl "http://localhost:8888/"
```

---

## 測試腳本

### 1. test_ntag424.sh - 完整功能測試
```bash
# 執行完整測試套件（32項測試）
./test_ntag424.sh
```

**測試內容：**
- NDEF 功能測試
- SDM 相關測試
- 手動驗證測試
- 錯誤處理測試
- 金鑰管理測試

### 2. simple_test.sh - 簡化測試
```bash
# 執行基本功能測試（9項測試）
./simple_test.sh
```

**適用場景：**
- 快速功能驗證
- 開發過程中的基本測試
- 新環境部署驗證

### 3. test_api.sh - API 功能測試
```bash
# 測試 API 服務功能
./test_api.sh
```

**測試內容：**
- 健康檢查
- CMAC 驗證
- 錯誤處理
- 參數驗證

### 4. test_manual_verify.sh - 手動驗證測試
```bash
# 測試手動驗證功能
./test_manual_verify.sh
```

**測試內容：**
- 參數方式手動驗證
- URL 方式手動驗證
- 格式驗證
- 錯誤處理

### 5. test_new_card.sh - 新卡片處理測試
```bash
# 測試新卡片處理流程
./test_new_card.sh
```

**測試內容：**
- 空白卡片檢測
- 設定流程指導
- 錯誤訊息驗證

---

## 配置檔案

### keys.txt - AES 金鑰配置
```
# 每行一個 32 位十六進位金鑰
00000000000000000000000000000000
00112233445566778899AABBCCDDEEFF
AABBCCDDEEFF00112233445566778899
12345678901234567890123456789012
```

**說明：**
- 第 1 行對應金鑰索引 1
- 第 2 行對應金鑰索引 2
- 最多支援 10 個金鑰
- 每個金鑰必須是 32 位十六進位字元

### urls.txt - URL 模板配置
```
https://nodered.contree.app/nfc
https://nodered.contree.app/test
https://www.google.com/
https://tatalotest1.gsct.tw/nfcWeb
```

**說明：**
- 每行一個 URL 模板
- 用於 SDM 設定時的 URL 選擇
- 支援動態參數（UID、計數器、CMAC）

---

## 整合範例

### JavaScript 整合
```javascript
// 驗證 CMAC
async function verifyCMAC(uid, ctr, cmac, keyIndex) {
    const url = `http://localhost:8888/verify?uid=${uid}&ctr=${ctr}&cmac=${cmac}&key=${keyIndex}`;
    
    try {
        const response = await fetch(url);
        const result = await response.json();
        
        if (result.success) {
            console.log('✅ CMAC 驗證成功');
            return true;
        } else {
            console.log('❌ CMAC 驗證失敗:', result.message);
            return false;
        }
    } catch (error) {
        console.error('API 呼叫失敗:', error);
        return false;
    }
}

// 使用範例
verifyCMAC('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1);
```

### Python 整合
```python
import requests
import json

def verify_cmac(uid, ctr, cmac, key_index, host='localhost', port=8888):
    """驗證 NTAG424 CMAC"""
    url = f"http://{host}:{port}/verify"
    params = {
        'uid': uid,
        'ctr': ctr,
        'cmac': cmac,
        'key': key_index
    }
    
    try:
        response = requests.get(url, params=params, timeout=5)
        result = response.json()
        
        if result['success']:
            print(f"✅ CMAC 驗證成功: {result['message']}")
            return True
        else:
            print(f"❌ CMAC 驗證失敗: {result['message']}")
            return False
            
    except requests.RequestException as e:
        print(f"請求錯誤: {e}")
        return False

# 使用範例
verify_cmac('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1)
```

### PHP 整合
```php
<?php
function verifyCMAC($uid, $ctr, $cmac, $keyIndex, $host = 'localhost', $port = 8888) {
    $url = "http://{$host}:{$port}/verify?" . http_build_query([
        'uid' => $uid,
        'ctr' => $ctr,
        'cmac' => $cmac,
        'key' => $keyIndex
    ]);
    
    $response = file_get_contents($url);
    $result = json_decode($response, true);
    
    if ($result['success']) {
        echo "✅ 驗證成功\n";
        return true;
    } else {
        echo "❌ 驗證失敗: " . $result['message'] . "\n";
        return false;
    }
}

// 使用範例
verifyCMAC('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1);
?>
```

### Node.js 整合
```javascript
const http = require('http');

function verifyCMAC(uid, ctr, cmac, keyIndex) {
    return new Promise((resolve, reject) => {
        const url = `http://localhost:8888/verify?uid=${uid}&ctr=${ctr}&cmac=${cmac}&key=${keyIndex}`;
        
        http.get(url, (res) => {
            let data = '';
            
            res.on('data', (chunk) => {
                data += chunk;
            });
            
            res.on('end', () => {
                try {
                    const result = JSON.parse(data);
                    if (result.success) {
                        console.log('✅ CMAC 驗證成功');
                        resolve(true);
                    } else {
                        console.log('❌ CMAC 驗證失敗:', result.message);
                        resolve(false);
                    }
                } catch (error) {
                    reject(error);
                }
            });
        }).on('error', (error) => {
            reject(error);
        });
    });
}

// 使用範例
verifyCMAC('0456735AD51F90', '000028', '222ED1BA962F7F5C', 1)
    .then(result => console.log('驗證結果:', result))
    .catch(error => console.error('錯誤:', error));
```

---

## 故障排除

### 常見問題

#### 1. 讀卡機未檢測到
**症狀：** 程式無法找到讀卡機
**解決方案：**
```bash
# 檢查 USB 連接
lsusb | grep uFR

# 檢查驅動
lsmod | grep ftdi

# 重新插拔讀卡機
```

#### 2. NDEF 格式驗證失敗
**症狀：** 驗證時出現 NDEF 格式錯誤
**解決方案：**
```bash
# 檢查卡片是否為新卡片
./nt4h_c_example readndef

# 如果是新卡片，先設定 SDM
./nt4h_c_example setsdm --url 1 --key 1

# 然後再驗證
./nt4h_c_example verify --key 1
```

#### 3. MAC 驗證失敗
**症狀：** CMAC 驗證失敗
**解決方案：**
```bash
# 檢查金鑰是否正確
cat keys.txt

# 確認使用正確的金鑰索引
./nt4h_c_example verify --key 1

# 檢查 SDM 是否正確設定
./nt4h_c_example setsdm --url 1 --key 1
```

#### 4. API 服務無法啟動
**症狀：** API 服務器啟動失敗
**解決方案：**
```bash
# 檢查端口是否被占用
netstat -tlnp | grep 8888

# 使用不同端口
./cmac_api_server 9999

# 檢查檔案權限
chmod +x cmac_api_server
```

#### 5. 手動驗證模式錯誤
**症狀：** 手動驗證時出現格式錯誤
**解決方案：**
```bash
# 檢查 UID 格式（14位十六進位）
echo "0456735AD51F90" | wc -c  # 應該是 15（包含換行符）

# 檢查計數器格式（6位十六進位）
echo "000028" | wc -c  # 應該是 7

# 檢查 CMAC 格式（16位十六進位）
echo "222ED1BA962F7F5C" | wc -c  # 應該是 17
```

### 除錯技巧

#### 1. 啟用詳細輸出
```bash
# 移除 --quiet 參數查看詳細輸出
./nt4h_c_example verify --key 1
```

#### 2. 檢查日誌檔案
```bash
# 查看操作日誌
tail -f ntag424_operations.log

# 查看最近的錯誤
grep "FAILED" ntag424_operations.log | tail -10
```

#### 3. 使用測試腳本診斷
```bash
# 執行完整測試診斷問題
./test_ntag424.sh

# 執行簡化測試快速檢查
./simple_test.sh
```

---

## 進階功能

### 1. 批量處理
```bash
# 使用綜合管理工具進行批量操作
./ntag424_tool.sh

# 選擇 "2) 批量操作模式"
# 輸入卡片數量和操作類型
```

### 2. 品質檢測
```bash
# 執行完整的品質檢測
./ntag424_tool.sh

# 選擇 "3) 質量檢測模式"
# 自動執行 6 項品質檢測
```

### 3. 生產報告
```bash
# 生成操作報告
./ntag424_tool.sh

# 選擇 "8) 生成操作報告"
# 查看詳細的統計資訊
```

### 4. 系統監控
```bash
# 檢查系統狀態
./ntag424_tool.sh

# 選擇 "9) 系統狀態檢查"
# 查看環境和設備狀態
```

### 5. 自定義配置
```bash
# 修改金鑰配置
vim keys.txt

# 修改 URL 配置
vim urls.txt

# 重新啟動服務
pkill cmac_api_server
./cmac_api_server 8888
```

---

## 性能指標

### 基準測試結果
- **單次讀取 UID**: ~200ms
- **單次 SDM 設定**: ~500ms
- **單次 CMAC 驗證**: ~300ms
- **API 回應時間**: ~50ms
- **批量處理速度**: ~1秒/卡

### 建議使用場景
- **小批量 (<50張)**: 單卡操作模式
- **中批量 (50-200張)**: 批量操作模式
- **大批量 (>200張)**: CLI 自動化腳本
- **品質控制**: 質量檢測模式
- **遠端驗證**: HTTP API 服務

---

## 技術支援

### 獲取幫助
1. **查看系統狀態**: `./ntag424_tool.sh` → 選項 9
2. **檢查操作日誌**: `./ntag424_tool.sh` → 選項 7
3. **生成操作報告**: `./ntag424_tool.sh` → 選項 8
4. **執行診斷測試**: `./test_ntag424.sh`

### 文檔資源
- `README_API.md` - API 快速指南
- `API_DOCUMENTATION.md` - 完整 API 文檔
- `API_USAGE_GUIDE.md` - API 使用說明
- `README_PRODUCTION.md` - 生產環境指南

---

**NTAG424 Linux64 Release v2.0**  
*專業、可靠、高效的 NTAG424 解決方案*

最後更新：2025-01-XX