Skip to content

VHL

Use case

This mode covers the same use case as the VHL & Autoread.

Use "pure" VHL for existing projects only. For new projects, we highly recommend VHL & Autoread as this mode supports latest products and features based on Autoread, e.g. Mobile ID, Wireless Upload, or similar developed in the future.

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

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.

  • Configure the reader for your cards' data structure. You can use our GUI tools in BALTECH ToolSuite to conveniently create and deploy the configuration (including wireless deployment options).
  • This configuration "translates" VHL commands into low-level commands, handles communication with the card, and returns the final results.
  • Control reader feedback (e.g. LED and beeper) and other hardware functionality directly via the host.
Diagram showing a host application interacting with a BALTECH reader via VHL commands, where the card-specific information is stored on the reader

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

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. It will include 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. 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.

  3. Test the VHL file that is part of your configuration.
    This step also helps you verify the parameters you'll later need to run VHL commands.

  4. 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 VHL.Select to scan for cards.

    Set AcceptConfCard wisely

    With this parameter, you decide if the reader configuration can later be updated with BALTECH ConfigCards or not. So make sure you set the parameter in line with project requirements.

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

    • 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 you can read additional data from the card.

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

      In VHL.Read and VHL.Write, you reference the VHL file in your configuration.

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