Introduction
The FreeMaster driver has a feature called TSA (Target Side Addressing) a mechanism that allows you to describe the data types and variables directly in the embedded application source code and make this information available to the FreeMASTER tool to describe the variables that we want to display in FreeMaster, making the information automatically available from our board to the FreeMaster software.
With TSA we make the address of our variable available without the necessity of symbol files (a file that contains the description of all the variables in our embedded application: name, address, and size of the variable) that the FreeMaster application normally will need to see the variables of our application. Thanks to the TSA mechanism we can also describe files in our embedded application mapping the file to its hexadecimal values and creating a variable that contains those values. This combined with the elimination of the need for a symbol file can allow us to insert a FreeMaster project in our embedded application and give it a Plug-and-Play function to the board.
Without TSA
With TSA
There is a special type for user resources like memory-mapped files, with this we can make our FreeMaster project file available to the FreeMaster software from our embedded application, giving our project a plug and play functionality with FreeMaster.
Example Description
In this example, we are going to convert a FreeMaster project file (.pmp or .pmpx) into a memory-mapped file, add that file to our embedded application, create a new TSA table for files and other types of active content where we are going to describe our new memory-mapped file and finally connect to FreeMaster and run our project automatically from our board.
Take notice that to follow this example you will need a FreeMaster project (.pmp or .pmpx) and an embedded application that already has the FreeMaster driver for connection with the project, more information about creating a FreeMaster project and configuring the board to run it can be found in How To implement an interface using FreeMaster. For this document we are going to expand the example from How To implement an interface using FreeMaster, you are invited to also use it or to use your FreeMaster project (just remember that the example code of this document will be based on the other example post).
Software/Hardware used
Hardware setup:
Board Used: FRDM-K64F
SDK: SDK_2.x_FRDM-K64F Version 2.8.2 (latest version)
Software setup:
Main Application (Embedded Application with FreeMaster Configuration) developed in: MCUXpresso IDE v11.2.0
FreeMaster Desktop Application Version: FreeMaster 3.0.2.6
Convert our FreeMaster project file to a hexadecimal block of data
First, we need to convert the project file (.pmpx) into a block of data in a C header file, what we need is the representation of our project file in hexadecimal values and save it as a variable so FreeMaster can use the TSA mechanism later to access it as a memory-mapped file.
To do this we can use the bin2h application, we are going to explain how to do it with bin2h but you are free to use any other method at your disposal. To download bin2h go to http://www.deadnode.org/sw/bin2h/:
The bin2h program is a command-line utility so we need to open our command-line interpreter of preference to use it (in this example we are going to use the Windows Command Prompt). Open your command-line interpreter and go to the direction where you downloaded the bin2h program (you can also add it to your Path environment variable so you can access bin2h from anywhere, you can see how that is done from https://www.java.com/en/download/help/path.xml).
Now the syntax to use bin2h is the next:
bin2h -flags variable_name < input file > output file
The input file is our FreeMaster project file, the output file is the name of the C header file that will be generated and the variable name is going to be the name of our array of hexadecimal values representing the project file (can be any name you want). We will add the -c flag to tell the application to include a variable with the size of the array.
So in the command line we write:
This will generate a data_example.h file containing a character array with the name example:
data_example.h contains:
At the end of the file another variable with the size in bytes of the array:
After creating the data_example.h file, we need to pass it to our source folder in the MCUXpresso project of our embedded application (remember for this document we are using the project example from https://community.nxp.com/docs/DOC-347236):
Implementing it in our code
TSA uses tables to describe the information and data we want to share with FreeMaster. We will need to create a new table with the description of the memory-mapped file of our FreeMaster Project (the data_example.h file).
In the c file of our application we add:
/* We include data_example.h in our code */
#include "data_example.h"
FMSTR_TSA_TABLE_BEGIN(files_and_links)
FMSTR_TSA_MEMFILE("/example.pmpx", example, example_size)
/* projects to be made available in FreeMASTER */
FMSTR_TSA_PROJECT("FreeMASTER Project (embedded in device)", "/example.pmpx")
FMSTR_TSA_TABLE_END();In this example, we named the table files_links to describe the content of the table, but it can be anything name we want. We use the FMSTR_TSA_MEMFILE to indicate the variable where our file is memory-mapped, it takes as arguments the name we are going to refer the project file when we are running the FreeMaster application (it has to end with pmp or pmpx so FreeMaster knows is a project file), the variable that contains the memory-mapped file and the size of that variable.
With FMSTR_TSA_PROJECT we facilitate the access to the FreeMaster project from the FreeMaster application, it creates a hyperlink to the project from the welcome page in FreeMaster, we need to indicate the text of the hyperlink and the name of the project file (the one we set up with FMSTR_TSA_MEMFILE), in the welcome page it will look like this:
After we create the table we need to add it in our table list (in this example we already have another table for our variables):
FMSTR_TSA_TABLE_LIST_BEGIN()
FMSTR_TSA_TABLE(first_table)
FMSTR_TSA_TABLE(files_and_links)
FMSTR_TSA_TABLE_LIST_END();To demonstrate the use of the TSA for memory-mapped files we are extending an example from the post How To implement an interface using FreeMasterHow To implement an interface using FreeMaster , in this example, we already have a TSA table for sharing our variables.
Our code should look something like this:
float sin_value = 0;
float angle_step = 0.0001;
FMSTR_TSA_TABLE_BEGIN(first_table)
FMSTR_TSA_RW_VAR(sin_value, FMSTR_TSA_FLOAT)
FMSTR_TSA_RW_VAR(angle_step, FMSTR_TSA_FLOAT)
FMSTR_TSA_TABLE_END();
FMSTR_TSA_TABLE_BEGIN(files_and_links)
FMSTR_TSA_MEMFILE("/example.pmpx", example, sizeof(example))
/* projects to be made available in FreeMASTER */
FMSTR_TSA_PROJECT("FreeMASTER Compare Project (embedded in device)", "/example.pmpx")
FMSTR_TSA_TABLE_END();
FMSTR_TSA_TABLE_LIST_BEGIN()
FMSTR_TSA_TABLE(first_table)
FMSTR_TSA_TABLE(files_and_links)
FMSTR_TSA_TABLE_LIST_END();
//The rest of our application
int main(void) {
With this done, now we can compile our code and program the flash of our board, to finally run our FreeMaster project from the board.
Running the project
Now let’s run the project from our embedded application, first open FreeMaster software and use the Connection Wizard to connect with your board:
Use the “Use direct connection to on-board USB port” option and select:
After that in the Welcome Page, you will see a new box-button under the “Explore the board” section of the Welcome Page:
Click on the button and the project will open, you can see that FreeMaster tools like the oscilloscope and configurations for the Variable Grid have been imported from our FreeMaster memory-mapped file. The FreeMaster project should look the same as when we created it.
Conclusion
With the use of the TSA feature, we have given our FreeMaster a plug and play functionality to run our project in any computer with FreeMaster without needing to pass our project file to that computer. The TSA table also allows us to share from our embedded application user resources like virtual directories, web URL hyperlinks, EEPROM files, and SD Card files, expanding the possibilities of what we can share and demonstrate with our application.
