MCUXpresso Task Definition

An MCUXpresso task, or a list of tasks, must respect a JSON schema defined by the MCUXpresso for VS Code extension. Files that respect the following pattern mcuxpresso-tasks*.json are automatically validated against the schema, when opened and edited within VS Code. Also, all tasks added in tasks.json that are MCUXpresso-specific (i.e. "type": "MCUXpresso") are also validated against the same schema.

There are multiple actions that can be performed using the MCUXpresso task system, and each of the actions requires a specific set of command options to be defined. The command options are defined within the commandOptions property of the task object.

MCUXpresso Task

Each task needs at least the "type", "version", "label", and "commandOptions" properties. The "runOptions" property is optional but it allows controlling the execution details of the task.

The sections below list the available commands and their required options.

High-level view of the basic properties

Property	Type	Required	Description
type	“MCUXpresso”	✓	MCUXpresso task type.
version	string	✓	MCUXpresso task version.
label	string	✓	The task label. This will be displayed in the Terminal view inside VS Code.
description	string		Optional description of the MCUXpresso task’s purpose and functionality.
id	string		Optional ID that can be assigned and help to uniquely identify the task within a sequence of tasks.
runOptions	object		Options that help controlling various aspects of the task execution.
awaitPreviousTasksCompletion	boolean		Whether to wait for all the previous async tasks to complete before starting current task. By default, previous tasks are not awaited for completion.
awaitTaskCompletion	boolean		Whether to wait for the task to complete before starting the next task. By default, task is awaited for completion.
executionDelay	number		Delay execution of current task with the given number of seconds. By default, no delay is applied.
executionTimeout	number		Timeout (in seconds) for current task execution. Task will be terminated once timeout occurs. A non-negative and non-zero value is valid. By default, no timeout is used.
retryCount	number		If task fails, retry for the specified number of times. Retrying might help in certain setups, for example when retrieving data over an unreliable network connection. By default, no retries are performed.
skip	boolean		Whether to skip the task. By default, task is executed.
taskOutputFile	string		Path to a file that will contain the task’s output. By default, a temporary file is automatically created.
commandOptions	object (combined)	✓	See specific command details below

Available commands

The commandOptions property defines the specific command to execute and its parameters.

Base Command Property

Property	Type	Required	Description
command	“installDependencies” | “installRemoteRepo” | “installRemoteStandalonePackage” | “installLocalRepo” | “installLocalArchive” | “installAchProduct” | “uninstallRepo” | “importExampleFromRepo” | “importProject” | “removeProject” | “buildProject” | “cleanProject” | “rebuildProject” | “eraseFlash” | “programFlash” | “runDebugProject”	✓	The MCUXpresso command to execute.

Description of individual commands

The section below provides details about each of the command type supported by the MCUXpresso for VS Code extension.

Command: "installDependencies"

Properties supported by the “installDependencies” command:

Property	Type	Required	Description
command	“installDependencies”	✓	ID of the command.
dependencyType	“sdkDeveloper” | “zephyrDeveloper” | “matterDeveloper” | “debugSupport”	✓	Types of dependencies valid for “installDependencies” task.

Command: "installRemoteRepo"

Properties supported by the “installRemoteRepo” command:

Property	Type	Required	Description
command	“installRemoteRepo”	✓	ID of the command.
repoDestinationPath	string	✓	Destination path used by “installRemoteRepo” task.
repoManifestFile	string		Manifest file used by “installRemoteRepo” task.
repoRevision	string	✓	Repository revision used by “installRemoteRepo” task.
repoType	“mcuxsdk_2.x” | “mcuxsdk” | “mcuxsdk_int” | “zephyr” | “zephyr_nxp” | “matter” | “matter_nxp”	✓	Repository type used by “installRemoteRepo” task.

Command: "installRemoteStandalonePackage"

Properties supported by the “installRemoteStandalonePackage” command:

Property	Type	Required	Description
command	“installRemoteStandalonePackage”	✓	ID of the command.
packageDestinationPath	string	✓	Installation package path used by “installRemoteStandalonePackage” task.
packageJsonFile	string	✓	JSON file name associated to the desired package used by “installRemoteStandalonePackage” task. See https://mcuxpresso.nxp.com/vscode/NXP.json for all the available packages.
packageVersion	string	✓	Version of the package installed via “installRemoteStandalonePackage” task.

Command: "installLocalRepo"

Properties supported by the “installLocalRepo” command:

Property	Type	Required	Description
command	“installLocalRepo”	✓	ID of the command.
repoPath	string	✓	Path to the local repository used by “installLocalRepo” task.

Command: "installLocalArchive"

Properties supported by the “installLocalArchive” command:

Property	Type	Required	Description
command	“installLocalArchive”	✓	ID of the command.
archiveDestinationPath	string	✓	Archive installation path used by “installLocalArchive” task.
archivePath	string	✓	Archive path used by “installLocalArchive” task.

Command: "installAchProduct"

Property	Type	Required	Description
command	“installAchProduct”	✓	ID of the command.
destinationPath	string	✓	Product destination path used by “installAchProduct” task.
productID	string	✓	Remote ID of ACH product used by “installAchProduct” task.
productName	string	✓	Product name used by “installAchProduct” task. Will be appended to “destinationPath”.
toolchainPath	string		Toolchain path used by the “installAchProduct” task, required for non-Zephyr projects imported from ACH repository.
zephyrSdkPath	string		Zephyr SDK path used by the “installAchProduct” task, required for Zephyr projects imported from ACH repository.

Command: "uninstallRepo"

Properties supported by the “uninstallRepo” command:

Property	Type	Required	Description
command	“uninstallRepo”	✓	ID of the command.
deleteFromDisk	boolean		Whether to delete repository from disk once task is executed. By default, repo is not deleted from disk.
repoPath	string	✓	Path to the repository to uninstall.

Command: "importExampleFromRepo"

Properties supported by the “importExampleFromRepo” command:

Property	Type	Required	Description
command	“importExampleFromRepo”	✓	ID of the command.
appType	“inRepository” | “inWorkspace” | “freestanding” | “standalone”	✓	Application type to be created by the “importExampleFromRepo” task. See the official MCUXpresso for VS Code documentation to understand what type of projects can be created depending on the repository type.
boardID	string	✓	Board ID used by the “importExampleFromRepo” task.
exampleLocation	string	✓	Folder name for a workspace application, or the full path for freestanding and standalone applications. Used by the “importExampleFromRepo” task.
importedProjectName	string	✓	Project name of the example imported using the “importExampleFromRepo” task.
outOfTreeBoardsDir	string		Custom board folder used by “importExampleFromRepo” task.
repoPath	string	✓	Path to the repository containing the example.
repoTemplateID	string	✓	ID of the template example imported using the “importExampleFromRepo” task.
toolchainPath	string	✓	Toolchain or Zephyr SDK path used by the “importExampleFromRepo” task.

Command: "importProject"

Properties supported by the “importProject” command:

Property	Type	Required	Description
command	“importProject”	✓	ID of the command.
projectDestinationPath	string	✓	Project destination path used by “importProject” task.
projectPath	string	✓	Project path used by “importProject” task.
repoPath	string		Repository path used by “importProject” task.
toolchainPath	string		Toolchain or Zephyr SDK path used by “importProject” task.

Command: "removeProject"

Properties supported by the “removeProject” command:

Property	Type	Required	Description
command	“removeProject”	✓	ID of the command.
deleteFromDisk	boolean		Whether to delete project from disk once task is executed. By default, project is not deleted.
projectName	string	✓	Project name used by “removeProject” task.

Command: "buildProject"

Properties supported by the “buildProject” command:

Property	Type	Required	Description
command	“buildProject”	✓	ID of the command.
buildConfigName	string	✓	Build configuration used by “buildProject” task.
buildConfigOverride	object		Override settings used by “buildProject” task.
boardID	string		Board ID.
buildDir	string		Build directory.
cmakeExtraArgs	string		Extra CMake arguments to be passed at build time.
debugConsole	“default” | “semihost” | “uart” | “none”		Debug console type used by the application.
projectName	string	✓	Project name used by “buildProject” task.

Command: "cleanProject"

Properties supported by the “cleanProject” command:

Property	Type	Required	Description
command	“cleanProject”	✓	ID of the command.
buildConfigName	string	✓	Build configuration used by “cleanProject” task.
buildConfigOverride	object		Override settings used by “cleanProject” task.
boardID	string		Board ID.
buildDir	string		Build directory.
cmakeExtraArgs	string		Extra CMake arguments to be passed at clean time.
debugConsole	“default” | “semihost” | “uart” | “none”		Debug console type used by the application.
projectName	string	✓	Project name used by “cleanProject” task.

Command: "rebuildProject"

Properties supported by the “rebuildProject” command:

Property	Type	Required	Description
command	“rebuildProject”	✓	ID of the command.
buildConfigName	string	✓	Build configuration used by “rebuildProject” task.
buildConfigOverride	object		Override settings used by “rebuildProject” task.
boardID	string		Board ID.
buildDir	string		Build directory.
cmakeExtraArgs	string		Extra CMake arguments to be passed at rebuild time.
debugConsole	“default” | “semihost” | “uart” | “none”		Debug console type used by the application.
projectName	string	✓	Project name used by “rebuildProject” task.

Command: "eraseFlash"

Properties supported by the “eraseFlash” command.

Property	Type	Required	Description
command	“eraseFlash”	✓	ID of the command.
debugConfigName	string		Debug configuration name to be used by the “eraseFlash” task.
debugConfigOverride	object		Override settings from debug configuration, used by the “eraseFlash” task.
probeSN	string	✓	Probe serial number to be used by the “eraseFlash” task.
projectName	string	✓	Project name used by “eraseFlash” task.

Command: "programFlash"

Properties supported by the “programFlash” command.

Property	Type	Required	Description
command	“programFlash”	✓	ID of the command.
baseAddressHex	string		Base address (hex format) for the file that will be programmed by the “programFlash” task.
debugConfigName	string		Debug configuration name to be used by the “programFlash” task.
debugConfigOverride	object		Override settings from debug configuration, used by the “programFlash” task.
eraseAllFlash	boolean		Whether to erase all flash during execution of “programFlash” task.
fileToProgram	string		Path to the binary/executable file to be programmed by the “programFlash” task.
probeSN	string	✓	Probe serial number to be used by the “programFlash” task.
projectName	string	✓	Project name used by “programFlash” task.
resetTargetOnExecution	boolean		Whether to reset target after the completion of the “programFlash” task.

Command: "runDebugProject"

Properties supported by the “runDebugProject” command:

Property	Type	Required	Description
command	“runDebugProject”	✓	ID of the command.
appOutputFile	string		Application output file path to be used by the “runDebugProject” task. By default, a temporary file is created.
debugConfigName	string		Debug configuration name to be used by the “runDebugProject” task.
debugConfigOverride	object		Override settings from debug configuration, used by the “runDebugProject” task.
probeSN	string	✓	Probe serial number to be used by the “runDebugProject” task.
projectName	string	✓	Project name used by “runDebugProject” task.
terminatePattern	string		Terminate pattern used by the “runDebugProject” task.
terminateTimeout	number		Terminate timeout used by the “runDebugProject” task. By default, 60 seconds is the default timeout.