Skip to content

Implement wired upload via the host

To deploy a configuration and/or firmware update via wired upload (i.e. USB or RS-232/UART), you can implement your own upload application, as an alternative to our Windows tool BALTECH Uploader.

A custom implementation makes sense if you e.g. need

  • an upload application with your own branding
  • an upload application that runs on a platform other than Windows
  • the upload to be integrated in a different application or into your own production environment.

Requirements

  • Host interface: USB and RS-232/UART
  • Readers with the following firmware:
    • 1100 v2.00 or above
    • Custom firmware originally created as of November 2021
  • Configuration and/or firmware in a supported format (see next section)

File formats

The following file formats are supported.

BEC2: Configuration (+ firmware)

BEC2 is the default format for an end-to-end encrypted, deployable configuration file. It may optionally also contain a firmware.

Limitations

How do I get a BEC2 file?

  1. Create a configuration in BALTECH ConfigEditor.

    • Make sure you use ConfigEditor v4.26 or above.
    • Make sure Support Legacy Firmware Versions is disabled.
      Otherwise, you'll get a BEC file, which is not supported.
    • If needed, package the configuration with a firmware.

  2. Release and export the configuration to obtain a BEC2 file.

Alternatively, you can order a configuration from us.

BF3: Firmware only

While the upload of BEC2 files is the standard case, you can also upload a BF3 file, which only contains a firmware.

Limitations

None; BF3 files can be uploaded at any time, regardless of whether the RFID interface of the reader is configured.

How do I get a BF3 file?

BF3 files are available on request. The firmware files downloadable on our website are in BF2 format and will not work.

File structure

Both BEC2 and BF3 files have the same structure:

  • Meta information
    A section with meta information in human-readable format; irrelevant for the upload.
  • Relevant data
    This is the data to transfer to the reader; it's separated from the meta information by a blank line; all following line breaks are irrelevant. Data is ASCII-encoded hexadecimal.

All line breaks have to be \r\n (CRLF Windows-style line breaks).

Structure of config or firmware file to implement wired upload for BALTECH RFID Nreaders

Implement upload

Implementation is the same for both BEC2 and BF3 files. The basic idea is as follows:

  1. The host starts the upload.
  2. The reader requests data blocks, one after the other.
    (Occasionally, it will also request a reconnect.)
  3. The host transfers each requested data block and thus continues the upload.
    (If a reconnect is requested as well, the host closes and reopens the connection first.)
Overview of process to upload a BEC2/BF3 file to a BALTECH reader

Start upload

  1. Run Main.Bf3UploadStart.
  2. The reader responds by requesting the first block of relevant data in the BEC2/BF3 file (see file structure). The data block is specified by its start byte (ReqDataAdr) and its length, i.e the number of bytes (ReqDataLen).
    1 byte corresponds to 2 digits of data in the BEC2/BF3 file. Counting starts from 0.

Example:
ReqDataAr = 0 and ReqDataLen = 5 specify the following data block.

Example data block in BEC2/BF3 file for upload to BALTECH RFID readers

Continue upload

  1. Run Main.Bf3UploadContinue to transfer the requested data block.

    To extract the data block from the BEC2/BF3 file, choose any parsing method that works for you. An example implementation is described in our app note.

  2. The reader responds by requesting the next data block.

    ReqDataLen may occasionally be 0. This happens when the reader is busy with internal tasks or needs to reboot (see following section). In this case, just transfer a data block of 0 bytes.

  3. These 2 steps repeat over and over. Upload is completed once the reader has received all required data blocks. This is indicated by the Continue bit being set to 0.

Reconnect after reboot

During the upload, the reader needs to reboot at least once. This is indicated by the Reconnect and ContainsReconnectRetryTimeout bits being set to 1.

In this case, disconnect and reconnect to the reader before running the next Main.Bf3UploadContinue command. ReconnectRetryTimeout indicates how long you have to try.

If you can't establish a connection during that time, the upload has failed and must be restarted.

Abort the upload

The upload is very robust and can be aborted at any point without problems. However, aborting a firmware upload upload may leave the reader with an incomplete firmware that is not fully functional (see boot status IncompleteFirmware); in this case, you can restore a fully functional firmware by repeating the upload.

Implement progress bar

To facilitate the implementation of a progress bar, the reader includes an estimation in one of its responses: This is indicated by the ContainsEstimation bit being set to 1. The response then contains the additional EstimatedNumberOfBytes field. This is an estimation of the total amount of data bytes to transfer.

The reader sends this estimation only once, after a few 100 ms.

Based on the number of bytes (length of data) already transferred, and the duration of that transfer, you can calculate the expected duration for the total amount of data bytes to transfer.

Smooth out the progress bar

With the above implementation, the progress bar will stop for a few seconds during the upload. This is due to the pauses in which the reader doesn't request any new data blocks (i.e. during internal tasks or when rebooting).

To compensate for the pauses and smooth out the progress bar, you can include the EstimatedTimeOverhead field in the calculation: This is the estimated overall duration of these pauses. For an example implementation, please refer to our appnote (see next section).

Try it out with our app note

The app note appnotes\reader_update in the SDK gives you a working example of the upload implementation.

Learn more about app notes

Title