.. include:: ../../README.rst

|newpage|

Overview
--------

Introduction
............

This demo application shows a simple Delay and Sum (DAS) bemformer. 
It shows the setup of the |I2S| for audio output via the DAC and very simple processing of
multi-channel audio frames to produce a single channel output based on a simple single steering direction.

Block diagram
.............

.. figure:: block_diagram.pdf
   :width: 80%

   Application block diagram

How to use lib_mic_array 
------------------------

The Makefile
............

To start using the microphone array library, you need to add ``lib_mic_array`` to you Makefile::

  USED_MODULES = .. lib_mic_array ...

This demo also uses the logging library (``lib_logging``) for the ``debug_printf``
function. This is a faster, but more limited version of the C-Standard Library
``printf`` function. So the Makefile also includes::

  USED_MODULES = .. lib_logging ..

The logging library is configurable at compile-time allowing calls to
``debug_printf()`` to be easily enabled or disabled. For the prints to
be enabled it is necessary to add the following to the compile flags::

  XCC_FLAGS = .. -DDEBUG_PRINT_ENABLE=1 ..

Includes
........

This application requires the system headers that defines XMOS xCORE specific
defines for declaring and initialising hardware:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: include <platform.h>
   :end-on: include <xclib.h>

The microphone array library functions are defined in ``lib_mic_array.h``. This header must
be included in your code to use the library. The support functions for the board are defined in
``mic_array_board_support.h`` and the logging functions are provided by ``debug_print.h``.

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: include "mic_array.h"
   :end-on: include "debug_print.h"

Also required is support for |I2S| and |I2C| through the headers:
   
.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: include "i2c.h"
   :end-on: include "i2s.h"

Allocating hardware resources
.............................

A PDM microphone requires a clock and a data pin. For eight PDM microphones a single 
clock can be shared between all microphones and the data can be sampled on a single 
8 bit port. On an xCORE the pins are controlled by ``ports``. The application therefore 
declares one 1-bit port and one 8-bit port:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: in port p_pdm_clk
   :end-on: in buffered port:32 p_pdm_mics

To generate the PDM clock a 24.576MHz master clock is divided by 8 using a clock block. These two hardware
resources are declared with:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: in port p_mclk 
   :end-on:  clock pdmclk      

and are configured with:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: configure_clock_src_divide(pdmclk
   :end-on:  start_clock(pdmclk);     

The result begin a 3.072MHz PDM clock is used for clocking the microphone data into the xCORE. Additionally, 
the LEDs and buttons are declared by
   
.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: p_leds leds
   :end-on:  in port p_buttons
   
And the |I2S| is declared with:
 
.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: p_i2s_dout[1]
   :end-on:  clock bclk
 
Demo Hardware Setup
-------------------

To run the demo, connect a USB cable to power the Microphone Array Ref Design v1
and plug the xTAG to the board and connect the xTAG USB cable to your
development machine. You will also need to connect headphones to the audio jack.

.. figure:: setup.jpg
   :width: 80%

   Hardware setup

|newpage|

Launching the demo application
------------------------------

Once the demo example has been built either from the command line using xmake or
via the build mechanism of xTIMEcomposer studio it can be executed on the Microphone Array Ref Design v1.

Once built there will be a ``bin/`` directory within the project which contains
the binary for the xCORE device. The xCORE binary has a XMOS standard .xe extension.

Launching from the command line
...............................

From the command line you use the ``xrun`` tool to download and run the code
on the xCORE device::

  xrun --xscope bin/app_lores_DAS_fixed.xe

Once this command has executed the application will be running on the
Microphone Array Ref Design v1.

Launching from xTIMEcomposer Studio
...................................

From xTIMEcomposer Studio use the run mechanism to download code to xCORE device.
Select the xCORE binary from the ``bin/`` directory, right click and go to Run
Configurations. Double click on xCORE application to create a new run configuration,
enable the xSCOPE I/O mode in the dialog box and then
select Run.

Once this command has executed the application will be running on the
Microphone Array Ref Design v1.

Running the application
.......................

Once the application is started using either of the above methods there will
be the output of the microphones through the headphones.

Buttons ``A`` and ``D`` rotate the direction of the beam which is indicated by the LEDs.
Buttons ``B`` and ``C`` decrease and increase the gain on the output signal respectively.

|newpage|

Task setup
----------

The PDM microphones interface task and the decimators have to be connected 
together and to the application (``lores_DAS_fixed()``). There needs to be one 
``mic_array_decimate_to_pcm_4ch()`` task per four channels that need processing. 
The PDM interface task, ``mic_array_pdm_rx()`` can process eight channels so only 
one is needed for this application. The PDM interface needs to be connected to the 
decimators via two streaming channels. Finally, the decimators have to be connected to 
the application.

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: streaming chan c_4x_pdm_mic[
   :end-before: return 0

Note that the decimators have to be on the same tile as the application due to shared frame memory.	

Frame memory
------------

For each decimator an block of memory must be allocated for storing FIR data. The size of the data 
block must be::

  Number of channels for that decimator * THIRD_STAGE_COEFS_PER_STAGE * Decimation factor * sizeof(int)

bytes. The data must also be double word aligned. For example:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: int data[8]
   :end-before: void lores_DAS_fixed
  
Note that on the xCORE-200 all global arrays are guaranteed to be double-word aligned.

Configuration
-------------

Configuration of the microphone array for the example is achieved through:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: mic_array_decimator_conf_common_t dcc =
   :end-before:  mic_array_init_time_domain_frame

All configuration options are described in the Microphone array library guide. Once configured 
then the decimators require initialization via:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: mic_array_init_time_domain_frame
   :end-before: while(1)

The decimators will start presenting samples in the form of frames that can be accessed with:

.. literalinclude:: app_lores_DAS_fixed.xc
   :start-on: mic_array_frame_time_domain *  current =
   :end-on: mic_array_get_next_time_domain_frame

The return value of ``mic_array_get_next_time_domain_frame()`` is a pointer to the frame that 
the application is allowed to access. The ``current`` frame contains the frame data in the 
``data`` member. ``data`` is a 2D array with the first index denoting the channel number and 
the second index denoting the frame index. The frame index used 0 for the oldest samples and 
increasing indices for newer samples.

Delay taps
----------

The delays on the microphones are calculated in a spread sheet included at the root folder of the application,
``mic_array_das_beamformer_calcs.xls``. The beam is focused to a point of one meter away at an angle of
thirty degrees from the plane of the microphone array in the direction indicated by the LEDs.

References
----------

.. nopoints::

  * XMOS Tools User Guide

    http://www.xmos.com/published/xtimecomposer-user-guide

  * XMOS xCORE Programming Guide

    http://www.xmos.com/published/xmos-programming-guide

  * XMOS Microphone Array Library

    http://www.xmos.com/support/libraries/lib_mic_array

  * XMOS |I2C| Library

    http://www.xmos.com/support/libraries/lib_i2c

  * XMOS |I2S| Library

    http://www.xmos.com/support/libraries/lib_i2s

	
|newpage|

Full source code listing
------------------------

Source code for app_lores_DAS_fixed.xc
......................................

.. literalinclude:: app_lores_DAS_fixed.xc
  :largelisting:

|newpage|
