Skip to content

VHL & Autoread

Use case

  • Besides a number, you want to read additional and/or larger amounts of data. (To read a number only, we recommend "pure" Autoread).
  • You want to write data to the card.

Implementation overview

What is VHL?

VHL stands for Very High Level card access. It's a macro command set that allows you to handle nearly all aspects of a card technology. Compared to low-level commands, however, VHL offers significant advantages:

  • Independence of card type
    All card-type-specific information is stored on the reader. If needed, you can later modify the reader setup without having to adapt your application.
  • Simplicity
    With a single command, you can read or write large data volumes - no complex command sequence needed. This also saves you the effort of familiarizing yourself with the details of the respective card type.
  • Reliability
    Communication errors are handled automatically as far as possible, e.g. using retry mechanisms.
  • Optimized performance
    VHL avoids unnecessary round trips to the application by handling communication between reader and card whenever possible. Depending on the amount of data to transfer and the interface you use, this may have a positive impact on performance.

What is Autoread?

The reader scans for cards and reads them autonomously (learn more).

How it works

This implementation is based on BALTECH Reader Protocol (BRP). To keep your effort low, we provide an SDK for the most common platforms.

This approach combines Autoread via BRP with the use of VHL commands:

  • The reader runs in Autoread mode to perform basic tasks autonomously, e.g. poll for cards or give feedback to the card holder.
  • Once the reader has detected a card, it reads the card's number and buffers it in an internal queue.
  • The reader pauses Autoread and waits for the host to retrieve the number from the queue, run VHL and/or other I/O commands. (If the host is implemented as an Ethernet server, this step requires the reader to open a connection first.)
  • When done, the host reenables Autoread.
Diagram showing a BALTECH reader in Autoread mode with bidirectional communication for USB, RS-232/UART, and Ethernet - host as client

Supported interfaces

  • USB HID (recommended with the SDK)
  • USB virtual COM port (recommended when not using the SDK, required for RDP)
  • RS-232/UART
  • Ethernet (host as client/host as server)

Alternatives

  • Use VHL without configuration if:

    • You don't want to configure readers.
    • You don't want to specify the card structure (i.e. the parameters to access the card) before putting readers in operation, but control the parameters flexibly during reader operation.

  • Use "pure" VHL for existing projects only.

Your workflow

Configure the reader

To prepare readers for access from your application, create a configuration for the readers. Alternatively, you can order a configuration from us.

Required equipment

  • A Windows computer with BALTECH ToolSuite installed
  • A test reader you can connect to your computer.
    If the productive reader type doesn't provide a USB connection, we recommend you use an ID-engine ZB to create and test the configuration.

To configure the reader:

  1. Create a configuration that contains an Autoread component (to enable Autoread on the reader) and a "VHL file" (in which you describe the card's data structure).

    If you work with the SDK, you can use one of the demo configurations in the app notes as a basis. To do so create a copy of it.

  2. Test the Autoread component.

  3. Test the VHL file. This step also helps you verify the parameters you'll later need to run VHL commands.

  4. To control access permissions and set up authenticated and encrypted communication, you can additionally configure Authentication and Encryption.

    Details
    • For non-Ethernet readers, use AES.
    • For Ethernet readers, use PKI.

  5. Configure the test reader to later test your application..

Set up SDK

The easiest way to use VHL is the BALTECH SDK, available for Windows, macOS, and Linux.

My platform's not supported

If you can't use the SDK, you can create the BRP command frames yourself. Please refer to the BRP specification and example frames.

To set up the SDK:

  1. Download the SDK from our website.
  2. Get familiar with its components. We recommend you get started by trying out the app notes.
  3. Integrate the SDK into your application.
  4. Set up a protocol stack to be able to run commands.

Run commands

Card interaction

  1. Run AR.Setmode with Mode = EnableOnce (0x02). This ensures that the reader pauses Autoread mode as soon as it has detected a card, so you can perform operations.
  2. Run AR.GetMessage to poll the reader for a detected card and its number.

  3. Run the VHL command(s) required for your operations. Here are the most important ones:

    • With VHL.Read you can read additional data from the card.

    • With VHL.Write you can write data to the card.

      In the last 2 commands, you reference the VHL file you've created.

  4. Start from 1. again to reenable Autoread mode.

Reader hardware control

There are various commands to control the reader hardware. You can control reader feedback (e.g. LED and beeper), reboot the reader, check its firmware version, etc.

What's next?

That's it for the development part. The next steps are as follows:

  1. Release and export the configuration
  2. Check deployment options and create a ConfigCard if needed.
  3. Install the readers and deploy the configuration.

Does someone else take over configuration management?

If someone else needs to adapt your configuration for various projects (e.g. exchange encryption keys), then please give them the released configuration in BALCFG format. They can then create a copy of it. When documenting what they need to change, you may want to reuse some of the how-tos you find here.

Troubleshooting & support

Got stuck somewhere along the way? Don't worry, we'll help you troubleshoot:

Title