VHL

Use case

  • You want to read data other than a number.
    (To read a number, we recommend Autoread).
  • You want to write data to the card.
  • You want to format cards.

Implementation overview

What is VHL?

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

  • Independence of card system
    All card-system-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 system.
  • 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.

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 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
  • Ethernet (client only)

Alternatives

  • Use VHL & Autoread if:

    • You run your host application as an Ethernet server.
    • You've used Autoread so far and want to "upgrade" to VHL to implement a more complex logic.
  • 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.

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 ToolSuitecall_made 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.
  1. Create a configuration file.

    If you work with the SDK, you can also use one of the demo configurations in the app notes as a template. To do so, derive and edit a copy of it.

  2. Add device settings to enable the host protocol.

    If the factory device settings fully meet your requirements, you can skip this step.

  3. Add a VHL file. Here, you describe the card's data structure.

  4. Test the VHL file. This step also helps you verify the parameters you'll later need to run VHL commands.
  5. To set up an encrypted channel, add security settings (for more details, see our encryption overview).
  6. Transfer your draft configuration to the test reader to later test your application.
  7. Ethernet only: If you want to assign a static IP address, create a separate IP configuration. Otherwise, readers will obtain an IP address dynamically via DHCP.

Set up SDK

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

Alternative for unsupported platforms

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. Downloadcall_made 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.Selectcall_made 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)call_made required for your operations. Here are the most important ones:

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. Finalize your configuration
  2. Create a ConfigCard in case the readers are difficult to connect via USB.
  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 finalized configuration in BALCFG format. They can then derive and edit 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: