nRF Auraconfig

The nRF Auraconfig sample implements the BIS gateway mode and may act as an Auracast™ broadcaster if you are using a preset compatible with Auracast. The sample features a shell interface that allows you to configure the broadcast source in many different ways.

In the BIS gateway mode, transmitting audio from the broadcast source happens using Broadcast Isochronous Stream (BIS) and Broadcast Isochronous Group (BIG).

Note

This sample is meant to be used with maximum two BIG with four BIS streams each.

Requirements 

The sample supports only and exclusively the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF5340 Audio DK	PCA10121 revision 1.0.0 or above	nrf5340_audio_dk	`nrf5340_audio_dk/nrf5340/cpuapp`

Note

The sample supports PCA10121 revisions 1.0.0 or above. The sample is also compatible with the following pre-launch revisions:

Revisions 0.8.0 and above.

Shell commands list 

The nRF Auraconfig uses a shell interface for all user interactions. This section lists the supported commands.

Description convention 

The command argument description uses the following convention:

Angle brackets mean that an argument is mandatory:
```
nac <arg>
```
Square brackets mean that an argument is optional:
```
nac [arg]
```

start 

Start the broadcaster with the current configuration. If no configuration is set, the broadcaster will not start.

To view the current configuration, use the show command. The optional argument sets the index of the BIG to start.

Usage:

nac start [BIG_index]

Examples:

The following commands starts any BIG that is configured:
```
nac start
```
The following command starts only the BIG 0:
```
nac start 0
```

stop 

Stop the broadcaster. The optional argument sets the index of the BIG to stop.

Usage:

nac stop [BIG_index]

Examples:

The following commands stops any BIG that is running:
```
nac stop
```
The following command stops only the BIG 0:
```
nac stop 0
```

show 

Shows the configuration for the different BIGs that are currently configured.

Usage:

nac show

Example output:

BIG 0:
    Streaming: false
    Advertising name: Lecture hall
    Broadcast name: Lecture
    Packing: interleaved
    Encryption: false
    Broadcast code:
    Subgroup 0:
            Preset: 24_2_1
                    PHY: 2M
                    Framing: unframed
                    RTN: 2
                    SDU size: 60
                    Max Transport Latency: 10 ms
                    Frame Interval: 10000 us
                    Presentation Delay: 40000 us
            Sampling rate: 24000 Hz
            Bitrate: 48000 bps
            Frame duration: 10000 us
            Octets per frame: 60
            Language: eng
            Context(s):
                    Live
            Program info: Mathematics 101
            Immediate rendering flag: set
            Number of BIS: 1
            Location:
                    BIS 0: Mono Audio

file list 

Lists the files and directories in the given directory on the SD card. If no directory is given, contents of the root directory is listed.

Usage:

nac file list [directory]

Example output:

nac file list

[DIR ]  16000hz
[DIR ]  24000hz
[DIR ]  32000hz
[FILE]  left-channel-announcement.wav
[FILE]  right-channel-announcement.wav

file select 

Selects a file from the SD card to be used as the audio source for the given stream. The file must be in the LC3 format, and one file may be used for multiple streams at the same time.

Usage:

nac file select <file> <BIG index> <subgroup index> <BIS index>

Example:

nac file select 16000hz/24_kbps/left-channel-announcement_16kHz_left_24kbps.lc3 1 2 0

This command command selects the file 16000hz/24_kbps/left-channel-announcement_16kHz_left_24kbps.lc3 for the BIS 0 in the subgroup 2 in the BIG 1.

packing 

Set the type of packing for the BIS streams, either sequential or interleaved.

Usage:

nac packing <seq/int> <BIG index>

Example:

nac packing int 0

This command sets the packing for the BIG 0 to interleaved.

preset 

Set the BAP preset for a BIG or subgroup. The presets are defined in the Basic Audio Profile specification. The supported presets can be listed with the nac preset print command.

Usage:

nac preset <preset> <BIG index> [subgroup index]

Examples:

The following command sets the preset for the BIG 0 to 24_2_1:
```
nac preset 24_2_1 0
```
The following command sets the preset for the subgroup 0 in the BIG 0 to 24_2_1:
```
nac preset 24_2_1 0 0
```

lang 

Set the language metadata for a subgroup.

Usage:

nac lang <language> <BIG index> <Subgroup index>

The language argument is a three-letter ISO 639-2 code.

Example:

nac lang eng 0 0

This command sets the language for the subgroup 0 in the BIG 0 to English.

immediate 

Set the immediate rendering flag for a subgroup.

Usage:

nac immediate <0/1> <BIG index> <Subgroup index>

Example:

nac immediate 1 0 0

This command sets the immediate rendering flag for the subgroup 0 in the BIG 0 to true.

num_subgroups 

Set the number of subgroups for a BIG. The maximum number of subgroups for each BIG is set by CONFIG_BT_BAP_BROADCAST_SRC_SUBGROUP_COUNT.

Usage:

nac num_subgroups <number> <BIG index>

Example:

nac num_subgroups 2 0

This command sets the number of subgroups for the BIG 0 to 2.

num_bises 

Set the number of BISes for a given subgroup. The maximum number of BISes for each subgroup is set by CONFIG_BT_BAP_BROADCAST_SRC_STREAM_COUNT.

Usage:

nac num_bises <number> <BIG index> <Subgroup index>

Example:

nac num_bises 2 0 0

This command sets the number of BISes for the subgroup 0 in the BIG 0 to 2.

context 

Sets the context metadata for a subgroup. The supported contexts can be listed with the nac context print command.

Usage:

nac context <context> <BIG index> <Subgroup index>

Example:

nac context Media 0 0

This command sets the context for the subgroup 0 in the BIG 0 to Media.

location 

Set the location metadata for a BIS. The supported locations can be listed with the nac location print command.

Usage:

nac location <location> <BIG index> <Subgroup index> <BIS index>

Example:

nac location fl 0 0 0

This command sets the location for the BIS 0 in the subgroup 0 in the BIG 0 to Front Left.

broadcast_name 

Set the broadcast name metadata for a BIG.

Usage:

nac broadcast_name <name> <BIG index>

Examples:

The following command sets the broadcast name for the BIG 0 to Lecture:
```
nac broadcast_name Lecture 0
```
The following command uses quotation marks for a longer name with spaces:
```
nac broadcast_name "Lecture hall" 0
```

encrypt 

Set the broadcast code by enabling or disabling encryption for a given BIG. The broadcast code is a 16-character string that is used to encrypt the broadcast, but shorter codes are also possible.

Usage:

nac encrypt <0/1> <BIG index> [broadcast_code]

Examples:

The following command enables encryption for the BIG 0 with the broadcast code “Auratest”:
```
nac encrypt 1 0 Auratest
```
The following command disables encryption for the BIG 0 after setting it:
```
nac encrypt 0 0
```

usecase 

Set a pre-defined use case. A use case is a set of configurations that are commonly used together. The command typically sets the number of subgroups, the number of BISes, the context, the location, and potentially metadata.

All pre-defined use cases can be listed with the nac usecase print command.

Usage:

nac usecase <use_case>

The use_case argument can either be an index or the name of a use case.

Example:

nac usecase 0

This command sets a unique configuration for the given use case and then calls show to display the configuration.

clear 

Clear any previous configuration.

Usage:

nac clear

adv_name 

Set the advertising name metadata for a BIG.

Note

Make sure each BIG has a unique advertising name.

Usage:

nac adv_name <name> <BIG index>

The maximum length of the advertising name is given by CONFIG_BT_DEVICE_NAME_MAX.

Example:

nac adv_name "Lecture hall" 0

This command sets the advertising name for the BIG 0 to “Lecture hall”.

Note

The name must be enclosed in quotation marks if it contains spaces.

program_info 

Set the program info metadata for a subgroup.

Usage:

nac program_info <info> <BIG index> <Subgroup index>

Example:

nac program_info "Mathematics 101" 0 0

This command sets the program info for the subgroup 0 in the BIG 0 to “Mathematics 101”.

phy 

Set the PHY for a BIG. The supported PHY values are:

1 - 1M
2 - 2M
4 - Coded

Usage:

nac phy <phy> <BIG index> <subgroup index>

Example:

nac phy 2 0 0

This command sets the PHY for the subgroup 0 in the BIG 0 to 2M.

framing 

Set the framing for a subgroup.

Usage:

nac framing <unframed/framed> <BIG index> <subgroup index>

Example:

nac framing unframed 0 0

This command sets the framing for the subgroup 0 in the BIG 0 to unframed.

rtn 

Set the number of retransmits for a subgroup.

Usage:

nac rtn <number> <BIG index> <subgroup index>

Example:

nac rtn 2 0 0

This command sets the number of retransmits for the subgroup 0 in the BIG 0 to 2.

sdu 

Set the Service Data Unit (SDU) size in octets for a subgroup.

Note

This command does not change the bitrate, only the size of the SDU.

Usage:

nac sdu <octets> <BIG index> <subgroup index>

Example:

nac sdu 60 0 0

This command sets the SDU size for the subgroup 0 in the BIG 0 to 60 octets.

mtl 

Set the maximum transport latency for a subgroup, in milliseconds.

Usage:

nac mtl <ms> <BIG index> <subgroup index>

Example:

nac mtl 10 0 0

This command sets the maximum transport latency for the subgroup 0 in the BIG 0 to 10 ms.

frame_interval 

Set the frame interval for a subgroup, in microseconds. The command supports the following values:

7500
10000

Usage:

nac frame_interval <us> <BIG index> <subgroup index>

Example:

nac frame_interval 10000 0 0

This command sets the frame interval for the subgroup 0 in the BIG 0 to 10 ms (10000 us).

pd 

Set the presentation delay for a subgroup, in microseconds.

Usage:

nac pd <us> <BIG index> <subgroup index>

Example:

nac pd 40000 0 0

This command sets the presentation delay for the subgroup 0 in BIG0 to 40 ms (40000 us).

broadcast_id fixed 

Set a fixed broadcast ID for a BIG. The broadcast ID is used to identify the broadcast. Its value is three octets long.

Usage:

nac broadcast_id fixed <BIG index> <broadcast_id in hexadecimal (3 octets)>

Examples:

nac broadcast_id fixed 0 0xAA1234

This command sets a fixed broadcast ID for the BIG 0 to 0xAA1234. This value will remain if the broadcast is stopped and started again.

broadcast_id random 

Set a random broadcast ID for a BIG. The broadcast ID is used to identify the broadcast. The broadcast ID will be generated anew every time the broadcaster is started.

Usage:

nac broadcast_id random <BIG index>

Examples:

nac broadcast_id random 0

This command sets a random broadcast ID for the BIG 0 each time it is started.

Configuration 

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

The sample is pre-configured with a generous default memory allocation, suitable for a wide range of use cases. You can modify these default settings in the prj.conf file. Using aggressive configurations can reduce air time availability for all streams, depending on the combination of options selected (like high bitrates, increased re-transmits, specific PHY settings).

SD card setup 

This sample can support pre-encoded LC3 data stored as LC3 files on an SD card. If you are not using an SD card, the system defaults to sending dummy data. The purpose of the dummy data is to test that the broadcast source has been correctly configured.

Make sure you format the SD card with a FAT file system.

Building and running 

This sample can be found under samples/bluetooth/nrf_auraconfig in the nRF Connect SDK folder structure.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

The nRF5340 Audio DK comes pre-programmed with basic firmware that indicates if the kit is functional. See Testing out of the box for more information.

Testing 

In this testing procedure, the development kit is programmed with the nRF Auraconfig sample.

To test the nRF Auraconfig sample, complete the following steps:

If you are using an SD card loaded with the pre-encoded LC3 data, insert it into your development kit.
Turn on the development kit.
Set up the serial connection with the development kit.
Configure a BIG using use case 1:
```
nac usecase 1
```
Start the broadcaster:
```
nac start
```

You can now send other shell commands, as listed in the Shell commands list.

Dependencies 

For the list of dependencies, check the application’s source files.