Article Contents

Overview
What the heck is a COM port?
Configuring the VTAP to operate in COM port mode
Controlling VTAP from COM port
Prep Work
Issue Passes with PassNinja
Making a Background App
Putting is all Together
Conclusion

Hardware

How to Control VTAP from Background (MacOSX)

Richard Grundy

Updated December 17, 2024 11:52

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 emulate 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 AppleScript

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:

MacOSX 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 on your Mac. Out of the many configurations we set above, we have the CommandInterfaces 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 command terminal (standard on every Mac) 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. On MacOSX we use this command to list out all the USB endpoints. The identifier will be the one starting with cu.usbmodem and it will appear and disappear as you plug/unplug the VTAP (similar to it's disk drive).

ioreg -p IOUSB && ls -al /dev/cu.*

Now that we've identified the COM port, we can open a connection and exchange data with the VTAP with common BASH file operations. The VTAP supports many data rates so we'll choose 115200 baud to keep responses wicked fast.

PORT=$(ls /dev/cu.usbmodem*)
exec 3<> $PORT
stty -f $PORT 115200

Now that the $PORT is open, we can ask the VTAP to list out it's boot info with the ?b instruction. We'll use the echo command and write it to the port file. Then, we read back the response (looking for "-" delimiter) and close the port like so:

echo "?b" > $PORT
read -d "-" RESP < $PORT
echo $RESP
exec 3<&- $PORT

vtap-boot-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 AppleScript since it has shell execution support, includes simple bindings to the MacOSX 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 terminal:

mkdir ~/nfc-com-port-tutorial
touch ~/nfc-com-port-tutorial/scan-log.txt
touch ~/nfc-com-port-tutorial/PassNinjaBot.scpt

Now we can launch the Script Editor from Spotlight, open the PassNinjaBot.scpt script, and export it as an application like so:

launch-applescript-save-as-application

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 familiar 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 serial port connection to the VTAP
Read for existing Scan text from VTAP
Close the serial port connection to the VTAP
Append the Scan to the log file
If Scan text is found,
> Parse it to notify the attendant
> Say something nice to the visitor
Wait 5 seconds and go to Step 1

For building the application we'll use Apple Script since it has native bindings for notifications and speech. The resulting script looks like this.

on idle
    -- run shell script to connect to COM port and wait for a Pass to be read
    -- add the Pass data to a log file prepended with a scan timestamp
    do shell script "PORT=$(ls /dev/cu.usbmodem*); read RESP < $PORT; $PORT; echo $(date) : $RESP >> ~/nfc-com-port-tutorial/scan-log.txt"
    -- open the log file and set up how to parse the scan results
    set scans to paragraphs of (read POSIX file "~/nfc-com-port-tutorial/scan-log.txt")
    set text item delimiters to {" : "}
    -- iterate through all the scans in the log file to grab the last one
    repeat with scan in scans
        if length of scan is greater than 0 then -- skip bad scans
            set scanItems to text items in scan -- parse out the items of the last scan
        end if
    end repeat
    -- send a desktop notification with the scan items rendered sensibly
    display notification "Active since " & item 4 of scanItems & " from " & item 5 of scanItems with title item 2 of scanItems subtitle item 3 of scanItems sound name "Blow"
    -- parse out the full name in first and last 
    set text item delimiters to {" "}
    set names to text items in item 3 of scanItems
    -- speak a personalized checkin message 
    say "Welcome " & item 1 of names & ", thanks for being a " & item 2 of scanItems
    return 5 -- wait 5 seconds before next idle loop
end idle

You can copy/paste it into the Apple Script editor and update it with your log file path. Then export it as PassNinjaBot with file format Application and the Stay open after run handler checkbox selected. 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 it to your login items under System Settings. launch-passninjabot-on-login

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:

MacOSX 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 command terminal. We then built a MacOSX 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