Skip to content

VHL & Autoread without reader configuration

Use case

This mode covers the same use case as VHL & Autoread. However, the following restriction applies:

  • You cannot work with complex card structures, e.g. where the data you want to access is distributed across multiple files or blocks.

We only recommend this mode if:

  • You don't want to configure the 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.

Implementation overview

What is VHL?

VHL stands for Very High Level card access. It's a simplistic macro command set that is independent of a specific card type (learn more).

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. (Autoread is enabled via factory settings and doesn't require you to configure the reader.)
  • 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.
  • At runtime, you temparily configure the reader via the host.
  • This configuration "translates" VHL commands into low-level commands, handles communication with the card, and returns the final results.
  • When done, the host reenables Autoread.
  • Control reader feedback (e.g. LED and beeper) and other hardware functionality directly via the host.
Diagram showing a BALTECH reader in Autoread mode and a host application interacting with it via VHL commands, with the card-specific information being stored in the host application

Exceptional cases requiring a configuration

In the vast majority of cases, you won't need to configure the reader. You only need to create a configuration if one or both of the following applies:

  • Your host protocol isn't enabled in the factory settings.
  • You want to control access permissions and set up authenticated and encrypted communication. In this case, you need to configure Authentication and Encryption.

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

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 only)

Your workflow

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.RestrictScanCardFamilies. This is optional, but recommended: It lets you optimize the Autoread card scanning process by filtering for required card families only. Otherwise, Autoread on an unconfigured reader will scan for all card types supported by the hardware.

  2. 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.

  3. Run AR.GetMessage repeatedly to poll the reader for a detected card and its number.

  4. Run VHL.Setup.
    With this command you dynamically create a "VHL file". This is a description of the card's data structure. It's needed to configure the reader for subsequent commands.

    Use a static VHL file for testing

    We recommend you verify the memory location parameters for VHL.Setup and subsequent commands before implementing them in your code. To do so, create a static VHL file and test it in BALTECH ToolSuite.

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

    • With VHL.GetCardType, you can check for the card type of the currently selected card.

    • With VHL.GetSnr, you can request the UID of the selected card.

      This won't work if the card returns a random ID.

    • With VHL.Read and VHL.Write, you can read data from or write data to the card.

      Set Id = 0xFF

      VHL.Read and VHL.Write have a parameter Id to reference the VHL file you want to use. To reference the dynamic VHL file created with VHL.Setup, set Id = 0xFF.

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

Mixing dynamic and static VHL files

In principle, it is possible to mix dynamic VHL files (created with VHL.Setup) and static VHL files (as part of the reader configuration for the VHL & Autoread). However, please note that the dynamic VHL file is lost as soon as you run VHL.Read or VHL.Write with a static VHL file. Thus, if you later want to run VHL.Read or VHL.Write with the VHL file again (i.e. with Id = 0xFF), you first need to rerun VHL.Setup to recreate the dynamic VHL file.

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. You can now install the readers (and, if necessary, deploy the configuration) as described here.

Troubleshooting & support

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

Title