1.. zephyr:code-sample:: argonkey_microphone
2   :name: Microphone
3   :relevant-api: audio_interface
4
5   Acquire audio through the ArgonKey's on-board MP34DT05 microphone.
6
7Overview
8********
9This sample provides an example of how to acquire audio through
10the on-board MP34DT05 microphone. The microphone generates a PDM
11stream which is acquired through I2S. The PDM stream is then
12converted to PCM using the OpenPDMFilter library, which is available
13in source code in this sample.
14
15Requirements
16************
17
18This sample requires the ArgonKey board plus a USB to TTL 1V8 serial
19cable to get the output audio stream. The board can be powered
20in either one of the following two ways:
21
22- mezzanine mode, plugging the ArgonKey to HiKey board through its 96Board
23  low-speed connector
24- standalone mode, supplying 5V directly on P1 connector
25
26References
27**********
28
29- :ref:`96b_argonkey`
30
31Building and Running
32********************
33
34.. zephyr-app-commands::
35    :zephyr-app: samples/boards/96boards/argonkey/microphone
36    :host-os: unix
37    :board: 96b_argonkey
38    :goals: run
39    :compact:
40
41Sample Output
42=============
43
44The example acquires 5s of audio and prints out the PCM stream on COM port.
45A USB to TTL 1V8 serial cable may be attached to the low speed connector on
46the back of the board on P3.5 (TX) and P3.7 (RX).
47
48As soon as the acquisition starts the green LED glows. At the end of the
49acquisition both the green and red LEDs go on and the PCM stream is sent
50on COM port. When the output is completed the green LED goes off and the red
51LED stays on. The process can be reiterated by pressing the RST button.
52
53- audio acquisition starts:     GRN on  - RED off
54- audio acquisition ends:       GRN on  - RED on
55- audio output ends:            GRN off - RED on
56
57The characteristics of the PCM audio are hardcoded in the example:
58
59- 16KHz sample rate
60- 16 bits per sample
61- 1 channel (mono), as only 1 microphone is available
62
63Five seconds of acquisition at a 16KHz sampling rate yields 80,000 16-bit samples.
64The microphone PDM requested clock should lead the MP34DT05 driver to select an
65oversampling/decimation factor equal to 128, resulting in a 2.048MHz bit clock.
66
67See pcm and pdm configuration in file :zephyr_file:`samples/boards/96boards/argonkey/microphone/src/main.c`.
68
69.. note:: It is possible to change the AUDIO_FREQ to 32000 acquiring only 2500 ms. In this
70   case the oversampling/decimation factor will be 64.
71
72At the end of the acquisition the PCM data will be printed on the terminal
73emulator in either binary or ASCII format. The output is controlled by
74following macro, off by default, in :zephyr_file:`samples/boards/96boards/argonkey/microphone/src/main.c`:
75
76* :c:macro:`PCM_OUTPUT_IN_ASCII`
77
78Binary PCM Output
79-----------------
80
81The ttyUSB0 port must be configured in raw mode to avoid having
82characters 'cooked' out.
83
84.. code-block:: console
85
86   stty -F /dev/ttyUSB0 115200 raw
87   cat /dev/ttyUSB0 > /tmp/sound.raw
88
89.. note:: The "cat /dev/ttyUSB0 > /tmp/sound.raw" command should be launched after the audio
90   acquisition starts (after green led glows) to avoid initial boot messages to enter in the file,
91   and before audio acquisition ends (before red led glows).
92
93.. note:: In case the character 0x0a is interpreted as NL and an 0x0d (CR) is added,
94   you may need to remove it::
95
96      dos2unix -f /tmp/sound.raw
97
98ASCII PCM Output
99----------------
100
101It is also possible to recompile and to have PCM output in ASCII, which needs
102to be converted to binary later on. The output format is the following:
103
104.. code-block:: console
105
106    ArgonKey test!!
107    -- start
108    0xfbe0,
109    0xfbf0,
110    0xfc0c,
111    0xfc24,
112    0xfc3c,
113    0xfc4c,
114    0xfc68,
115    0xfc48,
116
117    [...]
118
119    0xfb98,
120    0xfb98,
121    0xfbb8,
122    0xfbac,
123    0xfbc4,
124    0xfbe8,
125    0xfbf4,
126    -- end
127
128Play PCM Audio
129--------------
130
131Now that we have a binary PCM file (say sound.raw), you can use,
132for example, the audacity open source editor/player to load and play it.
133Use the 'Import->Raw Data' menu to load the sound.raw file as
134signed 16 bit PCM, Little Endian, mono format @16KHz.
135