This page supports the NXP Tech Days training session AMF-ENT-T4788 for "Hands-On Workshop: Developing with Zephyr™ OS in Visual Studio Code".  The full lab guides and installation pre-requisites are attached below. Here are some common tips for troubleshooting and resolving installation issues, or issues building Zephyr applications in VS Code.  If attending this session, and other issues occur, please post a comment here with details about the issue. The pre-reqs use the MCUXpresso Installer, which installs several tools, Python, and many Python modules.  If some tools or modules fail to install properly, it can help to try manualling installing these.  The Zephyr Project Getting Started page is a good reference for this and gives detailed steps to install everything needed. See MCUXpresso Installer fails to download a dependency file as a potential workaround. If the MCUXpresso Installer log shows errors installing a tool, see Installing with Administrator Rights and Manually Install Tools. To use Python commands from CLI, see Python Virtual Environment used by VS Code. If errors are related to Python, or missing Python modules like pip, West or others used for Zephyr builds, see Issues with multiple Python versions installed and Missing Python Modules. If you try to import a Zephyr project, but the FRDM-MCXN947 board is not available in the board list, you likely need to Change the Zephyr revision with Git.  This lab needs to use the main branch.  The MCUXpresso extension should show the Zephyr revision is v3.6.99. If you try to build a Zephyr project, and it fails because the file MCXN947VDF-pinctrl.h is missing, see Missing pinctrl file and HAL_NXP.

When using the MCUXpresso extension for VS Code and building a Zephyr application, one error that may occur is a missing pinctrl file.  The VS Code Output tab would show an error like this when the build fails: [cmake] In file included from zephyrproject/zephyr/boards/nxp/frdm_mcxn947/frdm_mcxn947.dtsi:7, [cmake] from zephyrproject/zephyr/boards/nxp/frdm_mcxn947/frdm_mcxn947_mcxn947_cpu0.dts:10, [cmake] from <command-line>: [cmake] zephyrproject/zephyr/boards/nxp/frdm_mcxn947/frdm_mcxn947-pinctrl.dtsi:7:10: fatal error: nxp/mcx/MCXN947VDF-pinctrl.h: No such file or directory [cmake] 7 | #include <nxp/mcx/MCXN947VDF-pinctrl.h>   This file is included in the HAL_NXP repo, which West should clone when the Zephyr repo is imported.  You can verify if this repo is missing.  If the Zephyr repo is at zephyrproject/zephyr, the HAL_NXP repo is at zephyrproject/modules/hal/nxp.  If the pinctrl file is missing, or this HAL_NXP repo is missing, it likely means the `west update` command failed or was interrupted when the repo was imported.  One option to resolve this is to re-import the Zephyr repo.  But this can take a long time, and needs to download and clone a large amount of files.  A faster option is to run the `west update` command using CLI. Open a command window, and Activate the Python Virtual Environment.  Change to the Zephyr repo directory.  The Windows command below uses the default path, but the VS Code Output log will show your local path: cd C:\Users\<username>\zephyrproject\zephyr Run the `west update` command.  Depending on how many repos are missing or need updating, this may take awhile.  Poor network bandwidth is one reason the `west update` command may have failed the first time.  If the updating the repos times out or is interrupted, you can run `west update` multiple times until all the repos are updated, and west gives no more errors.

Zephyr uses a Git repo, and the MCUXpresso Installer will install Git if needed when developing with Zephyr.  Using the MCUXpresso extension in VS Code to import a Zephyr repo will use Git to checkout a revision of that repo.  After importing the repo, you can change the revision.  One option is to re-import the Zephyr repo with a different revision.  But this can take a long time and needs to download and clone a large amount of files.  A faster option is to use Git to checkout a revision.  There are many Git clients available to do this, including a client integrated in VS Code.  But this example uses CLI Git commands. One reason to change the Zephyr revision is to use a newer revision, which may include more board support.  For example, the FRDM-MCXN947 board support was upstreamed to the Zephyr repo after the v3.6.0 release.  If the repo revision is v3.6.0 or earlier, this board will not be available.  When importing a Zephyr example, this board would not show up in the list.  To resolve this, checkout a newer revision of the repo.  Using the main branch revision will use the latest code in the repo. The MCUXpresso extension in VS Code shows the Zephyr revision of an installed repo.  The screenshot below shows v3.6.0.  When the version ends in .99, it means the revision is between releases.  v3.6.99 means the revision is after the v3.6.0 release, but before the next release.   To use Git with CLI in Windows, open a command window.  With the MCUXpresso extension for VS Code, you likely need to Activate the Python Virtual Environment.  Then change to the directory of the Zephyr repo.  This command uses the default path: cd C:\Users\<username>\zephyrproject\zephyr Fetch the latest from the Zephyr remote repo: git fetch Checkout the desired revision.  This can be a Git branch, release tag, or commit SHA.  This command checks out the latest main branch: git checkout main Anytime the Zephyr revision is changed, we must also run `west update` to synchronize the other repos in the West workspace: west update If a Zephyr project has already been imported into the VS Code workspace, just right-click the project and Clean it.  Then build that project, and it will use the new Zephyr revision. If you want to import a new project into the workspace, click the Refresh Repository button.  The Zephyr revision will update to match.  

The MCUXpresso extension for VS Code uses some Python modules, and uses dozens of modules when developing for Zephyr.  The MCUXpresso Installer will install the dependency modules needed for these tools.  However, if errors occur when running the Installer, or while building a Zephyr application, a possible reason is missing Python module(s).  A potential reason why a module was not installed could be Issues with multiple Python versions installed.  These Python modules can also be installed manually using CLI. The MCUXpresso Installer will check if a Python version is already installed, and will install Python if needed.  Then it creates a Python Virtual Environment used by VS Code, and tries to install pip into that Virtual Environment (VE).   If pip is missing, or fails to install, you can install it manually using this command.  First activate the VE, and then command using the path to the VE.  If needed, open the command window with Administrator rights.  This command installs pip with the default VE path in Windows: C:\Users\<username>\.mcuxpressotools\.venv\Scripts\python.exe -m ensurepip --upgrade Another Python module needed is West.  If West is missing, this typically causes errors while importing a repository, which runs the `west init` command.  You can also use CLI to verify if a Python module is installed in a specific Python version.  This command checks if West is installed, and reports the version if it is: C:\Users\<username>\.mcuxpressotools\.venv\Scripts\python.exe -m west --version Similar to the above steps installing pip, you can manually install west: C:\Users\<username>\.mcuxpressotools\.venv\Scripts\python.exe -m pip install west --upgrade When developing with Zephyr, dozens more Python modules are required.  Some of these modules are used when building a Zephyr application.  The Zephyr repo provides this requirements.txt, which provides a list of modules for pip to install.  If VS Code fails to build an app and gives an error of a missing Python module, you can use the steps above to manually install a single Python module.  But if 1 module is missing, likely there are more missing.  You can install all the required modules with this pip command.  This is done after the Zephyr repo is imported/cloned, and requires the path to the local Zephyr repo.  The command below uses the default repo path when imported in Windows: C:\Users\<username>\.mcuxpressotools\.venv\Scripts\python.exe -m pip install -r C:\Users\<username>\zephyrproject\zephyr\scripts\requirements.txt

The MCUXpresso Installer is a tool that installs other software, tools, and dependencies for the MCUXpresso extension for VS Code, or for developing with Zephyr.  It downloads these installers into a cache folder, and then executes the installers.  If errors occur when installing these components, the Installer log will show which tool failed to install.  If the reason for the failure is not clear, you can manually run the the installer for that tool.  This may resolve the issue, or it may provide more details why that installer fails. The MCUXpresso Installer log will give the path to the cache folder where the tool's installer is located.  Typically in Windows, this path is at: C:\Users\<username>\AppData\Local\Programs\MCUXpressoInstaller\.cache Installing with Administrator Rights may also help resolve the issue.

The MCUXpresso extension for VS Code leverages Python.  We sometimes see issues with tools when multiple versions of Python are installed, especially in Windows.   The MCUXpresso Installer will use a Python virtual environment.  But when installing Python modules, if other Python versions are already installed, there may be issues. If the MCUXpresso Installer or the MCUXpresso extension in VS Code show errors due to missing Python modules, here are some tips to manage this.  One option is to remove the other Python versions if they are not needed.  From a command prompt, you can find the different Python versions found in the PATH environment variable with this command: where python You can also manually install Python modules into specific Python versions, see Python Virtual Environment used by VS Code. Another potential option is to edit the PATH environment variable, and remove the paths to other Python versions.

When using the MCUXpresso Installer, or when manually installing the components required by VS Code or Zephyr, Administrator rights are usually required.  If a user does not have Admin rights, or if Admin rights are restricted, it may cause installation issues.   If installation issues occur in Windows, you may need to force installation as an Admin.  Typically in Windows, you can right-click on the installer executable in Windows Explorer, and select "Run as Administrator".  The MCUXpresso extension for VS Code can download and run the MCUXpresso Installer.  Once downloaded, you can manually run the Installer with Admin rights in Windows.  The Installer executable is typically downloaded to C:\Users\<username>\AppData\Local\Programs\MCUXpressoInstaller\.cache\MCUXpressoInstaller.exe If installing from CLI, running the command window as Admin can help avoid issues.  This is usefule with Python when installing pip or other modules, or if installing chocolately.  

The MCUXpresso Installer starting with v1.3 and the MCUXpresso extension for VS Code use a virtual environment (VE) for Python.  To manually use this VE from CLI, install new modules or upgrade modules, this VE needs to be activated. The VE is activated by running a script, in Windows the script is a activate.bat file.  The MCUXpresso Installer log shows the path to this script.  In Windows, this script is typically installed at C:\Users\<username>\.mcuxpressotools\.venv\Scripts\activate.bat.  Running this script from a command window activates that environment.  In the screenshot below, notice the prompt includes the (.venv) VE name after the script runs.  Now Python commands can be run within this VE.  If multiple Python versions are installed in the system, you can ensure the VE Python is used by using the full path to the VE Python executable.  For example, to install pip in this VE in Windows, run this command: C:\Users\<username>\.mcuxpressotools\.venv\Scripts\python.exe -m ensurepip --upgrade  

With the latest v1.2 release of the MCUXpresso Installer tools, some Windows users see errors when the Installer tries to download the gperf ZIP.  Gperf is included in the Zephyr dependencies.  This is a known issue, and the Installer will be updated in the next release to resolve this. In the meantime, there is a workaround to manually download a file, and store it in a cache folder used by the Installer.  If the Installer finds the file in that cache, it will not need to download it.  These steps assume Windows is used. It is best to run the Installer at least once, which will create the cache folder, and install the tools.  The install log in the Installer will give the URL of the file it tries to download.  For this specific gperf error, it fails to download from https://sourceforge.net/projects/gnuwin32/files/gperf/3.0.1/gperf-3.0.1-bin.zip.   Find the cache folder used by the Installer.  This folder path will also be shown in the Installer log.  In Windows, this path is C:\Users\<username>\AppData\Local\Programs\MCUXpressoInstaller\.cache Manually download the needed file, and save in the cache folder.  Then re-run the Installer, and it will install the tool from the cache folder.

This article has been updated 6/29/2023 for 6th Beta Release: Latest Release Versions: MCUXpresso extension for VS Code v2023.07 (1.0.68) MCUXpresso Installer v2023.07 (v1.0.85) LinkServer v2023.07 (v1.2.45) Release information provided in Extension Overview in Visual Studio Code Visual Studio Code Installation Windows install Visual Studio Code Ubuntu install Visual Studio Code macOS install Visual Studio Code Extension Installation Steps Launch Visual Studio Code Click the Marketplace icon found in the main left navigation pane Search "NXP" in Marketplace search bar.  Click "MCUXpresso for VS Code" Click Install in the MCUXpresso for VS Code extension.  Installation includes other required extensions (i.e. C/C++ by Microsoft) Dependency Installation Steps Links for the MCUXpresso Installer are in Quickstart Panel added by Visual Studio Code extension. Click Open MCUXpresso Installer The Installer UI launches to assist in adding required software tools/settings. Select from "Software Kits", "Debug Probes", and "Individual Components" appropriate for your development. Click Install NOTE: Installer can Check that you have the latest installer by clicking Cloud icon Your system should now be ready to begin developing with NXP.  Please review included Walkthrough OR "Online Documentation" for further assistance. Please provide feedback on these instructions below.

The following questions were answered during an online training. Hopefully, this is useful to new users. Question Answer Can the extension be installed over previous installations? Do you need to uninstall before downloading? Are there known issues if not done this way? If the installed extension version is newer than 0.9 (first marketplace version), there is not need to erase before, can be installed over. If you had a pre-release extension version (so the ones installed as vsix before) you have to uninstall first, since the product ID was changed so you'll end up seeing a duplicated MCUXpresso for VSCode extension. Does the extension provide peripheral and register views?  Both are available in the debug perspective. While the register view is populated by default,  for Peripheral view the tool requires the location of the svd file in your repository. The extension handles this information in most cases. However, the svd file can be manually specified (its filepath) in the project -> .vscode -> launch.json -> "svdPath" : "<your_svd_filepath>" Does the plugin include features for mcu-link pro, such as energy measurement? If not, is this in roadmap? The current extension includes a view called Analysis. For now, it only supports loading Energy Measurement sample files generated in MCUXpresso IDE. Energy measurement within VS Code will be added in a future release.  Does the extension provide RTOS analysis tools ? There already is an RTOS view provided by Embedded Tools extension. It becomes visible when going into debug mode.  When creating an SDK on MCUXpresso.nxp.com, do I need to create for a specific toolchain? MCUXpresso or GCC? ARM GCC In hello_world example, where is the startup.c and /drivers folder? There are a lot of files not shown in the Project Explorer The files from the example itself are located in the Project folder. The other files from the SDK are linked to a virtual directory called _repo_ that you can see in the Project Explorer. Do you need to reinstall SDKs already installed with MCUXpresso IDE? If you have your repos locally, you can use the Import Repository -> Local, and you simply select the directory where the repo is on disk. Still, this is available if you have an SDK Git repo or a zip/standalone SDK created for multiple toolchains. This is because both these variants will work for armgcc toolchain which is the one used by VSCode. The only installation that won't work will be a standalone/zip SDK which was generated for MCUXpresso IDE only. Only supports versions v2.13.0 or greater. In MCUXpresso when you compile a project you end up with a axf file but you can convert it to binary hex or srec with the binary utilites. Is there something similar here?  select executable file -> right click -> Binary Utilities How can I know which debug probe is used? You can check the DEBUG CONSOLE and you'll see connection details, once you connected. On the future versions, we plan to add some more descriptive information to see which probe is used by which project. Is the external MCUXpresso installer required? Could those tools also be installed through the extensions of VScode?  No, not planned, the idea of MCUXpresso Installer (long term) is to provide an installation process for overall MCUXpresso ecosystem, not only for VSCode When will the MCUXpresso IDE's "create a project" be available in the VScode plugin? For now, the strategy is to start from SDK the available projects. You can then add/remove components or change various settings (floating point, debug console type, library type, and some other in the future) . For this: right click on the project -> Configure. The "create a project" as defined inside MCUXpresso IDE will be addressed in a future release.

This video series shows the steps for getting started.  It is a video walkthrough to help visualize the steps detailed in "Installation steps for MCUXpresso for VS Code".   Part 1: MCUXpresso for Visual Studio Code NXP has made it easier for developers to work with NXP microcontrollers in Visual Studio Code.  The user can get a high-level overview of the NXP support at www.nxp.com/vscode.  You will need the following software: MCUXpresso Installer (Win; MacOS; Linux) Microsoft Visual Studio Code Download Part 2: What MCUXpresso Installer Prepares  Why do you need to use MCUXpresso Installer?  There are many required tools to support embedded development within Visual Studio Code.  This program installs the required tools so the user does not need to understand the complex dependencies to configure the different environments. Part 3: Add the MCUXpresso for VS Code Extension The NXP extension will eventually be installed by visiting the Extension Marketplace found in Visual Studio Code.  Until the public launch in July 2023, the extension can be manually added in the Extensions menu found by clicking the ellipsis to the right of the extensions search bar.   You will require the latest extension.  Download: mcuxpresso-0.5.60.vsix Part 4: Review the MCUXpresso Perspective The NXP extension provides a perspective within Visual Studio Code that makes it easy to view the necessary information, resources and tools. Part 5: Add a Software Repository / SDK The NXP extension provides a tool that imports software repositories from popular sources.  The developer can import from a remote repo, NXP archive file, or an existing local repo. Part 6: Import the first Project The NXP extension provide a Project Importing tool.  It is quick and easy to browse available projects and add them to the current workspace.  Users can import from a repository or an existing local project. Part 7: Build a Project in VS Code The NXP installer and extension prepares the toolchain for your platform.  After completing the installer and extension, NXP projects should build properly. Part 8: Start a Debug Session The NXP extension has added support to launch the default tools within VS Code using popular Debug Probes.  Segger J-Link, NXP LinkServer and PE Micro debug probes are identified and configured.  The Debug session launches and the user is able to analyze their project.