Skip to content

nRF54 Hardware-in-the-Loop (HIL) Quickstart

This page introduces the EmbedOps approach to Hardware-in-the-Loop (HIL) testing.

You will learn how to:

  • Connect a repository to the EmbedOps platform
  • Use an EmbedOps template to add HIL-specific assets
  • Provision a HIL Gateway device
  • Run a HIL test

Recommendation

This HIL Quickstart begins similarly to the EmbedOps CLI Quickstart. We recommend completing that quickstart first if you’re new to eo.

Hardware Requirements

This quickstart requires a Raspberry Pi 4 and an nRF54 Development Kit.

1. Follow Initial Steps from the CLI Quickstart

If you haven’t yet set up eo or familiarized yourself with the basics of EmbedOps, follow Steps 1–4 of the EmbedOps CLI Quickstart to:

  1. Sign up for an EmbedOps account
  2. Install all dependencies
  3. Install the EmbedOps CLI
  4. Log in with eo

Once these prerequisites are met, you can proceed here.

Dev Container vs. Host machine

  • Some commands in this quickstart are run on your host machine, and some are run in a Dev Container. To differentiate, host> and container> will be used as the terminal prompts to clarify where the command is run.

2. Create your project and connect it to the platform

Create a new directory for your nRF54 HIL Quickstart project and connect it to the EmbedOps platform. It will create an initial Dev Container and CI setup.

EmbedOps Projects and Repositories

Connecting your project to the EmbedOps Platform lets you link your Git repository to a corresponding repository on EmbedOps. The EmbedOps repository contains memory metrics, HIL tests, and links to your shared Git repo on GitLab/GitHub/Bitbucket. The EmbedOps repository is part of an EmbedOps Project, which can contain multiple EmbedOps repositories. For more info, take a look at the EmbedOps Projects Page.

host> mkdir nrf54-hil-quickstart
host> cd nrf54-hil-quickstart
host> git init
host> eo init

It will prompt you for your preferred CI provider and Linux distribution.

For the example project with GitHub, set the pipeline provider to GitHub and the Linux distribution to Ubuntu.

Warning

If you've registered Git repositories with the EmbedOps platform before, you may have multiple EmbedOps Projects and will be prompted to choose which project to add this to. Select "Trial Project".

Here's a video showing an example output from the eo init command:

Terminal
 

After running the above command, you now have:

  • A .embedops/repo_id.yml that will connect this repository to the EmbedOps platform
  • A .embedops/template-settings.yml that saves what you selected above
  • For the example project, the pipeline provider will be set to GitHub
  • An initial dev container configuration
  • For the example project, it will use an Ubuntu image as the base container
  • An initial CI configuration
  • For the example project, it will generate a .github/workflows/init.yml file and the /ci folder

Info

Commit and push the .embedops and .devcontainer folders so that everyone on your team can leverage the same EmbedOps features.

3. Apply nRF54 HIL Quickstart template

The nRF54L15 HIL Quickstart template:

  • Uses v3.1.1 of the nRF Connect SDK
  • Imports only necessary modules to minimize the time it takes to initialize the dev container
  • Configures ccache to store the cache in the root of the project for caching locally and exporting the cache in CI
  • Uses Zephyr's T2 topology

Run the following command to apply the nRF54L15 HIL Quickstart template:

host> eo add nrf54l15-hil-quickstart

This command creates files in your repository, including:

nrf54-hil-quickstart/
├── .devcontainer
│   ├── devcontainer.json
│   └── Dockerfile
├── .embedops
│   ├── hil
│   │   └── config.yml
│   ├── repo_id.yml
│   └── template-settings.yml
├── .github
│   └── workflows
│       ├── init.yml
│       └── zephyr-build-and-hil.yml
├── .gitignore
├── app
│   ├── CMakeLists.txt
│   ├── CMakePresets.json
│   ├── prj.conf
│   ├── src
│   │   └── ...
│   ├── sysbuild
│   │   └── mcuboot.conf
│   ├── sysbuild.conf
│   └── VERSION
├── ci
│   ├── hil.sh
│   ├── pipeline.json
│   ├── pipeline.sh
│   └── zephyr.sh
├── hil
│   ├── app_downgrade_0_1.bin
│   ├── conftest.py
│   ├── hil_sdk
│   │   └── ...
│   ├── README D5 HIL Kit.md
│   └── test_demo_app.py
├── init-west-workspace.sh
├── README.md
└── west.yml

Of particular importance is the following configuration file:

.embedops/hil/config.yml
hil_root: hil
hil_extras:
  - name: build/merged.hex

This YAML file configures the HIL setup for your project, specifying which directory contains your HIL tests and which extra files (such as firmware .hex files) to include.

HIL Configuration

By default, hil_root is set to hil, which is how the example project is organized. On your own projects, you can easily modify it if you organize your tests differently. The hil_extras can also be modified with any additional files you’d like EmbedOps to include when running tests on your hardware. To explore more YAML configurations, go to the YAML Config page.

As indicated in hil/README D5 HIL Kit.md:

  • conftest.py - Implements test fixtures for the various interfaces
  • test_demo_app.py - Multiple tests for all demo app features

4. Provision a Device

4a: Generate the Image for the Raspberry Pi

To provision a new HIL device on the EmbedOps platform, run the following from the root of your repository (where .embedops exists):

host> eo hil provision

It will take up to 5 minutes for it to download the gateway image, and return when it finishes. Below is a GIF demonstrating the terminal output:

Example of running eo hil provision

When provisioning succeeds, EmbedOps:

  1. Registers a HIL device on the EmbedOps platform
  2. Generates a gateway-image.img file used to flash an SD card

Use your favorite tool, such as Balena Etcher or Raspberry Pi Imager, to burn gateway-image.img onto an SD card. Insert the SD card into your Raspberry Pi.

Set up your hardware by connecting your Raspberry Pi to power and Ethernet, and to the nRF54L15 DK via USB. Setup should look like this:

Example HIL Gateway setup

Ethernet required

The current gateway image requires an Ethernet connection. Make sure your Raspberry Pi is connected via Ethernet for the HIL Gateway to function.

Finally, power on your Raspberry Pi so the EmbedOps platform can communicate with your device for HIL testing. It will take up to 10 minutes for the device to boot up.

Provisioning More Devices

To provision more Raspberry Pis to build a fleet of HIL setups, run the eo hil provision command and burn the new gateway image onto a new SD card for each Pi.

4b: See Available Devices in the Fleet

You can see the gateway is provisioned correctly by going to the EmbedOps platform and looking at the HIL Fleet page. You can see your provisioned device available online:

EmbedOps Platform screenshot of the available device

To check the status of devices in your fleet via the EmbedOps CLI, run:

host> eo hil fleet

You should see output similar to:

host> eo hil fleet       
Name     Source               Location             Status              
D-1      Trial Project        project              AVAILABLE

Troubleshooting

If either of the above steps displays the device as offline, verify that the Raspberry Pi has an Ethernet connection to the internet. Note that there is some latency between when a device connects or disconnects and when its status is updated.

EmbedOps Platform screenshot of an offline device

5. Build the Project with a Dev Container

The nRF54-based project in this quickstart includes source code that generates a HEX file to flash onto the nRF54 target.

5a: Build the project manually in the Dev Container

To get into the Dev Container, go to the Dev Container extension in VS Code and click the "+" at the top to open the drop-down selection. Select "Open Current Folder in Container", and it will auto-create the Dev Container and restart VS Code with the terminal running in the container. To learn more about dev containers in VS Code, see these Dev Container docs.

Workspace Folder

The Dev Container starts in the west workspace root at /west-workspace. Your repository is located at /west-workspace/<repo-name> (for example, /west-workspace/nrf54-hil-quickstart). The build commands below assume this location.

Once you're in the Dev Container, run:

container> west build --build-dir nrf54-hil-quickstart/build --pristine always nrf54-hil-quickstart/app --board nrf54l15dk/nrf54l15/cpuapp --sysbuild

Running commands outside the Dev Container

  • If you are NOT using VS Code, you can install the devcontainer CLI and run commands like so: 
    host> devcontainer up --workspace-folder .
host> devcontainer exec --workspace-folder . west build --build-dir nrf54-hil-quickstart/build --pristine always nrf54-hil-quickstart/app --board nrf54l15dk/nrf54l15/cpuapp --sysbuild

5b: Run the CI pipeline locally

You can also build the project by running the CI pipeline locally with the eo run <JOB_NAME> command. The job name is the name of the shell script in the ci/ directory. To run the zephyr job, which builds the project, run the following command:

host> eo run zephyr

Both approaches generate a build folder. The key file for flashing the nRF54 board is build/merged.hex, which you saw earlier at Step 3 as the name of the hex file in hil_extras.

6. Use eo for HIL

With your project now set up for EmbedOps HIL, you can run HIL-related commands using the eo CLI.

6a: Run HIL Tests

To trigger your HIL tests, simply run the following command on your host machine or in a dev container:

eo hil run

Logging Results Locally

By default, EmbedOps doesn't log the output of the HIL tests locally; it simply prints them to the terminal. The logs will still be available after the run on the EmbedOps Platform, but if you want to keep them locally, you can change the command to something like this: eo hil run 2>&1 | tee hil.log to store the results in the hil.log file.

The eo add nrf54l15-hil-quickstart command (from Step 3) added Python files containing the logic needed to program the device and execute tests. If everything is set up correctly, you should see the HIL run start, with logs of the tests from the Gateway:

Example of running eo hil run

The eo hil run command

  • Uploads all necessary assets for the tests
  • Establishes communication with the HIL Gateway
  • Executes the specified tests
  • Returns the output from the Gateway

There are a couple of flags you can set that allow you to limit which tests you run and where you run them.

  • -m [string]: Marker that will restrict which tests are run to only tests marked with @pytest.mark.<marker>. See test selection
  • -d device1,device2,...,deviceN: Comma delimited list of HIL Gateway device names to restrict the run to

How long does the HIL tests take?

It will take up to 10 minutes on the first run because it will install the Python dependencies. The following runs will take up to 5 minutes.

6b: Examining HIL Test Results

When the run command finishes, you'll be able to see the final number of tests passed in the terminal. You can also view all the logs for this HIL test run on the EmbedOps Platform. The eo hil run command will generate a URL where you can view the HIL test result.

...
[GW] ==== test session complete ====
[GW] Hil run url: https://app.embedops.io/app/<ORG_ID>/dashboard/<PROJECT_ID>/repo/<REPO_ID>/hil-tests/<HIL_RUN_ID>

Alternatively, the following eo command will open the nrf54-hil-quickstart project on the EmbedOps Platform in a browser:

host> eo open

On the EmbedOps platform, select "HIL Tests" to see a list of the most recent HIL runs, like below:

Example of HIL run results

Clicking into a particular run, you can then see all the logs that were output on the terminal during the eo hil run command:

Example of a HIL run logs

Next Steps

Congratulations on completing the HIL Quickstart! You’ve successfully configured your repository for HIL and run your first hardware-in-the-loop tests.

To dive deeper into the capabilities of our HIL framework, check out the Hardware-in-the-Loop (HIL) tab. There, you’ll find:

  • How-To Guides for advanced configurations
  • Reference Documentation for all HIL commands and features
  • HIL SDK Details (one of the modules auto-imported by the eo add nrf54l15-hil-quickstart command)