Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# 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)

- 2x Micro USB cable (one for power supply and one for the XTAG)

## Software Requirements

- XTC tools: 15.3.1.

- Graphviz: this software must be installed and the `dot` executable must be on the system path.

- Python: 3.12 or later.

- CMAKE: 3.21 or later.

Additionally, on Windows the following is required:

- ninja-build

## Setup Steps

Note

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

1. Prepare the development environment

   Windows

   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.1\SetEnv.bat"

   Linux and macOS

   On Linux and macOS:

   1. Open a terminal

   2. Activate the XTC environment using SetEnv

       source /path/to/xtc/tools/SetEnv

2. Create a sandbox folder with the command below:

       mkdir lib_audio_dsp_sandbox

3. Clone the library inside lib_audio_dsp_sandbox using SSH (if you have shared your keys with Github) or HTTPS:

       cd lib_audio_dsp_sandbox

       # with SSH
       git clone git@github.com:xmos/lib_audio_dsp.git

       # without SSH
       git clone https://github.com/xmos/lib_audio_dsp.git

   For troubleshooting SSH issues, please see this Github guide.

4. Get the lib_audio_dsp library dependencies inside lib_audio_dsp_sandbox. This step can take several minutes.

   Windows

   On Windows:

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

   Linux and macOS

   On Linux and macOS:

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

5. Create a Python virtualenv inside lib_audio_dsp_sandbox, and install lib_audio_dsp and it’s requirements.

   Note

   Make sure to use the same Python version as the the recommended in the Software Requirements section.

   Windows

   On Windows:

       python -m venv .venv
       call .venv/Scripts/activate.bat
       pip install -e ./lib_audio_dsp/python

   Linux and macOS

   On Linux and macOS:

       python3 -m venv .venv
       source .venv/bin/activate
       pip install -e ./lib_audio_dsp/python

6. Connect an XK-EVK-XU316 using both USB ports

7. The examples are presented as a Jupyter notebook for interactive development. Install Juptyer notebooks into the Python virtual environment with the command:

       pip install notebook==7.2.1

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 top level Jupyter notebook page should open, as can be seein in Fig. 1.

   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 (Fig. 2). This creates the pipeline and builds the app. Wait for all the cells to finish.

   Fig. 2 Run menu of the Jupyter Notebook

   Once finished, the setup phase is complete. The notebook should look like as in the example on Fig. 3.

   Fig. 3 Run Success of the Jupyter Notebook

   If there are any configuration or compilation errors, they will be displayed in the notebook in the Build and run cell, as in the example on Fig. 4.

   Fig. 4 Run Error of the Jupyter Notebook

Once the setup phase is complete, the user can proceed to either creating a custom pipeline, mapping the pipeline to audio input or output sources, or deploying the pipeline to the xcore. The Using the Tool section describes how to achieve this.

## 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.

   - From your sandbox, enable the Python Virtual Environment and print the path to the virtual environment directory. This can be done with the following commands:

   Windows

   On Windows:

       call .venv/Scripts/activate.bat
       echo %VIRTUAL_ENV%

   Linux and macOS

   On Linux and macOS:

       source .venv/bin/activate
       echo $VIRTUAL_ENV

2. From the `lib_audio_dsp_sandbox` folder, open the notebook by running:

       jupyter notebook lib_audio_dsp/examples/app_simple_audio_dsp_integration/dsp_design.ipynb