Requirements and setup

This page outlines the requirements that you need to meet before you start working with the HID Add-on.

Hardware requirements 

To use the HID Add-on, you need a development kit with an nRF54L Series SoC. The following table lists the supported hardware platforms and their board targets:

Hardware platforms	PCA	Board name	Board target
nRF54L15 DK	PCA10156	nrf54l15dk	`nrf54l15dk/nrf54l15/cpuapp`
nRF54L15 DK (emulating nRF54L10)	PCA10156	nrf54l15dk	`nrf54l15dk/nrf54l10/cpuapp`
nRF54L15 DK (emulating nRF54L05)	PCA10156	nrf54l15dk	`nrf54l15dk/nrf54l05/cpuapp`
nRF54LC10 DK	PCA10226	nrf54lc10dk	`nrf54lc10dk/nrf54lc10a/cpuapp`
nRF54LM20 DK (emulating nRF54LM20A)	PCA10184	nrf54lm20dk	`nrf54lm20dk/nrf54lm20a/cpuapp`
nRF54LM20 DK	PCA10184	nrf54lm20dk	`nrf54lm20dk/nrf54lm20b/cpuapp`
nRF54LS05 DK	PCA10214	nrf54ls05dk	`nrf54ls05dk/nrf54ls05a/cpuapp`
nRF54LS05 DK	PCA10214	nrf54ls05dk	`nrf54ls05dk/nrf54ls05b/cpuapp`

A single board is enough to build and run a HID peripheral that connects directly to a host over Bluetooth® LE or USB (if supported by the board). To evaluate a HID peripheral that communicates with the host through a dongle, you need the following two boards:

With a peripheral configuration.
With a dongle configuration. The board that is used as a dongle must support USB.

For details about the configuration of each supported board, see the nRF Desktop board configuration files section.

Get the HID Add-on code 

The HID Add-on is distributed as a Git repository and is managed through its own west manifest. The compatible nRF Connect SDK version is specified in the west.yml file. Follow the HID Add-on GitHub repository link to browse the codebase. To get the HID Add-on code, pick your method from the following:

Use the nRF Connect for Visual Studio Code extension, which provides a convenient way to clone the add-on and compatible nRF Connect SDK version.
Clone the add-on repository and initialize west with the add-on manifest.
Extend your west manifest with Add-on as a project.
Clone the Add-on repository and add the Add-on as a Zephyr module through CMake or environment variable.
Switch the west manifest to the Add-on in an existing nRF Connect SDK workspace.

Note

Use this method when you wish to specifically evaluate nRF Desktop or other tools provided by the Add-on, but do not have the nRF Connect SDK setup yet.

Clone the HID Add-on code, together with the compatible nRF Connect SDK:

Ensure you have installed Visual Studio Code and the nRF Connect for Visual Studio Code extension.
Follow the nRF Connect SDK installation guide to install nRF Connect SDK prerequisites and toolchain v3.4.2-rc1.

Note

The compatible version of the nRF Connect SDK will be cloned with the HID Add-on repository in the following steps. The version of nRF Connect SDK is fixed to the version of the HID Add-on and is hard-coded in the west.yml file of the HID Add-on.
Open the nRF Connect extension in Visual Studio Code by clicking its icon in the Activity Bar.
In the extension’s Welcome View, click Create a new application. The list of actions appears in Visual Studio Code’s quick pick.
Click Browse nRF Connect SDK Add-on Index. The list of available nRF Connect SDK add-ons appears in Visual Studio Code’s quick pick.
Select HID Add-on.
Select the Add-on version to install. Depending on the speed of your internet connection, the update might take some time.

Note

Use this method when you wish to specifically evaluate nRF Desktop or other tools provided by the Add-on, but do not have the nRF Connect SDK setup yet.

Follow the nRF Connect SDK installation guide to install nRF Connect SDK prerequisites and toolchain v3.4.2-rc1.

Note

The compatible version of the nRF Connect SDK will be cloned with the HID Add-on repository in the following steps. The version of nRF Connect SDK is fixed to the version of the HID Add-on and is hard-coded in the west.yml file of the HID Add-on.

Launch the installed toolchain:

nrfutil sdk-manager toolchain launch --ncs-version v3.4.2-rc1 --terminal

nrfutil sdk-manager toolchain launch --ncs-version v3.4.2-rc1 --shell

nrfutil sdk-manager toolchain launch --ncs-version v3.4.2-rc1 --shell

Initialize the HID Add-on repository using one of the following methods:
1. Initialize west with the remote manifest:
  west init -m https://github.com/nrfconnect/ncs-hid --mr v1.0.0
1. Clone the HID Add-on repository into the hid folder, which is the path expected by the add-on manifest:
  git clone --branch v1.0.0 https://github.com/nrfconnect/ncs-hid hid
2. Initialize west with the local manifest:
  west init -l hid
Update all repositories by running the following command:
```
west update
```
Depending on the speed of your internet connection, the update might take some time.

Note

Use this method when running a Zephyr workspace application or if you prefer to use a modification of the nRF Connect SDK manifest.

Add the HID Add-on repository as a project in the west manifest by including the following lines in your west.yml under the projects key:
```
- name: hid
  url: https://github.com/nrfconnect/ncs-hid
  revision: v1.0.0
  import: true
```
If you have already included the nRF Connect SDK in your west manifest, remove it or replace the above import key with the mapping:
```
import:
   name-blocklist:
   - nrf
```
Your west manifest must specify compatible versions of the nRF Connect SDK and Add-on.
Run west update to pull the HID Add-on repository.

Note

Use this method if you have a former installation of the nRF Connect SDK and would like to evaluate or use the HID Add-on with that installation. This method allows you to keep the nRF Connect SDK manifest unmodified.

Before using this approach, ensure that a compatible version of the nRF Connect SDK is installed. To identify the compatible nRF Connect SDK version, check the west.yml file of the HID Add-on. Since west does not manage the Add-on in this setup, you are responsible for keeping the versions synchronized.

Clone the Add-on repository:

git clone --branch v1.0.0 https://github.com/nrfconnect/ncs-hid

Set the CMake or environment variable EXTRA_ZEPHYR_MODULES to the Add-on code path. Use absolute path to ensure proper path resolution. Check the Environment Variables documentation for different ways of setting environment variables in Zephyr.

Note

Use this method if you already have an nRF Connect SDK workspace and want west to use the HID Add-on west.yml as the workspace manifest instead of the nRF Connect SDK one. You can switch back to the nRF Connect SDK manifest at any time.

Assuming you have an existing nRF Connect SDK workspace in the ncs folder, run the following commands:
1. Navigate to the workspace folder:
```
cd ncs
```
2. Clone the add-on repository into the hid folder, which is the path expected by the add-on manifest:
```
git clone --branch v1.0.0 https://github.com/nrfconnect/ncs-hid hid
```
3. Set the manifest path to the add-on directory:
```
west config manifest.path hid
```
4. Update the nRF Connect SDK modules:
```
west update
```
Optionally, run these commands in case you need to work on the nRF Connect SDK without the add-on:
1. Configure the manifest path back to the nRF Connect SDK directory:
```
west config manifest.path nrf
```
2. Update nRF Connect SDK modules:
```
west update
```
3. Check the current manifest path with the following command:
```
west config manifest.path
```
  The output should be:
```
nrf
```
  This means that the current workspace is using the nRF Connect SDK.

Requirements and setup

Hardware requirements

Get the HID Add-on code

Hardware requirements 

Get the HID Add-on code 