OpenBLT Host Library (LibOpenBLT)

The OpenBLT Host Library contains an application programming interface (API) for communicating with a microcontroller target, running the OpenBLT bootloader, for making firmware updates on the target. The goal of the OpenBLT Host Library is to empower you to quickly and efficiently create your own firmware update tool, in case you don’t prefer the standard MicroBoot and BootCommander tools that are included in the OpenBLT bootloader package.

When the firmware on the microcontroller, which runs the OpenBLT bootloader, should be updated, a program on the host system is needed to communicate the new firmware to the bootloader, via the communication protocol supported by the OpenBLT bootloader. LibOpenBLT contains all the functionality to achieve exactly this. It can parse the firmware file to extract (and manipulate) program data and it can communicate this program data to the OpenBLT bootloader that runs on the microcontroller target, which can then progam it into the memory of the microcontroller (typically internal flash memory).

LibOpenBLT was written in the C programming language (C99) and developed with cross-platform support in mind. It has been successfully tested on a Windows PC, Linux PC and even on embedded Linux systems such as a Raspberry Pi and a Beagle Board. It supports the XCP communication protocol using RS232, CAN, USB and TCP/IP communication as the transport layer. From a firmware file format perspective, it can handle firmware files in the Motorola S-record format (S19, S28 and S37). The library has a modular design, allowing effortless integration of additional communication protocols, transport layers, and firmware file formats.

The library is available with full source code and comes with a pre-configured build environment based on CMake, which allows easy building of LibOpenBLT into a shared library (and optionally into a static library). Because it is available in C source code format, as a shared library and as a static library, you are free to choose the programming language of your liking, when developing your custom firmware update tool. For example: C, C++, C#, Java, Python, Object Pascal, etc.

For details on the library’s API and its implementation, refer to the reference manual that is located at: .\Doc\RM_LibOpenBLT.pdf. For an example on how to actually use LibOpenBLT, have a look at the sources of the BootCommander program.

Run-time libraries

When you develop your own program based on LibOpenBLT, it is recommended to copy the LibOpenBLT shared library file, and the run-time libraries that it depends on, to the directory where your program's executable runs from. When distributing your program, you should include these run-time libraries as well.

Run-time libraries for Linux systems:

  • libopenblt.so

Run-time libraries for Windows systems:

  • libopenblt.dll
  • UsbBulkLib.dll
  • msvcr120d.dll

Building LibOpenBLT from sources

LibOpenBLT relies on CMake to automatically detect the build tools on your system and to generate the build environment for it. The following instructions assume that CMake is installed on your system and is available on the path. Windows users can download the installer from http://www.cmake.org/. Mainstream Linux distributions have CMake in their software repository and it can be installed from there. Example for Ubuntu based distributions:

sudo apt-get install cmake

Building on Linux with GCC

This method assumes that the basic tools needed for building software are installed. At least the GCC compiler and Make are needed. Additionally, libusb-1.0 is needed. On Ubuntu based distributions, the tools and dependencies can be installed via command:

sudo apt-get install build-essential libusb-1.0-0 libusb-1.0-0-dev

Using the terminal, set the working directory to ./Host/Source/LibOpenBLT/build. Next, type the following two commands to detect and generate the Unix Makefiles based build environment and then build the static LibOpenBLT library:

cmake ..
make

After a successful build, the shared library libopenblt.so is located in the ./Host directory.

Building on Windows with Microsoft Visual C++

This method assumes that Microsoft Visual C++ is installed. During the LibOpenBLT development, Microsoft Visual Studio 2013 Express was used. The method outlined here should work just fine with both older and newer versions of Microsoft Visual Studio.

Using the Command Prompt in Windows, set the working directory to .\Host\Source\LibOpenBLT\build and type the command:

cmake ..

A solution file for Microsoft Visual C++ is then automatically generated, called LibOpenBLT.sln. Open the solution in Microsoft Visual C++ and build the program from there, by selecting Build→Rebuild Solution from the menu.

After a successful build, the shared library libopenblt.dll is located in the ./Host directory.

Building on Windows with MinGW

This method assumes that the MinGW compiler toolchain is installed on your PC. The installer can be downloaded from https://sourceforge.net/projects/mingw-w64/.

Make sure the .\bin directory of the MinGW installation directory is added to your path in Windows. A quick way to verify that this is the case, run the following command from the Command Prompt in Windows and make sure the program could be found:

mingw32-make

Using the Command Prompt in Windows, set the working directory to .\Host\Source\LibOpenBLT\build. Next, type the following two commands to detect and generate the MinGW Makefiles based build environment and then build the static LibOpenBLT library:

cmake -G "MinGW Makefiles" ..
mingw32-make

After a successful build, the shared library libopenblt.dll is located in the .\Host directory.

Programming language bindings

Bindings for the OpenBLT Host Library are basically glue code, that enable you to call the LibOpenBLT API from a different programming language.

Python

The Python bindings are formatted as a standard Python package that you can directly install in your (virtual) Python environment. Refer to the README file in the SVN trunk for getting started instructions:

https://sourceforge.net/p/openblt/code/HEAD/tree/trunk/Host/Source/LibOpenBLT/bindings/python/

A video tutorial about getting started with the Python bindings is available in this blog article.

Pascal

The Pascal bindings come as a Pascal unit that you can add to your Delphi or Lazarus project. Refer to the README file in the SVN trunk for getting started instructions:

https://sourceforge.net/p/openblt/code/HEAD/tree/trunk/Host/Source/LibOpenBLT/bindings/pascal/

manual/libopenblt.txt · Last modified: 2018/07/10 17:27 by voorburg
 
Powered by PHP Driven by DokuWiki