samples/shields: Add example code to test x_nucleo_cca02m1 shield

This sample is made to demonstrate use of shield x-nucleo-cca02m1.
It uses the default shield soldering configuration, which means
both microphones in stereo mode. It has been tested using nucleo
F411RE board.

Signed-off-by: Armando Visconti <[email protected]>

Author: avisconti

samples/shields/x_nucleo_cca02m1/CMakeLists.txt

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+cmake_minimum_required(VERSION 3.13.1)
+
+# This sample is specific to x_nucleo_cca02m1 shield. Enforce -DSHIELD option
+set(SHIELD x_nucleo_cca02m1)
+
+include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
+project(x_nucleo_cca02m1)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})

samples/shields/x_nucleo_cca02m1/README.rst

@@ -0,0 +1,141 @@
+.. _x-nucleo-cca02m1-sample:
+
+X-NUCLEO-CCA02M1: Digital MEMS microphones SHIELD for STM32 Nucleo
+##################################################################
+
+Overview
+********
+This sample enables the two digital MEMS microphones on X-NUCLEO-CCA02M1
+shields
+
+This sample provides an example of how to acquire audio through
+the two digital MEMS microphones on X-NUCLEO-CCA02M1 shield.
+The microphone generates a PDM stream which is acquired through I2S.
+The PDM stream is then converted to PCM using the OpenPDMFilter external
+library.
+
+Requirements
+************
+
+This sample communicates over I2C with the X-NUCLEO-CCA02M1 shield
+stacked on a board with an Arduino connector. The board's I2C must be
+configured for the I2C Arduino connector (both for pin muxing
+and device tree). See for example the :ref:`nucleo_f411re_board` board
+source code:
+
+- :zephyr_file:`boards/arm/nucleo_f411re/nucleo_f411re.dts`
+- :zephyr_file:`boards/arm/nucleo_f411re/pinmux.c`
+
+References
+**********
+
+- X-NUCLEO-CCA02M1: https://www.st.com/en/ecosystems/x-nucleo-cca02m1.html
+
+Building and Running
+********************
+
+This sample runs with X-NUCLEO-CCA02M1 stacked on any board with a matching
+Arduino connector. For this example, we use a :ref:`nucleo_f411re_board` board.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/shields/x_nucleo_cca02m1
+   :board: nucleo_f411re
+   :goals: build
+   :compact:
+
+Sample Output
+=============
+
+The example acquires one second of audio and prints out the PCM stream on COM port.
+The acquisition starts immediately after the reset button is pressed.
+
+The characteristics of the PCM audio are hardcoded in the example:
+
+- 16KHz sample rate
+- 16 bits per sample
+- 2 channel (stereo)
+
+One second of acquisition at a 2 channels 16KHz sampling rate yields 32,000 16-bit samples.
+The microphone PDM requested clock should lead the MP34DT05 driver to select an
+oversampling/decimation factor to result in approximately a 2MHz bit clock.
+
+See PCM and PDM configuration in file :zephyr_file:`samples/shields/x_nucleo_cca02m1/src/main.c`.
+
+.. note:: It is possible to change the AUDIO_FREQ to 32000 acquiring only 500 ms.
+
+At the end of the acquisition the PCM data will be printed on the terminal
+emulator in either binary or ASCII format. The output is controlled by the
+:c:macro:`PCM_OUTPUT_IN_ASCII` macro, off by default, in
+:zephyr_file:`samples/shields/x_nucleo_cca02m1/src/main.c`.
+
+Binary PCM Output
+-----------------
+
+The Nucleo F411RE board presents itself to the host
+as a USB CDC class, and will use ``/dev/ttyACM0``
+device for communication. The ``/dev/ttyACM0`` port
+must be configured in raw mode to avoid having
+special characters (such as :kbd:`CNTL-Z` or :kbd:`CNTL-D`)
+processed or 'cooked' out.
+
+.. code-block:: console
+
+   stty -F /dev/ttyACM0 115200 raw
+   cat /dev/ttyACM0 > /tmp/sound.raw
+
+.. note:: In case the character 0x0a is interpreted as NL and an 0x0d (CR) is added,
+   you may need to remove it::
+
+      dos2unix -f /tmp/sound.raw
+
+ASCII PCM Output
+----------------
+
+It is also possible to recompile and to have PCM output in ASCII, which needs
+to be converted to binary later on. The output format is the following:
+
+.. code-block:: console
+
+    -- start
+    0xfbe0,
+    0xfbf0,
+    0xfc0c,
+    0xfc24,
+    0xfc3c,
+    0xfc4c,
+    0xfc68,
+    0xfc48,
+
+    [...]
+
+    0xfb98,
+    0xfb98,
+    0xfbb8,
+    0xfbac,
+    0xfbc4,
+    0xfbe8,
+    0xfbf4,
+    -- end
+
+Play PCM Audio
+--------------
+
+Now that we have a binary PCM file (say sound.raw), you can use,
+for example, the audacity open source editor/player to load and play it.
+
+Use the 'Import->Raw Data' menu to load the sound.raw file as
+signed 16 bit PCM, Little Endian, stereo format @16KHz:
+
+.. image:: img/audio_import.png
+     :width: 266px
+     :height: 287px
+     :align: center
+     :alt: audio_import
+
+After the file is imported you can analyze and play the one second audio file:
+
+.. image:: img/audio_file.png
+     :width: 1627px
+     :height: 505px
+     :align: center
+     :alt: audio_file

samples/shields/x_nucleo_cca02m1/img/audio_file.png

@@ -0,0 +1,14 @@
+CONFIG_STDOUT_CONSOLE=y
+CONFIG_PRINTK=y
+CONFIG_I2S=y
+CONFIG_GPIO=y
+CONFIG_AUDIO=y
+CONFIG_AUDIO_DMIC=y
+CONFIG_AUDIO_MPXXDTYY=y
+
+# When on-board microphone is used the DMA must run w/o things
+# that could slow it down. So DMA logging must be completely
+# disabled and DMA interrupts must run at maximum priority.
+
+CONFIG_DMA=y
+CONFIG_DMA_0_IRQ_PRI=0

samples/shields/x_nucleo_cca02m1/img/audio_import.png

@@ -0,0 +1,7 @@
+sample:
+  name: X-NUCLEO-CCA02M1 sensor shield
+tests:
+  test:
+    harness: shield
+    tags: shield
+    depends_on: arduino_i2s

samples/shields/x_nucleo_cca02m1/prj.conf

@@ -0,0 +1,197 @@
+/*
+ * Copyright (c) 2019 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <string.h>
+#include <zephyr.h>
+#include <misc/printk.h>
+
+#include <gpio.h>
+#include <led.h>
+
+#include <audio/dmic.h>
+
+/* uncomment if you want PCM output in ascii */
+/*#define PCM_OUTPUT_IN_ASCII		1  */
+
+#define STEREO	1
+
+#define AUDIO_FREQ		16000
+#define CHAN_SIZE		16
+#ifdef STEREO
+#define PCM_BLK_SIZE_MS		(((AUDIO_FREQ/1000) * sizeof(s16_t)) * 2)
+#else
+#define PCM_BLK_SIZE_MS		((AUDIO_FREQ/1000) * sizeof(s16_t))
+#endif
+
+#define NUM_MS		1000
+
+K_MEM_SLAB_DEFINE(rx_mem_slab, PCM_BLK_SIZE_MS, NUM_MS, 1);
+
+struct pcm_stream_cfg mic_streams = {
+	.pcm_rate = AUDIO_FREQ,
+	.pcm_width = CHAN_SIZE,
+	.block_size = PCM_BLK_SIZE_MS,
+	.mem_slab = &rx_mem_slab,
+};
+
+struct dmic_cfg cfg = {
+	.io = {
+		/* requesting a pdm freq around 2MHz */
+		.min_pdm_clk_freq = 1800000,
+		.max_pdm_clk_freq = 2500000,
+	},
+	.streams = &mic_streams,
+	.channel = {
+#ifdef STEREO
+		.req_num_chan = 2,
+#else
+		.req_num_chan = 1,
+#endif
+	},
+};
+
+void *rx_block[NUM_MS];
+size_t rx_size = PCM_BLK_SIZE_MS;
+
+#ifdef STEREO
+#include <stm32f4xx_ll_tim.h>
+
+/*
+ * MIC_CLK_x2:     PB4 (TIM3_CH1) - IN
+ * MIC_CLK_NUCLEO: PB5 (TIM3_CH2) - OUT
+ */
+static int AUDIO_IN_Timer_Init(void)
+{
+	TIM_TypeDef *tim3 = (TIM_TypeDef *)DT_TIM_STM32_3_BASE_ADDRESS;
+	LL_TIM_IC_InitTypeDef sICConfig;
+	LL_TIM_InitTypeDef sConfig;
+	LL_TIM_OC_InitTypeDef ocConfig;
+
+	/* Enable TIM3 peripheral clock */
+	LL_APB1_GRP1_EnableClock(DT_TIM_STM32_3_CLOCK_BITS);
+
+	/* Configure the Input: channel_1 */
+	LL_TIM_IC_StructInit(&sICConfig);
+	sICConfig.ICPolarity  = LL_TIM_IC_POLARITY_RISING;
+	sICConfig.ICActiveInput = LL_TIM_ACTIVEINPUT_DIRECTTI;
+	sICConfig.ICPrescaler = LL_TIM_ICPSC_DIV1;
+	sICConfig.ICFilter = 0;
+	if (LL_TIM_IC_Init(tim3, LL_TIM_CHANNEL_CH1, &sICConfig) == ERROR) {
+		return -1;
+	}
+
+	/* Configure TIM3 in Gated Slave mode for the external trigger
+	 * (Filtered Timer Input 1) */
+	LL_TIM_SetSlaveMode(tim3, LL_TIM_CLOCKSOURCE_EXT_MODE1);
+	LL_TIM_SetTriggerInput(tim3, LL_TIM_TS_TI1FP1);
+
+	/* Initialize TIM3 counter */
+	LL_TIM_StructInit(&sConfig);
+	sConfig.Prescaler = 0;
+	sConfig.ClockDivision = 0;
+	sConfig.Autoreload = 1;
+	sConfig.CounterMode = LL_TIM_COUNTERMODE_UP;
+	sConfig.RepetitionCounter = 0;
+	if (LL_TIM_Init(tim3, &sConfig) == ERROR) {
+		return -1;
+	}
+
+	LL_TIM_SetTriggerOutput(tim3, LL_TIM_TRGO_RESET);
+
+	/* Initialize TIM3 peripheral in PWM mode */
+	LL_TIM_OC_StructInit(&ocConfig);
+	ocConfig.OCMode = LL_TIM_OCMODE_PWM1;
+	ocConfig.OCPolarity = LL_TIM_OCPOLARITY_HIGH;
+	if (LL_TIM_OC_Init(tim3, LL_TIM_CHANNEL_CH2, &ocConfig) == ERROR) {
+		return -1;
+	}
+
+	LL_TIM_OC_SetCompareCH2(tim3, 1);
+
+	/* Enable TIM3 */
+	LL_TIM_CC_EnableChannel(tim3, LL_TIM_CHANNEL_CH1 | LL_TIM_CHANNEL_CH2);
+	LL_TIM_EnableCounter(tim3);
+
+	return 0;
+}
+#endif
+
+void main(void)
+{
+	int i;
+	u32_t ms;
+
+	printk("x_nucleo_cca02m1 test!!\n");
+
+	int ret;
+
+	struct device *mic_dev = device_get_binding(DT_ST_MPXXDTYY_0_LABEL);
+
+	if (!mic_dev) {
+		printk("Could not get pointer to %s device\n",
+			DT_ST_MPXXDTYY_0_LABEL);
+		return;
+	}
+
+#ifdef STEREO
+	ret = AUDIO_IN_Timer_Init();
+	if (ret < 0) {
+		printk("timer init error\n");
+		return;
+	}
+#endif
+
+	ret = dmic_configure(mic_dev, &cfg);
+	if (ret < 0) {
+		printk("microphone configuration error\n");
+		return;
+	}
+
+	ret = dmic_trigger(mic_dev, DMIC_TRIGGER_START);
+	if (ret < 0) {
+		printk("microphone start trigger error\n");
+		return;
+	}
+
+	/* Acquire microphone audio */
+	for (ms = 0; ms < NUM_MS; ms++) {
+		ret = dmic_read(mic_dev, 0, &rx_block[ms], &rx_size, 2000);
+		if (ret < 0) {
+			printk("microphone audio read error\n");
+			return;
+		}
+	}
+
+	/* print PCM stream */
+#ifdef PCM_OUTPUT_IN_ASCII
+	printk("-- start\n");
+	int j;
+
+	for (i = 0; i < NUM_MS; i++) {
+		u16_t *pcm_out = rx_block[i];
+
+		for (j = 0; j < rx_size/2; j++) {
+			printk("0x%04x,\n", pcm_out[j]);
+		}
+	}
+	printk("-- end\n");
+#else
+	unsigned char pcm_l, pcm_h;
+	int j;
+
+	for (i = 0; i < NUM_MS; i++) {
+		u16_t *pcm_out = rx_block[i];
+
+		for (j = 0; j < rx_size/2; j++) {
+			pcm_l = (char)(pcm_out[j] & 0xFF);
+			pcm_h = (char)((pcm_out[j] >> 8) & 0xFF);
+
+			z_impl_k_str_out(&pcm_l, 1);
+			z_impl_k_str_out(&pcm_h, 1);
+		}
+	}
+#endif
+}