FreeMASTER is a useful tool developed by NXP to perform debugging, logging, and tuning of control algorithms. This tutorial will cover the most basic usage of the tool, assuming the controller is being developed with the MATLAB/Simulink templates provided with the FlexCase. For advanced functionality and other options, please contact us to discuss your needs or visit NXP’s website for additional documentation.
WARNING: Directly accessing controller memory can cause unsafe conditions if not done safely. This tool should be used for development purposes only, and not for production deployments. Volatile data stores should be replaced in your Simulink model if the FlexCase is moving beyond a development environment.
Prerequisites
- Complete the quick start guide for a tutorial on connecting to the FlexCase and flashing binaries
- Complete the Simulink guide for building a model into a flashable binary
- Ensure you have FreeMASTER installed.
Configure the BDM Connection
- Power up the FlexCase and connect through VirtualHere
- Start FreeMASTER and run the “Connection Wizard” tool in the Tools Menu or by clicking the box in the main project page
- Enter the following options:
- Port Type: debugger probe or on-board debugger
- BDM Communication: Directly on target board
- OpenSDA with standard P&E Micro firmware
- Choose direct access to target memory
- Click “Plug-in Configuration” to establish the connection
- Driver: CortexM
- Connection: OpenSDA
- CortexM SWD Mode
- Click “Test Connection”
- A popup will indicate that the board is connected
- Click “Finish”. The software may prompt you to load symbolic information, which is covered in the next step.
Add Binary to Project
- Open the FreeMASTER sample template in Simulink (FMSample.slx) and build the model
- Flash FMSample.elf to the FlexCase using S32DS
- In FreeMASTER, follow the prompt to add symbolic information, or click “Project>Options>MAP Files” from the main menu
- Add the .elf binary that was just generated by Simulink
- Depending on the prompts, the connection to the board may start automatically, or you can toggle the connection with the GO/STOP buttons at the top of the menu
WARNING: Do not attempt to connect to the board while flashing new software is in progress, or attempt to flash software while FreeMASTER is connected.
Read Model Data Variables
- Start the connection to the board if not already started
- In the “Variable Watch” area at the bottom of the page, select “Create new watched variable”:
- Select the input variable for the simulated controller sample_in in the “Definition” tab. Leave the Modifying tab as is for now.
- Select the variable from the list of addresses available, and the name will automatically be updated*
- Make sure the type matches the definition in the simulink model (a single is a 4-byte floating point number)
- Select 100ms sampling period
*The specific address of sample_in (ex. 0x20000174) may be different in your binary based on small changes in the model or compiling process.
(Optional) If you cannot find a variable in the address list: MATLAB sometimes renames variables, which you can check manually after building the Simulink model. The most common change is modelname_DW.varname. If you still cannot find the name, right-click on the variable you wish to monitor, hover over C/C++ code, and click Navigate to C/C++ code. You will be able to see the renamed variable in the opened display. With higher Simulink code optimization settings (in the Configuration Parameters->Code Generation->Optimization), some variables may be eliminated if Simulink deems them fit for elimination. If you wish to disable this feature, you can set optimization to Minimum.
If formatted correctly, you should see the variable toggling between 0 and 1 at 1s intervals, as defined in the model.
Create a new watched variable for the controller output sample_out:
- Find the address from the list
- Set the type to 4 byte floating as before
- Set the polling rate to fastest for better time resolution.**
The simulated output should be attempting to follow the input with some oscillations, which we will use a scope to see in more detail.
**When you are developing your own projects, reading many variables at the “fastest” polling speed may cause bottle-necks, so only select fastest polling for variables that require it, and select an appropriate timing interval for others.
Create a new Oscilloscope from the Project Tree and insert the input and output variables:
- Set the period to 10ms, and the X-axis width to 5 seconds***
- In the variables tab, add sample_in and sample_out. Similar variables can be placed in the same block, or you can create multiple blocks for multiple Y-axes
***If your computer is struggling to display the plots, you can increase the sample time or decrease the X-axis width.
Write to a variable
In order to write directly to memory, we will be adding a variable to our Simulink model, making it viewable by FreeMASTER, and manipulating it live.
WARNING: Writing directly to memory has the potential to cause damage or unexpected behavior, and should only be done in the development phase of your project. Take extra care to ensure that the variable properties (size, type, min/max) match between the model and FreeMASTER.
- In Simulink, add a Data Store Memory block (found in the library Simulink/Signal Routing) with the following settings:
- Name: sample_gain
- Initial value: 1
- Data type: single
- Add a Data Store Read block and a Product block to connect the gain to the controller:
- Making sure FreeMASTER is disconnected first, build and flash the new .elf file.
- After the flash is successful, reconnect to the board in FreeMASTER. You should be prompted to reload the .elf file since it has been modified by Simulink, or you can press “Ctrl + M” to reload the file manually.
- Create a new watched variable for sample_gain:
- 4-byte floating point
- Sample time 1s (written variables will update immediately when user enters new value)
- In the Modifying tab, allow any value within limits 0 to 20. This setting is important to consider to prevent unexpected behavior.
- Adjust the controller gain and see the response of the output change. Try a value of 0.5 for an underdamped response or 15 for less stable oscillations. Selecting an invalid value will revert to the last valid entry.
Log Polling Data
Logging is available via the Oscilloscope properties.
In the Data Capture tab of the Oscilloscope properties, select the following:
- Capture data on background (logging whenever connected to the board)
- Recording starts always to new file
- Text format
- Create a destination directory for each session or project iteration, since the file names generated are generic (osc0001.txt, etc.)
- Change capture mode back to “Data capture off” so that capture can be manually switched from the main toolbar.
After connecting to the board, you should be able to toggle the recording setting and see new logs being generated in your chosen directory:
The different available logging options will depend on your specific application. Multiple oscilloscopes can be set up and recorded with different default settings for recording.
FreeMASTER over CAN
This option applies if you have a lite version of the FlexCase, or you wish to debug over CAN instead of IP. FreeMASTER can interace with various popular CAN debugging hardware (Vector, PEAK, Kvaser, etc.) with minimal changes to the configuration:
- In Simulink (FMSample.slx)
- Go to the Audesse Hardware Modules Config subsystem
- Uncomment the FreeMaster_Config block
- Rebuild the model, and flash it to the FlexCase
- In FreeMASTER
- Enter the Connection Wizard as before
- Select Connect over CAN bus with CAN card or USB-to-CAN module
- Connect your preferred USB-to-CAN device to your PC and click Plug-in Configuration
- Configure the device and set the baud rate to 1Mbps (other settings can remain default)
To prove functionality of the CAN interface, disconnect ethernet and wait for the FlexCase to disappear from Virtualhere; FreeMASTER should still show data updating. The original BDM functionality can be restored by commenting out the FreeMaster_Config block and re-running the connection wizard. The CAN bus being used for FreeMASTER should not be used for any other CAN functionality.
HTML GUI Elements
FreeMASTER is capable of rendering arbitrary HTML/JS to add more flexibility to the user. When adding functionality, always avoid using html/javascript templates or libraries from untrusted sources.
Download the HTML GUI sample from our sample software page. The archive contains the following files:
- example_flexcase.htm : base html page
- freemaster-client.js : NXP library for interfacing the html page with FreeMASTER
- simple-jsonrpc-js.js : connection for browser renderer
The unmodified version of the files can be found at the FreeMASTER installation path if needed (ex. C:/NXP/FreeMASTER 3.1/FreeMASTER/examples/scripting/JavaScript-JSON-RPC)
Unzip the archive and point to the HTML file in the FreeMASTER options. Make sure the rendering engine is set to Chromium/JSON-RPC.
The main project area should now show some basic html elements. If the page does not display immediately, press F5 to refresh the page. The FreeMASTER functions for reading/writing variables can be connected to generic display elements.
Next Steps
After completing this tutorial, you should be familiar with the basic functions available for debugging, logging, and calibrating your software during development. The HTML sample can be used to create custom dashboards and testing/calibration interfaces.
Since this particular method of data capture is based on polling, the data is not guaranteed to be synchronized with the execution loop of the processor. Other options are available to capture logs for debugging or analysis, so please let us know if your project has special requirements.
