Using the VTAP Android USB serial communications SDK

Overview

This package is designed to help you to write Android applications to control a VTAP reader over a USB serial interface. It includes:

  • Java classes that provide a lightweight interface to the VTAP reader's Command Interface over the USB virtual COM port.

  • An example Android app that demonstrates the use of these classes, both as

    • a pre-built apk file, and

    • a source code project for use with Android Studio.

The example application provides easy access to the full functionality of the VTAP Command Interface and the ability to send and receive files to/from the VTAP reader file system using the ZModem protocol.

The VTAP Command Interface allows for direct control of the VTAP reader as well as allowing updates to configuration, private keys and firmware to be performed over the USB serial, RS‑232, RS‑485 or TTL serial interfaces (depending on the VTAP reader product or configuration in use).

Functionality and Implementation

The VTAP reader Command Interface is a simple ASCII command line protocol designed to be used interactively via a terminal emulator or driven programmatically. It consists of commands to:

  • get VTAP reader serial number and device information;

  • poll for pass or tag data and type information;

  • control the LEDs and buzzer;

  • send messages to any of the VTAP reader peripheral interfaces;

  • and to set or get configuration values from the VTAP reader config.txt file.

Full details of these commands can be found in the VTAP Commands Reference Guide.

A high‑level API for easy use of these different groups of commands can be found in the vtap100 Java class, described below:

USB connection and intent filters

When importing code into your app you may need to ensure you have the USB filters and intents set up correctly to detect the VTAP reader when it is plugged in. They will need the vendor ID and product ID to identify the VTAP reader. The following codes or settings may be required in your app.

Example VTAP reader interface app

An example Android app is included, which demonstrates the use of the VTAP Command Interface. The full source code of this app is provided as a project for use with Android Studio.

To get started using a VTAP reader with Android, this app is also provided as a pre-built signed APK file, which can be sideloaded to an Android device. This file can be found in the 'built apk' folder of the VTAP Android SDK package.

When using a VTAP reader with an Android device, the VTAP reader’s USB keyboard emulation may cause the Android device to not show its on-screen keyboard when an input field is selected. This is because Android detects that an external keyboard device is present and assumes that this should be used instead of the on-screen keyboard. To avoid this issue:

  • Use an Android device setting to allow the on-screen keyboard to be used, even when it appears that there is an external keyboard. This setting can usually be found on an Android device under Settings->Additional Settings->Language then input->Keyboard, mouse and track pad
    (The exact location for this setting varies depending on the device and Android version). Ensure that the Use on-screen keyboard setting is checked.

  • Alternatively, you could make use of the VTAP setting KBEnable (from VTAP firmware v2.2.6.0) to disable the USB keyboard device of the VTAP reader. This is a setting you can include in the VTAP reader's config.txt file.
    KBEnable=0 ; will disable the USB keyboard device.

The example app source code includes the following files, as well as the VTAP Android SDK Java files described above:

  • MainActivity.java

    Used to start the example application, and called when the file explorer is used or when a new intent is set.

  • DeviceFragment.java

    Launches the TerminalFragment.

  • TerminalFragment.java

    Sets up the user interface, serial service and listeners for the app. Uses the vtap100 class to control the connected VTAP reader.

  • MyLog.java

    A thread‑safe logging class for logging to LogCat, a log file and to a TextField within the app.

  • SerialService.java

    Used to manage the serial connection. Creates notifications and queues serial data while activity is not in the foreground. The app uses the listener chain:
    SerialSocket → SerialService → TerminalFragment

  • Constants.java

    Constant definitions used by the app

Related Topics Link IconRelated reading: