Binding custom tasks to actions - nRF Connect for VS Code
Skip to content

Binding custom tasks to actions

The extension lets you create custom tasks and then bind them to the Build and Flash actions. You can bind custom tasks to most of the build and flash actions. When bound, these tasks will run instead of the standard commands. This is useful if you want to run a custom script that hooks into your own build system, or that performs pre- or postprocessing steps.

You can add custom tasks to the following actions:

  • Build
  • Pristine Build
  • Flash
  • Erase and Flash to Board

Note

Task bindings only apply to the primary Build command. They do not apply to the action Build All.

Task and binding configuration files

The following table lists locations where tasks definitions and binding definitions are stored, depending on the structure of your project.

Definition type Single-folder project Multi-root workspace
Tasks .vscode/tasks.json tasks key in <file-name>.code-workspace
Bindings .vscode/settings.json settings key in <file-name>.code-workspace

There are several pre-defined tasks that you can bind to the chosen actions: Build [pristine], Build [clean], or Flash. If you want to add custom tasks, you need to manually create them in tasks.json or the workspace configuration file. Then, you need to bind it to the action in settings.json or the workspace configuration file.

Bindings are stored in the nrf-connect.taskBindings property in the related binding configuration file. Tasks are matched to bindings using the tasks' label attribute. If a task is referenced in the configuration, but is not defined in the task configuration file or contributed by an extension, a warning message appears until the binding is removed.

You can also modify nrf-connect.taskBindings manually, which can be easier if you have many bindings or a complicated setup.

For more information on where tasks should be defined and what format they should take, read the VS Code tasks documentation.

How to locate configuration files

Depending on the structure of your project:

  • When working with a single-folder project:

    • The settings.json file is automatically created in the .vscode directory. To open it, choose the Preferences: Open User Settings (JSON) command from the Command Palette.
    • The tasks.json file is automatically created in the .vscode directory. To open it, choose the Tasks: Configure Task command from the Command Palette.
  • If you are working with a multi-root workspace, <file-name>.code-workspace file is created in a temporary location if you have opened a workspace, but not saved it. Make sure to save the workspace to keep the file.

Binding tasks to actions from GUI

The extension allows you to bind tasks using GUI. The extension lists both pre-defined tasks and tasks added manually and automatically updates the properties in the related setting files when you define the binding.

How to bind tasks

To bind a task to an action:

  1. Hover your cursor over Build or Flash from the Actions View.
  2. Click on the More actions... button (...) that appears to the right.
  3. Click on Bind Task to Action.
    A quick-pick menu appears in the Editor. This list includes pre-defined tasks and tasks you have defined manually (with their custom label identifier).
  4. Click on the action you want to bind.
  5. Click on the builds you want to bind to the action.

Binding two custom tasks to an action

Once you have bound tasks to an action, view them by hovering your mouse over Build or Flash, whichever you have bound the task to, and they will appear in the help text. You can also click on Manage Task Bindings under More actions... to open the setting file that contains the binding definition.

How to unbind tasks

To unbind tasks from an action:

  1. Right-click on Build or Flash.
  2. Click Remove Task Binding.

If multiple tasks are bound, select which one you wish to remove.

How to edit task file and entries

To edit the task configuration file, complete the following steps:

  1. Save the workspace.
  2. From the Command Palette, choose the Tasks: Configure Task command.
    The list of tasks available for configuration appears.
  3. Select the task you want to customize.
    The task configuration file opens in the Editor with a prefilled task entry.
  4. Change the task configuration based on your needs:

    1. Include the Task binding parameters of your choice.
      See Examples for reference.
    2. Include the label parameter with the custom name of the task.
      This is needed for binding the task.
    3. Optionally, include predefined extension variables and Visual Studio Code's Variable Reference.
  5. Save the file.

  6. Bind the task to the action of your choice.
    The task is listed with its custom label identifier.

How to manually add task binding

You can manually create task bindings in the binding configuration file by referencing the tasks defined in the correct task configuration file.

Complete the following steps:

  1. Open the binding configuration file.
  2. Add the following lines to the nrf-connect.taskBindings configuration option:

    {
      "nrf-connect.taskBindings": {
          "<action>": [{ "taskName": "<task_label>" }]
        }
    }
    
  3. Replace <action> with either flash or build and <task_label> with the task's custom label identifier.

  4. Save the file.

See Example of a single task for reference.

How to add application-specific flash options

If required, you can configure applications with additional flash options: softreset or skipBuild, or both. When set to true, these options are applied to all flash commands run through the UI that target that application.

The application-specific flash options are set in the binding configuration file.

To apply these options:

  1. Open the binding configuration file.
  2. Create the following entry, customizing it to your needs:

    {
        "nrf-connect.applicationOptions": {
            "/path/to/your/application": {
                "flash": {
                    "softreset": true,
                    "skipBuild": true
                }
            }
        }
    }
    

For the list of available variable substitutions, see predefined extension variables and Visual Studio Code's Variable Reference.

Examples

The following examples show some of the common task binding use cases.

Example of a single task

For example, let's assume you have a tasks.json file. If you have only one task that you would like to bind to an action, the file may look like follows:

{
  "version": "2.0.0",
  "tasks": [
        {
            "label": "My custom flash",
            "command": "${workspaceFolder}/my-flash-script.sh",
            "args": ["--build", "--erase", "--nrf52"],
            "presentation": {
                "echo": true,
                "reveal": "never",
                "clear": true
            }
        }
    ]
}

You can bind the task to the action by adding the following lines to the nrf-connect.taskBindings configuration option in the binding configuration file:

{
    "nrf-connect.taskBindings": {
      "build": [{ "taskName": "My custom flash" }]
  }
}

This way, the My custom flash task will be executed whenever the Build action is run.

Example of a restricted single task

You can also restrict task bindings to a given build configuration or a set of build configurations. For example, see the following lines in the binding configuration file:

{
  "nrf-connect.taskBindings": {
    "flash": [
      {
        "taskName": "My custom flash",
        "buildConfigs": [
          "build",
          "${workspaceFolder}/hello_world/build_1"
          "${workspaceFolder}/samples/bluetooth/perihperal_hids/build",
        ]
      }
    ]
  }
}

With this configuration, the My custom flash task will only be executed if the path of the active build matches the one that is listed in the buildConfigs property.

Note

The buildConfigs property is optional. If this property is not defined, then the binding will apply to all configurations.

Example of multiple tasks

You can bind multiple tasks to a build configuration in the binding configuration file. For example:

{
  "nrf-connect.taskBindings": {
      "build": [
          { "taskName": "My custom build" },
          { "taskName": "Staging build", "buildConfigs": ["build"] },
          { "taskName": "Release build", "buildConfigs": ["build"] },
      ]
  }
}

In this instance, three tasks have been bound to the build build configuration. The My custom build task was bound implicitly since no builds were declared in the binding, and the remaining two were bound by explicitly naming the build build configuration. When multiple tasks are bound, you will be given a choice of which to execute when you run the action.

Example of custom task types together

You can use the nrf-connect-build and nrf-connect-flash task types in the task configuration file for building and flashing a build configuration, respectively. See Task binding parameters for the list of parameters you can use for these task types.

For example, the following tasks.json file includes custom nrf-connect-build and nrf-connect-flash types for simplifying the building and flashing process of an nRF52840 DK using some of the accepted parameters:

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "nrf-connect-build",
            "config": "${workspaceFolder:hello_world}/build_nrf52840",
            "runCmake": false,
            "problemMatcher": [
                "$gcc",
                "$cmake",
                "$kconfig",
                "$kconfig_syntax",
                "$kconfig_syntax_files",
                "$dts",
                "$dts_syntax"
            ],
            "group": "build",
            "label": "nRF Connect: Build build_nrf52840 (active)"
        },
        {
            "type": "nrf-connect-flash",
            "config": "${workspaceFolder:hello_world}/build_nrf52840",
            "snr": "683888634",
            "erase": false,
            "problemMatcher": [],
            "label": "nRF Connect: Flash build_nrf52840 (active)"
        }
    ]
}

Example of custom runner task

In the following example, the tasks.json file includes custom nrf-connect-flash type from the previous example, but with the additional runner parameter set to nrfjprog.

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "nrf-connect-flash",
            "config": "${workspaceFolder:hello_world}/build_nrf52840",
            "snr": "683888634",
            "runner": "nrfjprog",
            "erase": false,
            "problemMatcher": [],
            "label": "nRF Connect: Flash build_nrf52840 (active)"
        }
    ]
}