817 lines
15 KiB
ReStructuredText
817 lines
15 KiB
ReStructuredText
.. _nrf_auraconfig:
|
|
|
|
nRF Auraconfig
|
|
##############
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
The nRF Auraconfig sample implements the :ref:`BIS gateway mode <nrf53_audio_app_overview>` 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.
|
|
|
|
.. _nrf_auraconfig_requirements:
|
|
|
|
Requirements
|
|
************
|
|
|
|
The sample supports only and exclusively the following development kits:
|
|
|
|
.. table-from-rows:: /includes/sample_board_rows.txt
|
|
:header: heading
|
|
:rows: nrf5340_audio_dk_nrf5340
|
|
|
|
.. 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.
|
|
|
|
.. _nrf_auraconfig_ui:
|
|
|
|
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:
|
|
|
|
.. parsed-literal::
|
|
:class: highlight
|
|
|
|
nac <*arg*>
|
|
|
|
* Square brackets mean that an argument is optional:
|
|
|
|
.. parsed-literal::
|
|
:class: highlight
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac start [BIG_index]
|
|
|
|
Examples:
|
|
|
|
* The following commands starts any BIG that is configured:
|
|
|
|
.. code-block:: console
|
|
|
|
nac start
|
|
|
|
* The following command starts only the BIG 0:
|
|
|
|
.. code-block:: console
|
|
|
|
nac start 0
|
|
|
|
----
|
|
|
|
stop
|
|
====
|
|
|
|
Stop the broadcaster.
|
|
The optional argument sets the index of the BIG to stop.
|
|
|
|
Usage:
|
|
|
|
.. code-block:: console
|
|
|
|
nac stop [BIG_index]
|
|
|
|
Examples:
|
|
|
|
* The following commands stops any BIG that is running:
|
|
|
|
.. code-block:: console
|
|
|
|
nac stop
|
|
|
|
* The following command stops only the BIG 0:
|
|
|
|
.. code-block:: console
|
|
|
|
nac stop 0
|
|
|
|
----
|
|
|
|
show
|
|
====
|
|
|
|
Shows the configuration for the different BIGs that are currently configured.
|
|
|
|
Usage:
|
|
|
|
.. code-block:: console
|
|
|
|
nac show
|
|
|
|
Example output:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac file list [directory]
|
|
|
|
Example output:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac file select <file> <BIG index> <subgroup index> <BIS index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
nac file select 16000hz/24_kbps/left-channel-announcement_16kHz_left_24kbps.lc3 1 2 0
|
|
|
|
This command selects the file :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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac packing <seq/int> <BIG index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac preset <preset> <BIG index> [subgroup index]
|
|
|
|
Examples:
|
|
|
|
* The following command sets the preset for the BIG 0 to ``24_2_1``:
|
|
|
|
.. code-block:: console
|
|
|
|
nac preset 24_2_1 0
|
|
|
|
* The following command sets the preset for the subgroup 0 in the BIG 0 to ``24_2_1``:
|
|
|
|
.. code-block:: console
|
|
|
|
nac preset 24_2_1 0 0
|
|
|
|
----
|
|
|
|
lang
|
|
====
|
|
|
|
Set the language metadata for a subgroup.
|
|
|
|
Usage:
|
|
|
|
.. code-block:: console
|
|
|
|
nac lang <language> <BIG index> <Subgroup index>
|
|
|
|
The ``language`` argument is a three-letter `ISO 639-2 code`_.
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac immediate <0/1> <BIG index> <Subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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 :kconfig:option:`CONFIG_BT_BAP_BROADCAST_SRC_SUBGROUP_COUNT`.
|
|
|
|
Usage:
|
|
|
|
.. code-block:: console
|
|
|
|
nac num_subgroups <number> <BIG index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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 :kconfig:option:`CONFIG_BT_BAP_BROADCAST_SRC_STREAM_COUNT`.
|
|
|
|
Usage:
|
|
|
|
.. code-block:: console
|
|
|
|
nac num_bises <number> <BIG index> <Subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac context <context> <BIG index> <Subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac location <location> <BIG index> <Subgroup index> <BIS index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac broadcast_name <name> <BIG index>
|
|
|
|
Examples:
|
|
|
|
* The following command sets the broadcast name for the BIG 0 to ``Lecture``:
|
|
|
|
.. code-block:: console
|
|
|
|
nac broadcast_name Lecture 0
|
|
|
|
* The following command uses quotation marks for a longer name with spaces:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac encrypt <0/1> <BIG index> [broadcast_code]
|
|
|
|
Examples:
|
|
|
|
* The following command enables encryption for the BIG 0 with the broadcast code "Auratest":
|
|
|
|
.. code-block:: console
|
|
|
|
nac encrypt 1 0 Auratest
|
|
|
|
* The following command disables encryption for the BIG 0 after setting it:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac usecase <use_case>
|
|
|
|
The ``use_case`` argument can either be an index or the name of a use case.
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac clear
|
|
|
|
----
|
|
|
|
adv_name
|
|
========
|
|
|
|
Set the advertising name metadata for a BIG.
|
|
|
|
.. note::
|
|
Make sure each BIG has a unique advertising name.
|
|
|
|
Usage:
|
|
|
|
.. code-block:: console
|
|
|
|
nac adv_name <name> <BIG index>
|
|
|
|
The maximum length of the advertising name is given by :kconfig:option:`CONFIG_BT_DEVICE_NAME_MAX`.
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac program_info <info> <BIG index> <Subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac phy <phy> <BIG index> <subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac framing <unframed/framed> <BIG index> <subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac rtn <number> <BIG index> <subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac sdu <octets> <BIG index> <subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac mtl <ms> <BIG index> <subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac frame_interval <us> <BIG index> <subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac pd <us> <BIG index> <subgroup index>
|
|
|
|
Example:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac broadcast_id fixed <BIG index> <broadcast_id in hexadecimal (3 octets)>
|
|
|
|
Examples:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac broadcast_id random <BIG index>
|
|
|
|
Examples:
|
|
|
|
.. code-block:: console
|
|
|
|
nac broadcast_id random 0
|
|
|
|
This command sets a random broadcast ID for the BIG 0 each time it is started.
|
|
|
|
----
|
|
|
|
.. _nrf_auraconfig_configuration:
|
|
|
|
Configuration
|
|
*************
|
|
|
|
|config|
|
|
|
|
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 :file:`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).
|
|
|
|
.. _nrf_auraconfig_configuration_sd:
|
|
|
|
SD card setup
|
|
*************
|
|
|
|
This sample can support pre-encoded LC3 data stored as LC3 files on an SD card.
|
|
You can use the `nRF Auracast configuration files`_ provided by Nordic Semiconductor for populating the 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.
|
|
|
|
.. _nrf_auraconfig_building:
|
|
|
|
Building and running
|
|
********************
|
|
|
|
.. |sample path| replace:: :file:`samples/bluetooth/nrf_auraconfig`
|
|
|
|
.. include:: /includes/build_and_run.txt
|
|
|
|
The nRF5340 Audio DK comes pre-programmed with basic firmware that indicates if the kit is functional.
|
|
See :ref:`nrf53_audio_app_dk_testing_out_of_the_box` for more information.
|
|
|
|
.. _nrf_auraconfig_testing:
|
|
|
|
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:
|
|
|
|
1. If you are using an :ref:`SD card loaded with the pre-encoded LC3 data <nrf_auraconfig_configuration_sd>`, 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:
|
|
|
|
.. code-block:: console
|
|
|
|
nac usecase 1
|
|
|
|
#. Start the broadcaster:
|
|
|
|
.. code-block:: console
|
|
|
|
nac start
|
|
|
|
You can now send other shell commands, as listed in the :ref:`nrf_auraconfig_ui`.
|
|
|
|
Dependencies
|
|
************
|
|
|
|
For the list of dependencies, check the application's source files.
|