Setup#

This section describes the requirements and the steps to run a basic pipeline. This document lists the necessary steps for both Windows and Linux/macOS. This section uses the app_simple_audio_dsp_integration example found within this repository. The steps will be broadly similar for any user-created project.

Note

Copying multiple lines into the console may not work as expected on Windows. To avoid issues, copy and execute each line individually.

Hardware Requirements#

  • xcore.ai evaluation board (XK-EVK-XU316 or XK-316-AUDIO-MC-AB)

  • xTag debugger and cable

  • 2x Micro USB cable (one for power supply and one for the xTag)

Software Requirements#

Additionally, on Windows the following is required:

Setup Steps#

Note

All the steps below are executed from the sandbox folder created in the second step.

  1. Prepare the development environment

    On Windows:

    1. Open the Command Prompt or other terminal application of choice

    2. Activate the XTC environment:

      call "C:\Program Files\XMOS\XTC\15.3.0\SetEnv.bat"

    On Linux and macOS:

    1. Open a terminal

    2. Activate the XTC environment using SetEnv

  2. Create a sandbox folder with the command below:

    mkdir lib_audio_dsp_sandbox

  3. Clone the library inside lib_audio_dsp_sandbox:

    git clone git@github.com:xmos/lib_audio_dsp.git

  4. Get the sandbox inside lib_audio_dsp_sandbox. This step can take several minutes.

    On Windows:

    cd lib_audio_dsp/examples/app_simple_audio_dsp_integration
cmake -B build -G Ninja
cd ../../..

    On Linux and macOS:

    cd lib_audio_dsp/examples/app_simple_audio_dsp_integration
cmake -B build
cd ../../..

  5. Create a requirements file inside lib_audio_dsp_sandbox.

    On Windows:

    echo -e lib_audio_dsp/python > requirements.txt
echo notebook >> requirements.txt

    On Linux or macOS:

    echo "-e lib_audio_dsp/python" > requirements.txt
echo notebook >> requirements.txt
chmod 644 requirements.txt

  6. Create a Python virtualenv inside lib_audio_dsp_sandbox.

    On Windows:

    python -m venv .venv
call .venv/Scripts/activate.bat
pip install -Ur requirements.txt
cd ..

    On Linux or macOS:

    python -m venv .venv
source .venv/bin/activate
pip install -Ur requirements.txt
cd ..

  7. Connect an XCORE-AI-EXPLORER using both USB ports

  8. Open the notebook by running from lib_audio_dsp_sandbox the following command:

    jupyter notebook lib_audio_dsp/examples/app_simple_audio_dsp_integration/dsp_design.ipynb

    If a blank screen appears or nothing opens, then copy the link starting with “http://127.0.0.1/” from the terminal into the browser. The following page should open:

    ../../_images/jupyter_notebook_top_level.png

    Fig. 1 Top-level page of the Jupyter Notebook#

  9. Run all the cells from the browser. From the menu at the top of the page click Run -> Run all cells:

    ../../_images/jupyter_notebook_run_tests.png

    Fig. 2 Run menu of the Jupyter Notebook#

    This creates the pipeline and builds the app. Wait for all the cells to finish

    Any configuration or compilation errors will be displayed in the notebook in the Build and run cell, as in the example below:

    ../../_images/config_error.png

    Fig. 3 Run error of the Jupyter Notebook#

  10. Update and run Pipeline design stage to add the desired audio processing blocks. A diagram will be generated showing the pipeline IO mapping.

    A simple pipeline example is shown in Fig. 4:

    ../../_images/pipeline_diagram.png

    Fig. 4 Diagram of a simple audio pipeline#

    See the top of the notebook for more information about this stage.

  11. Update and run the Tuning Stage cell to change the parameters before building. See the top of the notebook for more information about this stage.

Running a notebook after the first installation#

If running the notebook after the initial configuration, the following steps are required:

  1. Configure the settings below, using the instructions in the Setup Steps section:

    • Enable the XTC tools: the installation can be tested by running the command xrun --version from the terminal. If the command is not found, the XTC tools are not installed correctly.

    • Enable the Python Virtual Environment: this is checked by running the command echo %VIRTUAL_ENV% on Windows, or echo $VIRTUAL_ENV on Linux or macOS. The path should have been set.

  2. Open the notebook by running jupyter notebook lib_audio_dsp/examples/app_simple_audio_dsp_integration/dsp_design.ipynb from lib_audio_dsp_sandbox, as described in the Setup Steps section.