XNucleoCCA02M1.h

00001 /**
00002  ******************************************************************************
00003  * @file    XNucleoCCA02M1.h
00004  * @author  AST / Software Platforms and Cloud
00005  * @version V1.0
00006  * @date    October 17th, 2016
00007  * @brief   Class header file for the X_NUCLEO_CCA02M1 expansion board.
00008  ******************************************************************************
00009  * @attention
00010  *
00011  * <h2><center>&copy; COPYRIGHT(c) 2015 STMicroelectronics</center></h2>
00012  *
00013  * Redistribution and use in source and binary forms, with or without modification,
00014  * are permitted provided that the following conditions are met:
00015  *   1. Redistributions of source code must retain the above copyright notice,
00016  *      this list of conditions and the following disclaimer.
00017  *   2. Redistributions in binary form must reproduce the above copyright notice,
00018  *      this list of conditions and the following disclaimer in the documentation
00019  *      and/or other materials provided with the distribution.
00020  *   3. Neither the name of STMicroelectronics nor the names of its contributors
00021  *      may be used to endorse or promote products derived from this software
00022  *      without specific prior written permission.
00023  *
00024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00025  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00026  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00028  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00029  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00030  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00032  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00033  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034  *
00035  ******************************************************************************
00036  */
00037 
00038 
00039 /* Generated with STM32CubeTOO -----------------------------------------------*/
00040 
00041 
00042 /* Define to prevent recursive inclusion -------------------------------------*/
00043 
00044 #ifndef __X_NUCLEO_CCA02M1_CLASS_H
00045 #define __X_NUCLEO_CCA02M1_CLASS_H
00046 
00047 
00048 /* Configuration -------------------------------------------------------------*/
00049 
00050 /**
00051  * Enable to debug the duration of functions related to the I2S and USB usage
00052  * through an oscilloscope.
00053  */
00054 //#define X_NUCLEO_CCA02M1_DEBUG
00055 
00056 
00057 /* Includes ------------------------------------------------------------------*/
00058 
00059 /* ACTION 1 ------------------------------------------------------------------*
00060  * Include here platform specific header files.                               *
00061  *----------------------------------------------------------------------------*/
00062 #include "mbed.h"
00063 #include "I2S.h"
00064 #include "FrequencyDivider.h"
00065 #include "USBAudio.h"
00066 /* ACTION 2 ------------------------------------------------------------------*
00067  * Include here expansion board configuration's header files.                 *
00068  *----------------------------------------------------------------------------*/
00069 /* ACTION 3 ------------------------------------------------------------------*
00070  * Include here expansion board's components' header files.                   *
00071  *                                                                            *
00072  * Example:                                                                   *
00073  *   #include "COMPONENT_1.h"                                                 *
00074  *   #include "COMPONENT_2.h"                                                 *
00075  *----------------------------------------------------------------------------*/
00076 #include "component_def.h"
00077 #include "PDM2PCMAudio.h"
00078 
00079 
00080 /* Definitions ---------------------------------------------------------------*/
00081 
00082 /* Maximum number of mounted "X-NUCLEO-CCA02M1" Expansion Boards. */
00083 #define EXPBRD_MOUNTED_NR_MAX    1
00084 
00085 /* Bytes per sample. */
00086 #define BYTES_PER_SAMPLE         2
00087 
00088 /* Default paramters. */
00089 #define DEFAULT_FREQUENCY        32000
00090 #define DEFAULT_CHANNELS         2
00091 
00092 /* PCM buffer size and thresholds in ms. */
00093 #define PCM_BUFFER_TH_LOW_ms     1
00094 #define PCM_BUFFER_TH_MED_ms     4
00095 #define PCM_BUFFER_TH_HIG_ms     7
00096 #define PCM_BUFFER_SIZE_ms       9
00097 
00098 
00099 /* Types ---------------------------------------------------------------------*/
00100 
00101 /* Audio processor initialization structure. */
00102 typedef struct
00103 {
00104     uint32_t frequency;
00105     uint8_t channels;
00106 } XNucleoCCA02M1_init_t;
00107 
00108 
00109 /* Classes -------------------------------------------------------------------*/
00110 
00111 /** Class representing a X_NUCLEO_CCA02M1 board.
00112  */
00113 class XNucleoCCA02M1
00114 {
00115 public:
00116 
00117     /*** Constructor, Destructor, and Initialization Methods ***/
00118 
00119     /**
00120      * @brief Constructor.
00121      * @param dpin  pin name of the data input/output pin of the I2S device.
00122      * @param clk   pin name of the clock pin of the I2S device.
00123      * @param wsel  pin name of the word select output pin of the I2S device (might be NC for PDM sources).
00124      * @param fdpin pin name of the data input pin of the I2S device (for full-duplex operations, default = NC).
00125      * @param mck   pin name of the master clock output pin of the I2S device (additional pin when needed for some external audio devices, default = NC)
00126      */
00127     XNucleoCCA02M1(PinName dpin, PinName clk, PinName wsel = NC, PinName fdpin = NC, PinName mck = NC) :
00128         dev_i2s(dpin, clk, wsel, fdpin, mck),
00129         _usb_enabled(false),
00130         _volume(PDM2PCM_NOGAIN_VOLUME),
00131         _frequency(DEFAULT_FREQUENCY),
00132         _channels(DEFAULT_CHANNELS),
00133         _callback_attached(false)
00134 #ifdef X_NUCLEO_CCA02M1_DEBUG
00135         , _i2s_signal(D13),
00136         _usb_signal(D12),
00137         _buffer_overrun(D11),
00138         _buffer_underrun(D10)
00139 #endif
00140     {
00141         /* Checking stackability. */
00142         if (!(_number_of_boards < EXPBRD_MOUNTED_NR_MAX))
00143             error("Instantiation of the X_NUCLEO_CCA02M1 expansion board failed: it can be stacked up to %d times.\r\n", EXPBRD_MOUNTED_NR_MAX);
00144         _XNucleoCCA02M1_Id = _number_of_boards++;
00145     }
00146 
00147     /**
00148      * @brief Destructor.
00149      */
00150     virtual ~XNucleoCCA02M1(void) {}
00151 
00152 
00153     /*** Public Component Related Methods ***/
00154 
00155     /**
00156     * @brief  Initializing the X_NUCLEO_CCA02M1 board.
00157     * @param  init Pointer to device specific initalization structure.
00158     * @retval "0" in case of success, an error code otherwise.
00159     */
00160     virtual status_t init(void *init = NULL);
00161 
00162     /**
00163      * @brief  Enabling transmission via USB.
00164      * @param  None.
00165      * @retval "0" in case of success, an error code otherwise.
00166      */
00167     virtual status_t enable_usb(void);
00168 
00169     /**
00170      * @brief  Disabling transmission via USB.
00171      * @param  None.
00172      * @retval "0" in case of success, an error code otherwise.
00173      */
00174     virtual status_t disable_usb(void);
00175 
00176     /**
00177      * @brief  Start recording audio.
00178      * @param  None.
00179      * @retval "0" in case of success, an error code otherwise.
00180      */
00181     virtual status_t record(void);
00182 
00183     /**
00184      * @brief  Attach a user-defined callback that will be executed whenever PCM
00185      *         data are ready, i.e. once each millisecond.
00186      *         The provided PCM buffer will be filled by the microphones.
00187      * @param  fptr Callback to attach.
00188      * @retval None.
00189      */
00190     void attach(void (*fptr) (int16_t *PCM_buffer, uint16_t PCM_buffer_bytes));
00191 
00192     /**
00193      * @brief  Attach a user-defined non-static callback that will be executed
00194      *         whenever PCM data are ready, i.e. once each millisecond.
00195      *         The provided PCM buffer will be filled by the microphones.
00196      * @param  tptr Pointer to an object.
00197      * @param  mptr Pointer to an object's callback.
00198      * @retval None.
00199      */
00200     template<typename T>
00201     void attach(T *tptr, void (T::*mptr) (int16_t *PCM_buffer, uint16_t PCM_buffer_bytes));
00202 
00203 
00204     /*** Other Public Expansion Board Related Methods ***/
00205 
00206     /*** Public Expansion Board Related Attributes ***/
00207 
00208     /* ACTION 4 --------------------------------------------------------------*
00209      * Declare here a public attribute for each expansion board's component.  *
00210      * You will have to call these attributes' public methods within your     *
00211      * main program.                                                          *
00212      *                                                                        *
00213      *   Example:                                                             *
00214      *     COMPONENT_1 *component_1;                                          *
00215      *     COMPONENT_2 *component_2;                                          *
00216      *------------------------------------------------------------------------*/
00217 
00218 
00219 protected:
00220 
00221     /*** Protected Expansion Board Related Related Methods ***/
00222 
00223     /* ACTION 5 --------------------------------------------------------------*
00224      * Declare here a protected initialization method for each expansion      *
00225      * board's component.                                                     *
00226      *                                                                        *
00227      * Example:                                                               *
00228      *   bool init_COMPONENT_1(void);                                         *
00229      *   bool init_COMPONENT_2(void);                                         *
00230      *------------------------------------------------------------------------*/
00231     /**
00232      * @brief  I2S callback which is executed whenever PCM data are ready, i.e. once
00233      *         each millisecond.
00234      * @param  narg Narg flag.
00235      * @retval None.
00236      */
00237     void i2s_callback(int narg);
00238 
00239     /**
00240      * @brief  Sending PCM data via USB.
00241      * @param  None.
00242      * @retval None.
00243      */
00244     void usb_handler(void);
00245 
00246 
00247     /*** Expansion Board's Instance Variables ***/
00248 
00249     /* ACTION 6 --------------------------------------------------------------*
00250      * Declare here the component's static and non-static data, one variable  *
00251      * per line.                                                              *
00252      *                                                                        *
00253      * Example:                                                               *
00254      *   int instance_id;                                                     *
00255      *   static int number_of_instances;                                      *
00256      *------------------------------------------------------------------------*/
00257 public:
00258 
00259     /* I2S Audio Device (exclusive). */
00260     I2S dev_i2s;
00261 
00262 
00263 protected:
00264 
00265     /* USB Audio Device. */
00266     USBAudio *_usb_audio;
00267     bool _usb_enabled;
00268 
00269     /* PDM to PCM conversion library. */
00270     PDM2PCMAudio *_pdm2pcm;
00271 
00272     /* PDM to PCM conversion parameters. */
00273     uint32_t _volume;
00274 
00275     /* Microphone parameters. */
00276     uint32_t _frequency;
00277     uint32_t _channels;
00278 
00279     /* Size of the buffers to store audio data. */
00280     uint32_t _PDM_samples_one_ms;
00281     uint32_t _PDM_samples_two_ms;
00282     uint32_t _PCM_samples_one_ms;
00283 
00284     /* Input and output audio buffers. */
00285     uint16_t *_PDM_buffer_two_ms; /* Input double-buffered PDM audio data, from microphones. */
00286     int16_t  *_PCM_buffer_n_ms;   /* Output n-ms-buffered PCM audio data, to USB. */
00287 
00288     /* Support audio buffers for processing data. */
00289     uint16_t *_PDM_buffer_one_ms;
00290     int16_t  *_USB_PCM_buffer_one_ms;
00291     int16_t  *_USER_PCM_buffer_one_ms;
00292 
00293     /* Indexes of the output PCM buffer. */
00294     static uint32_t _PCM_buffer_read_index;
00295     static uint32_t _PCM_buffer_write_index;
00296 
00297     /* User-defined PCM-data-ready callback. */
00298     Callback<void(int16_t *PCM_buffer, uint16_t PCM_buffer_bytes)> _callback;
00299     bool _callback_attached;
00300 
00301     /* Accessing shared areas: the PCM buffer. */
00302     static SingletonPtr<PlatformMutex> _mutex;
00303 
00304     /* Expansion board identifier. */
00305     uint8_t _XNucleoCCA02M1_Id;
00306 
00307     /* Number of expansion boards. */
00308     static uint8_t _number_of_boards;
00309 
00310 #ifdef X_NUCLEO_CCA02M1_DEBUG
00311     /* Signals for debugging purposes. */
00312     DigitalOut _i2s_signal;
00313     DigitalOut _usb_signal;
00314     DigitalOut _buffer_overrun;
00315     DigitalOut _buffer_underrun;
00316 #endif
00317 };
00318 
00319 #endif /* __X_NUCLEO_CCA02M1_CLASS_H */
00320 
00321 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/