Building and running nRF Audio applications

This nRF Audio application source files can be found in their respective folders under applications/nrf_audio in the nRF Connect SDK folder structure.

You can build and program the applications in one of the following ways:

Building and programming using script - This is the suggested method. Using this method allows you to build and program multiple development kits at the same time.
Building and programming using standard methods - Using either of these methods requires manually providing source files for building each build configuration.

Note

Check the nRF Audio application known issues before building and programming the applications. Some of them might impact running the application on certain platforms.

For example, one of the known issues (OCT-2154) mentions intermittent audio stream on the headset when using USB audio interface on macOS.

Testing out of the box 

Each development kit comes preprogrammed with basic firmware that indicates if the kit is functional. Before building the application, you can verify if the kit is working by completing the following steps:

Plug the device into the USB port.
Turn on the development kit using the On/Off switch.
Observe RGB (bottom side LEDs around the center opening that illuminate the Nordic Semiconductor logo) turn solid yellow, OB/EXT turn solid green, and LED3 start blinking green.

You can now program the development kit.

Building and programming using script 

The suggested method for building each of the applications and programming it to the development kit is running the buildprog.py Python script. The script automates the process of selecting configuration files and building different applications. This eases the process of building and programming images for multiple development kits.

The script is located in the applications/nrf_audio/tools/buildprog directory.

Note

The buildprog.py script is an app-specific script for building and programming multiple kits and cores with various audio application configurations. The script will be deprecated in a future release. The audio applications will gradually shift only to using standard tools for building and programming development kits.

Preparing the JSON file 

The script depends on the settings defined in the nrf5340_audio_dk_devices.json file. Before using the script, make sure to update this file with the following information for each development kit you want to use. This is how the file looks by default:

{
       "sirk": "NRF5340_TWS_DEMO",
       "devices": [
              {
                     "nrf5340_audio_dk_snr": 1000,
                     "nrf5340_audio_dk_dev": "headset",
                     "location": [
                            "FRONT_LEFT"
                     ]
              },
              {
                     "nrf5340_audio_dk_snr": 1000,
                     "nrf5340_audio_dk_dev": "gateway",
                     "location": [
                            "NA"
                     ]
              },
              {
                     "nrf5340_audio_dk_snr": 1000,
                     "nrf5340_audio_dk_dev": "headset",
                     "location": [
                            "FRONT_RIGHT"
                     ]
              }
       ]
}

When preparing the JSON file, update the following fields:

nrf5340_audio_dk_snr - This field lists the SEGGER serial number. You can check this ten-digit number on the sticker on the nRF5340 Audio development kit. Alternatively, connect the development kit to your PC and run nrfutil device list in a command window to print the SEGGER serial number of all connected kits.
nrf5340_audio_dk_dev - This field assigns the specific nRF5340 Audio development kit to be headset or gateway.
location - This field is valid only for headsets. It sets the location on which the headset is meant to work, especially when using the default CIS transport mode configuration. For more information, see Configuring the headset location.
sirk - This field sets the SIRK for the device set, which is used in the unicast applications. The SIRK must be 16 characters long and cannot be the default SIRK defined in the Kconfig file (NRF5340_TWS_DEMO). If the default SIRK is used, the script will raise an error and stop building.

Running the script 

The script handles building and parallel programming of multiple kits. The following sections explain these two steps separately.

Script parameters for building

After editing the nrf5340_audio_dk_devices.json file, run buildprog.py to build the firmware for the development kits. The building command for running the script requires providing the following parameters:

Parameters for the script
Parameter	Description	Options	More information
Core type (`-c`)	Specifies the core type.	`app`, `net`, `both`	Firmware architecture
Application version (`-b`)	Specifies the application version.	`release`, `debug`	nRF Audio configuration files
Transport type (`-t`)	Specifies the transport type.	`broadcast`, `unicast`	Firmware architecture
Device type (`-d`)	Specifies the device type.	`headset`, `gateway`, `both`	Gateway and headset roles

For example, the following command builds headset and gateway applications using the script for the application core with the debug application version:

python buildprog.py -c app -b debug -d both -t unicast

The command can be run from any location, as long as the correct path to buildprog.py is given.

The build files are saved in separate subdirectories in the applications/nrf_audio/tools/build directory. The script creates a directory for each transport, device type, core, and version combination. For example, when running the command above, the script creates the unicast/gateway/app/debug, unicast/gateway/net/debug, unicast/headset/app/debug, unicast/headset/net/debug files and directories.

Script parameters for programming

The script can program the build files as part of the same python buildprog.py command used for building. Use one of the following programming parameters:

Programming (-p parameter) - If you run the buildprog script with this parameter, you can program one or both of the cores after building the files.
Sequential programming (-s parameter) - If you encounter problems while programming, include this parameter alongside other parameters to program sequentially.

Note

The development kits are programmed according to the serial numbers set in the JSON file. Make sure to connect the development kits to your PC using USB and turn them on using the POWER switch before you run the script with the programming parameter.

The command for programming can look as follows:

python buildprog.py -c both -b debug -d both -t unicast -p

This command builds the unicast headset and the gateway applications with debug version of both the application core binary and the network core binary - and programs each to its respective core. If you want to rebuild from scratch, you can add the --pristine parameter to the command (west’s -p for cannot be used for a pristine build with the script).

Note

If the programming command fails because of a readback protection error, run buildprog.py with the --recover_on_fail or -f parameter to recover and re-program automatically when programming fails. For example, using the programming command example above:

python buildprog.py -c both -b debug -d both -t unicast -p --recover_on_fail

Getting help

Run python buildprog.py -h for information about all available script parameters.

Configuration table overview

When running the script command, a table similar to the following one is displayed to provide an overview of the selected options and parameter values:

+------------+----------+---------+--------------+---------------------+---------------------+
| snr        | snr conn | device  | only reboot  | core app programmed | core net programmed |
+------------+----------+---------+--------------+---------------------+---------------------+
| 1010101010 | True     | headset | Not selected | Selected TBD        | Not selected        |
| 2020202020 | True     | gateway | Not selected | Selected TBD        | Not selected        |
| 3030303030 | True     | headset | Not selected | Selected TBD        | Not selected        |
+------------+----------+---------+--------------+---------------------+---------------------+

See the following table for the meaning of each column and the list of possible values:

Column	Indication	Possible values
`snr`	Serial number of the device, as provided in the `nrf5340_audio_dk_devices.json` file.	Serial number.
`snr conn`	Whether the device with the provided serial number is connected to the PC with a serial connection.	`True` - Connected.
`snr conn`		`False` - Not connected.
`device`	Device type, as provided in the `nrf5340_audio_dk_devices.json` file.	`headset` - Headset.
`device`		`gateway` - Gateway.
`only reboot`	Whether the device is to be only reset and not programmed. This depends on the `-r` parameter in the command, which overrides other parameters.	`Not selected` - No reset.
		`Selected TBD` - Only reset requested.
		`Done` - Reset done.
		`Failed` - Reset failed.
`core app programmed`	Whether the application core is to be programmed. This depends on the value provided to the `-c` parameter (see above).	`Not selected` - Core will not be programmed.
		`Selected TBD` - Programming requested.
		`Done` - Programming done.
		`Failed` - Programming failed.
`core net programmed`	Whether the network core is to be programmed. This depends on the value provided to the `-c` parameter (see above).	`Not selected` - Core will not be programmed.
		`Selected TBD` - Programming requested.
		`Done` - Programming done.
		`Failed` - Programming failed.

Building and programming using standard methods 

You can build the nRF Audio applications using the standard nRF Connect SDK build steps for nRF Connect for VS Code or the command line. This method requires manually providing source files for building each build configuration.

Application configuration files 

The application uses a prj.conf configuration file located in the application root directory for the default configuration. It also uses application-specific overlay files and can use additional files for different custom configurations. When you build the application, you can select one of these configurations using the FILE_SUFFIX variable.

See nRF Audio configuration files, Custom configurations, and Providing CMake options for more information.

The nRF Audio applications come with the following configuration files:

Application configurations
Configuration	File name	FILE_SUFFIX	Description
Debug (default)	`prj.conf`	No suffix	Debug version of the application. Provides full logging capabilities and debug optimizations to ease development.
Release	`prj_release.conf`	`release`	Release version of the application. Disables logging capabilities and disables development features to create a smaller application binary.
Application-specific overlay file	`unicast_server/overlay-unicast_server.conf`	`unicast_server`	Configuration file for the unicast server application.
Application-specific overlay file	`unicast_client/overlay-unicast_client.conf`	`unicast_client`	Configuration file for the unicast client application.
Application-specific overlay file	`broadcast_sink/overlay-broadcast_sink.conf`	`broadcast_sink`	Configuration file for the broadcast sink application.
Application-specific overlay file	`broadcast_source/overlay-broadcast_source.conf`	`broadcast_source`	Configuration file for the broadcast source application.

Building the application 

When you build the application, make sure to create the combination of configurations that matches the application mode you want to work with.

The following table summarizes the differences between the available nRF Audio applications.

Differences between nRF Audio applications
Application name (LE Audio role)	Application mode	Minimum amount of audio devices recommended for testing	FEM support
Broadcast sink	BIS (headset)	2
Broadcast source	BIS (gateway)	2	✔
Unicast client	CIS (gateway)	2 (three for CIS with TWS)	✔
Unicast server	CIS (headset)	2 (three for CIS with TWS)	✔

Complete the following steps to build each of the configurations you need:

Open nRF Connect for VS Code.
Create a new audio application in nRF Connect for VS Code by completing the steps listed in the Creating application in nRF Connect for VS Code section. Use the Copy a sample option and select the nRF Audio application when prompted.
Complete the steps listed on the How to set up a build configuration section in the nRF Connect for VS Code documentation to create a build configuration. Depending on the configuration and applications you want to build, set the correct combination of Application configuration files in the extension UI:
- Base configuration files (Kconfig fragments):
  - For the debug version: No file selected.
  - For the release version: prj_release.conf
- Extra Kconfig fragments:
  - For the unicast server application: unicast_server/overlay-unicast_server.conf
  - For the unicast client application: unicast_client/overlay-unicast_client.conf
  - For the broadcast sink application: broadcast_sink/overlay-broadcast_sink.conf
  - For the broadcast source application: broadcast_source/overlay-broadcast_source.conf
For other sections, check the tooltips in the extension UI.
Make sure the Generate only checkbox is not selected.
Generate and build the application by clicking the Generate and Build button.

You can now program the application to one or more development kits. See Programming the application.

Choose the combination of build flags:
1. Choose the configuration file for the device selected by using one of the following options:
  - For unicast headset: -DEXTRA_CONF_FILE=".\unicast_server\overlay-unicast_server.conf"
  - For unicast gateway: -DEXTRA_CONF_FILE=".\unicast_client\overlay-unicast_client.conf"
  - For broadcast headset: -DEXTRA_CONF_FILE=".\broadcast_sink\overlay-broadcast_sink.conf"
  - For broadcast gateway: -DEXTRA_CONF_FILE=".\broadcast_source\overlay-broadcast_source.conf"
2. Choose the application version (Application configuration files) by using one of the following options:
  - For the debug version: No build flag needed.
  - For the release version: -DFILE_SUFFIX=release
Build the application using the standard build steps for the command line. For example, if you want to build the firmware for the application core as a headset using the release application version, you can run the following command from the applications/nrf_audio/ directory:
```
west build -b nrf5340_audio_dk/nrf5340/cpuapp --pristine -- -DEXTRA_CONF_FILE=".\unicast_server\overlay-unicast_server.conf" -DFILE_SUFFIX=release
```
This command creates the build files directly in the build directory. This means that you cannot create build files for all devices you want to program, because the subsequent commands will overwrite the files in the build directory.

To work around this standard west behavior, you can add the -d parameter to the west command to specify a custom build folder for each device. This way, you can build firmware for different device configurations to separate directories before programming the development kits. Alternatively, you can use the Building and programming using script, which handles this automatically.

Programming the application 

After building the files for the development kit you want to program, follow the standard procedure for programming applications in the nRF Connect SDK.

If you want to program the same audio application to multiple development kits connected to your PC, you can use the following methods:

If you are programming using nRF Connect for VS Code, you can select several development kits for programming in the picker that appears after clicking the Flash action. See “How to flash multiple boards” under How to work with boards and devices in the nRF Connect for VS Code documentation for more information.
If you are programming using the command line, you need to program the application to each development kit using separate commands.

Programming CIS transport mode with two headsets or stereo

When using the default CIS transport mode configuration, if you want to use two headset devices or the stereo configuration, you must configure the headset location. Use the combined bitfield values, depending on which headset you want to configure:

Two headsets, left and right:

Left headset (--value 1):

nrfutil device x-write --address 0x00FF80F4 --value 1

Right headset (--value 2):

nrfutil device x-write --address 0x00FF80F4 --value 2

One stereo headset (--value 3):

nrfutil device x-write --address 0x00FF80F4 --value 3

Select the correct board when prompted with the popup. Alternatively, you can add the --serial-number parameter followed by the SEGGER serial number of the correct board at the end of the nrfutil device command. You can check the serial numbers of the connected devices with the nrfutil device list command.

Note

Make sure to check the nRF Audio application known issue OCT-2154 related to intermittent audio stream on the headset when using USB audio interface on macOS.