Broadcast Configuration Tool

The Broadcast Configuration Tool 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).

The following limitations apply to this sample:

Audio input: Pre-encoded LC3 data from an SD-card.
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 Broadcast Configuration Tool 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:
```
bct <arg>
```
Square brackets mean that an argument is optional:
```
bct [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:

bct start [BIG_index]

Examples:

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

stop 

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

Usage:

bct stop [BIG_index]

Examples:

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

show 

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

Usage:

bct 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:

bct file list [directory]

Example output:

bct 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:

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

Example:

bct 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:

bct packing <seq/int> <BIG index>

Example:

bct 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 bct preset print command.

Usage:

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

Examples:

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

lang 

Set the language metadata for a subgroup.

Usage:

bct lang <language> <BIG index> <Subgroup index>

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

Example:

bct 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:

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

Example:

bct 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:

bct num_subgroups <number> <BIG index>

Example:

bct 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:

bct num_bises <number> <BIG index> <Subgroup index>

Example:

bct 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 bct context print command.

Usage:

bct context <context> <BIG index> <Subgroup index>

Example:

bct 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 bct location print command.

Usage:

bct location <location> <BIG index> <Subgroup index> <BIS index>

Example:

bct 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:

bct broadcast_name <name> <BIG index>

Examples:

The following command sets the broadcast name for the BIG 0 to Lecture:
```
bct broadcast_name Lecture 0
```
The following command uses quotation marks for a longer name with spaces:
```
bct 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:

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

Examples:

The following command enables encryption for the BIG 0 with the broadcast code “Auratest”:
```
bct encrypt 1 0 Auratest
```
The following command disables encryption for the BIG 0 after setting it:
```
bct 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 bct usecase print command.

Usage:

bct usecase <use_case>

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

Example:

bct 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:

bct clear

adv_name 

Set the advertising name metadata for a BIG.

Note

Make sure each BIG has a unique advertising name.

Usage:

bct adv_name <name> <BIG index>

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

Example:

bct 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:

bct program_info <info> <BIG index> <Subgroup index>

Example:

bct 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:

bct phy <phy> <BIG index> <subgroup index>

Example:

bct 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:

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

Example:

bct 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:

bct rtn <number> <BIG index> <subgroup index>

Example:

bct 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:

bct sdu <octets> <BIG index> <subgroup index>

Example:

bct 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:

bct mtl <ms> <BIG index> <subgroup index>

Example:

bct 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:

bct frame_interval <us> <BIG index> <subgroup index>

Example:

bct 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:

bct pd <us> <BIG index> <subgroup index>

Example:

bct 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:

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

Examples:

bct 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:

bct broadcast_id random <BIG index>

Examples:

bct 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).

Building and running 

This sample can be found under samples/bluetooth/broadcast_config_tool 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 Broadcast Configuration Tool sample.

To test the Broadcast Configuration Tool sample, complete the following steps:

Turn on the development kit.
Set up the serial connection with the development kit.
Configure a BIG using use case 1:
```
bct usecase 1
```
Start the broadcaster:
```
bct 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.