GitHubHelp

mastashake08/nfc_ble_client

Python script that connects to my esp32 connected to my PN532 NFC Hat

★ 0Forks 0PythonGitHub ↗Compare

README

XIAO NFC Bridge - Python BLE Client

A cross-platform Python CLI client built with bleak that interfaces with the XIAO-NFC-Bridge ESP32-S3 firmware.

This tool replicates the core writing and reading capabilities of iOS/Android applications like NFC Tools, allowing you to queue NDEF payloads over Bluetooth Low Energy (BLE) and send them directly to a target NFC tag via an ESP32-S3 + PN532 setup.

Features

  • Live NFC Scan Notifications: Automatically listens for tag scans and prints decoded NDEF data in real time without interrupting terminal input.
  • Full NFC Tools Feature Parity:
    • Plain Text: Plain NDEF text records.
    • Web URLs / URIs: Standard http:// or https:// links.
    • iOS Shortcuts: Launch iOS Shortcuts automatically via shortcuts://.
    • GEO Location: Coordinates (geo:lat,lon) that open default map applications.
    • Wi-Fi Network Setup: Native Wi-Fi credential records (WIFI:S:...).
    • vCard Contacts: Standard contact cards for instant phone contact saving.
    • Calls / SMS / FaceTime: Direct action links (tel:, sms:, facetime:).
    • Payment & Social Links: Direct handles for PayPal, Venmo, CashApp, and social profiles.
    • Crypto Wallet Addresses: Bitcoin and Ethereum URI schemes (bitcoin:, ethereum:).
    • Android Application Records (AAR): Automatically open or prompt installation of specific Android packages via android.com:pkg.
    • Custom Schemes / Raw Payloads: Send arbitrary custom URI protocols or text strings.

Requirements

  • Python 3.8+
  • An active Bluetooth adapter on your host machine (macOS, Linux, or Windows).
  • An ESP32-S3 running the XIAO-NFC-Bridge firmware.

Installation

  1. Clone or navigate to the repository: 
    cd xiao-nfc-bridge/client


2. **Create a virtual environment (optional but recommended):**
```bash
python3 -m venv venv
source venv/bin/dev/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install bleak

Usage

  1. Power on your ESP32-S3 board. Ensure the firmware is running and advertising as XIAO-NFC-Bridge.
  2. Run the script:
python nfc_ble_client.py

Execution Flow

  1. The client scans for BLE devices advertising the name XIAO-NFC-Bridge with Service UUID 4fafc201-1fb5-459e-8fcc-c5c9c331914b.
  2. Upon connection, it subscribes to the Read Characteristic (beb5483e-...) for live tag notifications.
  3. The interactive menu presents 12 options for staging NDEF payloads.
  4. When an option is selected, the client writes the formatted string payload to the Write Characteristic (82910d19-...).
  5. Tap an NFC tag against the PN532 antenna — the firmware writes the staged payload to the tag and sends a confirmation back over BLE.

NDEF Formatting Details

Selection Output Format / URI Scheme NDEF Type / Payload
1. Text Sample text Well-Known / Text (T)
2. Web URL https://example.com Well-Known / URI (U)
3. iOS Shortcut shortcuts://run-shortcut?name=MyShortcut Well-Known / URI (U)
4. Location geo:37.7749,-122.4194 Well-Known / URI (U)
5. Wi-Fi Setup WIFI:S:MySSID;T:WPA;P:MyPassword;; MIME Media (application/vnd.wfa.wsc)
6. Contact (vCard) BEGIN:VCARD\nVERSION:3.0\n... MIME Media (text/vcard)
7. Call / SMS / FaceTime tel:+1234567890, sms:..., facetime:... Well-Known / URI (U)
8. Payments https://paypal.me/user, https://cash.app/$user Well-Known / URI (U)
9. Crypto Wallet bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa Well-Known / URI (U)
10. Android App (AAR) aar:com.example.app External Type (android.com:pkg)

Troubleshooting

  • Device Not Found: Ensure Bluetooth is enabled on your computer and the ESP32-S3 is not already paired or connected to another BLE device.
  • Permission Errors (Linux): You may need sudo privileges or appropriate bluez permissions to perform BLE scans. Run:
sudo setcap cap_net_raw,cap_net_admin+eip $(eval readlink -f$(which python3))
  • Write Failures on Tag: Check the serial monitor on the ESP32-S3 to verify the tag has sufficient NTAG pages available for larger payloads (e.g., vCards or complex Wi-Fi records).

Contributors

mastashake08

Issues