diff --git a/applications/nrf5340_audio/README.rst b/applications/nrf5340_audio/README.rst deleted file mode 100644 index 1fc48bb75d5b..000000000000 --- a/applications/nrf5340_audio/README.rst +++ /dev/null @@ -1,861 +0,0 @@ -.. _nrf53_audio_app_description: - -nRF5340 Audio configuration and testing -####################################### - -.. contents:: - :local: - :depth: 2 - -The nRF5340 Audio application has the following unique characteristics: - -* It is developed for use only with the :ref:`nRF5340 Audio development kit `. -* In its default configuration, the application requires the :ref:`LC3 software codec `. -* The application also comes with various application-specific tools, including the :file:`buildprog.py` Python script that simplifies building and programming the firmware. -* The application uses the :ref:`lib_bt_ll_acs_nrf53_readme` as the controller programmed to the network core. - This controller is required in all application configurations and testing scenarios. - -.. _nrf53_audio_app_requirements: - -Requirements -************ - -The nRF5340 Audio application is 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 application supports PCA10121 revisions 1.0.0 or above. - The application is 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 the application. -For CIS with TWS in mind, three kits are required. - -.. _nrf53_audio_app_requirements_codec: - -Software codec requirements -=========================== - -The nRF5340 Audio application only supports the :ref:`LC3 software codec `, developed specifically for use with LE Audio. - -.. _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 application. -Read the `nRF5340 Audio DK Hardware`_ documentation on Nordic Semiconductor Infocenter for more information about this development kit. - -.. _nrf53_audio_app_configuration_files: - -nRF5340 Audio configuration files -================================= - -The nRF5340 Audio application uses :file:`Kconfig.defaults` files to change configuration defaults automatically, based on the different application versions and device types. - -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. - -In addition, the application features the :file:`child_image` directory with an experimental :file:`hci_ipc.conf`. -This file is a work-in-progress implementation of the SoftDevice Controller that has not been thoroughly tested and should not be used. -The application is only tested using :ref:`lib_bt_ll_acs_nrf53_readme`. - -Requirements for FOTA -===================== - -To test Firmware Over-The-Air (FOTA), you need an Android or iOS device with the `nRF Connect Device Manager`_ app installed. - -If you want to do FOTA upgrades for the application core and the network core at the same time, you need an external flash shield. -See :ref:`nrf53_audio_app_configuration_configure_fota` for more details. - -.. _nrf53_audio_app_ui: - -User interface -************** - -The application implements a simple user interface based on the available PCB elements. -You can control the application using predefined switches and buttons while the LEDs display information. - -.. _nrf53_audio_app_ui_switches: - -Switches -======== - -The application uses the following switches on the supported development kit: - -+-------------------+-------------------------------------------------------------------------------------+ -| Switch | Function | -+===================+=====================================================================================+ -| **POWER** | Turns the development kit on or off. | -+-------------------+-------------------------------------------------------------------------------------+ -| **DEBUG ENABLE** | Turns on or off power for debug features. | -| | 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 | -+===============+===========================================================================================================+ -| **VOL-** | Depending on the moment it is pressed: | -| | | -| | * Long-pressed during startup: Changes the headset to the left channel one. | -| | * Pressed on the headset or the CIS gateway during playback: Turns the playback volume down (and unmutes).| -+---------------+-----------------------------------------------------------------------------------------------------------+ -| **VOL+** | Depending on the moment it is pressed: | -| | | -| | * Long-pressed during startup: Changes the headset to the right channel one. | -| | * Pressed on the headset or the CIS gateway during playback: Turns the playback volume up (and unmutes). | -+---------------+-----------------------------------------------------------------------------------------------------------+ -| **PLAY/PAUSE**| Starts or pauses the playback. | -+---------------+-----------------------------------------------------------------------------------------------------------+ -| **BTN 4** | Depending on the moment it is pressed: | -| | | -| | * Long-pressed during startup: Turns on the DFU mode, if | -| | the device is :ref:`configured for it`. | -| | * Pressed on the gateway during playback: Sends a test tone generated on the device. | -| | Use this tone to check the synchronization of headsets. | -| | * Pressed on the gateway during playback multiple times: Changes the tone frequency. | -| | The available values are 1000 Hz, 2000 Hz, and 4000 Hz. | -| | * Pressed on a BIS headset during playback: Change audio stream, if more than one is | -| | available. | -+---------------+-----------------------------------------------------------------------------------------------------------+ -| **BTN 5** | Depending on the moment it is pressed: | -| | | -| | * Long-pressed during startup: Clears the previously stored bonding information. | -| | * Pressed during playback: Mutes the playback volume. | -| | * Pressed on a BIS headset during playback: Change the gateway, if more than one is | -| | available. | -+---------------+-----------------------------------------------------------------------------------------------------------+ -| **RESET** | Resets the device to the originally programmed settings. | -| | 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 | -+==========================+===========================================================================================================+ -| **LED1** | Off - No Bluetooth connection. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Blinking blue - Depending on the device and the mode: | -| | | -| | * Headset: Kits have started streaming audio (BIS and CIS modes). | -| | * Gateway: Kit has connected to a headset (CIS mode) or has started broadcasting audio (BIS mode). | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid blue - Headset, depending on the mode: | -| | Kits have connected to the gateway (CIS mode) or found a broadcasting stream (BIS mode). | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **LED2** | Off - Sync not achieved. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid green - Sync achieved (both drift and presentation compensation are in the ``LOCKED`` state). | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **LED3** | Blinking green - The nRF5340 Audio DK application core is running. | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **CODEC** | Off - No configuration loaded to the onboard hardware codec. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid green - Hardware codec configuration loaded. | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **RGB1** | Solid green - The device is programmed as the gateway. | -| (bottom side LEDs around +-----------------------------------------------------------------------------------------------------------+ -| the center opening) | Solid blue - The device is programmed as the left headset. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid magenta - The device is programmed as the right headset. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid yellow - The device is programmed with factory firmware. | -| | It must be re-programmed as gateway or headset. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid red (debug mode) - Fault in the application core has occurred. | -| | 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. | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **RGB 2** | Controlled by the Bluetooth LE Controller on the network core. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Blinking green - Ongoing CPU activity. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid red - Error. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid white (all colors on) - The **RGB 2** LED is not initialized by the Bluetooth LE Controller. | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **ERR** | PMIC error or a charging error (or both). | -| | 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. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Solid yellow - Charging in progress. | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **OB/EXT** | Off - No 3.3 V power available. | -| +-----------------------------------------------------------------------------------------------------------+ -| | 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. | -| +-----------------------------------------------------------------------------------------------------------+ -| | 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. | -| (bottom side) +-----------------------------------------------------------------------------------------------------------+ -| | Solid green - Connected to PC. | -| +-----------------------------------------------------------------------------------------------------------+ -| | Rapid green flash - USB enumeration failed. | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ -| **HUB** | Off - No PC connection available. | -| (bottom side) +-----------------------------------------------------------------------------------------------------------+ -| | Green - Standard USB hub operation. | -+--------------------------+-----------------------------------------------------------------------------------------------------------+ - -.. _nrf53_audio_app_configuration: - -Configuration -************* - -|config| - -.. _nrf53_audio_app_configuration_select_bis: - -Selecting the BIS mode -====================== - -The CIS mode is the default operating mode for the application. -To switch to the BIS mode, set the :ref:`CONFIG_TRANSPORT_BIS ` Kconfig option to ``y`` in the :file:`prj.conf` file for the debug version and in the :file:`prj_release.conf` file for the release version. - -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 that the BIS headsets can receive audio stream from. -To configure the second gateway, add both the :ref:`CONFIG_TRANSPORT_BIS ` and the :ref:`CONFIG_BT_AUDIO_USE_BROADCAST_NAME_ALT ` Kconfig options set to ``y`` to the :file:`prj.conf` file for the debug version and to the :file:`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 ` 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_bidirectional: - -Selecting the CIS bidirectional communication -============================================= - -The CIS unidirectional mode is the default operating mode for the application. -To switch to the bidirectional mode, set the :ref:`CONFIG_STREAM_BIDIRECTIONAL ` Kconfig option to ``y`` in the :file:`prj.conf` file (for the debug version) or in the :file:`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 ` Kconfig option to ``y`` in the :file:`prj.conf` file (for the debug version) or in the :file:`prj_release.conf` file (for the release version). - -.. _nrf53_audio_app_configuration_select_i2s: - -Selecting the I2S serial -======================== - -In the default configuration, the gateway application uses the USB serial port as the audio source. -The :ref:`nrf53_audio_app_building` and :ref:`nrf53_audio_app_testing` steps also refer to using the USB serial connection. - -To switch to using the I2S serial connection, set the :ref:`CONFIG_AUDIO_SOURCE_I2S ` Kconfig option to ``y`` in the :file:`prj.conf` file for the debug version and in the :file:`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_configuration_configure_fota: - -Configuring FOTA upgrades -========================= - -.. caution:: - Firmware based on the |NCS| versions earlier than v2.1.0 does not support DFU. - FOTA is not available for those versions. - - You can test performing separate application and network core upgrades, but for production, both cores must be updated at the same time. - When updates take place in the inter-core communication module (HCI RPMsg), communication between the cores will break if they are not updated together. - -You can configure Firmware Over-The-Air (FOTA) upgrades to replace the applications on both the application core and the network core. -The nRF5340 Audio application supports the following types of DFU flash memory layouts: - -* Internal flash memory layout - which supports only single-image DFU. -* External flash memory layout - which supports :ref:`multi-image DFU `. - -The LE Audio Controller Subsystem for nRF53 supports both the normal and minimal sizes of the bootloader. -The minimal size is specified using the :kconfig:option:`CONFIG_NETBOOT_MIN_PARTITION_SIZE`. - -Hardware requirements for external flash memory DFU ---------------------------------------------------- - -To enable the external flash DFU, you need an additional flash memory shield. -See `Requirements for external flash memory DFU`_ in the nRF5340 Audio DK Hardware documentation in Infocenter for more information. - -Enabling FOTA upgrades ----------------------- - -The FOTA upgrades are only available when :ref:`nrf53_audio_app_building_script`. -With the appropriate parameters provided, the :file:`buildprog.py` Python script will add overlay files for the given DFU type. -To enable the desired FOTA functions: - -* To define flash memory layout, include the ``-m internal`` parameter for the internal layout (when using the ``release`` application version) or the ``-m external`` parameter for the external layout (when using either ``release`` or ``debug``). -* To use the minimal size network core bootloader, add the ``-M`` parameter. - -For the full list of parameters and examples, see the :ref:`nrf53_audio_app_building_script_running` section. - -FOTA build files ----------------- - -The generated FOTA build files use the following naming patterns: - -* For multi-image DFU, the file is called ``dfu_application.zip``. - This file updates two cores with one single file. -* For single-image DFU, the bin file for the application core is called ``app_update.bin``. - The bin file for the network core is called ``net_core_app_update.bin``. - In this scenario, the cores are updated one by one with two separate files in two actions. - -See :ref:`app_build_output_files` for more information about the image files. - -.. note:: - |nrf5340_audio_net_core_hex_note| - -Entering the DFU mode ---------------------- - -The |NCS| uses :ref:`SMP server and mcumgr ` as the DFU backend. -Unlike the CIS and BIS modes for gateway and headsets, the DFU mode is advertising using the SMP server service. -For this reason, to enter the DFU mode, you must long press **BTN 4** during each device startup to have the nRF5340 Audio DK enter the DFU mode. - -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 before 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 application, 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. - -.. _nrf53_audio_app_building: - -Building and running -******************** - -This sample can be found under :file:`applications/nrf5340_audio` in the nRF Connect SDK folder structure. - -.. note:: - Building and programming the nRF5340 Audio application is different from the :ref:`standard procedure ` of building and programming for the nRF5340 DK. - This is because the nRF5340 Audio application only builds and programs the files for the application core. - |nrf5340_audio_net_core_hex_note| - -You can build and program the application 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 ` before building and programming the application. - -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 **RGB1** (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 kits with either gateway or headset firmware before they can be used. - -.. _nrf53_audio_app_adding_FEM_support: - -Adding FEM support -================== - -You can add support for the nRF21540 front-end module (FEM) to this application by using 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 ``-DSHIELD=nrf21540ek_fwd`` to the ``west build`` command. - For example: - - .. code-block:: console - - west build -b nrf5340_audio_dk_nrf5340_cpuapp --pristine -- -DCONFIG_AUDIO_DEV=1 -DSHIELD=nrf21540ek_fwd -DCONF_FILE=prj_release.conf - -To set the TX power output, use the :ref:`CONFIG_NRF_21540_MAIN_TX_POWER ` and :ref:`CONFIG_NRF_21540_PRI_ADV_TX_POWER ` Kconfig options. - -.. note:: - When you build the nRF5340 Audio application with the nRF21540 FEM support, the :ref:`lib_bt_ll_acs_nrf53_readme` does not support the +20 dBm setting. - This is because of a power class restriction in the controller's QDID. - -See :ref:`ug_radio_fem` for more information about FEM in the |NCS|. - -.. _nrf53_audio_app_building_script: - -Building and programming using script -===================================== - -The suggested method for building the application and programming it to the development kit is running the :file:`buildprog.py` Python script, which is located in the :file:`applications/nrf5340_audio/tools/buildprog` directory. -The script automates the process of selecting :ref:`configuration files ` and building different versions of the application. -This eases the process of building and programming images for multiple 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: - -* ``nrf5340_audio_dk_snr`` -- This field lists the SEGGER serial number. - You can check this number on the sticker on the nRF5340 Audio development kit. - Alternatively, connect the development kit to your PC and run ``nrfjprog -i`` in a command window to print the SEGGER serial number of the kit. -* ``nrf5340_audio_dk_dev`` -- This field assigns the specific nRF5340 Audio development kit to be a headset or a gateway. -* ``channel`` -- This field is valid only for headsets operating in the CIS mode. - 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 ------------------- - -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, in line with :ref:`nrf53_audio_app_configuration_files`: - -* Core type (``-c`` parameter): ``app``, ``net``, or ``both`` -* Application version (``-b`` parameter): either ``release`` or ``debug`` -* Device type (``-d`` parameter): ``headset``, ``gateway``, or ``both`` -* DFU type (``-m`` parameter): ``internal``, ``external`` -* Network core bootloader minimal size (``-M``) - -See the following examples of the parameter usage with the command run from the :file:`buildprog` directory: - -* Example 1: The following command builds the application using the script for the application core with the ``debug`` application version for both the headset and the gateway: - - .. code-block:: console - - python buildprog.py -c app -b debug -d both - -* Example 2: The following command builds the application using the script for both the application and the network core (``both``). - It builds with the ``release`` application version, with the DFU internal flash memory layout enabled, and using the minimal size of the network core bootloader: - - .. code-block:: console - - python buildprog.py -c both -b release -d both -m internal -M - - If you run this command with the ``external`` DFU type parameter instead of ``internal``, the external flash memory layout will be enabled. - -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 the :file:`applications/nrf5340_audio/build` directory. -The script creates a directory for each application version and device type combination. -For example, when running the command above, the script creates the :file:`dev_gateway/build_debug` and :file:`dev_headset/build_debug` directories. - -Programming with the script - 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 command. - - The following parameters are available for programming: - - * Programming (``-p`` parameter) -- If you run the building script with this parameter, you can program one or both of the cores after building the files. - * Sequential programming (``-s`` parameter) -- If you are using Windows Subsystem for Linux (WSL) and encounter problems while programming, include this parameter alongside other parameters to program sequentially. - - The command for programming can look as follows: - - .. code-block:: console - - python buildprog.py -c both -b debug -d both -p - - This command builds the application with the ``debug`` application version for both the headset and the gateway and programs the application core. - Given the ``-c both`` parameter, it also takes the precompiled Bluetooth Low Energy Controller binary from the :file:`nrf/lib/bin/bt_ll_acs_nrf53/bin` directory and programs it to the network core of both the gateway and the headset. - - .. note:: - If the programming command fails because of :ref:`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 -p --recover_on_fail - - If you want to program firmware that has DFU enabled, you must include the DFU parameters in the command. - The command for programming with DFU enabled can look as follows: - - .. code-block:: console - - python buildprog.py -c both -b release -d both -m internal -M -p - -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 application using the standard |NCS| :ref:`build steps ` for the command line. - -.. note:: - Using this method requires you to build and program each development kit one at a time before moving to the next configuration, which can be time-consuming. - :ref:`nrf53_audio_app_building_script` is recommended. - -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 options: - - * For headset device: ``-DCONFIG_AUDIO_DEV=1`` - * For gateway device: ``-DCONFIG_AUDIO_DEV=2`` - - #. Choose the application version by using one of the following options: - - * For the debug version: No build flag needed. - * For the release version: ``-DCONF_FILE=prj_release.conf`` - -#. Build the application using the standard :ref:`build steps ` 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: - - .. code-block:: console - - west build -b nrf5340_audio_dk_nrf5340_cpuapp --pristine -- -DCONFIG_AUDIO_DEV=1 -DCONF_FILE=prj_release.conf - - Unlike when :ref:`nrf53_audio_app_building_script`, this command creates the build files directly in the :file:`build` directory. - This means that you first need to program the headset development kits before you build and program gateway development kits. - Alternatively, you can add the ``-d`` parameter to the ``west`` command to specify a custom build folder. This lets you build firmware for both - headset and gateway before programming any development kits. - -Programming the application ---------------------------- - -After building the files for the development kit you want to program, complete the following steps to program the application from the command line: - -1. Plug the device into the USB port. - - .. note:: - |usb_known_issues| - -#. Turn on the development kit using the On/Off switch. -#. Open a command prompt. -#. Run the following command to print the SEGGER serial number of your development kit: - - .. code-block:: console - - nrfjprog -i - - .. note:: - Pay attention to which device is to be programmed with the gateway HEX file and which devices are to be programmed with the headset HEX file. - -#. Program the network core on the development kit by running the following command: - - .. code-block:: console - - nrfjprog --program bin/*.hex --chiperase --coprocessor CP_NETWORK -r - - |nrf5340_audio_net_core_hex_note| -#. Program the application core on the development kit with the respective HEX file from the :file:`build` directory by running the following command: - - .. code-block:: console - - nrfjprog --program build/zephyr/zephyr.hex --coprocessor CP_APPLICATION --chiperase -r - - In this command, :file:`build/zephyr/zephyr.hex` is the HEX binary file for the application core. - If a custom build folder is specified, the path to this folder must be used instead of :file:`build/`. -#. If any device is not programmed due to :ref:`readback_protection_error`, complete the following steps: - - a. Run the following commands to recover the device: - - .. code-block:: console - - nrfjprog --recover --coprocessor CP_NETWORK - nrfjprog --recover - - #. Repeat steps 5 and 6 to program both cores again. - -#. 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: - - .. code-block:: console - - nrfjprog --memwr 0x00FF80F4 --val 0 - - * Right headset: - - .. code-block:: console - - nrfjprog --memwr 0x00FF80F4 --val 1 - - Select the correct board when prompted with the popup or add the ``--snr`` parameter followed by the SEGGER serial number of the correct board at the end of the ``nrfjprog`` command. - - -.. _nrf53_audio_app_testing: - -Testing -======= - -After building and programming the application, you can test it for both the CIS and the BIS modes. -The following testing scenarios assume you are using USB as the audio source on the gateway. -This is the default setting. - -.. _nrf53_audio_app_testing_steps_cis: - -Testing the default CIS mode ----------------------------- - -Complete the following steps to test the unidirectional CIS mode for one gateway and two headset devices: - -1. Make sure that the development kits are still plugged into the USB ports and are turned on. - - .. note:: - |usb_known_issues| - - After programming, **RGB2** starts blinking green on every device to indicate the ongoing CPU activity on the network core. - **LED3** starts blinking green on every device to indicate the ongoing CPU activity on the application core. -#. Wait for the **LED1** on the gateway to start blinking blue. - This happens shortly after programming the development kit and indicates that the gateway device is connected to at least one headset and ready to send data. -#. Search the list of audio devices listed in the sound settings of your operating system for *nRF5340 USB Audio* (gateway) and select it as the output device. -#. Connect headphones to the **HEADPHONE** audio jack on both headset devices. -#. Start audio playback on your PC from any source. -#. Wait for **LED1** to blink blue on both headsets. - When they do, the audio stream has started on both headsets. - - .. note:: - The audio outputs only to the left channel of the audio jack, even if the given headset is configured as the right headset. - This is because of the mono hardware codec chip used on the development kits. - If you want to play stereo sound using one development kit, you must connect an external hardware codec chip that supports stereo. - -#. Wait for **LED2** to light up solid green on the headsets to indicate that the audio synchronization is achieved. -#. Press the **VOL+** button on one of the headsets. - The playback volume increases for both headsets. -#. Press the **VOL-** button on the gateway. - The playback volume decreases for both headsets. -#. Press the **PLAY/PAUSE** button on any one of the devices. - The playback stops for both headsets and the streaming state for all devices is set to paused. -#. Press the **RESET** button on the gateway. - The gateway resets and the playback on the unpaused headset stops. - After some time, the gateway establishes the connection with both headsets and resumes the playback on the unpaused headset. -#. Press the **PLAY/PAUSE** button on any one of the devices. - The playback resumes in both headsets. -#. Press the **BTN 4** button on the gateway multiple times. - For each button press, the audio stream playback is stopped and the gateway sends a test tone to both headsets. - These tones can be used as audio cues to check the synchronization of the headsets. -#. Hold down the **VOL+** button and press the **RESET** button on the left headset. - After startup, this headset will be configured as the right channel headset. -#. Hold down the **VOL-** button and press the **RESET** button on the left headset. - After startup, this headset will go back to be configured as the left channel headset. - You can also just press the **RESET** button to restore the original programmed settings. - -After the kits have paired for the first time, they are now bonded. -This means the Long-Term Key (LTK) is stored on each side, and that the kits will only connect to each other unless the bonding information is cleared. -To clear the bonding information, press and hold **BTN 5** during boot. - -When you finish testing, power off the nRF5340 Audio development kits by switching the power switch from On to Off. - -.. _nrf53_audio_app_testing_steps_bis: - -Testing the BIS mode --------------------- - -Testing the BIS mode is identical to `Testing the default CIS mode`_, except for the following differences: - -* You must :ref:`select the BIS mode manually ` before building the application. -* You can play the audio stream with different audio settings on the receivers. - For example, you can decrease or increase the volume separately for each receiver during playback. -* When pressing the **PLAY/PAUSE** button on a headset, the streaming state only changes for that given headset. -* Pressing the **PLAY/PAUSE** button on the gateway will respectively start or stop the stream for all headsets listening in. -* Pressing the **BTN 4** button on a headset will change the active audio stream. - The default configuration of the BIS mode supports two audio streams (left and right). -* Pressing the **BTN 5** button on a headset will change the gateway source for the audio stream (after `Enabling the BIS mode with two gateways`_). - If a second gateway is not present, the headset will not play audio. - -.. _nrf53_audio_app_testing_steps_cis_walkie_talkie: - -Testing the walkie-talkie demo ------------------------------- - -Testing the walkie-talkie demo is identical to `Testing the default CIS mode`_, except for the following differences: - -* You must enable the Kconfig option mentioned in `Enabling the walkie-talkie demo`_ before building the application. -* Instead of controlling the playback, you can speak through the PDM microphones. - The line is open all the time, no need to press any buttons to talk, but the volume control works as in `Testing the default CIS mode`_. - -.. _nrf53_audio_app_porting_guide: - -Testing FOTA upgrades ---------------------- - -`nRF Connect Device Manager`_ can be used for testing FOTA upgrades. -The procedure for upgrading the firmware is identical for both headset and gateway firmware. -You can test upgrading the firmware on both cores at the same time on a headset device by completing the following steps: - -1. Make sure you have :ref:`configured the application for FOTA `. -#. Install `nRF Connect Device Manager`_ on your Android or iOS device. -#. Connect an external flash shield to the headset. -#. Make sure the headset runs a firmware that supports DFU using external flash memory. - One way of doing this is to connect the headset to the USB port, turn it on, and then run this command: - - .. code-block:: console - - python buildprog.py -c both -b debug -d headset --pristine -m external -p - - .. note:: - When using the FOTA related functionality in the :file:`buildprog.py` script on Linux, the ``python`` command must execute Python 3. - -#. Use the :file:`buildprog.py` script to create a zip file that contains new firmware for both cores: - - .. code-block:: console - - python buildprog.py -c both -b debug -d headset --pristine -m external - -#. Transfer the generated file to your Android or iOS device, depending on the DFU scenario. - See the `FOTA build files`_ section for information about FOTA file name patterns. - For transfer, you can use cloud services like Google Drive for Android or iCloud for iOS. -#. Enter the DFU mode by pressing and holding down **RESET** and **BTN 4** at the same time, and then releasing **RESET** while continuing to hold down **BTN 4** for a couple more seconds. -#. Open `nRF Connect Device Manager`_ and look for ``NRF5340_AUDIO_HL_DFU`` in the scanned devices window. - The headset is left by default. -#. Tap on :guilabel:`NRF5340_AUDIO_HL_DFU` and then on the downward arrow icon at the bottom of the screen. -#. In the :guilabel:`Firmware Upgrade` section, tap :guilabel:`SELECT FILE`. -#. Select the file you transferred to the device. -#. Tap :guilabel:`START` and check :guilabel:`Confirm only` in the notification. -#. Tap :guilabel:`START` again to start the DFU process. -#. When the DFU has finished, verify that the new application core and network core firmware works properly. - -Dependencies -************ - -.. note:: - The following lists mention the most important dependencies. - For the full list, check the application's Kconfig options. - All dependencies are automatically included. - -The application uses the following |NCS| components: - -* :ref:`lib_bt_ll_acs_nrf53_readme` -* :ref:`lib_contin_array` -* :ref:`lib_pcm_mix` -* :ref:`lib_tone` - -This application uses the following `nrfx`_ libraries: - -* :file:`nrfx_clock.h` -* :file:`nrfx_gpiote.h` -* :file:`nrfx_timer.h` -* :file:`nrfx_dppi.h` -* :file:`nrfx_i2s.h` -* :file:`nrfx_ipc.h` -* :file:`nrfx_nvmc.h` - -The application also depends on the following Zephyr libraries: - -* :ref:`zephyr:logging_api` -* :ref:`zephyr:kernel_api` -* :ref:`zephyr:zbus` -* :ref:`zephyr:api_peripherals`: - - * :ref:`zephyr:usb_api` - -* :ref:`zephyr:bluetooth_api`: - - * :file:`include/bluetooth/bluetooth.h` - * :file:`include/bluetooth/gatt.h` - * :file:`include/bluetooth/hci.h` - * :file:`include/bluetooth/uuid.h` - -.. _nrf53_audio_app_options: -.. _config_nrf53_audio_app_options: - -Application configuration options -********************************* - -.. options-from-kconfig:: - :show-type: - -.. |usb_known_issues| replace:: Make sure to check the :ref:`nRF5340 Audio application known issues ` related to serial connection with the USB. diff --git a/applications/nrf5340_audio/broadcast_sink/README.rst b/applications/nrf5340_audio/broadcast_sink/README.rst new file mode 100644 index 000000000000..a184542cb7b3 --- /dev/null +++ b/applications/nrf5340_audio/broadcast_sink/README.rst @@ -0,0 +1,98 @@ +.. _nrf53_audio_broadcast_sink_app: + +nRF5340 Audio: Broadcast sink +############################# + +.. contents:: + :local: + :depth: 2 + +The nRF5340 Audio broadcast sink application implements the :ref:`BIS headset mode `. +In this mode, receiving broadcast audio happens using Broadcast Isochronous Stream (BIS) and Broadcast Isochronous Group (BIG). + +The following limitations apply to this application: + +* One BIG, one of the two BIS streams (selectable). +* Audio output: I2S/Analog headset output. +* Configuration: 16 bit, several bit rates ranging from 32 kbps to 124 kbps. + +.. _nrf53_audio_broadcast_sink_app_requirements: + +Requirements +************ + +The application shares the :ref:`requirements common to all nRF5340 Audio application `. + +.. _nrf53_audio_broadcast_sink_app_ui: + +User interface +************** + +Most of the user interface mappings are common across all nRF5340 Audio applications. +See the :ref:`nrf53_audio_app_ui` page for detailed overview. + +This application uses specific mapping for the following user interface elements: + +* Long-pressed on the broadcast sink device during startup: + + * **VOL-** - Changes the headset to the left channel one. + * **VOL+** - Changes the headset to the right channel one. + +* Pressed on the broadcast sink device during playback: + + * **PLAY/PAUSE** - Starts or pauses listening to the stream. + * **VOL-** - Turns the playback volume down. + * **VOL+** - Turns the playback volume up. + * **BTN 4** - Changes audio stream (different BIS), if more than one is available. + * **BTN 5** - Changes the gateway, if more than one is available. + +* **LED1**: + + * Solid blue - Devices have synchronized with a broadcasted stream. + * Blinking blue - Devices have started streaming audio (BIS mode). + +* **RGB**: + + * Solid blue - The device is programmed as the left headset. + * Solid magenta - The device is programmed as the right headset. + +.. _nrf53_audio_broadcast_sink_app_configuration: + +Configuration +************* + +See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications. + +For information about how to configure applications in the |NCS|, see :ref:`modifying`. + +.. _nrf53_audio_broadcast_sink_app_building: + +Building and running +******************** + +This application can be found under :file:`applications/nrf5340_audio/broadcast_sink` in the nRF Connect SDK folder structure. + +The nRF5340 Audio DK comes preprogrammed with basic firmware that indicates if the kit is functional. +See :ref:`nrf53_audio_app_dk_testing_out_of_the_box` for more information. + +To build the application, see :ref:`nrf53_audio_app_building`. + +.. _nrf53_audio_broadcast_sink_app_testing: + +Testing +******* + +.. note:: + |nrf5340_audio_external_devices_note| + +To test the broadcast sink application, complete the following steps: + +1. Make sure you have another nRF5340 Audio DK for testing purposes. +#. Program the other DK with the :ref:`broadcast source ` application. + The broadcast sink device automatically synchronizes with the broadcast source after programming. +#. Proceed to testing the devices using the :ref:`nrf53_audio_broadcast_sink_app_ui` buttons and LEDs. + +Dependencies +************ + +For the list of dependencies, check the application's source files under :file:`applications/nrf5340_audio/broadcast_sink`. diff --git a/applications/nrf5340_audio/broadcast_source/README.rst b/applications/nrf5340_audio/broadcast_source/README.rst new file mode 100644 index 000000000000..7a0c283d8adc --- /dev/null +++ b/applications/nrf5340_audio/broadcast_source/README.rst @@ -0,0 +1,88 @@ +.. _nrf53_audio_broadcast_source_app: + +nRF5340 Audio: Broadcast source +############################### + +.. contents:: + :local: + :depth: 2 + +The nRF5340 Audio broadcast source application implements the :ref:`BIS gateway mode `. + +In this mode, transmitting broadcast audio happens using Broadcast Isochronous Stream (BIS) and Broadcast Isochronous Group (BIG). +Play and pause are emulated by enabling and disabling stream, respectively. + +The following limitations apply to this application: + +* One BIG with two BIS streams. +* Audio input: USB or I2S (Line in or using Pulse Density Modulation). +* Configuration: 16 bit, several bit rates ranging from 32 kbps to 124 kbps. + +.. _nrf53_audio_broadcast_source_app_requirements: + +Requirements +************ + +The application shares the :ref:`requirements common to all nRF5340 Audio application `. + +.. _nrf53_audio_broadcast_source_app_ui: + +User interface +************** + +Most of the user interface mappings are common across all nRF5340 Audio applications. +See the :ref:`nrf53_audio_app_ui` page for detailed overview. + +This application uses specific mapping for the following user interface elements: + +* Pressed on the broadcast source device during playback: + + * **PLAY/PAUSE** - Starts or pauses the playback of the stream. + * **BTN 4** - Toggles between the normal audio stream and different test tones generated on the device. + Use this tone to check the synchronization of headsets. + +* **LED1** - Blinking blue - Device has started broadcasting audio. +* **RGB** - Solid green - The device is programmed as the gateway. + +.. _nrf53_audio_broadcast_source_app_configuration: + +Configuration +************* + +See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications. + +For information about how to configure applications in the |NCS|, see :ref:`modifying`. + +.. _nrf53_audio_broadcast_source_app_building: + +Building and running +******************** + +This application can be found under :file:`applications/nrf5340_audio/broadcast_source` in the nRF Connect SDK folder structure. + +The nRF5340 Audio DK comes preprogrammed with basic firmware that indicates if the kit is functional. +See :ref:`nrf53_audio_app_dk_testing_out_of_the_box` for more information. + +To build the application, see :ref:`nrf53_audio_app_building`. + +After programming, the broadcast source automatically starts broadcasting the default 48-kHz audio stream. + +.. _nrf53_audio_broadcast_source_app_testing: + +Testing +******* + +.. note:: + |nrf5340_audio_external_devices_note| + +To test the broadcast source application, complete the following steps: + +1. Make sure you have another nRF5340 Audio DK for testing purposes. +#. Program the other DK with the :ref:`broadcast sink ` application. + The broadcast sink device automatically synchronizes with the broadcast source after programming. +#. Proceed to testing the broadcast source using the :ref:`nrf53_audio_broadcast_source_app_ui` buttons and LEDs. + +Dependencies +************ + +For the list of dependencies, check the application's source files. diff --git a/applications/nrf5340_audio/doc/adapting_application.rst b/applications/nrf5340_audio/doc/adapting_application.rst index d31478b02fe6..8317f32ca741 100644 --- a/applications/nrf5340_audio/doc/adapting_application.rst +++ b/applications/nrf5340_audio/doc/adapting_application.rst @@ -1,18 +1,18 @@ .. _nrf53_audio_app_adapting: -Adapting nRF5340 Audio application for end products -################################################### +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` application to end products. +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 application uses the following files as 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. @@ -30,7 +30,7 @@ For detailed instructions for adding Zephyr support to a custom board, see Zephy Application configuration sources ********************************* -The application configuration source file defines a set of options used by the nRF5340 Audio application. +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. @@ -38,7 +38,7 @@ The :file:`prj.conf` file is the default configuration file and it implements th 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. -The nRF5340 Audio application also use several :file:`Kconfig.defaults` files to change configuration defaults automatically, based on the different application versions and device types. +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. diff --git a/applications/nrf5340_audio/doc/building.rst b/applications/nrf5340_audio/doc/building.rst new file mode 100644 index 000000000000..c5cac4240c21 --- /dev/null +++ b/applications/nrf5340_audio/doc/building.rst @@ -0,0 +1,294 @@ +.. _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. + +.. note:: + Building and programming the nRF5340 Audio applications is different from the :ref:`standard procedure ` of building and programming for the nRF5340 DK. + This is because the nRF5340 Audio applications only build and program the files for the application core. + |nrf5340_audio_net_core_hex_note| + +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 ` 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, which is located in the :file:`applications/nrf5340_audio/tools/buildprog` directory. +The script automates the process of selecting :ref:`configuration files ` and building different applications. +This eases the process of building and programming images for multiple 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: + +* ``nrf5340_audio_dk_snr`` -- This field lists the SEGGER serial number. + You can check this number on the sticker on the nRF5340 Audio development kit. + Alternatively, connect the development kit to your PC and run ``nrfjprog -i`` in a command window to print the SEGGER serial number of the kit. +* ``nrf5340_audio_dk_dev`` -- This field assigns the specific nRF5340 Audio development kit to be a headset or a 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 +================== + +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: + +* Core type (``-c`` parameter): ``app``, ``net``, or ``both`` +* Application version (``-b`` parameter): either ``release`` or ``debug`` +* Device type (``-d`` parameter): ``headset``, ``gateway``, or ``both`` +* DFU type (``-m`` parameter): ``internal``, ``external`` +* Network core bootloader minimal size (``-M``) + +See the following examples of the parameter usage with the command run from the :file:`buildprog` directory: + +* Example 1: 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 + +* Example 2: The following command builds headset and gateway applications using the script for both the application and the network core (``both``). + It builds with the ``release`` application version, with the DFU external flash memory layout enabled, and using the minimal size of the network core bootloader: + + .. code-block:: console + + python buildprog.py -c both -b release -d both -m external -M + +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 the :file:`applications/nrf5340_audio/build` directory. +The script creates a directory for each application version and device type combination. +For example, when running the command above, the script creates the :file:`dev_gateway/build_debug` and :file:`dev_headset/build_debug` directories. + +Programming with the script + 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 command. + + The following parameters are available for programming: + + * Programming (``-p`` parameter) -- If you run the building 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. + + The command for programming can look as follows: + + .. code-block:: console + + python buildprog.py -c both -b debug -d both -p + + This command builds the headset and the gateway applications with the ``debug`` application version and programs the application core. + Given the ``-c both`` parameter, it also takes the precompiled Bluetooth Low Energy Controller binary from the :file:`nrf/lib/bin/bt_ll_acs_nrf53/bin` directory and programs it to the network core of both the gateway and the headset. + + .. note:: + If the programming command fails because of :ref:`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 -p --recover_on_fail + + If you want to program firmware that has DFU enabled, you must include the DFU parameters in the command. + The command for programming with DFU enabled can look as follows: + + .. code-block:: console + + python buildprog.py -c both -b release -d both -m external -M -p + +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 ` for the command line. + +.. note:: + Using this method requires you to build and program each development kit one at a time before moving to the next configuration, which can be time-consuming. + :ref:`nrf53_audio_app_building_script` is recommended. + +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 options: + + * For headset device: ``-DCONFIG_AUDIO_DEV=1`` + * For gateway device: ``-DCONFIG_AUDIO_DEV=2`` + + #. Choose the application version by using one of the following options: + + * For the debug version: No build flag needed. + * For the release version: ``-DCONF_FILE=prj_release.conf`` + +#. Build the application using the standard :ref:`build steps ` 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: + + .. code-block:: console + + west build -b nrf5340_audio_dk_nrf5340_cpuapp --pristine -- -DCONFIG_AUDIO_DEV=1 -DCONF_FILE=prj_release.conf + + Unlike when :ref:`nrf53_audio_app_building_script`, this command creates the build files directly in the :file:`build` directory. + This means that you first need to program the headset development kits before you build and program gateway development kits. + Alternatively, you can add the ``-d`` parameter to the ``west`` command to specify a custom build folder. This lets you build firmware for both + headset and gateway before programming any development kits. + +Programming the application +=========================== + +After building the files for the development kit you want to program, complete the following steps to program the applications from the command line: + +1. Plug the device into the USB port. + + .. note:: + |usb_known_issues| + +#. Turn on the development kit using the On/Off switch. +#. Open a command prompt. +#. Run the following command to print the SEGGER serial number of your development kit: + + .. code-block:: console + + nrfjprog -i + + .. note:: + Pay attention to which device is to be programmed with the gateway HEX file and which devices are to be programmed with the headset HEX file. + +#. Program the network core on the development kit by running the following command: + + .. code-block:: console + + nrfjprog --program bin/*.hex --chiperase --coprocessor CP_NETWORK -r + + |nrf5340_audio_net_core_hex_note| +#. Program the application core on the development kit with the respective HEX file from the :file:`build` directory by running the following command: + + .. code-block:: console + + nrfjprog --program build/zephyr/zephyr.hex --coprocessor CP_APPLICATION --chiperase -r + + In this command, :file:`build/zephyr/zephyr.hex` is the HEX binary file for the application core. + If a custom build folder is specified, the path to this folder must be used instead of :file:`build/`. +#. If any device is not programmed due to :ref:`readback_protection_error`, complete the following steps: + + a. Run the following commands to recover the device: + + .. code-block:: console + + nrfjprog --recover --coprocessor CP_NETWORK + nrfjprog --recover + + #. Repeat steps 5 and 6 to program both cores again. + +#. 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: + + .. code-block:: console + + nrfjprog --memwr 0x00FF80F4 --val 0 + + * Right headset: + + .. code-block:: console + + nrfjprog --memwr 0x00FF80F4 --val 1 + + Select the correct board when prompted with the popup or add the ``--snr`` parameter followed by the SEGGER serial number of the correct board at the end of the ``nrfjprog`` command. diff --git a/applications/nrf5340_audio/doc/configuration.rst b/applications/nrf5340_audio/doc/configuration.rst new file mode 100644 index 000000000000..05b42af39444 --- /dev/null +++ b/applications/nrf5340_audio/doc/configuration.rst @@ -0,0 +1,72 @@ +.. _nrf53_audio_app_configuration: + +Configuring the nRF5340 Audio applications +########################################## + +.. contents:: + :local: + :depth: 2 + +|config| + +.. _nrf53_audio_app_configuration_select_bidirectional: + +Selecting the CIS unidirectional communication +********************************************** + +By default, the nRF5340 build script tries to build the applications in the CIS bidirectional mode. +To switch to the unidirectional mode, set the ``CONFIG_STREAM_BIDIRECTIONAL`` Kconfig option to ``n`` in the :file:`prj.conf` file (for the debug version) or in the :file:`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:`prj.conf` file (for the debug version) or in the :file:`prj_release.conf` file (for the release version). + +.. _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:`prj.conf` file for the debug version and in the :file:`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 ` +* :ref:`Unicast client ` +* :ref:`Unicast server ` + +The :ref:`broadcast sink application ` 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 ``-DSHIELD=nrf21540ek_fwd`` to the ``west build`` command. + For example: + + .. code-block:: console + + west build -b nrf5340_audio_dk_nrf5340_cpuapp --pristine -- -DCONFIG_AUDIO_DEV=1 -DSHIELD=nrf21540ek_fwd -DCONF_FILE=prj_release.conf + +To set the TX power output, use the ``CONFIG_NRF_21540_MAIN_TX_POWER`` and ``CONFIG_NRF_21540_PRI_ADV_TX_POWER`` Kconfig options. + +.. note:: + When you build the nRF5340 Audio application with the nRF21540 FEM support, the :ref:`lib_bt_ll_acs_nrf53_readme` does not support the +20 dBm setting. + This is because of a power class restriction in the controller's QDID. + +See :ref:`ug_radio_fem` for more information about FEM in the |NCS|. diff --git a/applications/nrf5340_audio/doc/firmware_architecture.rst b/applications/nrf5340_audio/doc/firmware_architecture.rst index ba010dc2e82e..fe67c3842cfa 100644 --- a/applications/nrf5340_audio/doc/firmware_architecture.rst +++ b/applications/nrf5340_audio/doc/firmware_architecture.rst @@ -7,50 +7,47 @@ nRF5340 Audio overview and firmware architecture :local: :depth: 2 -The application can work as a gateway or a headset. -The gateway receives the audio data from external sources (USB or I2S) and forwards it to one or more headsets. -The headset is a receiver device that plays back the audio it gets from the gateway. -It is also possible to enable a bidirectional mode where one gateway can send and receive audio to and from one or two headsets at the same time. +Each nRF5340 Audio application corresponds to one specific LE Audio role: unicast client (gateway), unicast server (headset), broadcast source (gateway), or broadcast sink (headset). +The gateway receives the audio data from external sources (USB or line input/I2S) and forwards it to one or more headsets. +The headset is a receiver device that plays back the audio it gets from the gateway, and will act as earbuds, headphones, a speaker, hearing aids, or similar. -Both device types use the same code base, but different firmware, and you need both types of devices for testing the application. -Gateways and headsets can both run in one of the available application modes, either the *connected isochronous stream* (CIS) mode or in the *broadcast isochronous stream* (BIS) mode. -The CIS mode is the default mode of the application. +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. -Changing configuration related to the device type and the application modes requires rebuilding the firmware and reprogramming the development kits. +The applications use the same code base, but use different :file:`main.c` files and include different modules and libraries depending on the configuration. -Regardless of the configuration, the application handles the audio data in the following manner: +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. -1. The gateway receives audio data from the audio source over USB or I2S. -#. The gateway processes the audio data in its application core, which channels the data through the application layers: +.. _nrf53_audio_app_overview_differences: - a. Audio data is sent to the synchronization module (I2S-based firmware) or directly to the software codec (USB-based firmware). - #. Audio data is encoded by the software codec. - #. Encoded audio data is sent to the Bluetooth LE Host. +Differences between apps +************************ -#. The host sends the encoded audio data to the LE Audio Controller Subsystem for nRF53 on the network core. -#. The subsystem forwards the audio data to the hardware radio and sends it to the headset devices, as per the LE Audio specifications. -#. The headsets receive the encoded audio data on their hardware radio on the network core side. -#. The LE Audio Controller Subsystem for nRF53 running on each of the headsets sends the encoded audio data to the Bluetooth LE Host on the headsets' application core. -#. The headsets process the audio data in their application cores, which channel the data through the application layers: +The following table summarizes the differences between the available nRF5340 Audio applications. - a. Audio data is sent to the stream control module and placed in a FIFO buffer. - #. Audio data is sent from the FIFO buffer to the synchronization module (headsets only use I2S-based firmware). - #. Audio data is decoded by the software codec. +.. list-table:: Differences between nRF5340 Audio applications + :header-rows: 1 -#. Decoded audio data is sent to the hardware audio output over I2S. - -In the `I2S-based firmware for gateway and headsets`_, sending the audio data through the application layers includes a mandatory synchronization step using the synchronization module. -This proprietary module ensures that the audio is played at the same time with the correct speed. -For more information, see `Synchronization module overview`_. + * - Application + - LE Audio mode and role + * - :ref:`Unicast client` + - CIS gateway + * - :ref:`Unicast server` + - CIS headset + * - :ref:`Broadcast sink` + - BIS gateway + * - :ref:`Broadcast source` + - BIS headset .. _nrf53_audio_app_overview_modes: Application modes ***************** -The application can work either in the *connected isochronous stream* (CIS) mode or in the *broadcast isochronous stream* (BIS) mode, depending on the chosen firmware configuration. +Each application works either in the *connected isochronous stream* (CIS) mode or in the *broadcast isochronous stream* (BIS) mode. -.. figure:: /images/octave_application_topologies.svg +.. figure:: /images/nrf5340_audio_application_topologies.png :alt: CIS and BIS mode overview CIS and BIS mode overview @@ -59,10 +56,10 @@ 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 default configuration of the nRF5340 Audio application. - In this configuration, you can use the nRF5340 Audio development kit in the role of the gateway, the left headset, or the right headset. + This is the mode available for the unicast applications (:ref:`unicast client` and :ref:`unicast server`). + 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 application, the CIS mode offers both unidirectional and bidirectional communication. + 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. @@ -73,7 +70,8 @@ Connected Isochronous Stream (CIS) 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. - In this configuration, you can use the nRF5340 Audio development kit in the role of the gateway or as one of the headsets. + This is the mode available for the broadcast applications (:ref:`broadcast source` for headset and :ref:`broadcast sink` for gateway). + 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:: @@ -88,7 +86,7 @@ Firmware architecture The following figure illustrates the software layout for the nRF5340 Audio application: -.. figure:: /images/octave_application_structure_generic.svg +.. figure:: /images/nrf5340_audio_structure_generic.svg :alt: nRF5340 Audio high-level design (overview) nRF5340 Audio high-level design (overview) @@ -120,73 +118,86 @@ These modules include the following major ones: * 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: - - * Stream Control - This module handles events from the Bluetooth modules and buttons, receives audio from one module, and forwards the audio data to the next module. - - * Currently, each of the four main device types uses a separate stream control file: - - * CIS gateway (unicast client) - :file:`streamctrl_unicast_client.c` - * CIS headset (unicast server) - :file:`streamctrl_unicast_server.c` - * BIS gateway (broadcast source) - :file:`streamctrl_broadcast_source.c` - * BIS headset (broadcast sink) - :file:`streamctrl_broadcast_sink.c` +* Application-specific custom modules, including the synchronization module (part of `I2S-based firmware for gateway and headsets`_) - See `Synchronization module overview`_ for more information. - * FIFO buffers - * Synchronization module (part of `I2S-based firmware for gateway and headsets`_) - See `Synchronization module overview`_ for more information. - -Since the application architecture is uniform and the firmware code is shared, the set of audio modules in use depends on the chosen stream mode (BIS or CIS), the chosen audio inputs and outputs (USB or analog jack), and if the gateway or the headset configuration is selected. +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 version of the application, the bootloader is disabled by default. + 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. -Communications between modules -============================== - -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 application has their message structures described in :file:`nrf5340_audio_common.h`. - -The application uses the following buses: +Communication between modules +============================= - * ``le_audio_chan`` - For handling LE Audio events from the Bluetooth stream modules, specifically :file:`unicast_client.c`, :file:`unicast_server.c`, :file:`broadcast_source.c`, and :file:`broadcast_sink.c`. - * ``button_chan`` - For handling button events from :file:`button_handler.c`. - * ``bt_mgmt_chan`` - For handling ACL events from :file:`bt_mgmt.c`. - * ``volume_chan`` - For handling volume events from :file:`bt_rend.c`. - * ``cont_media_chan`` - For handling media events from :file:`content_ctrl.c`. - -The consumer functions for each of these buses are residing, for the most part, in the stream control files. -``volume_chan`` is an exception, with its consumer functions residing directly in :file:`hw_codec.c`. -The linking of producers and consumers is done in the stream control files. +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:`nrf5340_audio_common.h`. .. _nrf53_audio_app_overview_architecture_usb: USB-based firmware for gateway ============================== -The following figure shows an overview of the modules currently included in the firmware that uses USB: - -.. figure:: /images/octave_application_structure_gateway.svg - :alt: nRF5340 Audio modules on the gateway using USB - - nRF5340 Audio modules on the gateway using USB +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 that uses I2S: +The following figure shows an overview of the modules currently included in the firmware of applications that use I2S. -.. figure:: /images/octave_application_structure.svg - :alt: nRF5340 Audio modules on the gateway and the headsets using I2S +The Bluetooth LE RX FIFO is mainly used to make :file:`audio_datapath.c` (synchronization module) run in a separate thread. - nRF5340 Audio modules on the gateway and the headsets using I2S +Broadcast source I2S-based firmware +----------------------------------- -The Bluetooth LE RX FIFO is mainly used to make :file:`audio_datapath.c` (synchronization module) run in a separate thread. -After encoding the audio data received from I2S, the frames are sent by the encoder thread using a function located in :file:`streamctrl_unicast_client.c`, :file:`streamctrl_unicast_server.c`, :file:`streamctrl_broadcast_source.c`, or :file:`streamctrl_broadcast_sink.c`. +.. 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: @@ -213,7 +224,7 @@ 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/octave_application_structure_sync_module.svg +.. figure:: /images/nrf5340_audio_structure_sync_module.svg :alt: nRF5340 Audio synchronization module overview nRF5340 Audio synchronization module overview @@ -238,7 +249,7 @@ 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/octave_application_sync_module_states.svg +.. 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 diff --git a/applications/nrf5340_audio/doc/fota.rst b/applications/nrf5340_audio/doc/fota.rst new file mode 100644 index 000000000000..03ce1d49c0cf --- /dev/null +++ b/applications/nrf5340_audio/doc/fota.rst @@ -0,0 +1,134 @@ +.. _nrf53_audio_app_fota: + +Configuring and testing FOTA upgrades for nRF5340 Audio applications +#################################################################### + +.. contents:: + :local: + :depth: 2 + +All nRF5340 Audio applications share the same configuration and testing procedures for FOTA upgrades. + +Requirements for FOTA +********************* + +To test Firmware Over-The-Air (FOTA), you need an Android or iOS device with the `nRF Connect Device Manager`_ app installed. + +To enable the external flash DFU and do FOTA upgrades for the application core and the network core at the same time, you need an external flash shield. +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 +************************* + +.. caution:: + Firmware based on the |NCS| versions earlier than v2.1.0 does not support DFU. + FOTA is not available for those versions. + + You can test performing separate application and network core upgrades, but for production, both cores must be updated at the same time. + When updates take place in the inter-core communication module (HCI IPC), communication between the cores will break if they are not updated together. + +You can configure Firmware Over-The-Air (FOTA) upgrades to replace the applications on both the application core and the network core. +The nRF5340 Audio applications support the following types of DFU flash memory layouts: + +* Internal flash memory layout - which supports only single-image DFU. +* External flash memory layout - which supports :ref:`multi-image DFU `. + +The LE Audio Controller Subsystem for nRF53 supports both the normal and minimal sizes of the bootloader. +The minimal size is specified using the :kconfig:option:`CONFIG_NETBOOT_MIN_PARTITION_SIZE`. + +Enabling FOTA upgrades +********************** + +The FOTA upgrades are only available when :ref:`nrf53_audio_app_building_script`. +With the appropriate parameters provided, the :file:`buildprog.py` Python script will add overlay files for the given DFU type. +To enable the desired FOTA functions: + +* To define flash memory layout, include the ``-m internal`` parameter for the internal layout (when using the ``release`` application version) or the ``-m external`` parameter for the external layout (when using either ``release`` or ``debug``). +* To use the minimal size network core bootloader, add the ``-M`` parameter. + +For the full list of parameters and examples, see the :ref:`nrf53_audio_app_building_script_running` section. + +FOTA build files +================ + +The generated FOTA build files use the following naming patterns: + +* For multi-image DFU, the file is called ``dfu_application.zip``. + This file updates two cores with one single file. +* For single-image DFU, the bin file for the application core is called ``app_update.bin``. + The bin file for the network core is called ``net_core_app_update.bin``. + In this scenario, the cores are updated one by one with two separate files in two actions. + +See :ref:`app_build_output_files` for more information about the image files. + +.. note:: + |nrf5340_audio_net_core_hex_note| + +Entering the DFU mode +===================== + +The |NCS| uses :ref:`SMP server and mcumgr ` as the DFU backend. +Unlike the CIS and BIS modes for gateway and headsets, the DFU mode is advertising using the SMP server service. +For this reason, to enter the DFU mode, you must long press **BTN 4** during each device startup to have the nRF5340 Audio DK enter the DFU mode. + +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 before 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. + +.. _nrf53_audio_unicast_client_app_testing_steps_fota: + +Testing FOTA upgrades +********************* + +`nRF Connect Device Manager`_ can be used for testing FOTA upgrades. +The procedure for upgrading the firmware is identical for all applications. + +Testing FOTA upgrades on a headset device +========================================= + +You can test upgrading the firmware on both cores at the same time on a headset device by completing the following steps: + +1. Make sure you have :ref:`configured the application for FOTA `. +#. Install `nRF Connect Device Manager`_ on your Android or iOS device. +#. Connect an external flash shield to the headset. +#. Make sure the headset runs a firmware that supports DFU using external flash memory. + One way of doing this is to connect the headset to the USB port, turn it on, and then run this command: + + .. code-block:: console + + python buildprog.py -c both -b debug -d headset --pristine -m external -p + + .. note:: + When using the FOTA related functionality in the :file:`buildprog.py` script on Linux, the ``python`` command must execute Python 3. + +#. Use the :file:`buildprog.py` script to create a zip file that contains new firmware for both cores: + + .. code-block:: console + + python buildprog.py -c both -b debug -d headset --pristine -m external + +#. Transfer the generated file to your Android or iOS device, depending on the DFU scenario. + See the `FOTA build files`_ section for information about FOTA file name patterns. + For transfer, you can use cloud services like Google Drive for Android or iCloud for iOS. +#. Enter the DFU mode by pressing and holding down **RESET** and **BTN 4** at the same time, and then releasing **RESET** while continuing to hold down **BTN 4** for a couple more seconds. +#. Open `nRF Connect Device Manager`_ and look for ``NRF5340_AUDIO_HL_DFU`` in the scanned devices window. + The headset is left by default. +#. Tap on :guilabel:`NRF5340_AUDIO_HL_DFU` and then on the downward arrow icon at the bottom of the screen. +#. In the :guilabel:`Firmware Upgrade` section, tap :guilabel:`SELECT FILE`. +#. Select the file you transferred to the device. +#. Tap :guilabel:`START` and check :guilabel:`Confirm only` in the notification. +#. Tap :guilabel:`START` again to start the DFU process. +#. When the DFU has finished, verify that the new application core and network core firmware works properly. diff --git a/applications/nrf5340_audio/doc/index.rst b/applications/nrf5340_audio/doc/index.rst deleted file mode 100644 index ffb0eaf8148f..000000000000 --- a/applications/nrf5340_audio/doc/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _nrf53_audio_app: - -nRF5340 Audio -############# - -.. contents:: - :local: - :depth: 2 - -The nRF5340 Audio application demonstrates audio playback over isochronous channels (ISO) using LC3 codec compression and decompression, as per `Bluetooth® LE Audio specifications`_. - -.. note:: - There is an ongoing process of restructuring the nRF5340 Audio application project. - Several drivers and modules within the application folder are being moved to more suitable locations in the |NCS| or Zephyr. - Before this process has finished, developing out-of-tree applications can be more complex. - -.. note:: - This application and its DFU/FOTA functionality are marked as :ref:`experimental `. - -See the subpages for detailed documentation on the application and its internal modules: - -.. _nrf53_audio_app_subpages: - -.. toctree:: - :maxdepth: 1 - :caption: Subpages: - - firmware_architecture - feature_support - ../README - adapting_application diff --git a/applications/nrf5340_audio/doc/requirements.rst b/applications/nrf5340_audio/doc/requirements.rst new file mode 100644 index 000000000000..2e92c8047cf1 --- /dev/null +++ b/applications/nrf5340_audio/doc/requirements.rst @@ -0,0 +1,66 @@ +.. _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 `, 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 on Nordic Semiconductor Infocenter for more information about this development kit. + +You can :ref:`test the DK 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. + +In addition, the application features the :file:`child_image` directory with an experimental :file:`hci_ipc.conf`. +This file is a work-in-progress implementation of the SoftDevice Controller that has not been thoroughly tested and is currently not meant for production. +The application is only tested using :ref:`lib_bt_ll_acs_nrf53_readme`. diff --git a/applications/nrf5340_audio/doc/user_interface.rst b/applications/nrf5340_audio/doc/user_interface.rst new file mode 100644 index 000000000000..ae2121b8ef46 --- /dev/null +++ b/applications/nrf5340_audio/doc/user_interface.rst @@ -0,0 +1,159 @@ +.. _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`. | | +| +-----------------------------------------------------------------------------------------------------------+---------------------------------------------+ +| | 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). | | ++--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+ +| **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. | | ++--------------------------+-----------------------------------------------------------------------------------------------------------+---------------------------------------------+ diff --git a/applications/nrf5340_audio/index.rst b/applications/nrf5340_audio/index.rst new file mode 100644 index 000000000000..5bf9ba60a4df --- /dev/null +++ b/applications/nrf5340_audio/index.rst @@ -0,0 +1,30 @@ +.. _nrf53_audio_app: + +nRF5340 Audio applications +########################## + +The nRF5340 Audio applications demonstrate audio playback over isochronous channels (ISO) using LC3 codec compression and decompression, as per `Bluetooth® LE Audio specifications`_. + +.. note:: + nRF5340 Audio applications and their DFU/FOTA functionality are marked as :ref:`experimental `. + +See the subpages for detailed documentation of each of the nRF5340 applications and their internal modules: + +.. _nrf53_audio_app_subpages: + +.. toctree:: + :maxdepth: 1 + :caption: Subpages: + + doc/firmware_architecture + doc/feature_support + doc/requirements + doc/user_interface + doc/configuration + doc/building + broadcast_sink/README + broadcast_source/README + unicast_client/README + unicast_server/README + doc/fota + doc/adapting_application diff --git a/applications/nrf5340_audio/unicast_client/README.rst b/applications/nrf5340_audio/unicast_client/README.rst new file mode 100644 index 000000000000..b94a8c1a607e --- /dev/null +++ b/applications/nrf5340_audio/unicast_client/README.rst @@ -0,0 +1,141 @@ +.. _nrf53_audio_unicast_client_app: + +nRF5340 Audio: Unicast client +############################# + +.. contents:: + :local: + :depth: 2 + +The nRF5340 Audio unicast client application implements the :ref:`CIS gateway mode `. + +In this mode, one Connected Isochronous Group (CIG) can be used with two Connected Isochronous Streams (CIS). +Transmitting unidirectional or transceiving bidirectional audio happens using CIG and CIS. + +The following limitations apply to this application: + +* One CIG with two CIS. +* Audio input: USB or I2S (Line in or using Pulse Density Modulation). +* Audio output: USB or I2S/Analog headset output. +* Configuration: 16 bit, several bit rates ranging from 32 kbps to 124 kbps. + +.. _nrf53_audio_unicast_client_app_requirements: + +Requirements +************ + +The application shares the :ref:`requirements common to all nRF5340 Audio application `. + +.. _nrf53_audio_unicast_client_app_ui: + +User interface +************** + +Most of the user interface mappings are common across all nRF5340 Audio applications. +See the :ref:`nrf53_audio_app_ui` page for detailed overview. + +This application uses specific mapping for the following user interface elements: + +* Long-pressed on the unicast client device during startup: + + * **BTN5** - Clears the previously stored bonding information. + +* Pressed on the unicast client device during playback: + + * **PLAY/PAUSE** - Starts or pauses the playback of the stream. + * **VOL-** - Turns the playback volume down (and unmutes). + * **VOL+** - Turns the playback volume up (and unmutes). + * **BTN 4** - Sends a test tone generated on the device. Use this tone to check the synchronization of headsets. + * **BTN5** - Mutes the playback volume (and unmutes). + +* **LED1** - Blinking blue - Kit is streaming audio to a headset. +* **RGB** - Solid green - The device is programmed as the gateway. + +.. _nrf53_audio_unicast_client_app_configuration: + +Configuration +************* + +See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications. + +For information about how to configure applications in the |NCS|, see :ref:`modifying`. + +.. _nrf53_audio_unicast_client_app_building: + +Building and running +******************** + +This application can be found under :file:`applications/nrf5340_audio/unicast_client` in the nRF Connect SDK folder structure. + +The nRF5340 Audio DK comes preprogrammed with basic firmware that indicates if the kit is functional. +See :ref:`nrf53_audio_app_dk_testing_out_of_the_box` for more information. + +To build the application, see :ref:`nrf53_audio_app_building`. + +.. _nrf53_audio_unicast_client_app_testing: + +Testing +******* + +After building and programming the application, you can test the default CIS gateway mode using one unicast client device and at least one CIS headset device. +The recommended approach is to use another nRF5340 Audio DK programmed with the :ref:`unicast server application `, but you can also use an external CIS headset device. + +.. note:: + |nrf5340_audio_external_devices_note| + +The following testing scenario assumes you are using USB as the audio source on the gateway. +This is the default setting. + +Complete the following steps to test the unidirectional CIS mode for one gateway and at least one headset device: + +1. Make sure that the development kits are still plugged into the USB ports and are turned on. + + .. note:: + |usb_known_issues| + + **LED3** starts blinking green on every device to indicate the ongoing CPU activity on the application core. +#. Wait for the **LED1** on the gateway to start blinking blue. + This happens shortly after programming the development kit and indicates that the gateway device is connected to at least one headset and ready to send data. +#. Search the list of audio devices listed in the sound settings of your operating system for *nRF5340 USB Audio* (gateway) and select it as the output device. +#. Connect headphones to the **HEADPHONE** audio jack on the headset device. +#. Start audio playback on your PC from any source. +#. Wait for **LED1** to blink blue on the headset. + When they do, the audio stream has started on the headset. + + .. note:: + The audio outputs only to the left channel of the audio jack, even if the given headset is configured as the right headset. + This is because of the mono hardware codec chip used on the development kits. + If you want to play stereo sound using one development kit, you must connect an external hardware codec chip that supports stereo. + +#. Wait for **LED2** to light up solid green on the headsets to indicate that the audio synchronization is achieved. +#. Press the **VOL-** button on the gateway. + The playback volume decreases for the headset. +#. Press the **PLAY/PAUSE** button on any one of the devices. + The playback stops for the headset and the streaming state for all devices is set to paused. +#. Press the **BTN 4** button on the gateway multiple times. + For each button press, the audio stream playback is stopped and the gateway sends a test tone to the headset. + These tones can be used as audio cues to check the synchronization between two headsets. + +For other testing options, refer to :ref:`nrf53_audio_unicast_client_app_ui`. + +After the kits have paired for the first time, they are now bonded. +This means the Long-Term Key (LTK) is stored on each side, and that the kits will only connect to each other unless the bonding information is cleared. +To clear the bonding information, press and hold **BTN 5** during boot or reprogram all the development kits. + +When you finish testing, power off the nRF5340 Audio development kits by switching the power switch from On to Off. + +.. _nrf53_audio_unicast_client_app_testing_steps_cis_walkie_talkie: + +Testing the walkie-talkie demo +============================== + +Testing the walkie-talkie demo is identical to the default testing procedure, except for the following differences: + +* You must enable the Kconfig option mentioned in :ref:`nrf53_audio_app_configuration_enable_walkie_talkie` before building the application. +* Instead of controlling the playback, you can speak through the PDM microphones. + The line is open all the time, no need to press any buttons to talk, but the volume control works as in the default testing procedure. + +Dependencies +************ + +For the list of dependencies, check the application's source files. diff --git a/applications/nrf5340_audio/unicast_server/README.rst b/applications/nrf5340_audio/unicast_server/README.rst new file mode 100644 index 000000000000..fdcd4300fe0f --- /dev/null +++ b/applications/nrf5340_audio/unicast_server/README.rst @@ -0,0 +1,146 @@ +.. _nrf53_audio_unicast_server_app: + +nRF5340 Audio: Unicast server +############################# + +.. contents:: + :local: + :depth: 2 + +The nRF5340 Audio unicast server application implements the :ref:`CIS headset mode `. + +In this mode, one Connected Isochronous Group (CIG) can be used with two Connected Isochronous Streams (CIS). +Receiving unidirectional or transceiving bidirectional audio happens using CIG and CIS. +In addition, Coordinated Set Identification Service (CSIS) is implemented on the server side. + +The following limitations apply to this application: + +* One CIG, one of the two CIS streams (selectable). +* Audio output: I2S/Analog headset output. +* Audio input: PDM microphone over I2S. +* Configuration: 16 bit, several bit rates ranging from 32 kbps to 124 kbps. + +.. _nrf53_audio_unicast_server_app_requirements: + +Requirements +************ + +The application shares the :ref:`requirements common to all nRF5340 Audio application `. + +.. _nrf53_audio_unicast_server_app_ui: + +User interface +************** + +Most of the user interface mappings are common across all nRF5340 Audio applications. +See the :ref:`nrf53_audio_app_ui` page for detailed overview. + +This application uses specific mapping for the following user interface elements: + +* Long-pressed on the unicast server device during startup: + + * **VOL-** - Changes the headset to the left channel one. + * **VOL+** - Changes the headset to the right channel one. + * **BTN5** - Clears the previously stored bonding information. + +* Pressed on the unicast server device during playback: + + * **PLAY/PAUSE** - Starts or pauses the playback of the stream. + * **VOL-** - Turns the playback volume down. + * **VOL+** - Turns the playback volume up. + * **BTN5** - Mutes the playback volume (and unmutes). + +* **LED1** - Blinking blue - Kits have started streaming audio. +* **RGB**: + + * Solid blue - The device is programmed as the left headset. + * Solid magenta - The device is programmed as the right headset. + +.. _nrf53_audio_unicast_server_app_configuration: + +Configuration +************* + +See :ref:`nrf53_audio_app_configuration` and :ref:`nrf53_audio_app_fota` for configuration options common to all nRF5340 Audio applications. + +For information about how to configure applications in the |NCS|, see :ref:`modifying`. + +.. _nrf53_audio_unicast_server_app_building: + +Building and running +******************** + +This application can be found under :file:`applications/nrf5340_audio/unicast_server` in the nRF Connect SDK folder structure. + +The nRF5340 Audio DK comes preprogrammed with basic firmware that indicates if the kit is functional. +See :ref:`nrf53_audio_app_dk_testing_out_of_the_box` for more information. + +To build the application, see :ref:`nrf53_audio_app_building`. + +.. _nrf53_audio_unicast_server_app_testing: + +Testing +******* + +After building and programming the application, you can test the default CIS headset mode using one :ref:`unicast client application ` and one or two unicast server devices (this application). +The recommended approach is to use two other nRF5340 Audio DKs programmed with the :ref:`unicast client application ` for the CIS gateway and the unicast server application (this application) for the CIS headset, respectively, but you can also use an external device that supports the role of unicast server. + +.. note:: + |nrf5340_audio_external_devices_note| + +The following testing scenario assumes you are using USB as the audio source on the gateway. +This is the default setting. + +Complete the following steps to test the unidirectional CIS mode for one gateway and two headset devices: + +1. Make sure that the development kits are still plugged into the USB ports and are turned on. + + .. note:: + |usb_known_issues| + + **LED3** starts blinking green on every device to indicate the ongoing CPU activity on the application core. +#. Wait for the **LED1** on the gateway to start blinking blue. + This happens shortly after programming the development kit and indicates that the gateway device is connected to at least one headset and ready to send data. +#. Search the list of audio devices listed in the sound settings of your operating system for *nRF5340 USB Audio* (gateway) and select it as the output device. +#. Connect headphones to the **HEADPHONE** audio jack on both headset devices. +#. Start audio playback on your PC from any source. +#. Wait for **LED1** to blink blue on the headset. + When they do, the audio stream has started on the headset. + + .. note:: + The audio outputs only to the left channel of the audio jack, even if the given headset is configured as the right headset. + This is because of the mono hardware codec chip used on the development kits. + If you want to play stereo sound using one development kit, you must connect an external hardware codec chip that supports stereo. + +#. Wait for **LED2** to light up solid green on the headsets to indicate that the audio synchronization is achieved. +#. Press the **VOL+** button on one of the headsets. + The playback volume increases for the headset. +#. If you use more than one headset, hold down the **VOL+** button and press the **RESET** button on a headset. + After startup, this headset will be configured as the right channel headset. +#. If you use more than one headset, hold down the **VOL-** button and press the **RESET** button on a headset. + After startup, this headset will be configured as the left channel headset. + You can also just press the **RESET** button to restore the original programmed settings. + +For other testing options, refer to :ref:`nrf53_audio_unicast_server_app_ui`. + +After the kits have paired for the first time, they are now bonded. +This means the Long-Term Key (LTK) is stored on each side, and that the kits will only connect to each other unless the bonding information is cleared. +To clear the bonding information, press and hold **BTN 5** during boot or reprogram all the development kits. + +When you finish testing, power off the nRF5340 Audio development kits by switching the power switch from On to Off. + +.. _nrf53_audio_unicast_server_app_testing_steps_cis_walkie_talkie: + +Testing the walkie-talkie demo +============================== + +Testing the walkie-talkie demo is identical to the default testing procedure, except for the following differences: + +* You must enable the Kconfig option mentioned in :ref:`nrf53_audio_app_configuration_enable_walkie_talkie` before building the application. +* Instead of controlling the playback, you can speak through the PDM microphones. + The line is open all the time, no need to press any buttons to talk, but the volume control works as in the default testing procedure. + +Dependencies +************ + +For the list of dependencies, check the application's source files. diff --git a/doc/nrf/applications.rst b/doc/nrf/applications.rst index 00ee65eceb6e..ddec67d977e5 100644 --- a/doc/nrf/applications.rst +++ b/doc/nrf/applications.rst @@ -20,7 +20,7 @@ You can also run them on different hardware like a generic development kit, but ../../applications/asset_tracker_v2/README ../../applications/serial_lte_modem/README ../../applications/nrf_desktop/README - ../../applications/nrf5340_audio/doc/index + ../../applications/nrf5340_audio/index ../../applications/machine_learning/README ../../applications/matter_weather_station/README ../../applications/zigbee_weather_station/README diff --git a/doc/nrf/images/nrf5340_audio_application_topologies.png b/doc/nrf/images/nrf5340_audio_application_topologies.png new file mode 100644 index 000000000000..fd24b97ef318 Binary files /dev/null and b/doc/nrf/images/nrf5340_audio_application_topologies.png differ diff --git a/doc/nrf/images/nrf5340_audio_broadcast_sink_I2S_structure.svg b/doc/nrf/images/nrf5340_audio_broadcast_sink_I2S_structure.svg new file mode 100644 index 000000000000..0aa39d59a33e --- /dev/null +++ b/doc/nrf/images/nrf5340_audio_broadcast_sink_I2S_structure.svg @@ -0,0 +1,470 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Nordic Blue + + + + Nordic Blue.6 + LE Audio Controller Subsystem for nRF53 + + LE Audio Controller Subsystem for nRF53 + + Nordic Blue.7 + Radio + + Radio + + Nordic Blue.8 + UART (debug) + + UART (debug) + + Nordic Blue.9 + UART (debug) + + UART (debug) + + Nordic Blue.10 + TWI/I2C + + TWI/I2C + + Nordic Blue.11 + SPI4 + + SPI4 + + Nordic Blue.12 + SD card + + SD card + + Nordic Blue.13 + HW codec (CS47L63) + + HW codec (CS47L63) + + Nordic Blue.14 + Power module (INA231) + + Power module (INA231) + + Nordic Blue.15 + Error handler + + Error handler + + Nordic Blue.16 + Buttons + + Buttons + + Nordic Blue.17 + LEDs + + LEDs + + Dynamic connector + + + + Nordic Blueslate + Synchronization module (audio_datapath.c) + + Synchronization module (audio_datapath.c) + + Nordic Lake + audio_i2s.c + + audio_i2s.c + + Nordic Blue.25 + + + + Dynamic connector.26 + + + + Dynamic connector.29 + + + + Nordic Lake.30 + I2S (audio) + + I2S (audio) + + Nordic Sky + audio_sync_timer.c + + audio_sync_timer.c + + Nordic Blue.33 + + + + Sheet.264 + Network core + + Network core + + Sheet.265 + Application core + + Application core + + Nordic Middle Grey.42 + + + + Dynamic connector.44 + + + + Dynamic connector.45 + + + + Dynamic connector.46 + + + + Sheet.273 + bad_frame + + bad_frame + + Sheet.274 + sdu_ref + + sdu_ref + + Sheet.275 + bad_frame + + bad_frame + + Sheet.276 + sdu_ref + + sdu_ref + + Dynamic connector.72 + + + + Dynamic connector.73 + + + + Dynamic connector.74 + + + + Sheet.281 + cur_time + + cur_time + + Dynamic connector.77 + + + + Sheet.283 + frame_start_ts + + frame_start_ts + + Dynamic connector.80 + + + + Dynamic connector.81 + + + + Dynamic connector.82 + + + + Sheet.287 + HCI IPC + + HCI IPC + + Sheet.288 + Audio modules + + Audio modules + + Dynamic connector.86 + + + + Dynamic connector.87 + + + + Sheet.291 + + Nordic Blue.24 + + + + Sheet.293 + Peripheral modules + + Peripheral modules + + + Nordic Blue.103 + + + + Nordic Lake.104 + + + + Dynamic connector.105 + + + + Sheet.297 + Control data + + Control data + + Dynamic connector.107 + + + + Sheet.299 + Compressed audio + + Compressed audio + + Dynamic connector.109 + + + + Sheet.301 + Uncompressed audio + + Uncompressed audio + + Nordic Lake.111 + + + + Sheet.303 + Block working on compressed audio + + Block working on compressed audio + + Sheet.304 + Block working on uncompressed audio + + Block working on uncompressed audio + + Nordic Lake.114 + + + + Sheet.306 + HW layer element + + HW layer element + + Nordic Lake.115 + + + + Sheet.308 + Peripheral module + + Peripheral module + + Nordic Lake.117 + + + + Sheet.310 + Large main module + + Large main module + + Sheet.311 + Application source files + + Application source files + + Nordic Lake.120 + + + + Nordic Lake.121 + + + + Nordic Lake.123 + + + + Sheet.315 + Synchronization module + + Synchronization module + + Dynamic connector.126 + + + + Nordic Blue.128 + Bluetooth LE Host + + Bluetooth LE Host + + Dynamic connector.129 + + + + Dynamic connector.130 + + + + Dynamic connector.131 + + + + Nordic Blue.129 + + + + Sheet.322 + Bluetooth modules + + Bluetooth modules + + Nordic Light Grey.142 + broadcast_sink.c + + broadcast_sink.c + + Dynamic connector.48 + + + + Dynamic connector.47 + + + + Nordic Lake.43 + Bluetooth LE RX FIFO + + Bluetooth LE RX FIFO + + Sheet.333 + main.c + + main.c + + Sheet.334 + + Nordic Light Grey.335 + sw_codec_select.c + + sw_codec_select.c + + Nordic Lake.336 + Decoder + + Decoder + + + Dynamic connector.337 + + + + diff --git a/doc/nrf/images/nrf5340_audio_broadcast_source_I2S_structure.svg b/doc/nrf/images/nrf5340_audio_broadcast_source_I2S_structure.svg new file mode 100644 index 000000000000..b3528f55ac90 --- /dev/null +++ b/doc/nrf/images/nrf5340_audio_broadcast_source_I2S_structure.svg @@ -0,0 +1,428 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Dynamic connector.68 + + + + Nordic Middle Grey + audio_system.c + + audio_system.c + + Nordic Light Grey + sw_codec_select.c + + sw_codec_select.c + + Nordic Blue + + + + Nordic Blue.6 + LE Audio Controller Subsystem for nRF53 + + LE Audio Controller Subsystem for nRF53 + + Nordic Blue.7 + Radio + + Radio + + Nordic Blue.8 + UART (debug) + + UART (debug) + + Nordic Blue.9 + UART (debug) + + UART (debug) + + Nordic Blue.10 + TWI/I2C + + TWI/I2C + + Nordic Blue.11 + SPI4 + + SPI4 + + Nordic Blue.12 + SD card + + SD card + + Nordic Blue.13 + HW codec (CS47L63) + + HW codec (CS47L63) + + Nordic Blue.14 + Power module (INA231) + + Power module (INA231) + + Nordic Blue.15 + Error handler + + Error handler + + Nordic Blue.16 + Buttons + + Buttons + + Nordic Blue.17 + LEDs + + LEDs + + Dynamic connector + + + + Nordic Blueslate + Synchronization module (audio_datapath.c) + + Synchronization module (audio_datapath.c) + + Nordic Lake + audio_i2s.c + + audio_i2s.c + + Nordic Blue.25 + ` + + ` + + Dynamic connector.26 + + + + Dynamic connector.29 + + + + Nordic Lake.30 + I2S (audio) + + I2S (audio) + + Nordic Lake.31 + I2S RX FIFO + + I2S RX FIFO + + Nordic Sky + audio_sync_timer.c + + audio_sync_timer.c + + Nordic Blue.33 + + + + Sheet.264 + Network core + + Network core + + Sheet.265 + Application core + + Application core + + Nordic Lake.37 + Encoder + + Encoder + + Dynamic connector.44 + + + + Dynamic connector.49 + + + + Dynamic connector.50 + + + + Dynamic connector.74 + + + + Dynamic connector.75 + + + + Sheet.281 + cur_time + + cur_time + + Dynamic connector.77 + + + + Sheet.283 + frame_start_ts + + frame_start_ts + + Dynamic connector.80 + + + + Dynamic connector.81 + + + + Dynamic connector.82 + + + + Sheet.287 + HCI IPC + + HCI IPC + + Sheet.288 + Audio modules + + Audio modules + + Dynamic connector.86 + + + + Dynamic connector.87 + + + + Sheet.291 + + Nordic Blue.24 + + + + Sheet.293 + Peripheral modules + + Peripheral modules + + + Nordic Blue.103 + + + + Nordic Lake.104 + + + + Dynamic connector.105 + + + + Sheet.297 + Control data + + Control data + + Dynamic connector.107 + + + + Sheet.299 + Compressed audio + + Compressed audio + + Dynamic connector.109 + + + + Sheet.301 + Uncompressed audio + + Uncompressed audio + + Nordic Lake.111 + + + + Sheet.303 + Block working on compressed audio + + Block working on compressed audio + + Sheet.304 + Block working on uncompressed audio + + Block working on uncompressed audio + + Nordic Lake.114 + + + + Sheet.306 + HW layer element + + HW layer element + + Nordic Lake.115 + + + + Sheet.308 + Peripheral module + + Peripheral module + + Nordic Lake.117 + + + + Sheet.310 + Large main module + + Large main module + + Sheet.311 + Application source files + + Application source files + + Nordic Lake.120 + + + + Nordic Lake.121 + + + + Nordic Lake.123 + + + + Sheet.315 + Synchronization module + + Synchronization module + + Dynamic connector.126 + + + + Nordic Blue.128 + Bluetooth LE Host + + Bluetooth LE Host + + Nordic Blue.129 + + + + Sheet.322 + Bluetooth modules + + Bluetooth modules + + Nordic Light Grey.139 + broadcast_source.c + + broadcast_source.c + + Dynamic connector.143 + + + + Nordic Sky.328 + main.c + + main.c + + diff --git a/doc/nrf/images/nrf5340_audio_broadcast_source_USB_structure.svg b/doc/nrf/images/nrf5340_audio_broadcast_source_USB_structure.svg new file mode 100644 index 000000000000..a4ff333b654e --- /dev/null +++ b/doc/nrf/images/nrf5340_audio_broadcast_source_USB_structure.svg @@ -0,0 +1,372 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Nordic Blue + Bluetooth LE Host + + Bluetooth LE Host + + Nordic Blue.6 + LE Audio Controller Subsystem for nRF53 + + LE Audio Controller Subsystem for nRF53 + + Nordic Blue.7 + Radio + + Radio + + Nordic Blue.8 + UART (debug) + + UART (debug) + + Nordic Blue.9 + UART (debug) + + UART (debug) + + Nordic Blue.10 + TWI/I2C + + TWI/I2C + + Nordic Blue.11 + SPI4 + + SPI4 + + Nordic Blue.12 + SD card + + SD card + + Nordic Blue.14 + Power module (INA231) + + Power module (INA231) + + Nordic Blue.15 + Error handler + + Error handler + + Nordic Blue.16 + Buttons + + Buttons + + Nordic Blue.17 + LEDs + + LEDs + + Dynamic connector + + + + Nordic Blueslate + audio_system.c + + audio_system.c + + Nordic Lake + audio_usb.c + + audio_usb.c + + Nordic Blue.25 + + + + Dynamic connector.26 + + + + Nordic Lake.30 + USB (audio) + + USB (audio) + + Nordic Blue.33 + + + + Sheet.34 + Network core + + Network core + + Sheet.36 + Application core + + Application core + + Nordic Middle Grey.42 + + + + Dynamic connector.75 + + + + Dynamic connector.80 + + + + Dynamic connector.81 + + + + Dynamic connector.82 + + + + Sheet.83 + HCI IPC + + HCI IPC + + Sheet.84 + Audio modules + + Audio modules + + Dynamic connector.86 + + + + Dynamic connector.87 + + + + Nordic Blue.88 + + + + Nordic Lake.89 + + + + Dynamic connector.90 + + + + Sheet.91 + Control data + + Control data + + Dynamic connector.93 + + + + Sheet.94 + Compressed audio + + Compressed audio + + Dynamic connector.95 + + + + Sheet.96 + Uncompressed audio + + Uncompressed audio + + Nordic Lake.97 + + + + Sheet.98 + Block working on compressed audio + + Block working on compressed audio + + Sheet.99 + Block working on uncompressed audio + + Block working on uncompressed audio + + Nordic Lake.100 + + + + Sheet.101 + HW layer element + + HW layer element + + Sheet.102 + + Nordic Blue.24 + + + + Sheet.85 + Peripheral modules + + Peripheral modules + + + Nordic Lake.104 + USB RX FIFO + + USB RX FIFO + + Nordic Light Grey + sw_codec_select.c + + sw_codec_select.c + + Nordic Lake.105 + Encoder + + Encoder + + Dynamic connector.109 + + + + Dynamic connector.114 + + + + Nordic Lake.115 + + + + Sheet.116 + Peripheral module + + Peripheral module + + Nordic Lake.117 + + + + Sheet.118 + Large main module + + Large main module + + Sheet.119 + Application source files + + Application source files + + Nordic Lake.120 + + + + Nordic Lake.121 + + + + Dynamic connector.122 + + + + Nordic Blue.129 + + + + Dynamic connector.134 + + + + Sheet.135 + Bluetooth modules + + Bluetooth modules + + Sheet.136 + main.c + + main.c + + Nordic Blue.124 + + + + Nordic Light Grey.125 + broadcast_source.c + + broadcast_source.c + + diff --git a/doc/nrf/images/octave_application_structure_generic.svg b/doc/nrf/images/nrf5340_audio_structure_generic.svg similarity index 100% rename from doc/nrf/images/octave_application_structure_generic.svg rename to doc/nrf/images/nrf5340_audio_structure_generic.svg diff --git a/doc/nrf/images/octave_application_structure_sync_module.svg b/doc/nrf/images/nrf5340_audio_structure_sync_module.svg similarity index 100% rename from doc/nrf/images/octave_application_structure_sync_module.svg rename to doc/nrf/images/nrf5340_audio_structure_sync_module.svg diff --git a/doc/nrf/images/octave_application_sync_module_states.svg b/doc/nrf/images/nrf5340_audio_sync_module_states.svg similarity index 100% rename from doc/nrf/images/octave_application_sync_module_states.svg rename to doc/nrf/images/nrf5340_audio_sync_module_states.svg diff --git a/doc/nrf/images/nrf5340_audio_unicast_client_I2S_structure.svg b/doc/nrf/images/nrf5340_audio_unicast_client_I2S_structure.svg new file mode 100644 index 000000000000..46311514fae0 --- /dev/null +++ b/doc/nrf/images/nrf5340_audio_unicast_client_I2S_structure.svg @@ -0,0 +1,512 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Dynamic connector.68 + + + + Nordic Middle Grey + audio_system.c + + audio_system.c + + Nordic Light Grey + sw_codec_select.c + + sw_codec_select.c + + Nordic Blue + + + + Nordic Blue.6 + LE Audio Controller Subsystem for nRF53 + + LE Audio Controller Subsystem for nRF53 + + Nordic Blue.7 + Radio + + Radio + + Nordic Blue.8 + UART (debug) + + UART (debug) + + Nordic Blue.9 + UART (debug) + + UART (debug) + + Nordic Blue.10 + TWI/I2C + + TWI/I2C + + Nordic Blue.11 + SPI4 + + SPI4 + + Nordic Blue.12 + SD card + + SD card + + Nordic Blue.13 + HW codec (CS47L63) + + HW codec (CS47L63) + + Nordic Blue.14 + Power module (INA231) + + Power module (INA231) + + Nordic Blue.15 + Error handler + + Error handler + + Nordic Blue.16 + Buttons + + Buttons + + Nordic Blue.17 + LEDs + + LEDs + + Dynamic connector + + + + Nordic Blueslate + Synchronization module (audio_datapath.c) + + Synchronization module (audio_datapath.c) + + Nordic Lake + audio_i2s.c + + audio_i2s.c + + Nordic Blue.25 + + + + Dynamic connector.26 + + + + Dynamic connector.29 + + + + Nordic Lake.30 + I2S (audio) + + I2S (audio) + + Nordic Lake.31 + I2S RX FIFO + + I2S RX FIFO + + Nordic Sky + audio_sync_timer.c + + audio_sync_timer.c + + Nordic Blue.33 + + + + Sheet.264 + Network core + + Network core + + Sheet.265 + Application core + + Application core + + Nordic Lake.37 + Encoder + + Encoder + + Nordic Middle Grey.42 + + + + Dynamic connector.44 + + + + Dynamic connector.45 + + + + Dynamic connector.46 + + + + Dynamic connector.49 + + + + Dynamic connector.50 + + + + Sheet.273 + bad_frame + + bad_frame + + Sheet.274 + sdu_ref + + sdu_ref + + Sheet.275 + bad_frame + + bad_frame + + Sheet.276 + sdu_ref + + sdu_ref + + Dynamic connector.72 + + + + Dynamic connector.73 + + + + Dynamic connector.74 + + + + Dynamic connector.75 + + + + Sheet.281 + cur_time + + cur_time + + Dynamic connector.77 + + + + Sheet.283 + frame_start_ts + + frame_start_ts + + Dynamic connector.80 + + + + Dynamic connector.81 + + + + Dynamic connector.82 + + + + Sheet.287 + HCI IPC + + HCI IPC + + Sheet.288 + Audio modules + + Audio modules + + Dynamic connector.86 + + + + Dynamic connector.87 + + + + Sheet.291 + + Nordic Blue.24 + + + + Sheet.293 + Peripheral modules + + Peripheral modules + + + Nordic Blue.103 + + + + Nordic Lake.104 + + + + Dynamic connector.105 + + + + Sheet.297 + Control data + + Control data + + Dynamic connector.107 + + + + Sheet.299 + Compressed audio + + Compressed audio + + Dynamic connector.109 + + + + Sheet.301 + Uncompressed audio + + Uncompressed audio + + Nordic Lake.111 + + + + Sheet.303 + Block working on compressed audio + + Block working on compressed audio + + Sheet.304 + Block working on uncompressed audio + + Block working on uncompressed audio + + Nordic Lake.114 + + + + Sheet.306 + HW layer element + + HW layer element + + Nordic Lake.115 + + + + Sheet.308 + Peripheral module + + Peripheral module + + Nordic Lake.117 + + + + Sheet.310 + Large main module + + Large main module + + Sheet.311 + Application source files + + Application source files + + Nordic Lake.120 + + + + Nordic Lake.121 + + + + Nordic Lake.123 + + + + Sheet.315 + Synchronization module + + Synchronization module + + Dynamic connector.126 + + + + Nordic Blue.128 + Bluetooth LE Host + + Bluetooth LE Host + + Dynamic connector.129 + + + + Dynamic connector.130 + + + + Dynamic connector.131 + + + + Nordic Blue.129 + + + + Sheet.322 + Bluetooth modules + + Bluetooth modules + + Nordic Light Grey.140 + unicast_client.c + + unicast_client.c + + Dynamic connector.143 + + + + Dynamic connector.48 + + + + Dynamic connector.47 + + + + Nordic Lake.43 + Bluetooth LE RX FIFO + + Bluetooth LE RX FIFO + + Sheet.333 + main.c + + main.c + + Dynamic connector.339 + + + + Sheet.340 + + Nordic Light Grey.335 + sw_codec_select.c + + sw_codec_select.c + + Nordic Lake.336 + Decoder + + Decoder + + + diff --git a/doc/nrf/images/nrf5340_audio_unicast_client_USB_structure.svg b/doc/nrf/images/nrf5340_audio_unicast_client_USB_structure.svg new file mode 100644 index 000000000000..70e63997ee86 --- /dev/null +++ b/doc/nrf/images/nrf5340_audio_unicast_client_USB_structure.svg @@ -0,0 +1,443 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Nordic Blue + Bluetooth LE Host + + Bluetooth LE Host + + Nordic Blue.6 + LE Audio Controller Subsystem for nRF53 + + LE Audio Controller Subsystem for nRF53 + + Nordic Blue.7 + Radio + + Radio + + Nordic Blue.8 + UART (debug) + + UART (debug) + + Nordic Blue.9 + UART (debug) + + UART (debug) + + Nordic Blue.10 + TWI/I2C + + TWI/I2C + + Nordic Blue.11 + SPI4 + + SPI4 + + Nordic Blue.12 + SD card + + SD card + + Nordic Blue.14 + Power module (INA231) + + Power module (INA231) + + Nordic Blue.15 + Error handler + + Error handler + + Nordic Blue.16 + Buttons + + Buttons + + Nordic Blue.17 + LEDs + + LEDs + + Dynamic connector + + + + Nordic Blueslate + audio_system.c + + audio_system.c + + Nordic Lake + audio_usb.c + + audio_usb.c + + Nordic Blue.25 + + + + Dynamic connector.26 + + + + Nordic Lake.30 + USB (audio) + + USB (audio) + + Nordic Blue.33 + + + + Sheet.34 + Network core + + Network core + + Sheet.36 + Application core + + Application core + + Nordic Middle Grey.42 + + + + Nordic Lake.43 + Bluetooth LE RX FIFO + + Bluetooth LE RX FIFO + + Dynamic connector.45 + + + + Dynamic connector.46 + + + + Sheet.66 + bad_frame + + bad_frame + + Sheet.71 + sdu_ref + + sdu_ref + + Dynamic connector.72 + + + + Dynamic connector.74 + + + + Dynamic connector.75 + + + + Dynamic connector.80 + + + + Dynamic connector.81 + + + + Dynamic connector.82 + + + + Sheet.83 + HCI IPC + + HCI IPC + + Sheet.84 + Audio modules + + Audio modules + + Dynamic connector.86 + + + + Dynamic connector.87 + + + + Nordic Blue.88 + + + + Nordic Lake.89 + + + + Dynamic connector.90 + + + + Sheet.91 + Control data + + Control data + + Dynamic connector.93 + + + + Sheet.94 + Compressed audio + + Compressed audio + + Dynamic connector.95 + + + + Sheet.96 + Uncompressed audio + + Uncompressed audio + + Nordic Lake.97 + + + + Sheet.98 + Block working on compressed audio + + Block working on compressed audio + + Sheet.99 + Block working on uncompressed audio + + Block working on uncompressed audio + + Nordic Lake.100 + + + + Sheet.101 + HW layer element + + HW layer element + + Sheet.102 + + Nordic Blue.24 + + + + Sheet.85 + Peripheral modules + + Peripheral modules + + + Nordic Lake.103 + USB TX FIFO + + USB TX FIFO + + Nordic Lake.104 + USB RX FIFO + + USB RX FIFO + + Nordic Light Grey + sw_codec_select.c + + sw_codec_select.c + + Nordic Lake.105 + Encoder + + Encoder + + Nordic Lake.106 + Decoder + + Decoder + + Dynamic connector.107 + + + + Dynamic connector.109 + + + + Dynamic connector.111 + + + + Sheet.112 + bad_frame + + bad_frame + + Dynamic connector.113 + + + + Dynamic connector.114 + + + + Nordic Lake.115 + + + + Sheet.116 + Peripheral module + + Peripheral module + + Nordic Lake.117 + + + + Sheet.118 + Large main module + + Large main module + + Sheet.119 + Application source files + + Application source files + + Nordic Lake.120 + + + + Nordic Lake.121 + + + + Dynamic connector.122 + + + + Nordic Blue.129 + + + + Dynamic connector.131 + + + + Dynamic connector.132 + + + + Dynamic connector.133 + + + + Dynamic connector.134 + + + + Sheet.135 + Bluetooth modules + + Bluetooth modules + + Sheet.137 + main.c + + main.c + + Nordic Blue.124 + + + + Nordic Light Grey.126 + unicast_client.c + + unicast_client.c + + diff --git a/doc/nrf/images/nrf5340_audio_unicast_server_I2S_structure.svg b/doc/nrf/images/nrf5340_audio_unicast_server_I2S_structure.svg new file mode 100644 index 000000000000..d24c7fdf8876 --- /dev/null +++ b/doc/nrf/images/nrf5340_audio_unicast_server_I2S_structure.svg @@ -0,0 +1,512 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + Dynamic connector.68 + + + + Nordic Middle Grey + audio_system.c + + audio_system.c + + Nordic Light Grey + sw_codec_select.c + + sw_codec_select.c + + Nordic Blue + + + + Nordic Blue.6 + LE Audio Controller Subsystem for nRF53 + + LE Audio Controller Subsystem for nRF53 + + Nordic Blue.7 + Radio + + Radio + + Nordic Blue.8 + UART (debug) + + UART (debug) + + Nordic Blue.9 + UART (debug) + + UART (debug) + + Nordic Blue.10 + TWI/I2C + + TWI/I2C + + Nordic Blue.11 + SPI4 + + SPI4 + + Nordic Blue.12 + SD card + + SD card + + Nordic Blue.13 + HW codec (CS47L63) + + HW codec (CS47L63) + + Nordic Blue.14 + Power module (INA231) + + Power module (INA231) + + Nordic Blue.15 + Error handler + + Error handler + + Nordic Blue.16 + Buttons + + Buttons + + Nordic Blue.17 + LEDs + + LEDs + + Dynamic connector + + + + Nordic Blueslate + Synchronization module (audio_datapath.c) + + Synchronization module (audio_datapath.c) + + Nordic Lake + audio_i2s.c + + audio_i2s.c + + Nordic Blue.25 + + + + Dynamic connector.26 + + + + Dynamic connector.29 + + + + Nordic Lake.30 + I2S (audio) + + I2S (audio) + + Nordic Lake.31 + I2S RX FIFO + + I2S RX FIFO + + Nordic Sky + audio_sync_timer.c + + audio_sync_timer.c + + Nordic Blue.33 + + + + Sheet.264 + Network core + + Network core + + Sheet.265 + Application core + + Application core + + Nordic Lake.37 + Encoder + + Encoder + + Nordic Middle Grey.42 + + + + Dynamic connector.44 + + + + Dynamic connector.45 + + + + Dynamic connector.46 + + + + Dynamic connector.49 + + + + Dynamic connector.50 + + + + Sheet.273 + bad_frame + + bad_frame + + Sheet.274 + sdu_ref + + sdu_ref + + Sheet.275 + bad_frame + + bad_frame + + Sheet.276 + sdu_ref + + sdu_ref + + Dynamic connector.72 + + + + Dynamic connector.73 + + + + Dynamic connector.74 + + + + Dynamic connector.75 + + + + Sheet.281 + cur_time + + cur_time + + Dynamic connector.77 + + + + Sheet.283 + frame_start_ts + + frame_start_ts + + Dynamic connector.80 + + + + Dynamic connector.81 + + + + Dynamic connector.82 + + + + Sheet.287 + HCI IPC + + HCI IPC + + Sheet.288 + Audio modules + + Audio modules + + Dynamic connector.86 + + + + Dynamic connector.87 + + + + Sheet.291 + + Nordic Blue.24 + + + + Sheet.293 + Peripheral modules + + Peripheral modules + + + Nordic Blue.103 + + + + Nordic Lake.104 + + + + Dynamic connector.105 + + + + Sheet.297 + Control data + + Control data + + Dynamic connector.107 + + + + Sheet.299 + Compressed audio + + Compressed audio + + Dynamic connector.109 + + + + Sheet.301 + Uncompressed audio + + Uncompressed audio + + Nordic Lake.111 + + + + Sheet.303 + Block working on compressed audio + + Block working on compressed audio + + Sheet.304 + Block working on uncompressed audio + + Block working on uncompressed audio + + Nordic Lake.114 + + + + Sheet.306 + HW layer element + + HW layer element + + Nordic Lake.115 + + + + Sheet.308 + Peripheral module + + Peripheral module + + Nordic Lake.117 + + + + Sheet.310 + Large main module + + Large main module + + Sheet.311 + Application source files + + Application source files + + Nordic Lake.120 + + + + Nordic Lake.121 + + + + Nordic Lake.123 + + + + Sheet.315 + Synchronization module + + Synchronization module + + Dynamic connector.126 + + + + Nordic Blue.128 + Bluetooth LE Host + + Bluetooth LE Host + + Dynamic connector.129 + + + + Dynamic connector.130 + + + + Dynamic connector.131 + + + + Nordic Blue.129 + + + + Sheet.322 + Bluetooth modules + + Bluetooth modules + + Nordic Light Grey.141 + unicast_server.c + + unicast_server.c + + Dynamic connector.143 + + + + Dynamic connector.48 + + + + Dynamic connector.47 + + + + Nordic Lake.43 + Bluetooth LE RX FIFO + + Bluetooth LE RX FIFO + + Sheet.333 + main.c + + main.c + + Sheet.334 + + Nordic Light Grey.335 + sw_codec_select.c + + sw_codec_select.c + + Nordic Lake.336 + Decoder + + Decoder + + + Dynamic connector.337 + + + + diff --git a/doc/nrf/images/octave_application_topologies.svg b/doc/nrf/images/octave_application_topologies.svg deleted file mode 100644 index 2d36733d3b53..000000000000 --- a/doc/nrf/images/octave_application_topologies.svg +++ /dev/null @@ -1,3305 +0,0 @@ - - - - - - - - - - - - - - - - - - - Page-1 - - Sheet.172 - - - - Sheet.171 - - - - Sheet.170 - - - - Sheet.122 - - - - Sheet.125 - Connected Isochronous Stream (CIS) - - Connected Isochronous Stream (CIS) - - Sheet.164 - Broadcast Isochronous Stream (BIS) - - Broadcast Isochronous Stream (BIS) - - Sheet.137 - - - - Sheet.135 - - - - Sheet.136 - - - - Dynamic connector.141 - - - - Dynamic connector.142 - - - - Sheet.143 - - - - Sheet.157 - - - - Sheet.140 - - - - Sheet.158 - - - - Dynamic connector.146 - - - - Dynamic connector.147 - - - - Dynamic connector.148 - - - - Dynamic connector.149 - - - - Dynamic connector.150 - - - - Sheet.168 - Any number of receivers - - Any number of receivers - - Sheet.169 - - - - Dynamic connector.173 - - - - Sheet.174 - Synchronized playback - - Synchronized playback - - Sheet.177 - - - - Sheet.176 - - - - - - Sheet.178 - One audio source - - One audio source - - Sheet.180 - - - - - - Sheet.181 - - - - - - Sheet.182 - - - - - - Sheet.183 - - - - - - Sheet.184 - - - - - - Sheet.185 - - - - - - Sheet.186 - - - - - - diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-2.2.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-2.2.0.rst index de77090fee2f..132e8773bce3 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-2.2.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-2.2.0.rst @@ -291,7 +291,7 @@ nRF5340 Audio The figure now correctly shows the interaction with the Bluetooth modules. * An issue with Simple Management Protocol (SMP) not advertising in the CIS mode. * An issue with the ``mcumgr`` command being unable to receive in the BIS mode. - * The :ref:`nrf53_audio_app_porting_guide` section in the documentation did not mention long-pressing **BTN 4** while resetting the development kit to start DFU. + * The :ref:`nrf53_audio_unicast_client_app_testing_steps_fota` section in the documentation did not mention long-pressing **BTN 4** while resetting the development kit to start DFU. This has now been added to the documentation. * Removed support for the nRF5340 Audio DK (PCA10121) board version 0.7.1 or older. diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-2.3.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-2.3.0.rst index 63a655b575af..32778c5d1157 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-2.3.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-2.3.0.rst @@ -353,7 +353,7 @@ nRF5340 Audio * The power module has been refactored to use the upstream Zephyr INA23X sensor driver. * BIS headsets can now switch between two broadcast sources (two hardcoded broadcast names). - * :ref:`nrf53_audio_app_ui` and :ref:`nrf53_audio_app_testing_steps_cis` sections in the application documentation with information about using **VOL** buttons to switch headset channels. + * :ref:`nrf53_audio_app_ui` and "Testing the default CIS mode" sections in the application documentation with information about using **VOL** buttons to switch headset channels. * :ref:`nrf53_audio_app_requirements` section in the application documentation by moving the information about the nRF5340 Audio DK to `Nordic Semiconductor Infocenter`_, under `nRF5340 Audio DK Hardware`_. nRF Machine Learning (Edge Impulse) diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-2.4.0.rst b/doc/nrf/releases_and_maturity/releases/release-notes-2.4.0.rst index e688794d8837..3d7f6e31579b 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-2.4.0.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-2.4.0.rst @@ -387,7 +387,7 @@ nRF5340 Audio ------------- * Added Kconfig options for setting periodic and extended advertising intervals. - For more information on the options, see :ref:`nrf53_audio_app_options` (all options prefixed with ``CONFIG_BLE_ACL_PER_ADV_INT_`` and ``CONFIG_BLE_ACL_EXT_ADV_INT_``). + For more information on the options, see all options prefixed with ``CONFIG_BLE_ACL_PER_ADV_INT_`` and ``CONFIG_BLE_ACL_EXT_ADV_INT_``. * Updated: * LE Audio controller for the network core has been moved to the standalone :ref:`lib_bt_ll_acs_nrf53_readme` library. diff --git a/doc/nrf/releases_and_maturity/software_maturity.rst b/doc/nrf/releases_and_maturity/software_maturity.rst index b047a1613b91..b3d23a043170 100644 --- a/doc/nrf/releases_and_maturity/software_maturity.rst +++ b/doc/nrf/releases_and_maturity/software_maturity.rst @@ -99,7 +99,7 @@ The following subsections indicate the software maturity levels of the support f nRF5340 Audio ============= -The following table indicates the software maturity levels of the support for the :ref:`nrf53_audio_app` application. +The following table indicates the software maturity levels of the support for the :ref:`nrf53_audio_app` applications. .. toggle:: @@ -110,12 +110,12 @@ The following table indicates the software maturity levels of the support for th :align: center :widths: auto - * - Feature + * - Application - Description - Limitations - Maturity level - * - **Broadcast source** - - Transmitting broadcast audio using Broadcast Isochronous Stream (BIS) and Broadcast Isochronous Group (BIG). + * - :ref:`**Broadcast source** ` + - Broadcasting audio using Broadcast Isochronous Stream (BIS) and Broadcast Isochronous Group (BIG). Play and pause emulated by disabling and enabling stream, respectively. - The following limitations apply: @@ -125,7 +125,7 @@ The following table indicates the software maturity levels of the support for th * Configuration: 16 bit, several bit rates ranging from 32 kbps to 124 kbps. - Experimental - * - **Broadcast sink** + * - :ref:`**Broadcast sink** ` - Receiving broadcast audio using BIS and BIG. Synchronizes and unsynchronizes with the stream. @@ -136,7 +136,7 @@ The following table indicates the software maturity levels of the support for th * Configuration: 16 bit, several bit rates ranging from 32 kbps to 124 kbps. - Experimental - * - **Unicast client** + * - :ref:`**Unicast client** ` - One Connected Isochronous Group (CIG) with two Connected Isochronous Streams (CIS). Transmitting unidirectional or transceiving bidirectional audio using CIG and CIS. @@ -148,8 +148,8 @@ The following table indicates the software maturity levels of the support for th * Configuration: 16 bit, several bit rates ranging from 32 kbps to 124 kbps. - Experimental - * - **Unicast server** - - One CIG with two CIS streams. + * - :ref:`**Unicast server** ` + - One CIG with one CIS stream. Receiving unidirectional or transceiving bidirectional audio using CIG and CIS. diff --git a/doc/nrf/shortcuts.txt b/doc/nrf/shortcuts.txt index ff775a71902b..91bf29fb278c 100644 --- a/doc/nrf/shortcuts.txt +++ b/doc/nrf/shortcuts.txt @@ -178,6 +178,13 @@ .. |nrf5340_audio_net_core_hex_note| replace:: The network core for both gateway and headsets is programmed with the precompiled Bluetooth Low Energy Controller binary file :file:`ble5-ctr-rpmsg_.hex`, where ** corresponds to the controller version, for example :file:`ble5-ctr-rpmsg_3216.hex`. This file includes the LE Audio Controller Subsystem for nRF53 and is provided in the :file:`nrf/lib/bin/bt_ll_acs_nrf53/bin` directory. If :ref:`DFU is enabled `, the subsystem's binary file will be generated in the :file:`build/zephyr/` directory and will be called :file:`net_core_app_signed.hex`. +.. |nrf5340_audio_external_devices_note| replace:: Nordic Semiconductor seeks to provide seamless interoperability with as many LE Audio devices as possible. + However, vendors have reached different levels of maturity in their implementation. + Also, different platforms have different methods of connecting, pairing, and streaming. + For these reasons, providing a general guide on how to test with external devices is challenging. + The suggested approach is to test with Nordic Semiconductor devices on both sides first to verify basic functionalities and get familiar with the solution before using custom devices. + Contact `Technical Support team `_ if you need assistance. +.. |usb_known_issues| replace:: Make sure to check the :ref:`nRF5340 Audio application known issues ` related to serial connection with the USB. .. |trusted_execution| replace:: nRF5340 and nRF9160