auracaster/nrf5340_audio
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit for nrf5340_audio

Browse Source
This commit is contained in:
pstruebi
2025-06-30 09:28:01 +02:00
commit 62dbb94724
174 changed files with 27001 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/adapting_application.rst
+82
View File
@@ -0,0 +1,82 @@
.. _nrf53_audio_app_adapting:
Adapting nRF5340 Audio applications for end products
####################################################
.. contents::
:local:
:depth: 2
This page describes the relevant configuration sources and lists the steps required for adapting the :ref:`nrf53_audio_app` to end products.
Board configuration sources
***************************
The nRF5340 Audio applications use the following files as board configuration sources:
* Devicetree Specification (DTS) files - These reflect the hardware configuration.
See :ref:`zephyr:dt-guide` for more information about the DTS data structure.
* Kconfig files - These reflect the hardware-related software configuration.
See :ref:`kconfig_tips_and_tricks` for information about how to configure them.
* Memory layout configuration files - These define the memory layout of the application.
You can see the :file:`zephyr/boards/nordic/nrf5340_audio_dk` directory as an example of how these files are structured.
For information about differences between DTS and Kconfig, see :ref:`zephyr:dt_vs_kconfig`.
For detailed instructions for adding Zephyr support to a custom board, see Zephyr's :ref:`zephyr:board_porting_guide`.
.. _nrf53_audio_app_porting_guide_app_configuration:
Application configuration sources
*********************************
The application configuration source file defines a set of options used by the given nRF5340 Audio application.
This is a :file:`.conf` file that modifies the default Kconfig values defined in the Kconfig files.
Only one :file:`.conf` file is included at a time.
The :file:`prj.conf` file is the default configuration file and it implements the debug application version.
For the release application version, you need to include the :file:`prj_release.conf` configuration file.
In the release application version no debug features should be enabled.
Each nRF5340 Audio application also uses its own :file:`Kconfig.default` file to change configuration defaults automatically.
You need to edit :file:`prj.conf` and :file:`prj_release.conf` if you want to add new functionalities to your application, but editing these files when adding a new board is not required.
.. _nrf53_audio_app_porting_guide_adding_board:
Adding a new board
******************
.. note::
The first three steps of the configuration procedure are identical to the steps described in Zephyr's :ref:`zephyr:board_porting_guide`.
To use the nRF5340 Audio application with your custom board:
1. Define the board files for your custom board:
a. Create a new directory in the :file:`nrf/boards/<vendor>/` directory with the name of the new board.
#. Copy the nRF5340 Audio board files from the :file:`nrf5340_audio_dk` directory located in the :file:`zephyr/boards/nordic/` folder to the newly created directory.
#. Edit the DTS files to make sure they match the hardware configuration.
Pay attention to the following elements:
* Pins that are used.
* Interrupt priority that might be different.
#. Edit the board's Kconfig files to make sure they match the required system configuration.
For example, disable the drivers that will not be used by your device.
#. Build the application by selecting the name of the new board (for example, ``new_audio_board_name``) in your build system.
For example, when building from the command line, add ``-b new_audio_board_name`` to your build command.
FOTA for end products
*********************
Do not use the default MCUboot key for end products.
See :ref:`ug_fw_update` and :ref:`west-sign` for more information.
To create your own app that supports DFU, you can use the `nRF Connect Device Manager`_ libraries for Android and iOS.
Changing default values
***********************
Given the requirements for the Coordinated Set Identification Service (CSIS), make sure to change the Set Identity Resolving Key (SIRK) value when adapting the application.
doc/building.rst
+327
View File
@@ -0,0 +1,327 @@
.. _nrf53_audio_app_building:
Building and running nRF5340 Audio applications
###############################################
.. contents::
:local:
:depth: 2
This nRF5340 Audio application source files can be found in their respective folders under :file:`applications/nrf5340_audio` in the nRF Connect SDK folder structure.
You can build and program the applications in one of the following ways:
* :ref:`nrf53_audio_app_building_script` - This is the suggested method.
Using this method allows you to build and program multiple development kits at the same time.
* :ref:`nrf53_audio_app_building_standard` - Using this method requires building and programming each development kit separately.
.. important::
Building and programming using the |nRFVSC| is currently not supported.
.. note::
You might want to check the :ref:`nRF5340 Audio application known issues <known_issues_nrf5340audio>` before building and programming the applications.
.. _nrf53_audio_app_dk_testing_out_of_the_box:
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:
1. 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.
.. _nrf53_audio_app_building_script:
Building and programming using script
*************************************
The suggested method for building each of the applications and programming it to the development kit is running the :file:`buildprog.py` Python script.
The script automates the process of selecting :ref:`configuration files <nrf53_audio_app_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 :file:`applications/nrf5340_audio/tools/buildprog` directory.
.. note::
The :file:`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 :file:`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:
.. literalinclude:: ../tools/buildprog/nrf5340_audio_dk_devices.json
:language: json
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``.
* ``channel`` - This field is valid only for headsets.
It sets the channels on which the headset is meant to work.
When no channel is set, the headset is programmed as a left channel one.
.. _nrf53_audio_app_building_script_running:
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 :file:`nrf5340_audio_dk_devices.json` file, run :file:`buildprog.py` to build the firmware for the development kits.
The building command for running the script requires providing the following parameters:
.. list-table:: Parameters for the script
:header-rows: 1
* - Parameter
- Description
- Options
- More information
* - Core type (``-c``)
- Specifies the core type.
- ``app``, ``net``, ``both``
- :ref:`nrf53_audio_app_overview_architecture`
* - Application version (``-b``)
- Specifies the application version.
- ``release``, ``debug``
- | :ref:`nrf53_audio_app_configuration_files`
| **Note:** For FOTA DFU, you must use :ref:`nrf53_audio_app_building_standard`.
* - Transport type (``-t``)
- Specifies the transport type.
- ``broadcast``, ``unicast``
- :ref:`nrf53_audio_app_overview_architecture`
* - Device type (``-d``)
- Specifies the device type.
- ``headset``, ``gateway``, ``both``
- :ref:`nrf53_audio_app_overview_gateway_headsets`
For example, the following command builds headset and gateway applications using the script for the application core with the ``debug`` application version:
.. code-block:: console
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 :file:`buildprog.py` is given.
The build files are saved in separate subdirectories in the :file:`applications/nrf5340_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 :file:`unicast/gateway/app/debug`, :file:`unicast/gateway/net/debug`, :file:`unicast/headset/app/debug`, :file:`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:
.. code-block:: console
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 :ref:`readback protection error <readback_protection_error>`, run :file:`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:
.. code-block:: console
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:
.. code-block:: console
+------------+----------+---------+--------------+---------------------+---------------------+
| 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 :file:`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. |
| | +-------------------------------------------------+
| | | ``False`` - Not connected. |
+-----------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------------------+
| ``device`` | Device type, as provided in the :file:`nrf5340_audio_dk_devices.json` file. | ``headset`` - Headset. |
| | +-------------------------------------------------+
| | | ``gateway`` - Gateway. |
+-----------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------------------+
| ``only reboot`` | Whether the device is to be only reset and not programmed. | ``Not selected`` - No reset. |
| | This depends on the ``-r`` parameter in the command, which overrides other parameters. +-------------------------------------------------+
| | | ``Selected TBD`` - Only reset requested. |
| | +-------------------------------------------------+
| | | ``Done`` - Reset done. |
| | +-------------------------------------------------+
| | | ``Failed`` - Reset failed. |
+-----------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------------------+
|``core app programmed``| Whether the application core is to be programmed. | ``Not selected`` - Core will not be programmed. |
| | This depends on the value provided to the ``-c`` parameter (see above). +-------------------------------------------------+
| | | ``Selected TBD`` - Programming requested. |
| | +-------------------------------------------------+
| | | ``Done`` - Programming done. |
| | +-------------------------------------------------+
| | | ``Failed`` - Programming failed. |
+-----------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------------------+
|``core net programmed``| Whether the network core is to be programmed. | ``Not selected`` - Core will not be programmed. |
| | This depends on the value provided to the ``-c`` parameter (see above). +-------------------------------------------------+
| | | ``Selected TBD`` - Programming requested. |
| | +-------------------------------------------------+
| | | ``Done`` - Programming done. |
| | +-------------------------------------------------+
| | | ``Failed`` - Programming failed. |
+-----------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------------------+
.. _nrf53_audio_app_building_standard:
Building and programming using command line
*******************************************
You can also build the nRF5340 Audio applications using the standard |NCS| :ref:`build steps <programming_cmd>` for the command line.
.. _nrf53_audio_app_building_config_files:
Application configuration files
===============================
The application uses a :file:`prj.conf` configuration file located in the sample root directory for the default configuration.
It also provides additional files for different custom configurations.
When you build the sample, you can select one of these configurations using the :makevar:`FILE_SUFFIX` variable.
See :ref:`app_build_file_suffixes` and :ref:`cmake_options` for more information.
The application supports the following custom configurations:
.. list-table:: Application custom configurations
:widths: auto
:header-rows: 1
* - Configuration
- File name
- FILE_SUFFIX
- Description
* - Debug (default)
- :file:`prj.conf`
- No suffix
- Debug version of the application. Provides full logging capabilities and debug optimizations to ease development.
* - Release
- :file:`prj_release.conf`
- ``release``
- Release version of the application. Disables logging capabilities and disables development features to create a smaller application binary.
* - FOTA DFU
- :file:`prj_fota.conf`
- ``fota``
- | Builds the debug version of the application with the features needed to perform DFU over Bluetooth LE, and includes bootloaders so that the applications on both the application core and network core can be updated.
| See :ref:`nrf53_audio_app_fota` for more information.
.. _nrf53_audio_app_configuration_select_build:
Building the application
========================
Complete the following steps to build the application:
1. Choose the combination of build flags:
a. Choose the device type by using one of the following :ref:`CMake options for extra Kconfig fragments <cmake_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"``
#. Choose the application version (:ref:`nrf53_audio_app_building_config_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 :ref:`build steps <building>` 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 :file:`applications/nrf5340_audio/` directory:
.. code-block:: console
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 for headset device directly in the :file:`build` directory.
What this means is that you cannot create build files for all devices you want to program, because the subsequent commands will overwrite the files in the :file:`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 headset and gateway to separate directories before programming the development kits.
Alternatively, you can use the :ref:`nrf53_audio_app_building_script`, which handles this automatically.
Building the application for FOTA
---------------------------------
The following command example builds the application for :ref:`nrf53_audio_app_fota`:
.. code-block:: console
west build -b nrf5340_audio_dk/nrf5340/cpuapp --pristine -- -DEXTRA_CONF_FILE=".\unicast_server\overlay-unicast_server.conf" -DFILE_SUFFIX=fota
The command uses ``-DFILE_SUFFIX=fota`` to pick :file:`prj_fota.conf` instead of the default :file:`prj.conf`.
It also uses the ``--pristine`` to clean the existing directory before starting the build process.
Programming the application
===========================
After building the files for the development kit you want to program, follow the :ref:`standard procedure for programming applications <building>` in the |NCS|.
When using the default CIS configuration, if you want to use two headset devices, you must also populate the UICR with the desired channel for each headset.
Use the following commands, depending on which headset you want to populate:
* Left headset (``--value 0``):
.. code-block:: console
nrfutil device x-write --address 0x00FF80F4 --value 0
* Right headset (``--value 1``):
.. code-block:: console
nrfutil device x-write --address 0x00FF80F4 --value 1
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::
|usb_known_issues|
doc/configuration.rst
+87
View File
@@ -0,0 +1,87 @@
.. _nrf53_audio_app_configuration:
Configuring the nRF5340 Audio applications
##########################################
.. contents::
:local:
:depth: 2
|config|
.. _nrf53_audio_app_configuration_select_bidirectional:
Selecting the CIS bidirectional communication
*********************************************
To switch to the bidirectional mode, set the ``CONFIG_STREAM_BIDIRECTIONAL`` Kconfig option to ``y`` in the :file:`applications/nrf5340_audio/prj.conf` file (for the debug version) or in the :file:`applications/nrf5340_audio/prj_release.conf` file (for the release version).
.. _nrf53_audio_app_configuration_enable_walkie_talkie:
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 :file:`applications/nrf5340_audio/prj.conf` file (for the debug version) or in the :file:`applications/nrf5340_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 :kconfig:option:`CONFIG_TRANSPORT_BIS` Kconfig option to ``y`` in the :file:`applications/nrf5340_audio/prj.conf` file.
.. _nrf53_audio_app_configuration_select_bis_two_gateways:
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 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 :file:`applications/nrf5340_audio/prj.conf` file for the debug version and to the :file:`applications/nrf5340_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 :ref:`nrf53_audio_app_building`.
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.
.. _nrf53_audio_app_configuration_select_i2s:
Selecting the analog jack input using I2S
*****************************************
In the default configuration, the gateway application uses USB as the audio source.
The :ref:`nrf53_audio_app_building` and the testing steps also refer to using the USB serial connection.
To switch to using the 3.5 mm jack analog input, set the ``CONFIG_AUDIO_SOURCE_I2S`` Kconfig option to ``y`` in the :file:`applications/nrf5340_audio/prj.conf` file for the debug version and in the :file:`applications/nrf5340_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.
.. _nrf53_audio_app_adding_FEM_support:
Adding FEM support
******************
You can add support for the nRF21540 front-end module (FEM) to the following nRF5340 Audio applications:
* :ref:`Broadcast source <nrf53_audio_broadcast_source_app>`
* :ref:`Unicast client <nrf53_audio_unicast_client_app>`
* :ref:`Unicast server <nrf53_audio_unicast_server_app>`
The :ref:`broadcast sink application <nrf53_audio_broadcast_sink_app>` does not need FEM support as it only receives data.
Adding FEM support happens when :ref:`nrf53_audio_app_building`.
You can use one of the following options, depending on how you decide to build the application:
* If you opt for :ref:`nrf53_audio_app_building_script`, add the ``--nrf21540`` to the script's building command.
* If you opt for :ref:`nrf53_audio_app_building_standard`, add the ``-Dnrf5340_audio_SHIELD=nrf21540ek -Dipc_radio_SHIELD=nrf21540ek`` to the ``west build`` command.
For example:
.. code-block:: console
west build -b nrf5340_audio_dk/nrf5340/cpuapp --pristine -- -DEXTRA_CONF_FILE=".\unicast_server\overlay-unicast_server.conf" -Dnrf5340_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 :file:`applications/nrf5340_audio/sysbuild/ipc_radio/prj.conf`.
See :ref:`ug_radio_fem` for more information about FEM in the |NCS|.
doc/feature_support.rst
+44
View File
@@ -0,0 +1,44 @@
.. _nrf53_audio_app_dk_legal:
.. _nrf53_audio_feature_support:
nRF5340 Audio feature support and QDIDs
#######################################
.. contents::
:local:
:depth: 2
The following table lists features of the nRF5340 Audio application and their respective limitations and maturity level.
For an explanation of the maturity levels, see :ref:`Software maturity levels <software_maturity>`.
.. note::
Features not listed are not supported.
.. include:: /releases_and_maturity/software_maturity.rst
:start-after: software_maturity_application_nrf5340audio_table:
:end-before: software_maturity_protocol
.. _nrf5340_audio_dns_and_qdids:
nRF5340 Audio DNs and QDIDs
***************************
The following DNs (Design Numbers) and QDIDs (Qualified Design IDs) are related to the nRF5340 LE Audio applications:
nRF5340 DK Bluetooth DNs/QDIDs
See `nRF5340 DK Bluetooth DNs and QDIDs Compatibility Matrix`_ for the DNs/QDIDs for nRF5340 LE Audio applications.
A full Audio product DN will typically require DNs/QDIDs for Controller component, Host component, Profiles and Services component and LC3 codec component.
The exact DN/QDID numbers depend on the project configuration and the features used in the application.
.. note::
* The DNs/QDIDs listed in the Compatibility Matrix might not cover all use cases or combinations.
The full details of what is supported by a DN/QDID can be found in the associated ICS (Implementation Conformance Statement).
* The Audio applications do not demonstrate the full capabilities of the underlying DNs/QDIDs.
At the same time, the Audio applications may demonstrate features not available in the underlying DNs/QDID.
.. ncs-include:: lc3/README.rst
:docset: nrfxlib
:start-after: lc3_qdid_start
:end-before: lc3_qdid_end
doc/firmware_architecture.rst
+290
View File
@@ -0,0 +1,290 @@
.. _nrf53_audio_app_overview:
nRF5340 Audio overview and firmware architecture
################################################
.. contents::
:local:
:depth: 2
Each nRF5340 Audio application corresponds to one specific LE Audio role: unicast client (gateway), unicast server (headset), broadcast source (gateway), or broadcast sink (headset).
Likewise, each nRF5340 Audio application is configured for one specific LE Audio mode: the *connected isochronous stream* (CIS, unicast) mode or in the *broadcast isochronous stream* (BIS) mode.
See :ref:`nrf53_audio_app_overview_modes` for more information.
The applications use the same code base, but use different :file:`main.c` files and include different modules and libraries depending on the configuration.
You might need to configure and program two applications for testing the interoperability, depending on your use case.
See the testing steps for each of the application for more information.
.. _nrf53_audio_app_overview_gateway_headsets:
Gateway and headset roles
*************************
The gateway is a common term for a base device, such as the unicast client or an `Auracast™`_ (broadcast) source, often used with USB or analog jack input.
Often, but not always, the gateway is the largest or most stationary device, and is commonly the Bluetooth Central (if applicable).
The headset is a common term for a receiver device that plays back the audio it gets from the gateway.
Headset devices include earbuds, headphones, speakers, hearing aids, or similar.
They act as a unicast server or a broadcast sink.
With reference to the gateway, the headset is often the smallest and most portable device, and is commonly the Bluetooth Peripheral (if applicable).
You can :ref:`select gateway or headset build <nrf53_audio_app_configuration_select_build>` when :ref:`nrf53_audio_app_configuration`.
.. _nrf53_audio_app_overview_modes:
Application modes
*****************
Each application works either in the *connected isochronous stream* (CIS) mode or in the *broadcast isochronous stream* (BIS) mode.
.. figure:: /images/nrf5340_audio_application_topologies.png
:alt: CIS and BIS mode overview
CIS and BIS mode overview
Connected Isochronous Stream (CIS)
CIS is a bidirectional communication protocol that allows for sending separate connected audio streams from a source device to one or more receivers.
The gateway can send the audio data using both the left and the right ISO channels at the same time, allowing for stereophonic sound reproduction with synchronized playback.
This is the mode available for the unicast applications (:ref:`unicast client<nrf53_audio_unicast_client_app>` and :ref:`unicast server<nrf53_audio_unicast_server_app>`).
In this mode, you can use the nRF5340 Audio development kit in the role of the gateway, the left headset, or the right headset.
In the current version of the nRF5340 Audio unicast client, the application offers both unidirectional and bidirectional communication.
In the bidirectional communication, the headset device will send audio from the on-board PDM microphone.
See :ref:`nrf53_audio_app_configuration_select_bidirectional` in the application description for more information.
You can also enable a walkie-talkie demonstration.
In this demonstration, the gateway device will send audio from the on-board PDM microphone instead of using USB or the line-in.
See :ref:`nrf53_audio_app_configuration_enable_walkie_talkie` in the application description for more information.
Broadcast Isochronous Stream (BIS)
BIS is a unidirectional communication protocol that allows for broadcasting one or more audio streams from a source device to an unlimited number of receivers that are not connected to the source.
This is the mode available for the broadcast applications (:ref:`broadcast source<nrf53_audio_broadcast_source_app>` for gateway and :ref:`broadcast sink<nrf53_audio_broadcast_sink_app>` for headset).
In this mode, you can use the nRF5340 Audio development kit in the role of the gateway or as one of the headsets.
Use multiple nRF5340 Audio development kits to test BIS having multiple receiving headsets.
.. note::
In the BIS mode, you can use any number of nRF5340 Audio development kits as receivers.
The audio quality for both modes does not change, although the processing time for stereo can be longer.
.. _nrf53_audio_app_overview_architecture:
Firmware architecture
*********************
The following figure illustrates the high-level software layout for the nRF5340 Audio application:
.. figure:: /images/nrf5340_audio_structure_generic.svg
:alt: nRF5340 Audio high-level design (overview)
nRF5340 Audio high-level design (overview)
The network core of the nRF5340 SoC runs the SoftDevice Controller, which is responsible for receiving the audio stream data from hardware layers and forwarding the data to the Bluetooth LE host on the application core.
The controller implements the lower layers of the Bluetooth Low Energy software stack.
See :ref:`ug_ble_controller_softdevice` for more information about the controller, and :ref:`SoftDevice Controller for LE Isochronous Channels <nrfxlib:softdevice_controller_iso>` for information on how it implements ISO channels used by the nRF5340 Audio applications.
The application core runs both the Bluetooth LE Host from Zephyr and the application layer.
The application layer is composed of a series of modules from different sources.
These modules include the following major ones:
* Peripheral modules from the |NCS|:
* I2S
* USB
* SPI
* TWI/I2C
* UART (debug)
* Timer
* LC3 encoder/decoder
* Application-specific Bluetooth modules for handling the Bluetooth connection:
* Management - This module handles scanning and advertising, in addition to general initialization, controller configuration, and transfer of DFU images.
* Stream - This module handles the setup and transfer of audio in the Bluetooth LE Audio context.
It includes submodules for CIS (unicast) and BIS (broadcast).
* Renderer - This module handles rendering, such as volume up and down.
* Content Control - This module handles content control, such as play and pause.
* Application-specific custom modules, including the synchronization module (part of `I2S-based firmware for gateway and headsets`_) - See `Synchronization module overview`_ for more information.
Since the application architecture is the same for all applications and the code before compilation is shared to a significant degree, the set of modules in use depends on the chosen audio inputs and outputs (USB or analog jack).
.. note::
In the current versions of the applications, the bootloader is disabled by default.
Device Firmware Update (DFU) can only be enabled when :ref:`nrf53_audio_app_building_script`.
See :ref:`nrf53_audio_app_configuration_configure_fota` for details.
.. _nrf53_audio_app_overview_files:
Source file architecture
========================
The following figure illustrates the software layout for the nRF5340 Audio application on the file-by-file level, regardless of the application chosen:
.. figure:: /images/nrf5340audio_all_packages.svg
:alt: nRF5340 Audio application file-level breakdown
nRF5340 Audio application file-level breakdown
Communication between modules is primarily done through Zephyr's :ref:`zephyr:zbus` to make sure that there are as few dependencies as possible. Each of the buses used by the applications has their message structures described in :file:`zbus_common.h`.
.. _nrf53_audio_app_overview_architecture_usb:
USB-based firmware for gateway
==============================
The following figures show an overview of the modules currently included in the firmware of applications that use USB.
In this firmware design, no synchronization module is used after decoding the incoming frames or before encoding the outgoing ones.
The Bluetooth LE RX FIFO is mainly used to make decoding run in a separate thread.
Broadcast source USB-based firmware
-----------------------------------
.. figure:: /images/nrf5340_audio_broadcast_source_USB_structure.svg
:alt: nRF5340 Audio modules for the broadcast source using USB
nRF5340 Audio modules for the broadcast source using USB
Unicast client USB-based firmware
---------------------------------
.. figure:: /images/nrf5340_audio_unicast_client_USB_structure.svg
:alt: nRF5340 Audio modules for the unicast client using USB
nRF5340 Audio modules for the unicast client using USB
.. _nrf53_audio_app_overview_architecture_i2s:
I2S-based firmware for gateway and headsets
===========================================
The following figure shows an overview of the modules currently included in the firmware of applications that use I2S.
The Bluetooth LE RX FIFO is mainly used to make :file:`audio_datapath.c` (synchronization module) run in a separate thread.
Broadcast source I2S-based firmware
-----------------------------------
.. figure:: /images/nrf5340_audio_broadcast_source_I2S_structure.svg
:alt: nRF5340 Audio modules for the broadcast source using I2S
nRF5340 Audio modules for the broadcast source using I2S
Broadcast sink I2S-based firmware
---------------------------------
.. figure:: /images/nrf5340_audio_broadcast_sink_I2S_structure.svg
:alt: nRF5340 Audio modules for the broadcast sink using I2S
nRF5340 Audio modules for the broadcast sink using I2S
Unicast client I2S-based firmware
---------------------------------
.. figure:: /images/nrf5340_audio_unicast_client_I2S_structure.svg
:alt: nRF5340 Audio modules for the unicast client using I2S
nRF5340 Audio modules for the unicast client using I2S
Unicast server I2S-based firmware
---------------------------------
.. figure:: /images/nrf5340_audio_unicast_server_I2S_structure.svg
:alt: nRF5340 Audio modules for the unicast server using I2S
nRF5340 Audio modules for the unicast server using I2S
.. _nrf53_audio_app_overview_architecture_sync_module:
Synchronization module overview
===============================
The synchronization module (:file:`audio_datapath.c`) handles audio synchronization.
To synchronize the audio, it executes the following types of adjustments:
* Presentation compensation
* Drift compensation
The presentation compensation makes all the headsets play audio at the same time, even if the packets containing the audio frames are not received at the same time on the different headsets.
In practice, it moves the audio data blocks in the FIFO forward or backward a few blocks, adding blocks of *silence* when needed.
The drift compensation adjusts the frequency of the audio clock to adjust the speed at which the audio is played.
This is required in the CIS mode, where the gateway and headsets must keep the audio playback synchronized to provide True Wireless Stereo (TWS) audio playback.
As such, it provides both larger adjustments at the start and then continuous small adjustments to the audio synchronization.
This compensation method counters any drift caused by the differences in the frequencies of the quartz crystal oscillators used in the development kits.
Development kits use quartz crystal oscillators to generate a stable clock frequency.
However, the frequency of these crystals always slightly differs.
The drift compensation makes the inter-IC sound (I2S) interface on the headsets run as fast as the Bluetooth packets reception.
This prevents I2S overruns or underruns, both in the CIS mode and the BIS mode.
See the following figure for an overview of the synchronization module.
.. figure:: /images/nrf5340_audio_structure_sync_module.svg
:alt: nRF5340 Audio synchronization module overview
nRF5340 Audio synchronization module overview
Both synchronization methods use the SDU reference timestamps (:c:type:`sdu_ref`) as the reference variable.
If the device is a gateway that is :ref:`using I2S as audio source <nrf53_audio_app_overview_architecture_i2s>` and the stream is unidirectional (gateway to headsets), :c:type:`sdu_ref` is continuously being extracted from the LE Audio Controller Subsystem for nRF53 on the gateway.
The extraction happens inside the :file:`unicast_client.c` and :file:`broadcast_source.c` files' send function.
The :c:type:`sdu_ref` values are then sent to the gateway's synchronization module, and used to do drift compensation.
.. note::
Inside the synchronization module (:file:`audio_datapath.c`), all time-related variables end with ``_us`` (for microseconds).
This means that :c:type:`sdu_ref` becomes :c:type:`sdu_ref_us` inside the module.
As the nRF5340 is a dual-core SoC, and both cores need the same concept of time, each core runs a free-running timer in an infinite loop.
These two timers are reset at the same time, and they run from the same clock source.
This means that they should always show the same values for the same points in time.
The network core of the nRF5340 running the LE controller for nRF53 uses its timer to generate the :c:type:`sdu_ref` timestamp for every audio packet received.
The application core running the nRF5340 Audio application uses its timer to generate :c:type:`cur_time` and :c:type:`frame_start_ts`.
After the decoding takes place, the audio data is divided into smaller blocks and added to a FIFO.
These blocks are then continuously being fed to I2S, block by block.
See the following figure for the details of the compensation methods of the synchronization module.
.. figure:: /images/nrf5340_audio_sync_module_states.svg
:alt: nRF5340 Audio's state machine for compensation mechanisms
nRF5340 Audio's state machine for compensation mechanisms
The following external factors can affect the presentation compensation:
* The drift compensation must be synchronized to the locked state (:c:enumerator:`DRIFT_STATE_LOCKED`) before the presentation compensation can start.
This drift compensation adjusts the frequency of the audio clock, indicating that the audio is being played at the right speed.
When the drift compensation is not in the locked state, the presentation compensation does not leave the init state (:c:enumerator:`PRES_STATE_INIT`).
Also, if the drift compensation loses synchronization, moving out of :c:enumerator:`DRIFT_STATE_LOCKED`, the presentation compensation moves back to :c:enumerator:`PRES_STATE_INIT`.
* When audio is being played, it is expected that a new audio frame is received in each ISO connection interval.
If this does not occur, the headset might have lost its connection with the gateway.
When the connection is restored, the application receives a :c:type:`sdu_ref` not consecutive with the previously received :c:type:`sdu_ref`.
Then the presentation compensation is put into :c:enumerator:`PRES_STATE_WAIT` to ensure that the audio is still in sync.
.. note::
When both the drift and presentation compensation are in state *locked* (:c:enumerator:`DRIFT_STATE_LOCKED` and :c:enumerator:`PRES_STATE_LOCKED`), **LED2** lights up.
Synchronization module flow
---------------------------
The received audio data in the I2S-based firmware devices follows the following path:
1. The SoftDevice Controller running on the network core receives the compressed audio data.
#. The controller, running in the :zephyr:code-sample:`bluetooth_hci_ipc` sample on the nRF5340 SoC network core, sends the audio data to the Zephyr Bluetooth LE host running on the nRF5340 SoC application core.
#. The host sends the data to the stream control module.
#. The data is sent to a FIFO buffer.
#. The data is sent from the FIFO buffer to the :file:`audio_datapath.c` synchronization module.
The :file:`audio_datapath.c` module performs the audio synchronization based on the SDU reference timestamps.
Each package sent from the gateway gets a unique SDU reference timestamp.
These timestamps are generated on the headset Bluetooth LE controller (in the network core).
This enables the creation of True Wireless Stereo (TWS) earbuds where the audio is synchronized in the CIS mode.
It does also keep the speed of the inter-IC sound (I2S) interface synchronized with the sending and receiving speed of Bluetooth packets.
#. The :file:`audio_datapath.c` module sends the compressed audio data to the LC3 audio decoder for decoding.
#. The audio decoder decodes the data and sends the uncompressed audio data (PCM) back to the :file:`audio_datapath.c` module.
#. The :file:`audio_datapath.c` module continuously feeds the uncompressed audio data to the hardware codec.
#. The hardware codec receives the uncompressed audio data over the inter-IC sound (I2S) interface and performs the digital-to-analog (DAC) conversion to an analog audio signal.
doc/fota.rst
+84
View File
@@ -0,0 +1,84 @@
.. _nrf53_audio_app_fota:
Configuring and testing FOTA upgrades for nRF5340 Audio applications
####################################################################
.. contents::
:local:
:depth: 2
The nRF5340 Audio applications all support FOTA upgrades, and the application implementation is based on the procedure described in :ref:`ug_nrf53_developing_ble_fota`.
Requirements for FOTA
*********************
If the application is running on the nRF5340 Audio DK, you need an external flash shield to upgrade both the application and network core at the same time.
See `Requirements for external flash memory DFU`_ in the nRF5340 Audio DK Hardware documentation for more information.
.. _nrf53_audio_app_configuration_configure_fota:
Configuring FOTA upgrades
*************************
The nRF5340 Audio applications can be built with a :ref:`FOTA configuration <nrf53_audio_app_building_config_files>` that includes the required features and applications to perform firmware upgrades over Bluetooth LE.
The FOTA configuration requires that an external flash be available and that the required DTS overlay files use the external flash shield specified in the `Requirements for FOTA`_ above.
With the external flash connected, it is possible to upgrade both the application core and the network core at the same time.
See :ref:`multi-image DFU <ug_nrf5340_multi_image_dfu>` for more information about the FOTA process on the nRF5340 SoC.
.. caution::
Using the single-image upgrade strategy carries risk of the device being in a state where the application core firmware and the network core firmware are no longer compatible, which can result in a bricked device.
For devices where FOTA is the only DFU method available, multi-image upgrades are recommended to ensure compatibility between the cores.
Make sure to evaluate the risks for your device when selecting the FOTA method.
.. caution::
The application is provided with a memory partition configuration in :file:`pm_static_fota.yml`, which is required to perform FOTA using an external flash.
The partition configuration is an example that can be changed between versions, and can be incompatible with existing devices.
For this reason, always create a partition configuration that suits your application.
See :ref:`partition_manager` for more information on how to create a partition configuration.
Updating the SoftDevice
=======================
Both FOTA upgrade methods support updating the SoftDevice on the network core.
However, the current default build options for the SoftDevice create a binary that is too large to run on the network core together with a bootloader.
To reduce the size of the SoftDevice binary, you can disable unused features in the SoftDevice.
See :ref:`softdevice_controller` documentation for more information.
Entering the DFU mode
=====================
The |NCS| uses :ref:`SMP server and mcumgr <zephyr:device_mgmt>` as the DFU backend.
The SMP server service is separated from CIS and BIS services, and is only advertised when the application is in the DFU mode.
To enter the DFU mode, press **BTN 4** on the nRF5340 Audio DK during startup.
To identify the devices before the DFU takes place, the DFU mode advertising names mention the device type directly.
The names follow the pattern in which the device role is inserted between the device name and the ``_DFU`` suffix.
For example:
* Gateway: ``NRF5340_AUDIO_GW_DFU``
* Left Headset: ``NRF5340_AUDIO_HL_DFU``
* Right Headset: ``NRF5340_AUDIO_HR_DFU``
The first part of these names is based on :kconfig:option:`CONFIG_BT_DEVICE_NAME`.
.. note::
When performing DFU for the nRF5340 Audio applications, there will be one or more error prints related to opening flash area ID 1.
This is due to restrictions in the DFU system, and the error print is expected.
The DFU process should still complete successfully.
Building the FOTA configuration
*******************************
Use the :ref:`nrf53_audio_app_building_standard` procedure to build the nRF5340 Audio applications with the FOTA configuration.
Make sure to provide the :ref:`correct configuration file <nrf53_audio_app_building_config_files>` :file:`prj_fota.conf` when running the build command.
The :ref:`script-based method <nrf53_audio_app_building_script_running>` does not support building and programming the FOTA upgrades.
.. _nrf53_audio_unicast_client_app_testing_steps_fota:
Testing FOTA upgrades
*********************
To test FOTA for the nRF5340 Audio application, ensure the application is in the DFU mode, and then follow the testing steps in the FOTA over Bluetooth Low Energy section of :ref:`ug_nrf53_developing_ble_fota` (you can skip the configuration steps).
doc/requirements.rst
+67
View File
@@ -0,0 +1,67 @@
.. _nrf53_audio_app_requirements:
nRF5340 Audio application requirements
######################################
.. contents::
:local:
:depth: 2
The nRF5340 Audio applications are designed to be used only with the following hardware:
.. table-from-rows:: /includes/sample_board_rows.txt
:header: heading
:rows: nrf5340_audio_dk_nrf5340
.. note::
The applications supports PCA10121 revisions 1.0.0 or above.
The applications are also compatible with the following pre-launch revisions:
* Revisions 0.8.0 and above.
You need at least two nRF5340 Audio development kits (one with the gateway firmware and one with headset firmware) to test each of the applications.
For CIS with TWS in mind, three kits are required.
If you want to test with other hardware (for example, a mobile phone or PC), it is highly recommended to test with Audio DKs on both the gateway and headset side first to verify basic functionality before moving on to testing with other vendors.
.. _nrf53_audio_app_requirements_codec:
Software codec requirements
***************************
The nRF5340 Audio applications only support the :ref:`LC3 software codec <nrfxlib:lc3>`, developed specifically for use with LE Audio.
The applications can be configured for other alternative codecs, but this integration is beyond the scope of this documentation.
.. _nrf53_audio_app_dk:
.. _nrf53_audio_app_dk_features:
nRF5340 Audio development kit
*****************************
The nRF5340 Audio development kit is a hardware development platform that demonstrates the nRF5340 Audio applications.
Read the `nRF5340 Audio DK Hardware`_ documentation for more information about this development kit.
You can :ref:`test the DK out of the box <nrf53_audio_app_dk_testing_out_of_the_box>` before you program it.
.. _nrf53_audio_app_configuration_files:
nRF5340 Audio configuration files
*********************************
All applications use the :file:`Kconfig.defaults` located in the :file:`nrf5340_audio` directory.
Additionally, each nRF5340 Audio application uses its own, application-specific :file:`Kconfig.defaults` file from the application directory, which includes configuration specific to the given application.
These files change the configuration defaults automatically, based on the different application versions and device types.
For each application, only one of the following :file:`.conf` files is included when building:
* :file:`prj.conf` is the default configuration file and it implements the debug application version.
* :file:`prj_release.conf` is the optional configuration file and it implements the release application version.
No debug features are enabled in the release application version.
When building using the command line, you must explicitly specify if :file:`prj_release.conf` is going to be included instead of :file:`prj.conf`.
See :ref:`nrf53_audio_app_building` for details.
* :file:`prj_fota.conf` is the optional configuration file used for FOTA DFU.
When used, the build system builds the debug version of the application (:file:`prj.conf`), but with the features needed to perform DFU over Bluetooth LE.
It also includes bootloaders so that the applications on both the application core and network core can be updated.
When building using the command line, you must explicitly specify if :file:`prj_fota.conf` is going to be included instead of :file:`prj.conf`.
See :ref:`nrf53_audio_app_fota` for more information.
doc/user_interface.rst
+160
View File
@@ -0,0 +1,160 @@
.. _nrf53_audio_app_ui:
User interface
##############
.. contents::
:local:
:depth: 2
All nRF5340 Audio applications implement the same, simple user interface based on the available PCB elements of the nRF5340 Audio development kit.
You can control the application using predefined switches and buttons while the LEDs display information.
Some user interface options are only valid for some nRF5340 Audio applications.
.. _nrf53_audio_app_ui_switches:
Switches
********
The application uses the following switches on the supported development kit:
+-------------------+-------------------------------------------------------------------------------------+---------------------------------------+
| Switch | Function | Applications |
+===================+=====================================================================================+=======================================+
| **POWER** | Turns the development kit on or off. | All |
+-------------------+-------------------------------------------------------------------------------------+---------------------------------------+
| **DEBUG ENABLE** | Turns on or off power for debug features. | All |
| | This switch is used for accurate power and current measurements. | |
+-------------------+-------------------------------------------------------------------------------------+---------------------------------------+
.. _nrf53_audio_app_ui_buttons:
Buttons
*******
The application uses the following buttons on the supported development kit:
+---------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| Button | Function | Applications |
+===============+===========================================================================================================+=============================================+
| **VOL-** | Long-pressed during startup: Changes the headset to the left channel one. | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Pressed on the headset or the CIS gateway during playback: Turns the playback volume down. | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
| | | * :ref:`nrf53_audio_unicast_client_app` |
+---------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **VOL+** | Long-pressed during startup: Changes the headset to the right channel one. | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Pressed on the headset or the CIS gateway during playback: Turns the playback volume up. | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
| | | * :ref:`nrf53_audio_unicast_client_app` |
+---------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **PLAY/PAUSE**| Starts or pauses the playback of the stream or listening to the stream. | All |
+---------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **BTN 4** | Long-pressed during startup: Turns on the DFU mode, if | All |
| | the device is :ref:`configured for it<nrf53_audio_app_configuration_configure_fota>`. | |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Pressed on the gateway during playback: Toggles between the normal audio stream and different test | * :ref:`nrf53_audio_broadcast_source_app` |
| | tones generated on the device. Use this tone to check the synchronization of headsets. | * :ref:`nrf53_audio_unicast_client_app` |
| +-----------------------------------------------------------------------------------------------------------+ |
| | Pressed on the gateway during playback multiple times: Changes the test tone frequency. | |
| | The available values are 1000 Hz, 2000 Hz, and 4000 Hz. | |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Pressed on a BIS headset during playback: Change stream (different BIS), if more than one is available. | :ref:`nrf53_audio_broadcast_sink_app` |
+---------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **BTN 5** | Long-pressed during startup: Clears the previously stored bonding information. | * :ref:`nrf53_audio_unicast_server_app` |
| | | * :ref:`nrf53_audio_unicast_client_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Pressed during playback: Mutes the playback volume. | * :ref:`nrf53_audio_unicast_server_app` |
| | | * :ref:`nrf53_audio_unicast_client_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Pressed on a BIS headset during playback: Change the gateway, if more than one is available. | :ref:`nrf53_audio_broadcast_sink_app` |
+---------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **RESET** | Resets the device to the originally programmed settings. | All |
| | This reverts any changes made during testing, for example the channel switches with **VOL** buttons. | |
+---------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
.. _nrf53_audio_app_ui_leds:
LEDs
****
To indicate the tasks performed, the application uses the LED behavior described in the following table:
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| LED |Indication | Applications |
+==========================+===========================================================================================================+=============================================+
| **LED1** | Off - No Bluetooth connection. | All |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Solid blue on the CIS gateway and headset: Kits have connected. | * :ref:`nrf53_audio_unicast_server_app` |
| | | * :ref:`nrf53_audio_unicast_client_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Solid blue on the BIS headset: Kits have found a broadcasting stream. | :ref:`nrf53_audio_broadcast_sink_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Blinking blue on headset: Kits have started streaming audio (BIS and CIS modes). | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Blinking blue on the CIS gateway: Kit is streaming to a headset. | :ref:`nrf53_audio_unicast_client_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Blinking blue on the BIS gateway: Kit has started broadcasting audio. | :ref:`nrf53_audio_broadcast_source_app` |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **LED2** | Off - Sync not achieved. | All |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Solid green - Sync achieved (both drift and presentation compensation are in the ``LOCKED`` state). | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **LED3** | Blinking green - The nRF5340 Audio DK application core is running. | All |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **CODEC** | Off - No configuration loaded to the onboard hardware codec. | All |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Solid green - Hardware codec configuration loaded. | All |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **RGB** | Solid green - The device is programmed as the gateway. | * :ref:`nrf53_audio_broadcast_source_app` |
| | | * :ref:`nrf53_audio_unicast_client_app` |
| (bottom side LEDs around +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| the center opening) | Solid blue - The device is programmed as the left headset. | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Solid magenta - The device is programmed as the right headset. | * :ref:`nrf53_audio_broadcast_sink_app` |
| | | * :ref:`nrf53_audio_unicast_server_app` |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Solid yellow - The device is programmed with factory firmware. | All |
| | It must be re-programmed as gateway or headset. | |
| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| | Solid red (debug mode) - Fault in the application core has occurred. | All |
| | See UART log for details and use the **RESET** button to reset the device. | |
| | In the release mode, the device resets automatically with no indication on LED or UART. | |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **ERR** | PMIC error or a charging error (or both). | All |
| | Also turns on when charging the battery exceeds seven hours, since the PMIC has a protection timeout, | |
| | which stops the charging. | |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **CHG** | Off - Charge completed or no battery connected. | All |
| +-----------------------------------------------------------------------------------------------------------+ |
| | Solid yellow - Charging in progress. | |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **OB/EXT** | Off - No 3.3 V power available. | All |
| +-----------------------------------------------------------------------------------------------------------+ |
| | Solid green - On-board hardware codec selected. | |
| +-----------------------------------------------------------------------------------------------------------+ |
| | Solid yellow - External hardware codec selected. | |
| | This LED turns solid yellow also when the devices are reset, for the time then pins are floating. | |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **FTDI SPI** | Off - No data is written to the hardware codec using SPI. | All |
| +-----------------------------------------------------------------------------------------------------------+ |
| | Yellow - The same SPI is used for both the hardware codec and the SD card. | |
| | When this LED is yellow, the shared SPI is used by the FTDI to write data to the hardware codec. | |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **IFMCU** | Off - No PC connection available. | All |
| (bottom side) +-----------------------------------------------------------------------------------------------------------+ |
| | Solid green - Connected to PC. | |
| +-----------------------------------------------------------------------------------------------------------+ |
| | Rapid green flash - USB enumeration failed. | |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+
| **HUB** | Off - No PC connection available. | All |
| (bottom side) +-----------------------------------------------------------------------------------------------------------+ |
| | Green - Standard USB hub operation. | |
+--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+