Working with Matter - nxp-mcuxpresso/vscode-for-mcux GitHub Wiki
Matter (previously known as Project CHIP) is a new single, unified, application-layer connectivity standard designed to enable developers to connect and build reliable, secure IoT ecosystems and increase compatibility among Smart Home and Building devices.
The purpose of this extension is to provide a full development flow experience, starting from installing tools, source repository, capability to create and manage projects, build and debug applications.
All functionalities described below have been tested using the NXP downstream Matter repository, version 1.4.0.0 or higher.
Matter is supported on Windows, Linux, and macOS.
Dependencies
In addition to the extension itself, some extra tools and software components are required for the full development flow within VS Code.
Some of these dependencies are managed by the MCUXpresso Installer tool, others by the Bootstrap script and others must be manually managed by the user.
Dependencies installed by the MCUXpresso Installer tool:
Import remote source repository
REMOTE tab option in the Import Repository view will allow the user to specify the details about the remote repository.
The default revision from the remote repository is selected. If another revision is needed, check the expanded list.
After the repository is cloned, the extension will set up the environment by running the necessary scripts, first the checkout submodules script and then the Bootstrap script.
The imported Matter repository is displayed in the INSTALLED REPOSITORIES view.
Update repository
Update repository command can be used to run the setup scripts in order to update the environment.
Create project
Once a repository is imported, you can create your own application by importing an example from the repository.
Open Import Example from Repository view and fill the required fields:
- Choose a repository - select a Matter repository. The listed repositories are the ones also available in INSTALLED REPOSITORIES view;
- Choose a toolchain - the listed ones are automatically identified by the extension. Pick a suitable one or use Add toolchain path option from the combobox;
- Choose a board - select a desired board. The listed ones are the ones available in the loaded Matter repository;
- Choose a template - select a desired project template you want to start with;
Once the project is created, it is added in PROJECTS view. The created project is a repository type application, the example is kept in the Matter repository.
Build project
Matter projects are built using GN build system, the default Matter build system.
Build configuration
The PROJECTS view displays all available build configurations for each project. One is selected by default, any other can be selected using "Set as Default" option. Additionally, you can add, edit or delete a build configuration.
Open Build Configuration view and fill the required fields:
- Name - specify a desired build configuration name.
- Build Directory - specify a desired build directory name, location relative to the project path.
- Target - select a desired target from the provided list of supported targets. According to the selected option, additional GN arguments are passed to the build system. These options are embedded in the Matter framework.
- Linked SDK Path - specify the location of the SDK.
- GN Extra Args - specify additional GN args.
Note: Linked SDK Path and GN Extra Args fields are optional. When the user does not provide a location for the linked SDK, the default one (which is located in the Matter repository) is used.
Build command
Use the Build Selected button to start building the project.
If the SDK for the used target could not be detected because it was not already cloned and could not be found at its default location, the extension will allow the user to clone it from NXP GitHub.
A custom SDK path can also be set using the Linked SDK build configuration option.
After the SDK is detected (provided by user or cloned from GitHub at the default location), the extension starts building the project.
Flash
Pre flash actions option
The extension can automatically run the pre flash actions specific to the used platform when flashing or debugging a project if the user sets the skipPreflashActions option from launch.json file to false. By default, the execution of the pre flash scripts is disabled and the user must enable it when needed.
The pre flash scripts are located in the Matter metadata repository. Some examples of pre flash actions are: loading factory data, loading a secondary stage bootloader (SSBL), loading radio firmware (NBU), writing image directories needed by SSBL.
Note: The Matter metadata repository is located inside the Matter repository in matter-vscode-for-mcux directory.
The board must be in ISP in order to successfully execute the pre flash scripts.
After following the above steps to place the board in ISP mode, try to execute the pre flash scripts again:
After executing the pre flash scripts, it is recommended to set *skipPreflashActions" option to its initial "true" value, as after reset, the board is no longer in ISP mode so subsequent pre flash trials might fail.
Flash selected target command
Quick access links to program the flash or to fully erase the flash are available on the project context menu.
For more detailed instructions see Flash NXP GitHub Documentation.
Debug
Use the Debug button to start debugging the project.
Image Info
Choose a project which already has a built configuration target and use the "Load Artifact" button and select the build artifact file to use.
For more detailed instructions see Image Info NXP GitHub Documentation.
ZAP Tool
To open Zap Tool go to the context menu of the project and select "Open with Zap Tool" under the "Configure" group.
If multiple zap files are found, please select which zap file to be opened with Zap Tool.
Troubleshooting
For answers to common issues you may encounter when using Matter with the MCUXpresso for VS Code extension, please check Matter Troubleshooting Guide.