1 Objectives

In this lab, you will learn

• NXP development steps within Visual Studio Code
• Install software repository for NXP i.MX RT1060 Evaluation Kit
• Build the hello_world example for the i.MX RT1060
• Flash and run application
• RTOS Project thread awareness tools
• Explore Debug capabilities using Visual Studio Code

2 Pre-Requisites

This sample project lab is written for Windows10, but MCUXpresso for Visual Studio Code can also be easily installed on macOS and Linux.

• Follow software installation for MCUXpresso for VS Code extension
• Download or receive MCUXpresso SDK for i.MX RT1060 EVKB. (SDK_2_16_100_MIMXRT1060-EVKB.zip)

3 Hardware Requirements

• i.MX RT1060 Evaluation Kit (MIMXRT1060-EVKB)
• 1 Micro-USB cable

4 Preparing the Hardware

This lab targets the NXP i.MX RT1060 cross-over microcontroller evaluation kit. The kit provides a rich set of connected peripherals to help evaluate the device. It includes an on-board Debug Probe. The debug probe is pre-programmed with CMSIS-DAP firmware for this lab. To display debug messages in the examples, the lab connects to the comm port available through the same debug probe.

4.1 Connecting to Evaluation Kit

The following image and instructions will help properly setup your hardware:

Power, Debug and Comm Port

Connect one end of the USB cable to the PC running Visual Studio Code with the MCUXpresso extension. Connect the other end of the USB micro cable to the J1 USB connector on the Evaluation Kit. The LEDs on the Evaluation Kit will indicate power is applied.

5 Running “Hello World” Project

This lab section covers how to import a new NXP microcontroller example project into Visual Studio Code. Helpful steps are included to improve the development experience.

5.1 Add NXP SDK

The NXP extension adds tools to help add software repositories into the Visual Studio Code workspace. The software repository can be provided from three sources: Remote git url; NXP MCUXpresso SDK archive file; Existing git folder. This section will import the MCUXpresso SDK for the i.MX RT1060 cross-over microcontroller using the SDK archive file provided as Pre-requisite .

1. Click “Import Repository” button in the INSTALLED REPOSITORIES pane. A button is visible before the first repository is added. In the future, users can click the ‘+’ symbol in the top right of the Installed Repositories section for adding repositories.

   

2. Select the “LOCAL ARCHIVE” option to import the provided i.MX RT1060 SDK archive file.

3. Browse to the location of the i.MX RT1060 SDK file for the “Archive” entry. (In the Downloads folder)

4. Browse to a folder to be a common “Destination” to store SDKs. (i.e. C:\Users\NXP\VS-Code-Projects) Enter a name for the new SDK, in this case \SDK_2_16_100_MIMXRT1060

   

5. Click Import. The i.MX RT1060 SDK is extracted to the local folder and added to your INSTALLED REPOSITORIES pane.

   

Note: The current extension requires an NXP SDK to be v2.13.0 or newer.

5.2 Import Example Project

The NXP extension provides a PROJECTS pane to help developers import projects into their workspace. The user has three sources for importing a new project: a Repository; an existing local project; an archived project. This section will import an i.MX RT1060 example from the SDK just added to the INSTALLED REPOSITORIES pane.

1. Click Import Example from Repository. A button is visible when no projects are in the current workspace. In the future, the symbols in the top right of the Projects section can be used to import additional projects. Click ‘II\’ symbol to add Repository Examples. Click ‘[+]’ symbol to import projects on the PC that were created earlier by the MCUXpresso for VS Code extension. Click the ‘[ ]’ symbol to import a project in an archive file created earlier by the MCUXpresso for VS Code extension.

   

2. Fill out the appropriate information in the “Import Example from Repository” window. Click “Choose a repository” to select from a list of available/installed repositories. Select SDK_2_16_100_MIMXRT1060.

3. Click “Choose a toolchain” to select from a list of available build tools. The MCUXpresso Installer provides a default option of “gcc-arm-none-eabi-10.3”. The tool also looks in other default locations for MCUXpresso IDE installations. These may be listed as alternative options for GNU Arm toolchains. Select the “gxx-arm-non-eabi-10.3” option.

4. Click “Choose a board” to view the boards supported in the selected repository. Longer list of boards can be filtered by typing in the available selection area. (i.e. type 1060 to filter only RT1060 boards) Select EVK-MIMXRT1060. After a board is selected, a picture of the board will be displayed to help confirm the correct selection.

5. Click “Choose a template” to show a list of available examples in the selected repository. The long list of examples can be filtered by typing in the available selection area. (i.e. type Hello to filter Hello World examples) Select demo_apps/hello_world

   

6. Click Browse for the “Location” field. Choose a folder location for new projects to be created. For this lab, use the same folder used for the SDKs (i.e. C:\users\NXP\VS-Code-Projects)

7. Click Create. This will add a new “Hello World” example for the i.MX RT1060 to your Projects pane.

5.3 Explore and Edit Project

The NXP MCUXpresso extension provides useful information for each project with a Project pane. The developer can quickly determine the SDK type, Board, Device and SDK version for a project. The view also provides a Components view that lists the software components available to a developer in the project. The list uses icons to indicate if the component is used or not in the project. Developers can add components to the project by clicking on the component. This adds the component to the project Cmake file, so the project includes the component when being built.

1. View Project information in NXP Project pane Expand the different elements under the Projects pane.

Note: Collapse the other panes to maximize the area for the Project information. * a. Settings * b. MCU * c. Build Configurations * d. Repository * e. Project Files

2. To view the files included in a project, click on an Explorer icon . There are two icons available to go to the Explorer perspective. Selecting the project name in the list will display project icons. The 2-page icon represents Explorer. The same 2-page icon is provided at the top of the Left pane navigation. Click on the 2-page icon that appears to the right of the project name.

   

3. The Explorer file perspective is now displayed. The files in the Hello World project are listed in the Explorer view.

4. The Explorer view is where you can modify the files within a project. Click on the hello_world.c file to open the main file in the Visual Studio Code editor.

   

5. Modify the “hello world.\r\n” on line 48 to a custom message.

   

6. Press Ctrl-S to save the changes to the project file.

You have now modified the default project and are ready to build the project.

5.4 Build Project

The build process is configured when the project is created. The user can initiate the build from an icon in the project view. To the right of the project name, the gear wheel icon will start the build for that project. You need to return to the MCUXpresso extension perspective by clicking the “X” icon in the left navigation pane. You may still be in the Explorer perspective from prior section.

1. Click the gear wheel to the right of the hello_world project. This will start the build process. The OUTPUT terminal tab at the bottom of the screen displays the build progress.

2. Alternatively, you can right click on the project name to display additional build options. Clicking Rebuild or Clean Build will remove build artifacts from prior builds to allow the project to be built again. Otherwise, clicking Build Selected will result in an output of “no work to do”.

   

The build process should complete with an exit code of 0… Success!

5.5 Temporary Debug Probe Setting

Before debugging the application, the GDB timeout needs to be extended for some PCs. The CMSIS-DAP probe configuration as a USB storage device requires this increased timeout. J-Link and LPC-Link probe firmware does not have the same requirement.

Note: This step will not be required in future versions of the MCUXpresso Extension of VS Code.

1. To update the launch file, switch to the Explorer view (Ctrl+Shift+E) and open the file hello_world > .vscode > launch.json

2. Make changes to the configuration by updating the gdbInitCommands attribute and save the file (Ctrl+S):

   "gdbInitCommands": [
       "set remotetimeout 60000",
       ...
   ]
   

   

5.6 Flash and Debug Project

MCUXpresso for Visual Studio Code allows users to program and debug projects for NXP microcontrollers. These steps require that Debug Probe drivers are properly installed and configured. MCUXpresso for Visual Studio Code allows the use of popular debug probes from NXP, Segger and PEmicro. MCUXpresso Installer included the option to properly install support for the different debug probes.

The built project output binary is flashed to the target board before launching a debug session. The Debug session provides controls and views to help the developer analyze the operation of the project. The following steps will show how to successfully flash and program the i.MX RT1060 evaluation kit.

1. Confirm that the on board debug probe is connected to the PC USB port.

2. Click the Refresh arrow in the DEBUG PROBES pane to detect connected debug probes.

   

3. Click the Build Configurations to view the different options included in the imported project.

   To properly debug the project, we will change the Default configuration to be “flexspi_nor_debug”.

   This will allow the debug probe to write the program to the spi flash.

   

4. Starting a Debug session begins by programming the target device with the built project image.

   Click the common Play triangle icon to the right of the selected project.

   

5. Visual Studio Code Debug sessions provide a different “Run and Debug” perspective for the user. This is reflected by the Bug icon in the primary left navigation pane now being highlighted.

   Key tools are labeled in the following image:

   • a. Start Debug: Another place to launch debug
   • b. Debug Controls: Pause; Step Over; Step Into; Step Over; Restart; Stop
   • c. Variables: Locals and Registers
   • d. Watch: Add expressions to continue to monitor
   • e. Call Stack: List of active subroutines in the program
   • f. Breakpoints: Add, Toggle and View targeted code

   

6. Visual Studio Code integrates a serial console to view project debug messages.

   Click the “Serial Monitor” tab at the bottom of the screen.

7. Select the “VCom Port” under port options. Make sure Baud rate = 115200.

8. Click “Start Monitoring“

   

5.7 Setting Breakpoints

1. Add a Breakpoint to code. Use Call Stack to navigate to subroutine of interest. In this case main().

   Click main() under the Call Stack pane.

   Note: You may need to pause the program if your call stack indicates it is running.

2. The editor will open the hello_world.c file where main() is located. Click to the left of line 52. A red icon will appear and an entry is added to Breakpoints pane.

3. Use Debug Controls to Continue/Step through code

4. The Hello_World program is looping while waiting to receive characters from the serial port.

   Type characters in the Serial Monitor where it indicates “Type in a message to send to the serial port”.

   Press Enter.

   The sent character triggers the active Breakpoint. The session is paused at the breakpoint.

   The Variables pane updates to show the sent character was captured by the device.

   

5. Some developers may want to observe this behavior at an assembly code level. Visual Studio Code makes it easy to add an assembly view to debug.

   Right Click main() when hovering over it in the Call Stack pane.

   Select “Open Disassembly View”.

   

   Developers can leave both windows open side-by-side to and use the Debug controls to evaluate the step-by-step execution of the program.

This completes this section of the lab. You have imported and experimented with your first project within MCUXpresso for Visual Studio Code.

6 Running an RTOS Project

The next part of the lab will demonstrate additional development features within VS Code. Selecting an example that includes an RTOS adds additional debug tools for thread awareness.

6.1 Import FreeRTOS Semaphore Project

Repeat the same steps used to import the Hello World example in the prior section. This SDK includes a FreeRTOS project that demonstrates the use of semaphores. This example is useful for viewing the state and size of different threads.

1. Use the image below to help complete the steps to import the “freertos_sem” project. Refer back to section 5.2 to review the required steps.

   

6.2 Build RTOS Project

Build the freertos_sem project using the same steps from the hello_world project. Refer to section 5.4 to review the details.

6.3 Temporary Debug Probe Setting

You must follow same modification to the project degub configuration file. The GDB timeout needs to be extended for some PCs. The CMSIS-DAP probe configuration as a USB storage device requires this increased timeout. J-Link and LPC-Link probe firmware does not have the same requirement.

Note: This step will not be required in future versions of the MCUXpresso Extension of VS Code.

1. To update the launch file, switch to the Explorer view (Ctrl+Shift+E) and open the file freertos_sem > .vscode > launch.json

2. Make changes to the configuration by updating the gdbInitCommands attribute and save the file (Ctrl+S):

   "gdbInitCommands": [
       "set remotetimeout 60000",
       ...
   ]
   

   

6.4 Flash and Debug RTOS Project

Start a debug session for the freertos_sem project. Use the same steps learned in the hello_world project.

Note #1: Reminder to verify that the prior Debug session for Hello World was stopped. The Debug Controls will still be visible if the debug session was not stopped.

Note #2: Starting a debug session for a second project can cause VS Code to request that you reset the debug probe connection. Watch to see if this request is provided by a notification in the lower right corner of the screen. If so, click the Reset button provided within the notification.

1. Click the Debug symbol to the right of the FreeRTOS Sem project in the Projects pane.

2. Use the Debug control icons to “Resume/Continue” the program execution.

3. Open the Serial Monitor to view the debug output of the FreeRTOS semaphore project.

   The project will print the status of the threads as they change.

   

4. View the addition of the Embedded Tools: RTOS Viewer for Thread Awareness tab. This is added when the Debug session is paused for a project that has multiple threads. Pause the program using the Debug Controls. Notice the changes to the status of the threads.

   

5. The Call Stack can be used to learn more information about the Threads in the project.

   • a. 1 task calling a “producer” routine
   • b. 3 tasks calling a consumer routine
   • c. 1 task calling an Idle task.
   • d. 1 task calling a Timer task

   

6. The Watch window can help analyze the state of Variables in the Call Stack threads

   Click on the ‘+’ in the Watch window. Manually type in pvParameters.

   This variable stores the number of the Consumer/Producer.

   

7. Use the Debug controls to Continue / Pause execution.

   Click on the consumer_task and producer_task in Call Stack to see value of pvParameters.

This completes the RTOS project section of the lab.

7 Flash Programmer

The NXP extension for Visual Studio Code provides a user interface for Flash Programing. The feature is listed under the Quickstart panel. The user can use all the features of the attached debug probe to flash a connected target. The following steps introduce the different capabilities.

1. Click on “Flash Programmer” under the Quickstart Panel.

2. Click on LinkServer in the prompt asking “Select probe type.”

   For this lab the debug probe uses LinkServer.

   Note: Similar functions are available if a SEGGER J-Link probe was used.

   

3. The programmer “Project” field automatically lists the open projects

   Click on the “hello_world” project.

4. The programmer “Program” tab allows the user to select the file to flash.

   Click on “Browse” and select the binary file from the opened project directory.

   The elf file can be found in the build output folder:

   …\mimxrt1060evkb_hello_world\armgcc\flexspi_nor_debug/hello_world.elf

5. The format should be set to “elf”

6. Click “Run” to reprogram the EVK with the selected binary file.

7. The programmer “Erase” tab provides another location to erase target devices.

8. The programmer “Resurrect” tab is useful for the recovery of Kinetis devices.

   If a Kinetis device fails to respond, this utility repairs a required section of memory.

9. The programmer “Preview” button shows the command it is configured to execute.

   This may be helpful to check the command parameters before modifying the target.

   Click “preview” to display a text window with the command preview.

The following are preview’s for the default Program and Erase commands:

Program Command:

c:\NXP\LinkServer_1.0.13\LinkServer.exe flash --probe MRA0AQER MIMXRT1062xxxxA:MIMXRT1060-EVKB load c:\Users\NXP\VS-Code-Projects\mimxrt1060evkb_hello_world\hello_world.bin –erase-all

Erase Command:

c:\NXP\LinkServer_1.0.13\LinkServer.exe flash --probe MRA0AQER MIMXRT1062xxxxA:MIMXRT1060-EVKB erase

8 Image Info

Developers have requested a popular view for inspecting the project image. The MCUXpresso extension adds this view. The structure of the project can be reviewed. The following steps walk through the Hello World example to show the benefits of the view.

Image Info is a visual utility used to display static function callgraph, memory usage and memory content over a provided build artifact (i.e. executable, library, object file).

Additionally, if the build stage is set to provide stack usage information (i.e. .su files generated by -fstack-usage option in gcc compiler), the generated callgraph will also display local and global consumed stack plus source location of the symbol from graph.

You have the following options to load a file into the Image Info view:

1. Choose a project which already has a built configuration target and use "Load Current Build Artifact Selection" button from the Image Info toolbar.

2. Choose an existing build artifact file (executable, object or library file) and choose "Image

   Info" option from its context menu.

   

Once loaded, the view will display three trees. Callgraph, Memory and File:

8.1 Callgraph

Callgraph displays all the function calls in a tree. It also displays this additional information:

• Run address
• Depth of call
• Static or dynamic allocation
• Local and global cost (stack allocation)

If a recursive call is identified, the callgraph only displays the second occurrence and marks it with "Recursive" message:

8.2 Memory

Memory tree displays the identified memories (only for executable, not for object files) with this additional information:

• Start and end addresses
• Size of the memory
• Occupied and free space plus usage information as %

Each memory contains sections and then symbols, all of them containing various information like:

• Run address
• Load address (only available if map file is available in project)
• Occupied size

Note: Some difference might appear comparing sum of all symbols in a section and the size of used space in that section. This is because only summing symbols does not take into account padding and alignments.

8.3 Toolbar options

Once an image is loaded into this view, you have several view options:

• Refresh: Will populate a built image from the last file selected

  

• Sort symbols by name

  

• For Callgraph only: Sort ascending or descending by local or global stack consumption (cost)

  

• For C++ only: set to display symbols as mangled or demangled form

  

• Enable/Disable ASM Symbols Stripping when -fstack-usage option is active

  

• Collapse all the expanded nodes

  

9 Heap & Stack

MCUXpresso for Visual Studio Code provides a utility to view and track Heap and Stack consumption. The tool currently supports Baremetal projects. (Support is planned for RTOS) Heap memory is used to store dynamic variables. Heap is allocated more dynamically, not as formal as the memory allocated for the Stack. Heap overflow occurs when you have a large number of variables, or you continue to allocate memory without freeing it after.

Stack is used to store local variables wich are used inside of a called function. Stack overflow occurs when your program uses more memory space in the call stack than has been allocated to the stack. This is usually caused by recursive functions or declaration of a large array or matrix.

This section will modify the existing Hello World project from the earlier section. (Alternatively, a new Hello World project can be created with a new Heap-Stack name)

9.1 Initial Project Stack Usage

1. Start Debug for the selected project. Click Debug play icon to the right of project. Notice the initial Heap and Stack values.

   

2. The Heap and Stack values are minimal. Click Pause and Continue in the Debug controls. Hello World continues to not demand much memory.

Note: The Heap & Stack view can be included while in the Debug perspective. In the MCUXpresso view, click on the Heap & Stack title and Drag the field to the Right of the editor. The Heap & Stack view will snap to the right of the editor.

9.2 Modify Project for Stack Overflow

1. Navigate to the Explorer file view from the old or new hello_world project.

   

2. Modify the hello_world.c project file to include a recursive function to impact the Heap & Stack.

• a. Add the following code above the int main(void).

  long long recursive(){
      long long a[20];
      long long x = recursive();
      return x + 5;
  }
  

• b. Insert the recursive(); function inside main(void) after the variable definition.

  

3. Put a Breakpoint at line 42 of the project. To trigger when the recursive routine is called.

4. Build and then Debug the project

   The program will break before the first call of the recursive() function.

   The Heap and Stack values should be the same as before the project was modified.

5. Use the Debug Controls to step into the program. This will isolate each call to recursive().

   The Call Stack view tracks each call to the recursive function.

   The Stack values will increase due to the memory required to push the large variables to the stack.

6. Click the “Step In” control until the Stack value exceeds 70%.

   The view will change to a Yellow warning icon when the allocated stack memory exceeds 70%.

7. Click the “Step In” control until the Stack value becomes 100%.

   The view will change to a Red overflow warning when the allocated stack memory exceeds 100%.

10 Peripheral View

Visual Studio Code provides a Peripheral View in the Debug perspective. The view lists the different peripherals that are included in the project. The tool shows the state of the registers that control these peripherals. The values of the registers can be modified to test the affects caused by the changes. The following steps shows how the tool can be used to view/change the state of GPIO on the i.MX RT1060 EVKB.

10.1 Create GPIO Project

A useful example for testing the GPIO drivers is the “igpio_led_output”. The example toggles the state of an output LED. The Peripheral view can display the GPIO port status and control registers. This provides the developer access to the register values the microcontroller is manipulating.

1. Create a new “igpio_led_output” project.

   Use same process outlined in section 5.2 Import Example Project.

   The following image can help with required fields.

   

10.2 Temporary Debug Probe Settings

The project settings must be updated before the project can be properly debugged. First, the GDB timeout needs to be extended for some PCs. The CMSIS-DAP probe configuration as a USB storage device requires this increased timeout. J-Link and LPC-Link probe firmware does not have the same requirement.

Second, the project settings must be updated to identify the location for the devices System View Description (SVD) file. The SVD file for the i.MX RT1060 cross-over microcontroller is included in the installed SDK. The file is located in the devices folder. The typical file name is DEVICE_CORETYPE_CORENUMBER.xml. For this RT1060 project you will provide the path to MIMXRT1062.xml.

This information must be added to the launch.json file, this allows the tool to properly include these settings when the debug tool is “launched”.

Note: These steps will not be required in future versions of the MCUXpresso Extension of VS Code.

1. Go to the Explorer file view to open launch.json for gpio project.

   

2. Open the .vscode folder to access the configuration files for VS Code.

   Click-to-open the launch.json file

   

3. Update the gdbInitCommands attribute and save the file (Ctrl+S):

   "gdbInitCommands": [
       "set remotetimeout 60000",
       ...
   ]
   

   

4. Add the SVD path to the end of the existing launch.json

   The exact path will depend on the folder you selected when you extracted the SDK.

   Note: Be sure to add the comma between the previous JSON node and the new svdPath.

10.3 Setup Peripheral View

1. Build and Debug Project clicking on the Debug icon.

2. Pause the Debug session using Debug Controls. The execution should be stopped in the main() while loop. If not, open Call Stack and click main()

3. Place a Breakpoint at the GPIO_PortToggle() routine at line 58

   This will pause the execution every time the LED is toggled.

   This will make it easy to monitor the changes in the GPIO registers.

   

4. Next, open the Peripheral View using a direct command with the Command Pallet.

   To view the Command Pallet press (Ctrl-Shift-P).

   Type Peripheral. Select “Focus on Peripheral View”.

   

   This will add the Peripheral View to the Debug Perspective. The tool will display “Peripheral View”.

5. Move the new Peripheral View tool to the right pane of the window for more space. The Title can be grabbed and dragged-dropped to other locations on the screen. NOTE: It may be displayed as a Bug/Play icon if it shares the pane with another tool. Drag it below the other tool in the right pane to separate them and display both titles.

   VS.

The Peripheral View tool now lists all of the registers associated with the device. How do you locate the specific registers of interest in your project?

10.4 Identify Peripheral of Interest

Use the editor to explore the definitions for the LED in the GPIO Output project. The editor will drive into the definitions within the project files and provide the GPIO assignment. Follow the next steps to locate and pin these registers of interest into the Peripheral View tool:

1. View the parameters for GPIO_PortToggle() used in main(). EXAMPLE_LED_GPIO represents the LED on the i.MX RT1060 EVK. Right-Click on this parameter, then select Go to Definition (F12)

2. The editor moves to the Definition and shows the assignment to BOARD_USER_LED_GPIO. This is still an indirect assignment. Not showing the end GPIO of the device. Right-Click on BOARD_LED_RED_GPIO, then select Go to Definition (F12)

3. The editor opens the board.h file for the i.MX RT1060 Evaluation Kit.

   #define BOARD_USER_LED_GPIO GPIO1
   

   This identifies GPIO1 as the base register that controls the LED.

4. Search for “GPIO1” in the Peripheral View search window

   Pin the GPIO1 register by selecting the push-pin to the right of the filtered value.

   

   This provides easy access to this register at the top of the list view.

5. Expand GPIO1 to list all of the relative registers and values.

   Notice the DR – GPIO data register.

   

   This register displays the GPIO1 output values [31:0] for the port.

   The value of the 8th bit position 000x_0000_0000 represents the LED.

   A ‘0’ value in the 000x_0000_0000 position represents a Low level output to the LED.

   The LED will be on when assigned a high level ‘1’.

10.5 View/Change State of Peripheral

The next steps will show how to view how the GPIO1 register changes when the example program runs.

1. Make sure the program is running. You may need to click the Continue Debug button.

2. The igpio_led_output program toggles the value of the GPIO1 register.

   Keep an eye on the Peripheral View display of the DR register value.

   Press the Debug “Continue” button (or F5) to have debug run to the enabled breakpoint.

   The DR register value will change (flash) and the LED will toggle on/off.

   Repeat the last 2 steps: Pressing the Debug continue button.

   The state of the DR and the LED will continue to change.

   

3. The Peripheral View also provides Write access to these peripheral registers.

   The value of the DR can be manually changed by the user. Click on the DR value.

   Change the value of the 8th bit (000x_0000_0000) between ‘1’ and ‘0’.

   Submitting the new value will change the state of the LED.

This completes the Getting Started labs for VS Code and the i.MX RT1060-EVKB.