How to add vendor tools to Workshop¶

Some west runners call vendor-supplied tools provided separately from the Zephyr SDK bundle and Ubuntu archive. Such tools can be packaged as an in-project SDK to be included in the Workshop environment via a setup-project hook. This will lead workshop refresh to install them automatically. This guide covers the general procedure, then works through it with two examples: SEGGER J-Link for the jlink runner, and nRF Util for the nrfutil runner.

Prerequisites¶

Before starting, ensure you have these requirements satisfied:

A launched zephyr-26-04 Workshop with a synced workspace, as created in Get started with Workshop.
A development board connected to the host, with a custom-device plug already connected for its flash or debug probe, as described in How to access hardware from Workshop.

All host commands in this guide must be run from the project directory that contains .workshop/zephyr-26-04.yaml.

Create a tool SDK¶

Create an in-project SDK directory with a hooks subdirectory:

$ mkdir -p .workshop/<TOOL_SDK_NAME>/hooks
$ editor .workshop/<TOOL_SDK_NAME>/sdk.yaml

This SDK carries no plugs of its own. Hardware access still comes from the custom-device plug declared in your board-device SDK. Give the SDK a name only:

.workshop/<TOOL_SDK_NAME>/sdk.yaml¶

name: <TOOL_SDK_NAME>

and now we can add the hook file.

Add an install hook¶

Create the setup-project hook:

$ editor .workshop/<TOOL_SDK_NAME>/hooks/setup-project

Populate the hook with the commands that download and install the vendor tool, for example a curl download followed by apt-get install:

.workshop/<TOOL_SDK_NAME>/hooks/setup-project¶

#!/bin/bash
set -euo pipefail

# Download the tool. The -f flag makes curl fail on HTTP errors
# instead of saving the error page as the download.
tool_archive=/tmp/<TOOL_ARCHIVE>
curl -fsSL -o "${tool_archive}" "<TOOL_DOWNLOAD_URL>"

# Check the downloaded file before installing it.
# For a Debian package, use dpkg-deb:
dpkg-deb -I "${tool_archive}"

# Install it as a Debian package.
sudo apt-get update
sudo apt-get install -y "${tool_archive}"

rm -f "${tool_archive}"

A hook that fails stops the refresh and rolls back the Workshop. The reported error may not name the real cause, such as a blocked download that saved an HTML error page. The -f flag and the check above make the hook fail on the download, with a clear message.

Now make the hook executable on the host:

$ chmod +x .workshop/<TOOL_SDK_NAME>/hooks/setup-project

Add the tool SDK¶

Add the in-project SDK to the sdks list in .workshop/zephyr-26-04.yaml:

sdks:
  # Existing SDK entries...
  - name: project-<TOOL_SDK_NAME>

Apply the updated definition:

$ workshop refresh zephyr-26-04

The hook runs only during a refresh and will reinstall the tool every time the Workshop filesystem is rebuilt.

Verify the tool¶

Open a shell in the Workshop and check that the tool is on the PATH:

$ workshop shell zephyr-26-04
workshop@zephyr-26-04:/project$ command -v <TOOL_BINARY>

You should observe a filepath for the tool. If nothing is returned, the tool is absent. You should review the hook and rerun workshop refresh.

The rest of this guide applies the procedure above to two Nordic vendor tools that share a single tool SDK, nordic-tools, because both are needed to flash the same class of Nordic boards.

Example: SEGGER J-Link¶

The jlink runner flashes Nordic boards through their on-board J-Link debug probe. Neither the SEGGER J-Link tools nor a Linux package for them is part of the SDK bundle or the Ubuntu archive.

Create the tool SDK:

$ mkdir -p .workshop/nordic-tools/hooks
$ editor .workshop/nordic-tools/sdk.yaml

.workshop/nordic-tools/sdk.yaml¶

name: nordic-tools

SEGGER protects the download with the license agreement plus a web application firewall (WAF) that checks each request. An unattended hook can receive a CAPTCHA page instead of the package, and a browser User-Agent does not pass the check. Vendor the package instead of downloading it in the hook.

Open the J-Link downloads page with a browser, or another method that passes the WAF check. Download the current 64-bit Linux .deb package under J-Link Software and Documentation Pack. The file name changes with each J-Link release. Copy the package into the project:

$ mkdir -p .workshop/nordic-tools/vendor
$ cp <DOWNLOAD_PATH>/JLink_Linux_V<VERSION>_x86_64.deb \
    .workshop/nordic-tools/vendor/

Create the setup-project hook to install the package from the vendor directory:

.workshop/nordic-tools/hooks/setup-project¶

#!/bin/bash
set -euo pipefail

jlink_deb=/project/.workshop/nordic-tools/vendor/JLink_Linux_V<VERSION>_x86_64.deb
dpkg-deb -I "${jlink_deb}"
sudo apt-get -o DPkg::Lock::Timeout=600 install -y "${jlink_deb}"

The hook installs the package from the vendor directory on every refresh. Reinstalling the 60 MB package adds about three minutes to each refresh.

If your network passes the WAF check without a browser, the hook can download the package instead. Replace <PACKAGE_FILE_NAME> with the current file name from the downloads page:

alternative: .workshop/nordic-tools/hooks/setup-project¶

#!/bin/bash
set -euo pipefail

jlink_deb=/tmp/JLink_Linux_x86_64_deb.deb
curl -fsSL --data 'accept_license_agreement=accepted' \
    -o "${jlink_deb}" \
    "https://www.segger.com/downloads/jlink/<PACKAGE_FILE_NAME>"
dpkg-deb -I "${jlink_deb}"
sudo apt-get update
sudo apt-get install -y "${jlink_deb}"
rm -f "${jlink_deb}"

The -f flag stops curl from saving an error or CAPTCHA page as the package. The hook then fails during the download instead of at the install step.

Make the hook executable:

$ chmod +x .workshop/nordic-tools/hooks/setup-project

Add the SDK and apply it:

sdks:
  # Existing SDK entries...
  - name: project-nordic-tools

$ workshop refresh zephyr-26-04

Verify the tool and flash with the jlink runner:

$ workshop shell zephyr-26-04
workshop@zephyr-26-04:/project$ command -v JLinkExe
/usr/bin/JLinkExe

workshop@zephyr-26-04:/project/zephyr$ west flash -r jlink

Example: nRF Util¶

The nrfutil runner flashes Nordic boards through the device command bundle of nRF Util. nRF Util is not part of the SDK bundle or the Ubuntu archive either.

If you already created the nordic-tools SDK for J-Link above, reuse it and append to the existing hook. Otherwise create the SDK as shown in the J-Link example first.

Open the nRF Util downloads page and copy the download link for Linux (x64).

Append the download and the device command bundle to the hook:

.workshop/nordic-tools/hooks/setup-project¶

nrfutil_bin=/usr/local/bin/nrfutil
sudo curl -fsSL -o "${nrfutil_bin}" "<NRFUTIL_LINUX_X64_URL>"
sudo chmod +x "${nrfutil_bin}"
nrfutil install device

Replace <NRFUTIL_LINUX_X64_URL> with the link you copied. The device command bundle includes the commands the nrfutil runner uses to flash and manage devices.

If you have not already applied the nordic-tools SDK, add it to .workshop/zephyr-26-04.yaml and refresh, as shown in the J-Link example. Otherwise, reapply the definition to pick up the updated hook:

$ workshop refresh zephyr-26-04

Verify the tool and flash with the nrfutil runner:

$ workshop shell zephyr-26-04
workshop@zephyr-26-04:/project$ command -v nrfutil
/usr/local/bin/nrfutil

workshop@zephyr-26-04:/project/zephyr$ west flash -r nrfutil

The board documentation lists the options each runner accepts.