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

# Examples

Example applications are included with `lib_mic_array` to illustrate both the default usage model and advanced/custom integration approaches.

These examples are located in the `examples` directory of the library. All examples run on the XK-VOICE-L71 hardware platform.

Examples overview:

- `app_mic_array` — demonstrates the default way of using the mic array in an application (recommended starting point).

- `app_custom_filter` - demonstrates using a custom decimation filter in the mic array processing

- `app_shutdown` — demonstrates shutting down and restarting the mic array.

- `app_par_decimator` — demonstrates an advanced integration approach. Replaces the standard decimator component with a custom two-threaded implementation.

## Running the examples

This section describes how to build and run the example applications provided with the `lib_mic_array` library. The application used here is `app_mic_array` which demonstrates use of the default mic array API. For other examples, the process is similar, except for the application/folder name.

### Required hardware

- 1x `XK-VOICE-L71` board

- 2x Micro USB cable (For USB power and XTAG)

- 3.5mm audio cable to connect to the line out connector on the ``XK-VOICE-L71` board

### Setup procedure

1. Connect the XTAG to the `XK-VOICE-L71`

2. Connect one Micro USB cable between the host computer and the `XK-VOICE-L71` USB port.

3. Connect the other Micro USB cable between the host computer and the XTAG.

XK-VOICE-L71 setup shows the `XK-VOICE-L71` board with all the cables connected.

Fig. 2 XK-VOICE-L71 setup

### Building

The following instructions assumes that the XMOS XTC tools has been downloaded and installed (see README for required version).

Installation instructions can be found here. Particular attention should be paid to the section Installation of required third-party tools.

The application uses the XMOS build and dependency system, xcommon-cmake. xcommon-cmake is bundled with the XMOS XTC tools.

To configure the build, run the following from an XTC command prompt:

    cd examples
    cd app_mic_array
    cmake -G "Unix Makefiles" -B build

Any missing dependencies will be downloaded by the build system at this configure step.

Finally, the application binaries can be built using `xmake`:

    xmake -j -C build

The example build four configurations - `1mic_isr`, `1mic_thread`, `2mic_isr` and `2mic_thread`, which indicate the number of microphones used and whether the PDM RX service runs in an ISR or a hardware thread. The executable binaries (.xe files) for each configuration are placed in `bin/<config>` directory (e.g. `bin/2mic_isr/app_mic_array_2mic_isr.xe`).

### Running the application

To run the application from the `/examples/app_mic_array` directory, execute:

    xrun --xscope bin/2mic_isr/app_mic_array_2mic_isr.xe

The command above runs the `2mic_isr` configuration. To run a different configuration, replace `2mic_isr` in the path with the desired build variant.

When running, the application captures the microphones audio and routes it to the DAC on the `XK-VOICE-L71` after linearly scaling the PCM samples received from `lib_mic_array` by a factor of 64. Connect headphones to the 3.5mm LINE OUT jack on the board to listen to the captured microphone signal.

### Other examples

#### `app_custom_filter`

The `app_custom_filter` example behaves like `app_mic_array`, but instead of using the default decimation filters provided by the library, it uses a custom decimation filter.

It demonstrates the use of `mic_array_init_custom_filter()`, the mic array initialization API for custom filters. The filter used is `good_2_stage_filter_int.pkl`, which is generated by running the filter design script `design_filter.py`. This filter is then quantized and interleaved into the format required by the mic array component by running the `combined.py` script, as described in Designing a custom filter. The script produces a header file (`good_2_stage_filter.h`) containing the first and second stage filter coefficients and related defines. This header is included in the example and is located in the `app_custom_filter/src` directory. For details, see Using custom filters.

#### `app_par_decimator`

The `app_par_decimator` example behaves like `app_mic_array`, but internally uses a custom mic array decimator implementation. The custom decimator runs in two threads, with each thread processing one channel of microphone output. This example serves as a reference for using `lib_mic_array` in applications with many microphone channels, where decimation must be split across multiple hardware threads (e.g., two decimator threads, each handling four channels).

#### `app_shutdown`

The `app_shutdown` example demonstrates shutting down and restarting the mic array each time `Button A` on the `XK-VOICE-L71` is pressed. Each press shuts down the mic array component and restarts it at a different output sampling frequency, cycling between 16 kHz and 48 kHz.

The terminal stdout displays the current sampling rate on each button press:

    Starting at sample rate 16000
    Starting at sample rate 48000
    Starting at sample rate 16000
    Starting at sample rate 48000
    Starting at sample rate 16000
    Starting at sample rate 48000
    Starting at sample rate 16000