Article Contents

Hardware

How to Control VTAP from Background (Windows)

Richard Grundy

Updated December 17, 2024 05:34

Overview

The VTAP series of NFC readers from DotOrigin are popular because of their ease of use and broad compatibility. For most NFC targets, the VTAPs are plug and play out of the box due to their convenient Keyboard mode. They essentially act like a keyboard and stream out whatever data they read over NFC as keystrokes. This works ok when hosting the VTAP on a dedicated computer with your application in the foreground but can be problematic if you need to switch between applications while scanning. This guide covers how to setup a VTAP reader to read NFC targets from the background using it's (virtual) COM port interface over USB. vtap-reading-from-background

In this article, we're going to learn:

What a COM port is
How to configure the VTAP to operate in COM port mode
How to communicate with the VTAP over the COM port
How read passes over the COM port using Powershell

The best way to learn anything is by doing. Enter PassNinjaBot. We're going to build this simple application that controls the VTAP while running in the background. PassNinjaBot will detect PassNinja passes read by the VTAP, it will figure out some details about the pass holder, and it will greet them with a personalized welcome. To get this done, this tutorial assumes you have the following:

Windows computer with available USB port
Apple or Google Wallet pass issued by PassNinja
VTAP series NFC reader properly configured for PassNinja passes

What the heck is a COM port?

A COM port is just a simple way for hardware devices and computers to send and recieve serial data between each other - asynchronously. In our case for this tutorial, between a VTAP reader and your Mac. Due to it's legacy and popularity, most Operating Systems include standard COM port drivers that load when a COM port interface is detected on the USB scan chain. This triggers the OS to create a unique identifier for the COM port so that programs can detect, open, and close serial connections on the fly. We'll explore how to do that with the VTAP next.

Configuring the VTAP to operate in COM port mode

The VTAP can be configured into COM port mode by updating the config.txt file that appears when plugging it in over USB. The process is covered in the How to Configure VTAP guide. You'll need to enable the COM port keys and disable the keyboard emulation key to conceal reader activity into the background. Add or modify these lines in your config.txt and power cycle the reader:

; This section turns on/off the keyboard wedge/barcode scanner emulation mode
KBLogMode=0

; This section can be used to enable the virtual COM port, by changing to ComPortEnable=1
ComPortEnable=1
ComPortMode=1
CommandInterfaces=1
PassiveInterfaces=0
ComPortSource=80

Once rebooted, the VTAP will enumerate as a COM port device and load the necessary drivers for latest Windows systems. On Windows 7 machines you will need to download and install this custom VTAP VCP driver. Out of the many configurations we set above, we have the CommandInterfdaces key set to 1 to let the COM port interface to send commands to the VTAP. Then the PassiveInterfaces key set to 0 puts the reader into Active mode where scans are streamed out as they occur. The ComPortSource key contains a bit mask that filters for NFC targets you want the VTAP to scan and is broken out like so:

Bit 7 (0x80) = Mobile Pass (Apple VAS/Google Wallet Smart Tap)
Bit 6 (0x40) = STUID (DESFireEV1/EV2, MIFARE2GO passes, Apple Secure Access passes)
Bit 5 (0x20) = Write to card emulation mode (see VTAP NFC tag emulation settings)
Bit 4 (0x10) = RFU
Bit 3 (0x08) = RFU
Bit 2 (0x04) = Scanners
Bit 1 (0x02) = Command interface messages (see Dynamic configuration commands)
Bit 0 (0x01) = Card/Tag UID

NFC targets can include VAS passes as well as Secure Access passes and physical cards/tags but for this guide we will focus on VAS passes and set ComPortSource to 80 (only Bit 7 enabled). For a full list of configurations you can look through this VTAP Serial Integration guide published by Dot Origin.

Controlling VTAP from COM port

Now that we have the VTAP connected with a COM port interface, we can write some software to control it. We'll use the Powershell terminal (standard on Windows) to get started. This will allow us to interact with the VTAP COM port directly and build a working script step by step. It will also make it easy to copy/paste commands into a script file later.

The first step is to find the VTAP COM port's identifier. Use this command to list out all the USB endpoints, it'll be the one starting with COM and end with a number. It should appear and disappear as you plug/unplug the VTAP similar to it's disk drive.

Get-PnpDevice -PresentOnly | Where-Object { $_.InstanceId -match '^USB' } | ft -a`

Now that we've identified the COM port, we can create a serial connection object and set it up to exchange data with the VTAP. The VTAP supports many data rates so we'll choose 115200 baud to keep scans wicked fast. We'll also set the DtrEnable bit to allow data from the VTAP to be received and open the port for exchange:

$Port = New-Object System.IO.Ports.SerialPort "COM5",115200`
$Port.DtrEnable = 1
$Port.Open()

Now that the $Port is open, we can ask the VTAP to list out all it's active configurations (like ones we set in last section) with the % instruction. We'll use the Write() command and make sure to include carriage return (\r) and line feed (\n) characters per VTAP specifications. Then, we read back the response like so:

$Port.Write("%`r`n")
$Port.ReadExisting()
$Port.Close()

vtap-config-over-comport

Congrats, you're now controlling the VTAP from the COM port! Next we'll look at making an application that does this from the background. 🤖

Prep Work

Before we write any code to control the VTAP programmatically, let's setup an environment to make an application. We'll use Powershell since it has shell execution support, includes simple bindings to the Windows environment, and makes it easy to export a standalone application. To start let's create a workspace folder named nfc-com-port-tutorial to contain all our application files. Then, we're going to create a log file to catch all the application's activity with time stamps. This will help with debugging and prove useful with tracking who our PassNinjaBot says hi to 👋🏼. Do this from a Powershellterminal:

mkdir ~/nfc-com-port-tutorial
ni ~/nfc-com-port-tutorial/scan-log.txt
curl https://i.imgur.com/9aMlPkQ.png -o ~/nfc-com-port-tutorial/bot-logo.png
ni ~/nfc-com-port-tutorial/PassNinjaBot.ps1

Now we can launch any text file editor and open PassNinjaBot.ps1 for editting. But before we get to adding any code, we'll need to make a wallet pass.

Issue Passes with PassNinja

To make our PassNinjaBot greet pass holders properly, we'll need to create passes with tasty NFC content. Read up on this guide to make a pass with static NFC data. Let's put the data in the NFC message field with the following formatting:

Member Level : Name : Year : Hometown

This will allow our application to parse through the text by segmenting on the ":" delimiter and produce a relevant greeting. And don't worry if you make a mistake, you can quickly update the pass with a new NFC message with just one API call.

Making a Background App

Next we'll put the COM port commands into our script, sprinkle in some scan notifications, and build it into our PassNinjaBot application. Like any good bot, the PassNinjaBot will need to communicate something helpful and log all it's activities. With that in mind, the things to do are:

Open a COM port connection to the VTAP
Read for existing Scan text from VTAP
If Scan text is found,
> Parse it to notify the attendant
> Say something nice to the visitor
> Log the Scan to a text file
If VTAP connection still open, go to Step 2
Close the COM port connection to the VTAP

For building the application we'll use Windows Powershell since it has native bindings for notifications and speech. For notifications, we use this package which you can install on Powershell with this command:

Install-Module -Name BurntToast

The resulting script looks like this. You can copy/paste it into a text file and update it with your COM port identifier, logo file path, and log file path. Then save it as PassNinjaBot.ps1 so you can run it as a Powershell script.

$Port = New-Object System.IO.Ports.SerialPort "COM#",115200 
$Port.DtrEnable = 1                                    # enable Data To Recieve
if (-not ($Port.IsOpen)) { $Port.Open() }              # check port is not already open
Add-Type -AssemblyName System.Speech                   # set up Bot to talk
$BotTalk = New-Object -TypeName System.Speech.Synthesis.SpeechSynthesizer
Do {
    $Scan = $Port.ReadExisting()                       # Read the pending scan data
    $Scan = $Scan.Replace("`r`n", '')                  # remove CR and LF characters
    if (-not ([string]::IsNullOrEmpty($Scan))) {
        $ScanItems = $Scan -split " : "                # parse scan data by way of delimiter ' : '
        $Title = $ScanItems[0]+": "+$ScanItems[1]      
        $Subtitle = "Active since "+$ScanItems[3]+" from "+$ScanItems[2]
        $Names = $ScanItems[1] -split " "
        $Greeting = "Welcome " +$Names[0]+", thanks for being a "+$ScanItems[0]
        New-BurntToastNotification -AppLogo "~/nfc-com-port-tutorial/bot-logo.png" -Text $Title, $Subtitle
        $BotTalk.Speak($Greeting)
        Add-Content -Path "~/nfc-com-port-tutorial/scan-log.txt" -Value "$(Get-Date) : $Scan"
    }
    Sleep 1                                            # Sleep for a second
}
While ($Port.IsOpen)
$Port.Close()

Once you test it out a bit and are happy with it, you can turn it into an standalone executable with the ps2exe package. Install and run it like so:

Install-Module -Name ps2exe
Invoke-PS2EXE .\PassNinjaBot.ps1 .\PassNinjaBot.exe

And there you have it, a PassNinjaBot application that scans for passes, keeps an activity log, notifies attendant, welcomes visitor, and runs in the background!! Just double-click it to run or add to your startup items. windows-notification-scan-log

Putting is all Together

Now that we have all the pieces, let's put it all together! Follow these steps to test out the experience:

Windows machine and VTAP connected over USB
Launch PassNinjaBot and check that scan-log.txt is present
Double-tap iPhone power button to launch Apple Wallet and authenticate with FaceID/TouchID/Passkey
Present iPhone top end to VTAP scan surface and what the magic happen!
Verify Welcome greeting is spoken, scan notification appears, and scan-log.txt captured the activity.

The PassNinjaBot application is a great tool for checking people in to your event or business without hijacking your computer. It's powered by secured NFC passes that only VTAPs with the right encryption keys can read. The PassNinja API accelerates the issuance and updating of passes so you can deliver memorable experiences for your customers to keep them coming back and telling thier friends about it. PassNinjaBot used the NFC message to utter a peronsalized welcome but extending it with use of AI could easily make it a personalized conversation.

Conclusion

In this guide we walked you through connecting to the VTAP over it's COM port interface and sending it instructions from the Windows Powershell. We then built a Windows application that controls the VTAP and logs scan activity from the background. And finally we outlined an effective method to issue passes with delimited metadata that can create great experiences for visitors while securely managing their level of service.

If you have any feedback on this article, let us know! Email content@passninja.com

Was this article helpful?

Yes No