FreeMASTER communication library in a C/C++ project

[#1]

Intro

One not widely known feature of the FreeMASTER tool is the ability of using FreeMASTER communication library in a custom C/C++ project. This library implements the proprietary communication protocol and allows developers to interact with the target board from their own desktop application (complementary to FreeMASTER GUI and JSON-RPC API usage).

Note: although this approach grants developers full control over the communication with the target board it lacks some advanced features of the FreeMASTER tool such as symbol loading (it does not include TSA loading and ELF parsing functionalities) and users need to pass numeric addresses when reading and writing embedded project variables.    

This article is meant to provide a basic example on the communication library usage in a custom C/C++ project based on the shared library distributed with FreeMASTER Lite and CMake build system.

An similar articles covering the same topic using Python can be found here.

Prerequisites

Required files for this example are located under FreeMASTER Lite installation directory (default location C:\NXP\FreeMASTER 3.x\FreeMASTER):

• include - folder containing required header files
• lib - folder containing shared library

You can include and link corresponding files manually, but in case you want to follow this example you will need CMake 3.12 or newer.

Code Example

#include <cstdio>
#include <mcbcom/mcbcom.h>

int main()
{
    HMCBCOM_t pCom;
    HRESULT_t result = McbOpenComEx(&pCom,"RS232;port=COM3;speed=115200;tmoRI=40;tmoRTM=40;tmoRTC=50;tmoWTM=40;tmoWTC=50");

    if (MCB_FAILED(result))
    {
        printf("Could not open communication channel. Error code: %#010x\n", result);
        return 1;
    }

    MCB_RESP_GETINFO_t boardInfo;
    result = McbGetInfo(pCom, &boardInfo);

    if (MCB_SUCCEEDED(result))
    {
      printf("Board is using FreeMASTER Driver v%d.\n", boardInfo.protVer);
      printf("Embedded application description %s.\n", boardInfo.descr);
    }

    McbCloseCom(pCom);
    return 0;
}

1. Include mcbcom header file
2. Create a pCom (communication handler) of type HMCBCOM_t.
3. Open a communication channel by passing a reference to the communication handler (will be initialized internally by mcbcom library and a connections string.
4. A good practice is to check result status after each command execution before proceeding.
5. This particular example queries board information and displays it in the terminal.
   Check mcbcom.h for the list of supported commands/functions.
6. Final step is to close the communication to free the communication channel.

CMake Configuration

The attached archive contains CMake configuration that will facilitate importing FreeMASTER dependencies in your custom project.

1. Download the attached archive and extract it to your local system (eventually your workspace)
2. Create a CMakeLists.txt file in your workspace with the following content:

   # At LEAST 3.12 but newer is better
   cmake_minimum_required(VERSION 3.12 FATAL_ERROR)
   
   # Example application using mcbcom library
   project(fmstr_demo LANGUAGES CXX)
   
   # Application source files
   add_executable(${PROJECT_NAME}
       main.cpp
   )
   
   # Search for FreeMASTER's mcbcom library
   find_package(FreeMASTER REQUIRED COMPONENTS mcbcom)
   
   # Link mcbcom library
   target_link_libraries(${PROJECT_NAME} FreeMASTER::mcbcom)

   Note that to use FreeMASTER library you need only 2 function calls
   1. find_package - looks for FreeMASTER package (the files you downloaded in the previous step will help)
   2. target_link_libraries - links the library to your project
3. Create a build folder in your workspace and open a terminal window in that folder.
   At this point your workspace should look like this:
   
4. Configure custom project (using Visual Studio 2019):
   

   cmake .. -G "Visual Studio 16 2019" -A "Win32" -DCMAKE_PREFIX_PATH="C:/FreeMASTER Demo/cmake"

   Note: FreeMASTER comes with a 32 bit library, thus I specified Win32 architecture. Additionally, I set CMAKE_PREFIX_PATH pointing to the downloaded cmake folder.
   In case FreeMASTER is installed in a custom location you need to define FREEMASTER_ROOT pointing to FreeMASTER Lite installation directory (root of include and lib folders) "-DFREEMASTER_ROOT=path_to_FreeMASTER_Lite". 
   After this command is executed you will find the generated solution in the build folder.

   Same steps can be done using CMake GUI:
   

Running the code

After building the project make sure to copy the library next to your executable or add its folder to system path and run fmstr_demo.exe.