Embedded module TQMa117xL

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.

Prerequisites

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)

Preface

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.

Flash to SPI-NOR on TQMa117xL

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

Serial Downloader

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

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

This guide describes how to prepare, build, run and debug Cortex-M7 MCUXpresso example applications on STKa117xL with Windows and Linux.

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

Prerequisites

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

Prepare Host System

On Windows Host

This section lists the required 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)

Create a local workspace 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 lists the required 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

Verify that ~/.profile contains the following entries:

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.

Create a local workspace directory:

mkdir ~/workspace
cd ~/workspace

Set up Workspace

Go to the root workspace directory and then clone the 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 installation directory needs to be added to the PATH environment variable.

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

Compile the Application

Remove old builds if necessary

On Windows Host

rmdir build /s

On Linux Host

rm -rf ./build

Available example applications for TQMa117xL:

List of Applications

Demo	Path used in the build command	Description
CANFD Ping Pong	`driver_examples/flexcan/canfd_ping_pong_buffer_transfer`	Demonstrates CANFD message ping pong between two boards over CAN bus.
EEPROM	`eeprom/m24cxx`	Uses onboard M24C64 EEPROM to read and write data.
FlexCAN Ping Pong	`driver_examples/flexcan/ping_pong_buffer_transfer`	Demonstrates CAN message ping pong between two boards over CAN bus.
FlexSPI NOR	`driver_examples/flexspi/nor/polling_transfer`	Demonstrates simple operations on the FlexSPI NOR flash.
Hello World	`demo_apps/hello_world/`	Hello World demo, to make sure everything has been set up correctly.
LED Blinky	`demo_apps/led_blinky`	Uses the Cortex-M7 to toggle a green LED on a GPIO pin periodically.
RTC Internal	`driver_examples/rtc`	Demonstrates how to use internal SNVS RTC with Alarm function.
RTC External	`driver_examples/rtc_external`	Demonstrates how to use RTC on I2C bus with Alarm function.
Temperature Sensor	`temperature_sensor`	Uses the onboard SE97B sensor to read the current temperature.

Additional information about the example applications on TQMa117xL can be found on our GitHub. For information about a specific application, refer to the corresponding example directory.

Build the Example:

west build -b tqma117xl-mba117xl mcuxsdk-examples-tq/_boards/tqma117xl-mba117xl/examples/<application_path>/ -Dcore_id=cm7 -DCUSTOM_BOARD_ROOT="mcuxsdk-examples-tq/_boards" --config=debug
#e.g. for the hello world 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
release	Speed- and size-optimized build for internal memory

The final build is located in build/<application_name>.elf.

Run and Debug the Demo

The applications can also be debugged via VS Code or GDB-Server.

Run the Demo using VS Code

Configure VS Code Settings
Open the workspace in VS Code and create a folder .vscode in the workspace root. Create a settings.json 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:

{
    "configurations": [
        {
            "showDevDebugOutput": "both",
            "type": "cortex-debug",
            "request": "launch",
            "name": "Load into ram",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/build/<application_name>_cm7.elf",
            "servertype": "jlink",
            "device": "MIMXRT1176xxxA_M7",
            "runToEntryPoint": "main",
            "interface": "jtag",
            "serverArgs": [
                "-endian", 
                "little",
                "-LocalhostOnly",
                "-speed", 
                "4000"
            ],
            "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

Boot the Board
Set the Board to Serial downloader mode:

Serial Downloader

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 virtual serial interfaces. The first interface will print serial output from the board's Linux and the second interface will receive the serial output from Cortex M7. Connect the Segger J-Link Debug Probe to X48.

Run the Demo
In VS Code, swap to the Run and Debug section on the left side and choose “Load into 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. The demo's output should be printed in the Cortex-M7 terminal.

Run and Debug the Demo using GDBServer

Boot the Board
Set the Board to Serial downloader mode:

Serial Downloader

Open the Debugserver
Open a terminal and start the J-Link GDB Server. Change the device specification (here: MIMXRT1176xxxA_M7) if necessary.

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

Note: On Windows, make sure that JLinkGDBServerCL.exe is available via the PATH environment variable or use the full path to the executable.

Run the Demo
Open a second terminal and start GDB.

# Windows
& '.\Program Files (x86)\Arm\GNU Toolchain 15.2 mingw-w64-i686-arm-none-eabi\bin\arm-none-eabi-gdb.exe'

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

With GDB, execute the following to start debugging the demo

file <PATH.elf>
target remote localhost:50000
monitor reset
monitor halt
load
monitor go

The demo's output should be printed in the Cortex-M7 terminal.

Table of Contents

Embedded module TQMa117xL

Prerequisites

Preface

Flash to SPI-NOR on TQMa117xL

Serial Downloader

SPI Boot

Prerequisites

Prepare Host System

Set up Workspace

Compile the Application

Run and Debug the Demo

Run the Demo using VS Code

Serial Downloader

Run and Debug the Demo using GDBServer

Serial Downloader