Sample applications in this repository demonstrate basic usage of NXP FreeMASTER tool and FreeMASTER communication driver running in Zephyr RTOS. The FreeMASTER driver enables communication between the MCU Zephyr application and FreeMASTER tool running on a host PC. This can be either FreeMASTER desktop application or FreeMASTER Lite command-line tool.
Both FreeMASTER tools support wide range of physical communication interfaces such as UART, CAN, USB, Network TCP/UDP or Segger RTT. All these options are also supported by the FreeMASTER Zephyr driver and are demonstrated in sample applications herein.
Refer to nxp.com/freemaster for more information about NXP FreeMASTER tools.
All sample applications here are very similar. The differences are in board-specific overlay files and in the main() function code which takes care of hardware-specific initialization of the FreeMASTER communication interface.
The rest of the source code is located in a common directory and is shared by all samples. Application features are quite trivial, the main purpose is to enable basic visualization and control of the application data in FreeMASTER tool.
Communication
- The main() function initializes hardware interface and enters an endless main thread loop.
- FreeMASTER thread is created automatically on background and takes care of additional initialization of the communication interface and later it handles the communication and protocol decoding.
Endless increments
- The main thread loop endlessly increments var8, var16 and var32 variables so the values eventually overflow and wrap around to 0.
- The increment amount is stored in inc variables (var8inc, var16inc, var32inc) which are writable from FreeMASTER UI.
- By modifying the inc increments, you can control how quickly the variables overflow and observe it as typical saw-tooth shaped graphs in FreeMASTER.
Dummy threads
- Two dummy Zephyr threads are automatically created. The threads perform mathematically intensive work to keep the CPU busy.
- A context data control how much CPU each of the dummy threads consume and how deep the thread function nests in a self-recursive calls.
- All this "useless" work is done on purpose - FreeMASTER may modify the control data so the CPU and thread stack usage can be observed in the control dashboard displayed in the FreeMASTER.
- BEWARE: Zephyr RTOS and MCU hardware cannot prevent stack overflow condition so by using more than 30-level recursion, the dummy threads stack may cause an application crash.
FreeMASTER TSA tables
- All variables accessed from FreeMASTER tool are referenced in so-called TSA tables located in the application source code.
- FreeMASTER parses variable names, addresses and data types from TSA, so it does not need to load this information from application ELF file.
- Loading ELF file is also possible, but use of TSA enables the same FreeMASTER project to be used with any of the sample applications without change.
- Even the FreeMASTER project file (zephyr_demo.pmp) is stored as a constant C byte array in a TSA table which makes it possible for FreeMASTER to load it directly from the connected application memory. Refer to icon which appears in the FreeMASTER Welcome Page after connection is established. Note that this option is only available on targets with enough Flash memory.
-
Zephyr Threads and CPU load displayed in FreeMASTER UI. The UI is built in HTML and JScript. It uses a FreeMASTER JSON-RPC interface to get access to target MCU memory and gather information about Zephyr threads. The UI runs in Chromium or Edge web browser view hosted directly in the FreeMASTER window.
-
Application variables are displayed in runtime Oscilloscope graphs. The graphs shows a typical saw-tooth pattern of endlessly incremented integer variables.
Clone this repository using Zephyr west tool. The repository home folder is samples/freemaster and it contains the main workspace manifest file west.yml.
west init -m "https://github.com/nxp-zephyr/fmstr-zephyr-samples.git" --mr main fmstr-zephyr
Feel free to modify the west.yml file to change the way the Zephyr RTOS code is loaded. By default, the public version of Zephyr RTOS and NXP FreeMASTER middleware module will be cloned from the GitHub server.
cd fmstr-zephyr
west update
- fmstr_serial - uses Serial UART communication or (legacy) USB stack
- fmstr_usb - uses USB NEXT stack to implement CDC virtual serial communication
- fmstr_can - uses CAN bus for CAN or CAN-FD communication
- fmstr_net - uses TCP or UDP network socket communication
- fmstr_rtt - uses Segger RTT communication over J-Link interface
See more details in readme.md file located in the root folder of each example.
Each sample has its own Kconfig and prj.conf files. Run a guiconfig inside selected sample directory to configure the application, FreeMASTER module and Zephyr RTOS features. Typically, you will want to run the guiconfig for selected target board, for example FRDM-MCXN947:
cd fmstr_serial
west build -b frdm_mcxn947/mcxn947/cpu0 -t guiconfig
-
The demo configuration appears at the top of the list,
-
FreeMASTER module configuration is in the Modules/nxp_freemaster section.
The following configuration options are enabled in all sample applications' prj.conf files. There are also other application-specific options and Zephyr RTOS features configured in each application Kconfig file.
Also refer to the main FreeMASTER module Kconfig file located in modules/freemaster/zephyr.
- Require FreeMASTER driver module:
CONFIG_USE_FREEMASTER=y
- Auto-create the FreeMASTER thread. The thread runs the FreeMASTER interface initialization and handles communication and protocol processing. It greatly simplifies use of FreeMASTER in Zephyr, but as a standalone thread it also consumes some resources. Thread Auto-creation can be disabled and the thread can be created programmatically by the application. For maximum resource saving, the thread functions may even be called by other application threads.
CONFIG_FMSTR_USE_THREAD=y
- Configure FreeMASTER working thread stack size and priority. The defaults provided in Kconfig are typically not needed to be changed.
CONFIG_FMSTR_THREAD_STACK_SIZE=2048
CONFIG_FMSTR_THREAD_PRIORITY=3
- Configure FreeMASTER features and number of service instances. Refer to FreeMASTER documentation to get familiar with Recorder, Oscilloscope, Pipes, TSA and other FreeMASTER features.
CONFIG_FMSTR_USE_RECORDER=2
CONFIG_FMSTR_USE_SCOPE=1
CONFIG_FMSTR_USE_PIPES=2
CONFIG_FMSTR_USE_TSA=y
- The following settings enable Zephyr shell to run over selected FreeMASTER pipe.
CONFIG_SHELL=y
CONFIG_FMSTR_USE_PIPE_SHELL=y
CONFIG_FMSTR_SHELL_INIT_LOG_LEVEL=3
- Also the Zephyr logging and printk may use the same output as shell, meaning that it will also print output to FreeMASTER pipe.
CONFIG_LOG=y
CONFIG_SHELL_LOG_BACKEND=y
CONFIG_LOG_BUFFER_SIZE=2048
CONFIG_LOG_PRINTK=y
- Extended thread information can be enabled, so the FreeMASTER may display it in the demo UI dashboard.
CONFIG_THREAD_RUNTIME_STATS=y
CONFIG_SCHED_THREAD_USAGE=y
- Before debugging the application, it might be helpful to turn off the optimizations. Makes sure to leave it 'n' for production builds.
CONFIG_NO_OPTIMIZATIONS=n
fmstr_serial - example using Serial UART communication
Configuration for FRDM-MCXN947 board
cd samples/freemaster/fmstr_serial
west build -b frdm_mcxn947/mcxn947/cpu0 -t guiconfig
Build
cd samples/freemaster/fmstr_serial
west build -b frdm_mcxn947/mcxn947/cpu0
All sample code in this repository is available under BSD 3 Clause License. However, when porting the FreeMASTER support to new boards, please consider license agreement applicable to FreeMASTER Zephyr module. The NXP LA_OPT_Online Code Hosting license enables use of the FreeMASTER software solely in combination with a NXP Product. A similar license restriction applies to use of the FreeMASTER desktop tool and to FreeMASTER Lite.
- FreeMASTER driver repository
- FreeMASTER Zephyr samples (this one)
- FreeMASTER MCUXpresso SDK examples
Copyright 2025 NXP