OpenBLT Bootloader

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.

Note that LibOpenBLT was designed for PCs and embedded Linux devices. If you would like to integrate similar functionality on a microcontroller, have a look at [[manual:libmicroblt|LibMicroBLT]].

{{:manual:libopenblt_architecture.png?nolink&|}}

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 [[http://www.cmake.org|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


**Important note for Windows users**: Starting with OpenBLT version 1.14, LibOpenBLT is built and distributed as a 64-bit library. That means that your own custom program, which accesses the LibOpenBLT library, must also be built as a 64-bit application. With other words:
  * If you develop your custom program in Python, install and use the 64-bit Python interpreter. 
  * If you develop your custom program in Lazarus, install the 64-bit version of Lazarus.
  * If you develop your custom program in Delphi, set the __Target Platforms__ to __64-bit Windows Platform__ in the //Project Manager//.
  * If you develop your custom program in C#, set the __Platform target__ to __x64__.
  * Etc.

If you use the LibOpenBLT shared library from before OpenBLT version 1.14, or if you rebuilt it yourself as 32-bit, then your own custom program must also be built as a 32-bit application.


===== Building LibOpenBLT from sources =====
LibOpenBLT relies on [[http://www.cmake.org|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: 
<code>sudo apt-get install cmake</code>

==== 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:
<code>sudo apt-get install build-essential libusb-1.0-0 libusb-1.0-0-dev</code>

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:

<code>
cmake ..
make
</code>

{{:manual:libopenblt_build_linux_gcc.png?nolink&|}}

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 2019 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:
<code>
cmake ..
</code>

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. 

{{:manual:libopenblt_build_windows_msvc.png?nolink&|}}

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

Note that if you want to build a 32-bit version of LibOpenBLT, generate the build environment with command "**cmake -A Win32 ..**" instead. This is recommended if you use OpenBLT from before version 1.14.
==== Building on Windows with MinGW ====

This method assumes that the MinGW compiler toolchain is installed on your PC. A convenient way to install it, is by downloading the installer that bundles the Code::Blocks IDE together with MinGW. When using OpenBLT version 1.14 or newer, it is recommended to download the [[https://sourceforge.net/projects/codeblocks/files/Binaries/20.03/Windows/codeblocks-20.03mingw-setup.exe/download|64-bit installer version]], because all included PC binaries are 64-bit as well. Otherwise you can download the [[https://sourceforge.net/projects/codeblocks/files/Binaries/20.03/Windows/32bit/codeblocks-20.03-32bit-mingw-32bit-setup.exe/download|32-bit installer version]].

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: 
<code>
mingw32-make
</code>

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 LibOpenBLT library: 

<code>
cmake -G "CodeBlocks - MinGW Makefiles" ..
mingw32-make
</code>

{{:manual:libopenblt_build_windows_mingw.png?nolink&|}}

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 [[https://www.feaser.com/en/blog/?p=208|this blog article]]. 

==== C# ====

The C# bindings are formatted as a wrapper class with static methods. You can directly copy the class file to your C# 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/csharp/

A tutorial about getting started with the C# bindings is available on the [[https://www.feaser.com/en/blog/2021/03/develop-your-own-firmware-update-tool-in-c-with-libopenblt/|developer blog]].

==== 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/

Note that the [[manual:microboot|MicroBoot]] firmware update tool itself is developed using Lazarus, using exactly these bindings. The OpenBLT download package includes the full source code for MicroBoot. You can use it as a reference on how to use the Pascal bindings for LibOpenBLT.
OpenBLT Bootloader

User Tools

Site Tools

Page Tools
