doc: audio: app-specific kconfigs

Added pages for documenting app-specific Kconfigs.
OCT-3407.

Signed-off-by: Grzegorz Ferenc <[email protected]>

Author: greg-fer

applications/nrf5340_audio/doc/configuration.rst

@@ -7,153 +7,170 @@ Configuring the nRF5340 Audio applications
    :local:
    :depth: 2
 
-|config|
-
-.. _nrf53_audio_app_kconfigs:
-
-Configuration options
-*********************
-
-The application comes with the following application-specific Kconfig options:
-
-.. _CONFIG_STREAM_BIDIRECTIONAL:
 
-CONFIG_STREAM_BIDIRECTIONAL
-   Enables bidirectional communication mode for CIS streams.
+The nRF5340 Audio applications introduce Kconfig options that you can use to configure audio functionality, device roles, and transport modes.
+You can use these options to select between gateway and headset roles, choose between CIS (unicast) and BIS (broadcast) transport modes, and configure audio-specific features.
 
-.. _CONFIG_WALKIE_TALKIE_DEMO:
+The nRF5340 Audio applications align the configuration with the nRF5340 Audio use case by overlaying Kconfig defaults and selecting or implying the required Kconfig options.
+Among others, the Kconfig options for Bluetooth, Zephyr's audio subsystems, and hardware peripherals are selected to ensure they are enabled.
 
-CONFIG_WALKIE_TALKIE_DEMO
-   Enables the walkie-talkie demo functionality using bidirectional streams.
+The :option:`CONFIG_NRF5340_AUDIO` option is the main Kconfig option that activates all nRF5340 Audio functionality.
+See the :file:`Kconfig.defaults` file for details related to the default common configuration.
 
-.. _CONFIG_TRANSPORT_BIS:
+.. note::
+   Part of the default configuration is applied by modifying the default values of Kconfig options.
+   Changing configuration in menuconfig does not automatically adjust user-configurable values to the new defaults.
+   So, you must update those values manually.
+   For more information, see the Stuck symbols in menuconfig and guiconfig section on the :ref:`kconfig_tips_and_tricks` in the Zephyr documentation.
 
-CONFIG_TRANSPORT_BIS
-   Enables Auracast™ (broadcast) mode for working with broadcast sources and sinks.
+   The default Kconfig option values are automatically updated if configuration changes are applied directly in the configuration files.
 
-.. _CONFIG_BT_AUDIO_USE_BROADCAST_NAME_ALT:
+The application-specific Kconfig options mentioned on this page are listed in :ref:`nRF5340 Audio: Application-specific Kconfig options <config_audio_app_options>`.
 
-CONFIG_BT_AUDIO_USE_BROADCAST_NAME_ALT
-   Enables BIS mode with two gateways, allowing headsets to switch between gateways.
-
-.. _CONFIG_BT_AUDIO_BROADCAST_NAME_ALT:
-
-CONFIG_BT_AUDIO_BROADCAST_NAME_ALT
-   Provides an alternative name for the second gateway in BIS mode.
+|config|
 
-.. _CONFIG_BT_AUDIO_SCAN_DELEGATOR:
+.. _nrf53_audio_device_role_configuration:
 
-CONFIG_BT_AUDIO_SCAN_DELEGATOR
-   Enables scan delegator.
-   When the scan delegator feature is enabled, the broadcast sink will not search for a predefined broadcast source.
-   Instead, it will wait for a broadcast assistant to connect and control it.
+Configuring the device role
+***************************
 
-.. _CONFIG_AUDIO_SOURCE_I2S:
+The nRF5340 Audio application supports two device roles: gateway and headset.
+See :ref:`nrf53_audio_app_overview_gateway_headsets` for more information about these roles.
 
-CONFIG_AUDIO_SOURCE_I2S
-   Switches from USB audio source to 3.5 mm jack analog input using I2S.
+You can :ref:`select gateway or headset build <nrf53_audio_app_configuration_select_build>` when :ref:`nrf53_audio_app_building`.
 
-.. _CONFIG_NRF5340_AUDIO_SD_CARD_MODULE:
+The :option:`CONFIG_AUDIO_DEV` Kconfig option defines the nRF5340 Audio device role.
+The device role can be either a gateway (:option:`CONFIG_AUDIO_DEV` set to ``2``) or a headset (:option:`CONFIG_AUDIO_DEV` set to ``1``).
 
-CONFIG_NRF5340_AUDIO_SD_CARD_MODULE
-   Enables the SD card module (enabled by default on the nRF5340 Audio DK).
+Each role automatically implies the nRF5340 Audio modules needed for the role.
+For example, the gateway role automatically enables USB audio source support, while the headset role enables I2S audio output.
 
-.. _CONFIG_SD_CARD_PLAYBACK:
+.. _nrf53_audio_transport_mode_configuration:
 
-CONFIG_SD_CARD_PLAYBACK
-   Enables SD card playback functionality.
+Configuring the transport mode
+******************************
 
-.. _CONFIG_SD_CARD_PLAYBACK_STACK_SIZE:
+The nRF5340 Audio application supports two transport modes for LE Audio:
 
-CONFIG_SD_CARD_PLAYBACK_STACK_SIZE
-   Sets the stack size for the SD card playback thread (default: 4096).
+* Connected Isochronous Stream (CIS) - for unicast communication
+* Broadcast Isochronous Stream (BIS) - for broadcast communication
 
-.. _CONFIG_SD_CARD_PLAYBACK_RING_BUF_SIZE:
+See :ref:`nrf53_audio_app_overview_modes` for detailed information about these modes.
 
-CONFIG_SD_CARD_PLAYBACK_RING_BUF_SIZE
-   Sets the size of the ring buffer for audio data (default: 960).
+The transport mode is selected using the following Kconfig options:
 
-.. _CONFIG_SD_CARD_PLAYBACK_THREAD_PRIO:
+* (Default mode) :option:`CONFIG_TRANSPORT_CIS` - Enables CIS mode for clients and servers (unicast applications).
+  With this option enabled, you can configure application Kconfig options specific to unicast communication (see :file:`applications/nrf5340_audio/src/bluetooth/bt_stream/unicast/Kconfig`).
+* :option:`CONFIG_TRANSPORT_BIS` - Enables BIS mode for `Auracast™`_ sources and sinks (broadcast applications).
+  With this option enabled, you can configure application Kconfig options specific to broadcast communication (see :file:`applications/nrf5340_audio/src/bluetooth/bt_stream/broadcast/Kconfig`).
 
-CONFIG_SD_CARD_PLAYBACK_THREAD_PRIO
-   Sets the priority for the SD card playback thread (default: 7).
+The transport mode selection automatically configures the appropriate Bluetooth stack components and audio processing modules.
 
 .. _nrf53_audio_app_configuration_select_bidirectional:
 
 Selecting the CIS bidirectional communication
-*********************************************
+=============================================
 
-To switch to the bidirectional mode, set the :ref:`CONFIG_STREAM_BIDIRECTIONAL<nrf53_audio_app_kconfigs>` 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).
+To switch to the bidirectional mode, set the :option:`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 :ref:`CONFIG_WALKIE_TALKIE_DEMO<nrf53_audio_app_kconfigs>` 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).
+To switch to using the walkie-talkie, set the :option:`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.
+If you want to work with `Auracast™`_ (broadcast) sources and sinks, set the :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 :ref:`CONFIG_TRANSPORT_BIS<nrf53_audio_app_kconfigs>` and the :ref:`CONFIG_BT_AUDIO_USE_BROADCAST_NAME_ALT<nrf53_audio_app_kconfigs>` 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 :ref:`CONFIG_BT_AUDIO_BROADCAST_NAME_ALT<nrf53_audio_app_kconfigs>` or use the default alternative name.
+To configure the second gateway, add both the :option:`CONFIG_TRANSPORT_BIS` and the :option:`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 :option:`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:
+.. _nrf53_audio_source_configuration:
 
-Selecting the analog jack input using I2S
-*****************************************
+Configuring the audio source
+****************************
+
+The nRF5340 Audio application supports multiple audio sources for gateway devices.
+See :ref:`nrf53_audio_app_overview_architecture_usb` and :ref:`nrf53_audio_app_overview_architecture_i2s` for information about the firmware architecture differences.
+
+The audio source is selected using the following Kconfig options:
+
+* USB audio source (:option:`CONFIG_AUDIO_SOURCE_USB`) - Uses USB as the audio source (default for gateway)
+* I2S audio source (:option:`CONFIG_AUDIO_SOURCE_I2S`) - Uses 3.5 mm jack analog input using I2S
 
 In the default configuration, the gateway application uses USB as the audio source.
 The :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 :ref:`CONFIG_AUDIO_SOURCE_I2S<nrf53_audio_app_kconfigs>` 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.
+The audio source selection affects the firmware architecture and available features.
+USB audio source is limited to unidirectional streams due to CPU load considerations, while I2S supports bidirectional communication.
+
+.. _nrf53_audio_app_configuration_select_i2s:
+
+Selecting the analog jack input using I2S
+=========================================
+
+To switch to using the 3.5 mm jack analog input, set the :option:`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:
+.. _nrf53_audio_codec_configuration:
 
-Adding FEM support
+Configuring codecs
 ******************
 
-You can add support for the nRF21540 front-end module (FEM) to the following nRF5340 Audio applications:
+The nRF5340 Audio application uses both software and hardware codecs.
+The software codec is responsible for encoding and decoding, while the hardware codec is responsible for DAC/ADC and other audio processing.
+See :ref:`nrf53_audio_app_overview_architecture` for information about how both codecs are integrated into the firmware architecture.
 
-* :ref:`Broadcast source <nrf53_audio_broadcast_source_app>`
-* :ref:`Unicast client <nrf53_audio_unicast_client_app>`
-* :ref:`Unicast server <nrf53_audio_unicast_server_app>`
+You can enable the software codec using the :option:`CONFIG_SW_CODEC_LC3` Kconfig option.
+This codec is mandatory for LE Audio.
 
-The :ref:`broadcast sink application <nrf53_audio_broadcast_sink_app>` does not need FEM support as it only receives data.
+You can enable the CS47L63 hardware codec using the :option:`CONFIG_NRF5340_AUDIO_CS47L63_DRIVER` Kconfig option.
 
-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:
+The codec selection affects audio quality, processing requirements, and power consumption.
 
-* 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:
+.. _nrf53_audio_quality_configuration:
 
-  .. code-block:: console
+Configuring audio quality
+*************************
 
-     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
+The nRF5340 Audio application provides extensive configuration options for audio quality.
+These settings affect the :ref:`nrf53_audio_app_overview_architecture_sync_module` and overall audio performance.
 
-To set the TX power output, use the :kconfig:option:`CONFIG_BT_CTLR_TX_PWR_ANTENNA` and :kconfig:option:`CONFIG_MPSL_FEM_NRF21540_TX_GAIN_DB` Kconfig options in :file:`applications/nrf5340_audio/sysbuild/ipc_radio/prj.conf`.
+See :ref:`config_audio_app_options` for the list of options to configure the following audio quality settings:
 
-See :ref:`ug_radio_fem` for more information about FEM in the |NCS|.
+* Frame duration (example: :option:`CONFIG_AUDIO_FRAME_DURATION_10_MS`)
+* Sample rates (example: :option:`CONFIG_AUDIO_SAMPLE_RATE_16000_HZ`)
+* Bit depth (example: :option:`CONFIG_AUDIO_BIT_DEPTH_16`)
+* Presentation delay (example: :option:`CONFIG_AUDIO_MIN_PRES_DLY_US`)
+
+.. _nrf53_audio_bluetooth_configuration:
+
+Configuring Bluetooth LE Audio
+******************************
+
+The nRF5340 Audio application introduces application-specific configuration options related to Bluetooth LE Audio.
+These options configure the Bluetooth stack components described in :ref:`nrf53_audio_app_overview_architecture`.
+
+See :ref:`config_audio_app_options` for options starting with ``CONFIG_BT_AUDIO``.
 
 .. _nrf53_audio_app_configuration_sd_card_playback:
 
@@ -162,6 +179,7 @@ Enabling SD card playback
 
 The SD Card Playback module allows you to play audio files directly from an SD card inserted into the nRF5340 Audio development kit.
 This feature supports both WAV and LC3 audio file formats and is compatible with all nRF5340 Audio applications.
+See :ref:`nrf53_audio_app_overview_architecture_sd_card_playback` for detailed information about the SD card playback module.
 
 File format support requirements
 ================================
@@ -185,14 +203,14 @@ Configuring SD card playback
 
 To enable SD card playback functionality, you need to set the following Kconfig options to ``y``:
 
-* :ref:`CONFIG_NRF5340_AUDIO_SD_CARD_MODULE<nrf53_audio_app_kconfigs>` - to enable the SD card module; this option is enabled by default on nRF5340 Audio DK
-* :ref:`CONFIG_SD_CARD_PLAYBACK<nrf53_audio_app_kconfigs>` - to enable the playback functionality
+* :option:`CONFIG_NRF5340_AUDIO_SD_CARD_MODULE` - to enable the SD card module; this option is enabled by default on nRF5340 Audio DK
+* :option:`CONFIG_SD_CARD_PLAYBACK` - to enable the playback functionality
 
 Optionally, you can also set the following Kconfig options:
 
-* :ref:`CONFIG_SD_CARD_PLAYBACK_STACK_SIZE<nrf53_audio_app_kconfigs>`
-* :ref:`CONFIG_SD_CARD_PLAYBACK_RING_BUF_SIZE<nrf53_audio_app_kconfigs>`
-* :ref:`CONFIG_SD_CARD_PLAYBACK_THREAD_PRIO<nrf53_audio_app_kconfigs>`
+* :option:`CONFIG_SD_CARD_PLAYBACK_STACK_SIZE`
+* :option:`CONFIG_SD_CARD_PLAYBACK_RING_BUF_SIZE`
+* :option:`CONFIG_SD_CARD_PLAYBACK_THREAD_PRIO`
 
 Shell commands for SD card playback
 ===================================
@@ -250,3 +268,31 @@ To play audio from the SD card, complete the following steps:
    The audio from the SD card will be mixed with any existing audio stream and played through the device's audio output.
 #. To stop the playback, issue the ``sd_card_playback stop`` command.
 #. To exit the shell, issue the ``exit`` command.
+
+.. _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 :kconfig:option:`CONFIG_BT_CTLR_TX_PWR_ANTENNA` and :kconfig:option:`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|.

applications/nrf5340_audio/doc/configuration_options.rst

@@ -0,0 +1,13 @@
+.. _config_audio_app_options:
+
+nRF5340 Audio: Application-specific Kconfig options
+###################################################
+
+.. contents::
+   :local:
+   :depth: 2
+
+Following are the application-specific configuration options that can be configured for the nRF5340 Audio applications and their internal modules:
+
+.. options-from-kconfig:: /../../../../../nrf/applications/nrf5340_audio/Kconfig
+   :show-type:

applications/nrf5340_audio/doc/firmware_architecture.rst

@@ -30,7 +30,7 @@ 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`.
+You can :ref:`select gateway or headset build <nrf53_audio_app_configuration_select_build>` when :ref:`nrf53_audio_app_building`.
 
 .. _nrf53_audio_app_overview_modes:
 

applications/nrf5340_audio/index.rst

@@ -54,4 +54,5 @@ See the subpages for detailed documentation of each of the nRF5340 applications
    unicast_server/README
    doc/fota
    doc/adapting_application
+   doc/configuration_options
    doc/audio_api