.. _rb3_gen2: RB3 Gen2 ################################################## 1. `Architecture Overview <#Architecture Overview>`__ 2. `Create a Yocto Image <#create-a-yocto-image>`__ 3. `Flash the Yocto image <#flash-the-yocto-image>`__ 4. `Setting up the RB3 <#setting-up-the-rb3>`__ 5. `Running an AudioReach Usecase <#running-an-audioreach-usecase>`__ 6. `Next Steps <#next-steps>`__ 7. `Troubleshooting <#troubleshooting>`__ This guide provides AudioReach Architecture overview on RB3 (Robotics) platform and walks through steps on how to create a Yocto image that integrates AudioReach, load that image on a RB3 Gen2 device, and then run an AudioReach usecase. Architecture Overview ===================== .. figure:: images/rb3_gen2_reference.png :figclass: fig-center :scale: 65 % The above architecture diagram illustrates the playback/record use-case on a RB3 Gen2 using AudioReach. In this setup, PulseAudio test applications are utilized to play/record an audio clip, and the sound is rendered/captured through devices like microphone and speaker. For more details refer :ref:`here `. .. note:: AudioReach is currently transitioning from PulseAudio to PipeWire as the primary audio server. This documentation will be updated as the migration progresses. Create a Yocto image ==================== The first step is to integrate AudioReach components into a Yocto build that can be loaded onto the RB3 device. This involves syncing a Yocto build and then integrating the meta-audioreach layer, which is currently available as a Github repository. Before following these steps, it would be helpful to learn the basics of how to use a Yocto project. To do this, please refer to the official `Yocto `_ documentation site. There are two options for building a Yocto image that incorporates AudioReach components. One option is to use the Qualcomm Linux builds and the other option is using meta layers directly. Using Qualcomm Linux builds (Released CRM builds) -------------------------------------------------- For instructions on setting up a Yocto build with AudioReach components, refer `build guide `_. The build setup process varies based on your Qualcomm access level. For comprehensive details about different access levels, visit the `Working with Qualcomm `_ page. **Important Note:** While unregistered users can access basic images for flashing, meaningful AudioReach development requires at least a registered user access level. Registered users gain access to essential development tools like AudioReach Creator (ARC). We strongly recommend registering with Qualcomm to unlock the full AudioReach development experience. **Note:** * RB3 Platform is based QCS6490 chipset and supported machine names are qcs6490-rb3gen2-core-kit and qcs6490-rb3gen2-vision-kit. * To access the ADSP firmware source code, you must be registered as an Authorized user with Qualcomm. * Qualcomm Linux supports different versions for Application Development. The `Software Architecture Guide `_ provides detailed information about these versions: * The Base version is an upstream, open-source software stack without Qualcomm proprietary software. * The Custom version includes downstream Qualcomm proprietary software with extra SDKs and improved power performance. For AudioReach-based solutions, you should use the Custom variant. Directly pulling using meta layers (AudioReach latest source code) ------------------------------------------------------------------- The current Qualcomm Linux builds for RB3 utilize components from the Code Linaro codebase. We are actively working to enable direct integration from upstream GitHub repositories, which will allow developers to access the latest AudioReach source code directly. Flash the Yocto image ====================== To flash the Yocto image onto your RB3 Gen2 device, follow the instructions provided in the `Flashing Guide `_. Setting up the RB3 Gen2 ======================== Setup the RB3 hardware using `Qualcomm Linux documentation `_ Follow below sections to setup the device for this guide: * Power up the device * Set up debug UART * Verify the Qualcomm Linux version * Connect to a network Set up Audio hardware ---------------------- Activate the digital microphone interface (DMIC) on the board, by following steps in section "Set up audio hardware" from `here `_ Check for Sound Card --------------------- * Check if Sound card is enumerated: .. code-block:: bash cat /proc/asound/cards Check for PulseAudio Service ----------------------------- * Check if PulseAudio service is running .. code-block:: bash systemctl status pulseaudio Enable Real-time Calibration Mode ---------------------------------- ARC (AudioReach Creator) is a tool that allows the user to perform several functionalities related to the audio usecase, including creating and editing audio usecase graphs, and editing audio configurations while running an audio usecase in real time. For more information on ARC, please refer to the :ref:`arc_design` page. **NOTE:** ARC is currently supported only on Windows host machine. The below steps will demonstrate how to connect ARC to the RB3 so that the usecase graph can be viewed in real time. * Connect a type C cable to RB3 at one end and the USB cable to Windows host machine. * Install ARC (also known as QACT) on a Windows host machine using :ref:`steps_to_install_arc`. You will need at least QACT 8.1 * Open ARC, Click on "Connect to Device". Running an AudioReach Usecase ============================= Once all of the above setup is complete, we are ready to run Audio use-case on RB3. The below section list steps to run playback and record use-case using PulseAudio. Check out `Enable Audio use-cases using PulseAudio `_ to know more. Playback -------- * Push a ".wav" file onto some location in the RB3, such as the "/etc" folder. * Find the IP Address of RB3 device by connecting the serial shell using UART console. * Use scp (Secure Copy Protocol) to copy a wav file from host machine to the RB3 device. .. code-block:: bash scp root@:/etc/ * Connect an external audio device (such as speakers or headphones) to the audio port of the RB3 if not already connected. * Open serial shell terminal window on host machine and run below command to start the playback usecase: .. code-block:: bash paplay -d low-latency0 Now the ".wav" file should play through the external audio device. If the RB3 is connected to ARC, the current usecase graph will appear in the graph view. The system logs for the usecase will be saved in the file "/var/log/messages". Record ------ * Open serial shell terminal window on host machine and run below command to start the record usecase: .. code-block:: bash parec --rate=48000 --format=s16le --channels=1 --file-format=wav -d regular0 Above command stores the recorded .wav file at specified path. Next Steps ========== Exploring AudioReach Components in the QCLINUX Build ----------------------------------------------------- * Recipes for AudioReach components are available at Path: /workspace/layers/meta-qcom-hwe/recipes-multimedia/audio/. * To modify existing code follow below steps: * Check for the recipe name from above path. * Use `devtool `_ to get fetch source as below: .. code-block:: bash cd /workspace/ # example build_dir build-qcom-wayland devtool modify #Example for qcom-agm_git.bb recipe devtool modify qcom-agm * This extracts the source code at path /workspace/build-qcom-wayland/workspace/source/qcom-agm/ directory. * **Note:** The following table maps Qualcomm Linux project names to `AudioReach `_ GitHub repository names: +--------------------------+---------------------------------+ | Downstream Name | Upstream Project Name | +==========================+=================================+ | qcom-agm | audioreach-graphmgr | +--------------------------+---------------------------------+ | qcom-pal | audioreach-pal | +--------------------------+---------------------------------+ | qcom-acdbdata | audioreach-conf | +--------------------------+---------------------------------+ | qcom-args | audioreach-graphservices | +--------------------------+---------------------------------+ | pulseaudio-plugin | audioreach-pulseaudio-plugin | +--------------------------+---------------------------------+ Adding a new Module to ADSP Image ---------------------------------- * ADSP source code is available only for Authorized users. * If you have Authorized access, refer to `Adding a Custom Module in SPF `_ guide to integrate a new module into ADSP Image. * Alternatively, you can use the Hexagon SDK to compile a standalone .so file for your custom module on the ADSP. The Hexagon SDK can be downloaded from the `Qualcomm Developer Network `_. Troubleshooting ================ Checkout `Audio Troubleshooting `_ guide for Audio logging and debugging.