Skip to content

Commit c9eacbc

Browse files
claudeclaude
committed
Add NFC CDC browser reader application
- Create Vite React TypeScript application with TailwindCSS - Implement WebUSB CDC communication layer for USB serial devices - Add NFC reader command handlers for ACS ACR518 and compatible readers - Build UI with reader connection, command buttons, and log output - Support card UID reading, MIFARE Classic operations, custom APDU - Configure GitHub Actions workflow for build and deploy to GitHub Pages - Set base path to ./ for proper GitHub Pages deployment https://claude.ai/code/session_016HeGaCzSEnvSn9LfUxEwAx
1 parent 79fdd51 commit c9eacbc

16 files changed

Lines changed: 5805 additions & 1 deletion

‎.github/workflows/deploy.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Build and Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: true
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@v4
24+
25+
- name: Setup Node.js
26+
uses: actions/setup-node@v4
27+
with:
28+
node-version: '20'
29+
cache: 'npm'
30+
31+
- name: Install dependencies
32+
run: npm ci
33+
34+
- name: Build
35+
run: npm run build
36+
37+
- name: Setup Pages
38+
uses: actions/configure-pages@v4
39+
40+
- name: Upload artifact
41+
uses: actions/upload-pages-artifact@v3
42+
with:
43+
path: './dist'
44+
45+
deploy:
46+
environment:
47+
name: github-pages
48+
url: ${{ steps.deployment.outputs.page_url }}
49+
runs-on: ubuntu-latest
50+
needs: build
51+
steps:
52+
- name: Deploy to GitHub Pages
53+
id: deployment
54+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist
12+
dist-ssr
13+
*.local
14+
15+
# Editor directories and files
16+
.vscode/*
17+
!.vscode/extensions.json
18+
.idea
19+
.DS_Store
20+
*.suo
21+
*.ntvs*
22+
*.njsproj
23+
*.sln
24+
*.sw?

‎README.md‎

Lines changed: 103 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,103 @@
1-
# nfc-cdc-browser-reader
1+
# NFC CDC Browser Reader
2+
3+
A web-based NFC reader interface that uses WebUSB to communicate with ACS ACR518 (ACR1281S-C1) and compatible NFC readers configured in CDC (serial) mode.
4+
5+
## Features
6+
7+
- **WebUSB CDC Communication**: Direct USB communication with NFC readers in CDC/serial mode
8+
- **Card UID Reading**: Read NFC card unique identifiers (MIFARE, ISO14443-A)
9+
- **Reader Commands**: Send common reader commands (firmware version, serial number, antenna control)
10+
- **MIFARE Classic Support**: Authenticate and read MIFARE Classic card blocks
11+
- **Custom APDU**: Send custom APDU commands for advanced operations
12+
- **Continuous Polling**: Auto-detect cards when placed on the reader
13+
- **LED/Buzzer Control**: Control reader LEDs and buzzer for feedback
14+
15+
## Supported Readers
16+
17+
- ACS ACR1281S-C1 (ACR518)
18+
- ACS ACR122U
19+
- ACS ACR1252U
20+
- Other ACS readers in CDC mode
21+
- Generic USB-CDC NFC readers
22+
23+
## Browser Requirements
24+
25+
WebUSB is required. Supported browsers:
26+
- Google Chrome (recommended)
27+
- Microsoft Edge
28+
- Opera
29+
30+
**Note**: Firefox and Safari do not support WebUSB.
31+
32+
## How to Read a Card UID
33+
34+
1. Open the application in a supported browser
35+
2. Click "Connect Reader" and select your NFC reader from the popup
36+
3. Place an NFC card on the reader
37+
4. Click "Get UID" to read the card's unique identifier
38+
39+
For continuous reading, click "Auto Poll" to automatically detect cards.
40+
41+
## Common APDU Commands
42+
43+
| Command | Description |
44+
|---------|-------------|
45+
| `FF CA 00 00 00` | Get Card UID |
46+
| `FF CA 01 00 00` | Get Card ATS/Historical Bytes |
47+
| `FF 00 48 00 00` | Get Firmware Version |
48+
| `FF 00 4A 00 00` | Get Serial Number |
49+
| `FF 00 52 0A 00` | Buzzer (100ms) |
50+
| `FF 82 00 00 06 FF FF FF FF FF FF` | Load Default Key |
51+
| `FF 86 00 00 05 01 00 BB 60 00` | Authenticate Block BB with Key A |
52+
| `FF B0 00 BB 10` | Read Block BB (16 bytes) |
53+
54+
## ACR518 CDC Mode Setup
55+
56+
To configure an ACS ACR1281S-C1 (ACR518) for CDC mode:
57+
58+
1. Use the ACS reader configuration tool
59+
2. Set the operation mode to "CDC" or "Serial"
60+
3. The reader will appear as a USB CDC device (COM port on Windows, ttyACM on Linux)
61+
62+
## Development
63+
64+
```bash
65+
# Install dependencies
66+
npm install
67+
68+
# Start development server
69+
npm run dev
70+
71+
# Build for production
72+
npm run build
73+
74+
# Preview production build
75+
npm run preview
76+
```
77+
78+
## Deployment
79+
80+
This project is configured to deploy to GitHub Pages automatically when pushing to the main branch.
81+
82+
The GitHub Actions workflow will:
83+
1. Install dependencies
84+
2. Build the project with `./` as the base path
85+
3. Deploy to GitHub Pages
86+
87+
## Technical Details
88+
89+
### Protocol
90+
91+
The application uses the USB CDC (Communications Device Class) protocol to communicate with NFC readers. For ACS readers in CDC mode:
92+
93+
- Commands are wrapped in a frame: `STX (0x02) + LEN (2 bytes) + DATA + ETX (0x03) + LRC`
94+
- APDU commands use the PC/SC-lite pseudo-APDU format with CLA=0xFF
95+
- Responses follow the same framing with SW1/SW2 status bytes
96+
97+
### Security Note
98+
99+
WebUSB requires user interaction to connect to devices, ensuring that web pages cannot access USB devices without explicit permission.
100+
101+
## License
102+
103+
MIT

‎index.html‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>📡</text></svg>" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>NFC CDC Browser Reader</title>
8+
</head>
9+
<body>
10+
<div id="root"></div>
11+
<script type="module" src="/src/main.tsx"></script>
12+
</body>
13+
</html>

0 commit comments

Comments
 (0)