ipwxp/NFCcreate-web

Fork 0

ipwxp fcccb1789b frist

2025-09-25 19:04:00 +08:00

14 KiB

Raw Blame History

NTAG424 Linux64 Release 開發者操作手冊

📋 目錄

概述
檔案結構
快速開始
核心程式
API 服務
測試腳本
配置檔案
整合範例
故障排除
進階功能

概述

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. 基本環境檢查

cd linux64_release

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

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

2. 基本操作

# 讀取卡片 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 服務

# 啟動 API 服務器
./cmac_api_server 8888

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

核心程式

nt4h_c_example - 主要 CLI 工具

基本語法

./nt4h_c_example <command> [options]

主要命令

1. 讀取 UID

# 詳細模式
./nt4h_c_example getuid --key 1

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

2. 設定 SDM

# 使用 URL 索引 1 和金鑰 1
./nt4h_c_example setsdm --url 1 --key 1

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

3. CMAC 驗證

# 標準驗證（需要讀卡機）
./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 操作

# 寫入 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. 金鑰管理

# 變更金鑰
./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 服務器

啟動服務

# 預設端口 8080
./cmac_api_server

# 指定端口
./cmac_api_server 8888

API 端點

1. 健康檢查

curl "http://localhost:8888/health"

回應：

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

2. CMAC 驗證

curl "http://localhost:8888/verify?uid=0456735AD51F90&ctr=000028&cmac=222ED1BA962F7F5C&key=1"

成功回應：

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

失敗回應：

{
  "success": false,
  "message": "CMAC verification failed (status: 0x000000CA)",
  "timestamp": "2025-01-XX T15:30:14Z"
}

3. API 說明頁面

curl "http://localhost:8888/"

測試腳本

1. test_ntag424.sh - 完整功能測試

# 執行完整測試套件（32項測試）
./test_ntag424.sh

測試內容：

NDEF 功能測試
SDM 相關測試
手動驗證測試
錯誤處理測試
金鑰管理測試

2. simple_test.sh - 簡化測試

# 執行基本功能測試（9項測試）
./simple_test.sh

適用場景：

快速功能驗證
開發過程中的基本測試
新環境部署驗證

3. test_api.sh - API 功能測試

# 測試 API 服務功能
./test_api.sh

測試內容：

健康檢查
CMAC 驗證
錯誤處理
參數驗證

4. test_manual_verify.sh - 手動驗證測試

# 測試手動驗證功能
./test_manual_verify.sh

測試內容：

參數方式手動驗證
URL 方式手動驗證
格式驗證
錯誤處理

5. test_new_card.sh - 新卡片處理測試

# 測試新卡片處理流程
./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 整合

// 驗證 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 整合

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
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 整合

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. 讀卡機未檢測到

症狀： 程式無法找到讀卡機 解決方案：

# 檢查 USB 連接
lsusb | grep uFR

# 檢查驅動
lsmod | grep ftdi

# 重新插拔讀卡機

2. NDEF 格式驗證失敗

症狀： 驗證時出現 NDEF 格式錯誤 解決方案：

# 檢查卡片是否為新卡片
./nt4h_c_example readndef

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

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

3. MAC 驗證失敗

症狀： CMAC 驗證失敗 解決方案：

# 檢查金鑰是否正確
cat keys.txt

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

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

4. API 服務無法啟動

症狀： API 服務器啟動失敗 解決方案：

# 檢查端口是否被占用
netstat -tlnp | grep 8888

# 使用不同端口
./cmac_api_server 9999

# 檢查檔案權限
chmod +x cmac_api_server

5. 手動驗證模式錯誤

症狀： 手動驗證時出現格式錯誤 解決方案：

# 檢查 UID 格式（14位十六進位）
echo "0456735AD51F90" | wc -c  # 應該是 15（包含換行符）

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

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

除錯技巧

1. 啟用詳細輸出

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

2. 檢查日誌檔案

# 查看操作日誌
tail -f ntag424_operations.log

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

3. 使用測試腳本診斷

# 執行完整測試診斷問題
./test_ntag424.sh

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

進階功能

1. 批量處理

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

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

2. 品質檢測

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

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

3. 生產報告

# 生成操作報告
./ntag424_tool.sh

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

4. 系統監控

# 檢查系統狀態
./ntag424_tool.sh

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

5. 自定義配置

# 修改金鑰配置
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 服務

技術支援

獲取幫助

查看系統狀態: ./ntag424_tool.sh → 選項 9
檢查操作日誌: ./ntag424_tool.sh → 選項 7
生成操作報告: ./ntag424_tool.sh → 選項 8
執行診斷測試: ./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

14 KiB Raw Blame History Unescape Escape

NTAG424 Linux64 Release 開發者操作手冊

📋 目錄

概述

系統需求

檔案結構

快速開始

1. 基本環境檢查

2. 基本操作

3. 啟動 API 服務

核心程式

nt4h_c_example - 主要 CLI 工具

基本語法

主要命令

1. 讀取 UID

2. 設定 SDM

3. CMAC 驗證

4. NDEF 操作

5. 金鑰管理

參數說明

API 服務

cmac_api_server - HTTP API 服務器

啟動服務

API 端點

1. 健康檢查

2. CMAC 驗證

3. API 說明頁面

測試腳本

1. test_ntag424.sh - 完整功能測試

2. simple_test.sh - 簡化測試

3. test_api.sh - API 功能測試

4. test_manual_verify.sh - 手動驗證測試

5. test_new_card.sh - 新卡片處理測試

配置檔案

keys.txt - AES 金鑰配置

urls.txt - URL 模板配置

整合範例

JavaScript 整合

Python 整合

PHP 整合

Node.js 整合

故障排除

常見問題

1. 讀卡機未檢測到

2. NDEF 格式驗證失敗

3. MAC 驗證失敗

4. API 服務無法啟動

5. 手動驗證模式錯誤

除錯技巧

1. 啟用詳細輸出

2. 檢查日誌檔案

3. 使用測試腳本診斷

進階功能

1. 批量處理

2. 品質檢測

3. 生產報告

4. 系統監控

5. 自定義配置

性能指標

基準測試結果

建議使用場景

技術支援

獲取幫助

文檔資源

14 KiB

Raw Blame History