GTK4 NFC Explorer App for the Raspberry Pi
by NFCRenCS in Circuits > Raspberry Pi
148 Views, 0 Favorites, 0 Comments
GTK4 NFC Explorer App for the Raspberry Pi
PTX205R GTK4 Reader is a desktop application for the Raspberry Pi 5. It uses the Renesas RUL SDK to control a PTX205R NFC reader over SPI. It is a GTK4 front end for the reader's main functions.
Discovery: Start polling for NFC cards of RF technologies A, B, F and V. All cards in the field are listed in a table, with RF technology, protocol, ID, bit rate and technology-specific details. The list keeps cards that have already left the field.
NDEF: Read NDEF messages from a card and see the decoded records (URI, Text, Smart Poster, MIME and others) next to the raw bytes. You can also build a message from standard record types and write it to a card. The types are URI, Text, Smart Poster, phone, email, SMS, geo location, vCard, Wi-Fi and Android app.
Polling: Adjust the discovery parameters, such as the idle time and the card limit per RF technology.
HCE: Make the PTX205R emulate an NFC Forum Type 4 tag that a phone or another reader can read and write.
The reader is initialized in a background thread at startup. Discovery, NDEF operations and card emulation run in a worker thread, so the UI stays responsive. A menu offers About and Preferences windows, with a dark-mode setting that is stored between sessions. Keyboard shortcuts reset discovery, quit the application and open Preferences.
The project originally started with the SDK's NFC_FORUM_BASIC_DISCOVERY example. It aims to show how to integrate the RUL SDK and its reference SPI HAL and OSAL into a GUI application.
Supplies
Hardware
- Raspberry Pi 5 with SPI enabled
- PTX205R EB
Software
- Raspberry Pi OS Trixie
- build-essential
- libgtk-4-dev
- libglib2.0-dev-bin
- pkg-config
- cmake
- Project source code
NFC Tag(s)
- Type 2, 3, 4 or 5
- RF-technology A, B, F or V
Prepare the PTX205R Evaluation Board
On the PTX205R EB solder the jumpers for:
- MCU OFF
- PMOD_VDD TO VDD_IO
Also solder a PMOD connector, if it's not already there.
Prepare the Raspberry Pi 5
Enable SPI
Turn on Preferences -> Control Center -> Interfaces -> SPI.
Or using the command line:
Install Required Packages
Prerequisites for Raspberry Pi OS Trixie:
Connect the Board to the Raspberry
Connect the PTX205R EB PMOD to the Raspberry Pi 5 SPI pins:
- MOSI: GPIO 10
- MISO: GPIO 9
- SCK: GPIO 11
- NSS: GPIO 7
- IRQ: GPIO 19
- SEN: GPIO 21
- GND: GND
Plug in the PTX205R EB's USB-C port for power.
Clone the Repository
GitHub repository: renesas/ptx-rul-gtk: RUL SDK with GTK GUI
Build and Run
Build
Build from PROJECTS/PTX2xxR/NFC_EXPLORER:
The preset builds into BUILD/ for Linux and SPI, with console printing and file logging.
Run
It can be started from any directory. It finds its schema in BUILD/schemas/ and libRUL.so next to the executable. For this to work, SPI must be enabled and your user must be in the spi and gpio groups. LogOutput.txt is written to the current directory.
To start over, delete the contents of BUILD/ except .gitkeep.
Building the AppImage
Prerequisites: the packages above, plus curl, and internet access the first time. The script downloads linuxdeploy, its GTK plugin and the AppImage plugin into tools/appimage/.cache/.
Build from the repository root:
The script:
- configures and builds a Release build in tools/appimage/build/
- installs it into an AppDir and compiles the settings schema
- bundles GTK4 and its libraries and libRUL.so
- writes PTX205R_NFC_Explorer-<version>-aarch64.AppImage to the repository root
The version comes from SRC/EXAMPLES/ptx_NFCExplorer/ptx_Version.h.
Run it on any Raspberry Pi 5 with Trixie or newer, without installing GTK4:
The target needs FUSE 2 (sudo apt install libfuse2t64), or start it with --appimage-extract-and-run.
Portability: the AppImage runs on systems with the same or a newer glibc than the build machine.
NFC Discovery, NDEF Read-write, Host Card Emulation
The tabs are Discovery, NDEF, Polling and HCE. While discovery or emulation is running, you can't switch tabs. All tabs stay disabled until the PTX205R has finished initializing.
Polling
Sets the discovery parameters. They apply the next time discovery starts.
General:
- The idle time between polling cycles (default 100 ms) and low power card detection (LPCD). LPCD can be off, on every cycle, or regular polling only every n-th cycle.
Per technology (A, B, F, V):
- enable or disable the technology
- poll it only every n-th cycle (1–10)
- set the maximum number of devices resolved per cycle
- Type-F bit rate: 212 or 424 kbit/s.
RESTORE DEFAULTS resets everything.
Discovery
Finds the cards in the reader's field.
START/STOP starts and stops polling for RF technologies A, B, F and V. RESET clears the list and restarts discovery.
Each card is one row in a table. The columns are number, RF technology, protocol, bit rate, ID (NFCID1, NFCID0, NFCID2 or UID), detection count and technology-specific details. The tooltip on Details shows the complete SENS_RES/SEL_RES, SENSB_RES, SENSF_RES or INVENTORY_RES.
The tab supports several cards at once. Cards stay in the list after they leave the field, and the list is cleared on restart. It holds up to 50 entries.
A card is only activated when it is alone in the field. If there are several cards, the protocols they support are listed instead.
NDEF
Reads and writes NDEF messages on one card.
Read:
- READ starts discovery and STOP ends it. CLEAR empties the output.
- When a card is activated, the output shows a summary line (technology, protocol, ID). The decoded records and the raw bytes follow.
- The decoder handles URI, Text, Smart Poster, MIME, absolute URI, external type and empty records. Any other record is shown as hex.
- A malformed message shows the records parsed so far, with a warning.
Write:
- Pick a record type, fill in the fields and click ADD. REMOVE deletes the selected record and CLEAR deletes all of them.
- The available types are URI, Text, Smart Poster, Phone, Email, SMS, Geo location, vCard, MIME, Wi-Fi and Android app.
- The message is limited to 256 bytes. The list shows its size and raw bytes.
- WRITE writes the message to the first activated card and then stops discovery. If no card is activated within about 10 polling cycles, it gives up. The card must already be NDEF-formatted.
- A status line reports the result.
HCE
Makes the PTX205R act as an NFC-A Type 4 tag (host card emulation), so that a phone or another reader can read or write it.
The tag's NDEF message is built with the same editor as on the NDEF tab. The default is the URI https://www.renesas.com/en/products/ptx205r.
START/STOP starts and stops the emulation. Every START resets the tag to the message in the editor. The editor is locked while the emulation is running.
The tag is writable. If a reader writes a new NDEF message, it appears under Message written by reader, decoded and as raw bytes. It is then served until you click STOP.
The Emulation log shows what happens during the session.
Q-Measurement
This tab measures the Q factor of the NFC antenna. The PTX sweeps a frequency range centered on 13.56 MHz and measures the RF amplitude at each step. The amplitude is plotted live in a graph.
Settings
Frequency span is the sweep range, 13.56 MHz ± span/2. The default is 3000 kHz.
Frequency step is the distance between measurement points. The default is 5 kHz. A sweep may have at most 1000 points.
ADC averaging is the number of ADC samples averaged per frequency (1–32). The default is 8.
Result
When the sweep completes, the peak amplitude gives the resonance frequency.
The −3 dB corners are the frequencies on both sides where the amplitude falls to 0.708 of the peak. They are drawn in the graph.
Q = f_res / (f_upper − f_lower). The tab also shows the bandwidth.
If a corner falls outside the sweep range, no result is shown. Increase the span or decrease the step.
If the ADC clips, the sweep stops and shows the frequency where it happened. Reduce the signal level.
Buttons
START/STOP runs or aborts a sweep. A stopped sweep gives no result.
EXPORT CSV saves the last sweep, including the settings and result.
RESTORE DEFAULTS resets the settings.
The other tabs are locked while a measurement is running.
Q-Factor
Q-factor of an NFC antenna tells you how efficiently the antenna's LC resonant circuit stores energy compared to how much it loses in resistance.
Q = f₀ / BW = ωL / R (f₀ = resonant frequency, 13.56 MHz; BW = −3 dB bandwidth; R = total series loss)
Why it matters
Higher Q: stronger field and better read range, with higher voltage on the antenna for the same drive.
Too high Q: narrow bandwidth. The modulation sidebands get attenuated, which limits data rate and causes ringing. It also makes the antenna very sensitive to detuning.
Too low Q: wasted power and a weak field.
Typical NFC antennas are designed for a Q of roughly 10–30, depending on the data rate and protocol.
What you use it for
Tuning the antenna to 13.56 MHz and checking the match.
Detecting losses from nearby metal, ferrite or a tag/card (loading lowers Q and shifts f₀).
Verifying the design balances range against bandwidth and timing (rise/fall times).
Conclusion
This application demonstrates how easy it is to integrate the RUL SDK and the PTX205R into a working NFC reader GUI application, using GTK4 and the Raspberry Pi. It serves as an example and it can be a starting point or an inspiration for NFC reader applications.