Configuring the nRF Audio applications

The nRF Audio applications introduce Kconfig options that you can use to configure audio functionality, device roles, and transport modes. You can use these options to select between gateway and headset roles, choose between CIS (unicast) and BIS (broadcast) transport modes, and configure audio-specific features.

The nRF Audio applications align the configuration with the nRF Audio use case by overlaying Kconfig defaults and selecting or implying the required Kconfig options. Among others, the Kconfig options for Bluetooth, Zephyr’s audio subsystems, and hardware peripherals are selected to ensure they are enabled.

The CONFIG_APP_NRF_AUDIO option is the main Kconfig option that activates all nRF Audio functionality. See the Kconfig.defaults file in the nrf_audio directory for details related to the default common configuration.

Note

Part of the default configuration is applied by modifying the default values of Kconfig options. Changing configuration in menuconfig does not automatically adjust user-configurable values to the new defaults. So, you must update those values manually. For more information, see the Stuck symbols in menuconfig and guiconfig section on the Kconfig - Tips and Best Practices in the Zephyr documentation.

The default Kconfig option values are automatically updated if configuration changes are applied directly in the configuration files.

The application-specific Kconfig options mentioned on this page are listed in nRF Audio: Application-specific Kconfig options.

See Configuring and building for information about how to permanently or temporarily change the configuration.

Configuring the device role 

The nRF Audio application supports two device roles: gateway and headset. See Gateway and headset roles for more information about these roles.

You can select gateway or headset build when Building and running nRF Audio applications.

The CONFIG_AUDIO_DEV Kconfig option defines the nRF Audio device role. The device role can be either a gateway (CONFIG_AUDIO_DEV set to 2) or a headset (CONFIG_AUDIO_DEV set to 1).

Each role automatically implies the nRF Audio modules needed for the role. For example, the gateway role automatically enables USB audio source support, while the headset role enables I2S audio output.

Configuring the transport mode 

The nRF Audio application supports two transport modes for LE Audio:

Connected Isochronous Stream (CIS) - for unicast communication
Broadcast Isochronous Stream (BIS) - for broadcast communication

See Application modes for detailed information about these modes.

The transport mode is selected using the following Kconfig options:

(Default mode) CONFIG_TRANSPORT_CIS - Enables CIS mode for clients and servers (unicast applications). With this option enabled, you can configure application Kconfig options specific to unicast communication (see applications/nrf_audio/src/bluetooth/bt_stream/unicast/Kconfig).
CONFIG_TRANSPORT_BIS - Enables BIS mode for Auracast™ sources and sinks (broadcast applications). With this option enabled, you can configure application Kconfig options specific to broadcast communication (see applications/nrf_audio/src/bluetooth/bt_stream/broadcast/Kconfig).

The transport mode selection automatically configures the appropriate Bluetooth stack components and audio processing modules.

Selecting the CIS bidirectional communication 

To switch to the bidirectional mode, set the CONFIG_STREAM_BIDIRECTIONAL Kconfig option to y in the applications/nrf_audio/prj.conf file (for the debug version) or in the applications/nrf_audio/prj_release.conf file (for the release version).

Enabling the walkie-talkie demo

The walkie-talkie demo uses one or two bidirectional streams from the gateway to one or two headsets. The PDM microphone is used as input on both the gateway and headset device. To switch to using the walkie-talkie, set the CONFIG_WALKIE_TALKIE_DEMO Kconfig option to y in the applications/nrf_audio/prj.conf file (for the debug version) or in the applications/nrf_audio/prj_release.conf file (for the release version).

Enabling the Auracast™ (broadcast) mode 

If you want to work with Auracast™ (broadcast) sources and sinks, set the CONFIG_TRANSPORT_BIS Kconfig option to y in the applications/nrf_audio/prj.conf file.

Enabling the BIS mode with two gateways 

In addition to the standard BIS mode with one gateway, you can also add a second gateway device. The BIS headsets can then switch between the two gateways and receive the audio stream from one of the two gateways.

To configure the second gateway, add both the CONFIG_TRANSPORT_BIS and the CONFIG_BT_AUDIO_USE_BROADCAST_NAME_ALT Kconfig options set to y to the applications/nrf_audio/prj.conf file for the debug version and to the applications/nrf_audio/prj_release.conf file for the release version. You can provide an alternative name to the second gateway using the CONFIG_BT_AUDIO_BROADCAST_NAME_ALT or use the default alternative name.

You build each BIS gateway separately using the normal procedures from Building and running nRF Audio applications. After building the first gateway, configure the required Kconfig options for the second gateway and build the second gateway firmware. Remember to program the two firmware versions to two separate gateway devices.

Configuring the headset location 

When using the default CIS transport mode configuration, if you want to use two headset devices or the stereo configuration, you must also define the correct headset location.

The nRF Audio applications use audio location definitions from the Audio Location Definition chapter in the Bluetooth Assigned Numbers specification. These correspond to the bitfields in the bt_audio_location enum in the zephyr/include/zephyr/bluetooth/assigned_numbers.h file. When building the audio application, the location value is used to populate the UICR with the correct bitfield for each headset.

You can set the location for each headset in the following ways, depending on the building and programming method:

When Building and programming using script, set the location for each headset in the nrf5340_audio_dk_devices.json file. Use the location labels from the Audio Location Definition chapter in the Bluetooth Assigned Numbers specification. For example:
```
[
 {
   "nrf5340_audio_dk_snr": 1000,
   "nrf5340_audio_dk_dev": "headset",
   "location": ["FRONT_LEFT"]
 }
]
```
When Building and programming using standard methods, set the location for each headset when running the programming command. Use the combined bitfield values from the zephyr/include/zephyr/bluetooth/assigned_numbers.h file to define the headset location. For example, if you want to use the stereo configuration, use the 0x3 value, which is the combined bitfield value of the left (0x01) and right (0x02) location:
```
nrfutil device x-write --address 0x00FF80F4 --value 3
```

The following table lists some of the available locations and their bitfield values:

Example audio locations and their bitfield values
Audio location	Value from specification	Bitfield value
Mono Audio	`0x00000000`	n/a
`"FRONT_LEFT"`	`0x00000001`	`0`
`"FRONT_RIGHT"`	`0x00000002`	`1`
Stereo	n/a	`3` (`0` and `1` set)

Configuring the audio source 

The nRF Audio application supports multiple audio sources for gateway devices. See USB-based firmware for gateway and I2S-based firmware for gateway and headsets for information about the firmware architecture differences.

The audio source is selected using the following Kconfig options:

USB audio source (CONFIG_AUDIO_SOURCE_USB) - Uses USB as the audio source (default for gateway)
I2S audio source (CONFIG_AUDIO_SOURCE_I2S) - Uses 3.5 mm jack analog input using I2S

In the default configuration, the gateway application uses USB as the audio source. The Building and running nRF Audio applications and testing steps also refer to using the USB serial connection.

The audio source selection affects the firmware architecture and available features. USB audio source is limited to unidirectional streams due to CPU load considerations, while I2S supports bidirectional communication.

Selecting the analog jack input using I2S 

To switch to using the 3.5 mm jack analog input, set the CONFIG_AUDIO_SOURCE_I2S Kconfig option to y in the applications/nrf_audio/prj.conf file for the debug version and in the applications/nrf_audio/prj_release.conf file for the release version.

When testing the application, an additional audio jack cable is required to use I2S. Use this cable to connect the audio source (PC) to the analog LINE IN on the development kit.

Configuring codecs 

The nRF Audio application uses both software and hardware codecs. The software codec is responsible for encoding and decoding, while the hardware codec is responsible for DAC/ADC and other audio processing. See Firmware architecture for information about how both codecs are integrated into the firmware architecture.

You can enable the software codec using the CONFIG_SW_CODEC_LC3 Kconfig option. This codec is mandatory for LE Audio.

You can enable the CS47L63 hardware codec using the CONFIG_NRF_AUDIO_CS47L63_DRIVER Kconfig option.

The codec selection affects audio quality, processing requirements, and power consumption.

Configuring audio quality 

The nRF Audio application provides extensive configuration options for audio quality. These settings affect the Synchronization module overview and overall audio performance.

See nRF Audio: Application-specific Kconfig options for the list of options to configure the following audio quality settings:

Frame duration (example: CONFIG_AUDIO_FRAME_DURATION_10_MS)
Sample rates (example: CONFIG_AUDIO_SAMPLE_RATE_16000_HZ)
Bit depth (example: CONFIG_AUDIO_BIT_DEPTH_16)
Presentation delay (example: CONFIG_AUDIO_MIN_PRES_DLY_US)

Configuring Bluetooth LE Audio 

The nRF Audio application introduces application-specific configuration options related to Bluetooth LE Audio. These options configure the Bluetooth stack components described in Firmware architecture.

See nRF Audio: Application-specific Kconfig options for options starting with CONFIG_BT_AUDIO.

Configuring power measurements 

The power measurements are disabled by default in the debug version of the application.

Note

Enabling power measurements in the debug version together with debug logging increases the power consumption compared with the release version of the application. For better results, consider using the Power Profiler Kit II (PPK2) and the Power Profiler app from nRF Connect for Desktop to measure the power consumption.

To enable power measurements in the debug version, set the CONFIG_NRF5340_AUDIO_POWER_MEASUREMENT Kconfig option to y in the applications/nrf_audio/prj.conf file.

Enabling SD card playback 

The SD Card Playback module allows you to play audio files directly from an SD card inserted into the nRF5340 Audio development kit. This feature supports both WAV and LC3 audio file formats and is compatible with all nRF Audio applications. See SD card playback module overview for detailed information about the SD card playback module.

File format support requirements 

The SD card playback module supports both WAV and LC3 audio file formats. The audio files must meet the following requirements:

WAV files must be 48 kHz, 16-bit, mono PCM format.
LC3 files must be in the LC3 file format with proper headers.

SD card requirements 

Make sure the SD card meets the following requirements:

Formatted with FAT32 or exFAT file system.
Audio files are placed in the root directory or subdirectories.

Configuring SD card playback 

To enable SD card playback functionality, you need to set the following Kconfig options to y:

CONFIG_NRF_AUDIO_SD_CARD_MODULE - to enable the SD card module; this option is enabled by default on nRF5340 Audio DK
CONFIG_SD_CARD_PLAYBACK - to enable the playback functionality

Optionally, you can also set the following Kconfig options:

Shell commands for SD card playback 

When SD card playback is enabled, the following shell commands are available:

SD card playback shell commands
Command	Description
`sd_card_playback play_wav <filename>.wav`	Play a WAV file from the SD card
`sd_card_playback play_lc3 <filename>.lc3`	Play an LC3 file from the SD card
`sd_card_playback list_files`	List files in the current directory
`sd_card_playback cd <directory>`	Change to a different directory
`sd_card_playback cd /`	Return to the root directory

To issue these commands, you can use the RTT or UART serial connection.

Example usage 

To play audio from the SD card, complete the following steps:

Configure the SD card playback module in your application as described in Configuring SD card playback.
Build and run the application.
Insert a properly formatted SD card with audio files into the development kit.
Connect to the device using the RTT or UART serial connection. For example, you can use the Serial Terminal app to connect to the device.
In the terminal:
1. Issue the following command to list files on the SD card:
```
sd_card_playback list_files
```
2. Issue the following command to play a WAV file:
```
sd_card_playback play_wav <filename>.wav
```
3. Issue the following command to play an LC3 file:
```
sd_card_playback play_lc3 <filename>.lc3
```
The audio from the SD card will be mixed with any existing audio stream and played through the device’s audio output.
To stop the playback, issue the sd_card_playback stop command.
To exit the shell, issue the exit command.

Adding FEM support 

You can add support for the nRF21540 front-end module (FEM) to the following nRF Audio applications:

The broadcast sink application does not need FEM support as it only receives data.

Adding FEM support happens when Building and running nRF Audio applications. You can use one of the following options, depending on how you decide to build the application:

If you opt for Building and programming using script, add the --nrf21540 to the script’s building command.

If you opt for Building and programming using standard methods, add the -Dnrf_audio_SHIELD=nrf21540ek -Dipc_radio_SHIELD=nrf21540ek to the west build command. For example:

west build -b nrf5340_audio_dk/nrf5340/cpuapp --pristine -- -DEXTRA_CONF_FILE=".\unicast_server\overlay-unicast_server.conf" -Dnrf_audio_SHIELD=nrf21540ek -Dipc_radio_SHIELD=nrf21540ek

To set the TX power output, use the CONFIG_BT_CTLR_TX_PWR_ANTENNA and CONFIG_MPSL_FEM_NRF21540_TX_GAIN_DB Kconfig options in applications/nrf_audio/sysbuild/ipc_radio/prj.conf.

See Developing with Front-End Modules for more information about FEM in the nRF Connect SDK.