Skip to content

Hardware-in-the-Loop (HIL) Quick Start

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 Quick Start begins similarly to the EmbedOps CLI (eo) Quick Start. We recommend completing that Quick Start first if you’re new to eo.

Hardware Requirements

This Quick Start requires a Rasbperry Pi 4 and an nRF53 Development Kit. If you don't have this hardware, you can purchase a kit on DigiKey that includes everything you need.

1. Follow Initial Steps from the CLI Quick Start

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

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

Once these prerequisites are met, you can proceed here.

2. Fork Template Repo

EmbedOps HIL supports creating and running HIL tests on the nRF53 platform. For this Quick Start, fork our nRF53 HIL Quick Start. Forking the project into your own user or organization group within your Git provider is highly recommended so that you can push changes.

3. Connect Your Repo to the Platform

From the root of your forked repository, run:

eo init

This step associates your repository with the EmbedOps platform and generates a file named:

.embedops/repo_id.yml
repo_id: 93080dde-09ee-4ec7-a269-50896a8a3ed6

This file is necessary for HIL functionality.

Info

Commit and push this .embedops/repo_id.yml file so that everyone on your team can leverage the same EmbedOps features.

Once the last command completes, create an initial Dev Container and CI setup by running:

eo add init

Warning

Future versions of EmbedOps may merge the functionality of eo add init into eo init, removing the need for a separate command.

Below is a GIF demonstrating the terminal output:

Example of running eo add init

4. Apply HIL template

EmbedOps provides a hil template that adds the files needed for HIL testing:

eo add hil

The CLI prompts you to select a target platform. Choose D5_NRF5340_HIL_KIT for this Quick Start:

Select a target platform::

[x] D5_NRF5340_HIL_KIT
[ ] Custom


j/k, up/down: select • enter: choose • q, esc: quit

This command creates files in your repository, including:

nrf-hil-quickstart/
├── .embedops/
│   └── hil
│       └── config.yml
└── hil/
    └── hil_sdk/
        └── ...
    ├── README D5 HIL Kit.md
    ├── conftest.py
    ├── test_demo_app.py
    └── ...

Of particular importance is the following configuration file:

.embedops/hil/config.yml
hil_root: hil
hil_extras:
  - name: build/zephyr/merged_domains.hex
    external_module: false

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.

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

By default, hil_root is hil, but feel free to modify it if you organize your tests differently. Also, update hil_extras with any additional files you’d like EmbedOps to include when running tests on your hardware.

5. Provision a Device

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

eo hil provision

Below is a GIF demonstrating the terminal output:

Example of running eo hil provision

When provisioning succeeds, EmbedOps:

  1. Registers a HIL device in the 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.

Your hardware 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.

6. Build the Project with a Dev Container

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

6a: Adjust the Dev Container Configuration for Nordic

Edit the file .devcontainer/devcontainer.json (generated from eo add init in Step 3) with the following:

.devcontainer/devcontainer.json
{
    "image": "nordicplayground/nrfconnect-sdk:v2.5-branch",
    "workspaceMount": "source=${localWorkspaceFolder},target=/workdir/project,type=bind",
    "workspaceFolder": "/workdir/project",
    "onCreateCommand": "echo $(nrfutil toolchain-manager env --as-script) >> ~/.bashrc"
}

This configuration sets up a Dev Container using the Nordic nRF Connect SDK image so you can build your project in a consistent environment.

6b: Build the Project

Open the Dev Container and run:

west build --pristine --board nrf5340dk_nrf5340_cpuapp

Running commands within the Dev Container

  • If you are using VS Code, see these Dev Container docs for instructions on opening a terminal within a Dev Container.

  • If you are NOT using VS Code, you can install the devcontainer CLI and run commands like so: 

    devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . west build --pristine --board nrf5340dk_nrf5340_cpuapp

This command generates a build folder. The key file for flashing the nRF53 board is build/zephyr/merged_domains.hex.

7. Use eo for HIL

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

7a: See Available Devices in the Fleet

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

eo hil fleet

If you have followed the earlier steps and provisioned a device, you should see output similar to:

$ eo hil fleet       

D-1 AVAILABLE

7b: Run HIL Tests

To trigger your HIL tests, simply run:

eo hil run

The eo add hil command (from Step 4) added Python files containing the logic needed to program the device and execute tests. If everything is set up correctly, you should see output resembling:

Example of running eo hil run

This command

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

Next Steps

Congratulations on completing the HIL Quick Start! 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, refer to the links on the left. 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 hil command)