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 Matter MCUXpresso SDK repository, version 1.4.2 or higher.
Note: MCUXpresso for VS Code extension version 25.11 introduced Matter integration aligned with the MCUXpresso SDK architecture and added NXP support for Matter version 1.4.2, where Matter is considered as a middleware and functions as an SDK component within the MCUXpresso SDK repository. Prior to this extension version, NXP Matter was a separate repository, available at Matter GitHub link and required specific integration steps. Please be aware that the legacy Matter architecture is no longer maintained but remains supported in the extnesion. Users are recommended to migrate to the new MCUXpresso SDK architecture.
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.
Note: On Windows, it is recommended to clone the repository as close as possible to the C: drive directory (e.g.,
C:\matter) to avoid potential issues with long file paths that may exceed Windows path length limitations.
The default revision from the remote repository is selected. If another revision is needed, check the expanded list.
The default west manifest file will be used to clone the repository with all necessary dependencies and submodules. To select another manifest file, check the Use custom manifest file option and select the desired file from the drop-down list. For example, to clone only the minimal set of SDK components required for Matter, use the custom west_matter_minimal.yml manifest file.
After the repository is cloned, the extension will set up the environment by running the Bootstrap script.
The imported Matter repository is displayed in the IMPORTED REPOSITORIES view.
Update repository
Update repository command can be used to synchronize your local repository with the latest changes from the remote repository.
Setup environment (Run Bootstrap Script command)
Run Bootstrap Script command can be used to run the setup script, to install required Python dependencies for the Matter environment and ensure all development tools are properly configured. This script additionally installs the ZAP Tool.
Create project
Once a repository is imported, you can create your own application by importing an example from the repository. Go to Import Example viewer as explained on Create project and fill the required fields:
- Choose a repository - select a Matter repository. The listed repositories are the ones also available in IMPORTED REPOSITORIES view;
- 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;
- Application type - select the desired application type, choose "Repository application" if you want to use the application directly in the repository folder (example's sources will not be copied), choose "Freestanding application" if you want to keep the application in a user provided location (example's sources will be copied);
- Choose a toolchain - the listed ones are automatically identified by the extension. Pick a suitable one or use Add toolchain path option from the combo box;
Build project
Matter projects are built using CMake build system.
For building the project, the standard steps described in Build project section should be followed.
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.
- Config File - specify a custom configuration file. Documentation for changing configuration file.
- CMake Extra Args - specify additional CMake args.
Note: For detailed information about available build configurations and their specific options, please refer to the README file of your example project.
Flash
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
Debug project command
Use the Debug button to start debugging the project.
For more detailed instructions see Debug NXP GitHub Documentation.
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 depending on the configuration that you target to build.
If the ZAP file will be modified, the corresponding Matter file will be automatically regenerated at build time as a pre-build step.
Kernel Configuration (guiconfig)
To open Kernel Configuration Tool go to the context menu of the project and select "Open Kconfig GUI Configuration" under the "Configure" group.
Project Integrated Terminal
Open MCUXpresso Terminal specific for the project using project menu -> Open in Integrated Terminal.
The opened MCUXpresso terminal will have the environment completely configured for the project and the associated repository type, including system specific variables, virtual python environment (if available), utility tools access (i.e. west, available debug probe software). Example command to build the project appears in green. The command is constructed specific for the project and it can be used as is for a quick west build.
Matter documentation and Troubleshooting
For comprehensive documentation and solutions to common issues when developing with Matter, please refer to the Matter documentation.