Embedded module TQMa117xL

Build the Demo
Flash the Demo

This guide describes how to flash an already built hello_world_demo to STKa117xL using NXPs MCUXpresso Secure Provisioning Tool.

Segger J-Link Debug Probe
Demo Artefacts built according to the Building a Demo Guide
An NXP Account for the MCUXpresso Secure Provisioning Tool (v.26.03)

Download and install NXPs Secure Provisioning Tool. An NXP Account is necessary to download the Software.

Build the Demo according to the Guide. Use the build configurations flexspi_nor_debug or flexspi_nor_release. The resulting artefact will be adjusted and flashed to SPI-NOR of TQMa117xL.

Use the following DIP switch configuration to put the board into serial downloader mode.

Serial Downloader

S3

S4

S5

S6

Open the Secure Provisioning Tool and create a new workspace. Select a location and choose the correct processor (e.g. MIMXRT1176 (RT1170-EVKB)), then click “create”.

Select the processor menu in the top left corner.

Pick the correct processor.

Select the programming interface menu.

Pick UART as connection type and set the COM port to the one that is used for the target hardware connection. Set the baud rate to 115200. Check the connection with the “Test Connection” button afterwards.

Go into the boot memory configuration.

Configure the parameters like the following.

Swap to the “Build image” tab and select the hello_world_cm7.elf, then click “Build Image”.

Swap to the “Write image” tab. The correct image (./bootable_images/hello_world_cm7.bin) should be selected already. Click “Write Image”.

Open a serial terminal, select the COM Port of the target and a baud rate of 115200.

Power off the board and select the SPI boot mode using the following DIP switch configuration:

SPI Boot

S3

S4

S5

S6

When powering on the board now, the serial terminal should print a “hello world” message.

This guide describes how to prepare, build and run a Cortex-M7 MCUXpresso hello world demo on STKa117xL with Windows and Linux.

Unless otherwise specified, the commands apply to both operating systems.

Segger J-Link Debug Probe
Windows 10/11 or Ubuntu 22.04 and above

On Windows Host

This section describes the installation of the following tools:

Python3 (including pip) (version 3.8 or above)
ARM GNU Toolchain (e.g. version 15.2rel1, use AArch32 bare-metal target (arm-gnu-toolchain-15.2.rel1-mingw-w64-i686-arm-none-eabi.msi))
Segger J-Link Software (version 9.34b)
Visual Studio Code (VS Code)
VS Code Extension Cortex-Debug (ID: marus25.cortex-debug)
CMake (version 3.30 or above)
West (version 1.5.0 or above)
Ninja (version 1.13.0)

Download the installers and complete the installation wizards for Python, the ARM GNU Toolchain, Segger J-Link, and Visual Studio Code. If these tools are already installed, make sure their versions meet the version requirements mentioned above. CMake and West will be installed after the workspace is set up.

Remember the installation directories for the ARM GNU Toolchain and Segger J-Link as they are important later on.

In VS Code, install the Cortex-Debug extension. (ID: marus25.cortex-debug)

Set up a workspace directory in a local directory

mkdir workspace
cd workspace

The ARMGCC_DIR system variable must be set to the installation directory of the ARM GNU toolchain. (e.g. C:\Program Files (x86)\Arm\GNU Toolchain mingw-w64-i686-arm-none-eabi) This can be achieved in the Windows Settings → System → Advanced System Settings → Advanced → Environment Variables

On Linux Host

This section describes the installation of the following tools:

Python3 (including pip) (version 3.8 or above)
ARM GNU Toolchain (e.g. version 15.2rel1, use AArch32 bare-metal target (arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz))
Segger J-Link Software (version 9.34b)
CMake (version 3.30 or above)
West (version 1.5.0 or above)
Ninja (version 1.13.0)

Install Python

sudo apt update  
sudo apt install git python3-full python-is-python3 python3-pip

Download and install the SEGGER J-Link software package: https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.deb

cd ~/Downloads 
sudo dpkg -i JLink_Linux_V934b_x86_64.deb

Install the ARM GNU Linux Toolchain

wget https://developer.arm.com/-/media/Files/downloads/gnu/15.2.rel1/binrel/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz
sudo tar --xz -xf arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz --directory /opt
rm arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi.tar.xz

Check the ~/.profile

cat ~/.profile

It should contain the following lines:

# set PATH so it includes user's private bin if it exists
PATH="$HOME/bin:$PATH"
# set PATH so it includes user's private bin for python if it exists
PATH="$HOME/.local/bin:$PATH"

Create an ARMGCC_DIR environment variable

export ARMGCC_DIR=/opt/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi/

Note: The exported variable will be gone if the terminal is closed.

Set up the workspace directory

mkdir ~/workspace
cd ~/workspace

Go to the root workspace directory and then clone the Git Repository:

git clone https://github.com/tq-systems/mcuxsdk-examples-tq.git

Install necessary dependencies for the SDK:

pip install ninja jsonschema cmake west
pip install -r mcuxsdk-examples-tq/scripts/requirements.txt

Initialize the workspace

west init --local mcuxsdk-examples-tq 
west update

Note: If the installed commands (e.g. west) are not recognized, their location needs to be added to PATH first.

For Windows, add the following to the system environment:
C:/Users/<Username>/AppData/Roaming/Python/Python3x/Scripts

For Linux, execute:
export PATH=$PATH:$HOME/.local/bin

Remove old builds if necessary

On Windows Host

rmdir build /s

On Linux Host

rm -rf ./build

Build the demo

west build -b tqma117xl-mba117xl mcuxsdk-examples-tq/_boards/tqma117xl-mba117xl/examples/demo_apps/hello_world/ -Dcore_id=cm7 -DCUSTOM_BOARD_ROOT="mcuxsdk-examples-tq/_boards" --config=debug

Build configuration and parameters:

Parameters:

-DCUSTOM_BOARD_ROOT: Necessary for board definitions outside of the mcuxsdk directory.
-Dcore_id: Target core for the build (e.g. cm7, cm33).
--config: Optional, used to set the build configuration. Uses configuration debug by default.
--pristine: With this parameter, the build directory is cleaned before the build process.

Build Configurations:

Build Configuration	Description
debug	Build for SRAM with full debug symbols and no optimization
flexspi_nor_debug	Build for NOR Flash with full debug symbols and no optimization (XIP possible). Data, Heap, and Stack are allocated in internal SRAM
flexspi_nor_sdram_debug	Build for NOR Flash with full debug symbols and no optimization (XIP possible). Data, Heap, and Stack are offloaded to external SDRAM
release	Speed- and size-optimized build for internal memory
flexspi_nor_release	Speed- and size-optimized build for NOR Flash (XIP possible). Data, Heap, and Stack are allocated in internal SRAM
flexspi_nor_sdram_release	Speed- and size-optimized build for NOR Flash (XIP possible). Data, Heap, and Stack are offloaded to external SDRAM

The final build is located in ~/build/hello_world_cm7.elf.

On Windows Host

In the root directory (where the mcusdk repositories and the build folder are located), create a directory .vscode. Create a settings.json in .vscode with the following content and modify the installation paths:

{
    "cortex-debug.gdbPath": "<arm-none-eabi-gdb.exe path>",
    "cortex-debug.armToolchainPath": "<arm-none-eabi-gcc.exe path>",
    "cortex-debug.JLinkGDBServerPath": "<JLinkGDBServerCL.exe path>",
    "cortex-debug.variableUseNaturalFormat": true,
}

Note: The content can also be copied from /mcuxsdk-examples-tq/templates/settings.json

Create a launch.json with the following content and change the device specification if necessary:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug J-Link Ram",
      "type": "cortex-debug",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "servertype": "jlink",
      "device": "MIMXRT1176xxxA_M7",
      "interface": "jtag",
      "executable": "${workspaceFolder}\\build\\hello_world_cm7.elf",
      "serverArgs": [
        "-endian",
        "little",
        "-LocalhostOnly",
        "-speed",
        "4000",
        "-device",
        "MIMXRT1176xxxA_M7?BankAddr=0x30000000&Loader=nCS@AD18_CLK@AD19_D0@AD20_D1@AD21_D2@AD22_D3@AD23&BankAddr=0x60000000&Loader=nCS@SDB100_CLK@SDB101_D0@SDB102_D1@SDB103_D2@SDB104_D3@SDB105"
      ],
      "postLaunchCommands": [
        "target remote localhost:50000",
        "monitor reset",
        "monitor halt",
        "load"
      ]
    }
  ]
}

Note: The content can also be copied from /mcusdk-examples-tq/_boards/tqma117xl-mba117xl/templates/launch.json

Set the Board to Serial downloader mode:

Serial Downloader

S6

The DIP-Switches S3-S5 can all be turned off. Connect the Starterkit to the Host as described in the STKa117xL Quickstart Guide and open two new terminals with the first and second COM Port devices. The first port will print serial output from the boards Linux and the second port will receive the serial output from Cortex M7.

In VS Code, swap to the Run and Debug section on the left side and choose “Debug J-Link Ram” from the dropdown menu. Then, click the green PLAY button (or press F5).

The program will be loaded onto the board and will start the main function. A “Hello World” text should be printed on the serial console

On Linux Host

Set the Board to Serial downloader mode:

Serial Downloader

S6

The DIP-Switches S3-S5 can all be turned off. Connect the Starterkit to the Host as described in the STKa117xL Quickstart Guide and open two new serial terminals with the first and second COM Port device. The first port will print serial output from the boards Linux and the second port will receive the serial output from Cortex M7.

Open another terminal and open the debugserver there. Change the device specification (here: MIMXRT1176xxxA_M7) if necessary.

JLinkGDBServerCLExe -device MIMXRT1176xxxA_M7 -if JTAG -speed 4000 -port 50000

Connect to the GDB server in the first terminal

/opt/arm-gnu-toolchain-15.2.rel1-x86_64-arm-none-eabi/bin/arm-none-eabi-gdb

Execute the following to start debuging the demo

target remote localhost:50000
monitor reset
monitor halt
load ~/workspace/build/hello_world_cm7.elf 
monitor go

The second serial terminal should print a “hello world.” message.

Embedded module TQMa117xL

Prerequisites

Preface

Flash to SPI-NOR on TQMa117xL

Serial Downloader

SPI Boot

Prerequisites

Prepare Host System

Set up Workspace

Compile the Demo

Run and Debug the Demo

Configure VS Code settings

Boot the Board

Serial Downloader

Run the Demo

Boot the Board

Serial Downloader

Open the Debugserver

Run the Demo