Board Support  Version 1.0
Functions available when using the Board Software Components
 All Data Structures Functions Variables Groups Pages
Audio

Audio Interface. More...

Content

 Stream Identifiers
 Identifiers for audio streams.
 
 Channel Identifiers
 Identifiers for audio channels.
 
 Data Format Identifiers
 Identifiers for audio data formats.
 
 Audio Events
 Identifiers for audio events.
 

Functions

void Audio_SignalEvent (uint32_t event)
 Signal Audio Events.
 
int32_t Audio_Initialize (Audio_SignalEvent_t cb_event)
 Initialize Audio Interface.
 
int32_t Audio_Uninitialize (void)
 De-initialize Audio Interface.
 
int32_t Audio_SendData (const void *data, uint32_t num)
 Prepare for sending data to Audio output stream.
 
int32_t Audio_ReceiveData (void *data, uint32_t num)
 Prepare for receiving data from Audio input stream.
 
uint32_t Audio_GetDataTxCount (void)
 Get transmitted data count.
 
uint32_t Audio_GetDataRxCount (void)
 Get received data count.
 
int32_t Audio_Start (uint8_t stream)
 Start Audio stream.
 
int32_t Audio_Stop (uint8_t stream)
 Stop Audio stream.
 
int32_t Audio_Pause (uint8_t stream)
 Pause Audio stream.
 
int32_t Audio_Resume (uint8_t stream)
 Resume Audio stream.
 
int32_t Audio_SetVolume (uint8_t stream, uint8_t channel, uint8_t volume)
 Set volume level for Audio stream.
 
int32_t Audio_SetMute (uint8_t stream, uint8_t channel, bool mute)
 Set mute state for Audio stream.
 
int32_t Audio_SetDataFormat (uint8_t stream, uint8_t format)
 Set Audio data format.
 
int32_t Audio_SetFrequency (uint8_t stream, uint32_t frequency)
 Set Audio stream frequency.
 

Description

Audio Interface.

Audio interface functions connect to an audio controller on your device and can be used to send data to an output unit (speaker) and receive data from an input unit (microphone).

Code Example

The following code example is a stub that should demonstrate the principal usage of the audio interface.

:
void AudioThread (void const *argument) {
Audio_Initialize (&Audio_Cbk);
Audio_SetVolume (AUDIO_STREAM_IN, 0, 10 | AUDIO_VOLUME_AUTO_GAIN);
while (1) {
Audio_SetVolume(AUDIO_STREAM_OUT, 0, volume | AUDIO_VOLUME_AUTO_GAIN);
switch (Command) {
case START_REC:
Audio_ReceiveData(nextdata, SAMP_NUM);
break;
case STOP_CMD:
break;
case START_PLY:
Audio_SendData(lastdata, SAMP_NUM);
break;
}
osDelay(1);
}
}

Function Documentation

uint32_t Audio_GetDataRxCount ( void  )

Get received data count.

Returns
number of data items received

The function Audio_GetDataRxCount returns the number of currently received data items during Audio_ReceiveData operation.

uint32_t Audio_GetDataTxCount ( void  )

Get transmitted data count.

Returns
number of data items transmitted

The function Audio_GetDataTxCount returns the number of currently transmitted data items during Audio_SendData operation.

int32_t Audio_Initialize ( Audio_SignalEvent_t  cb_event)

Initialize Audio Interface.

Parameters
[in]cb_eventpointer to event notification function
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_Initialize initializes the audio interface. It is called when the middleware component starts operation.

The function performs the following operations:

  • Initializes the resources needed for the audio interface.
  • Registers the event notification function Audio_SignalEvent (callback function).

The parameter cb_event is a pointer to the Audio_SignalEvent function; use a NULL pointer when no callback signals are required.

int32_t Audio_Pause ( uint8_t  stream)

Pause Audio stream.

Parameters
[in]streamstream identifier
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_Pause pauses data transfer for an audio stream. Data stay registered and the transfer can be resumed by calling the Audio_Resume function.

The parameter stream specifies the stream (see Stream Identifiers).

int32_t Audio_ReceiveData ( void *  data,
uint32_t  num 
)

Prepare for receiving data from Audio input stream.

Parameters
[out]datapointer to buffer for data to receive
[in]numnumber of data items to send
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_ReceiveData registers for data to be received from the audio input stream. Actual transfer of data is started by calling the Audio_Start function and can be paused by calling the Audio_Pause function. It is resumed by calling the Audio_Resume function. It can also be canceled by calling the Audio_Stop function.

When transfer is active and no data is registered to be received, the AUDIO_EVENT_RX_OVERFLOW event is signaled by the Audio_SignalEvent callback function.

The parameter data is a pointer to the buffer for receiving the audio data. The parameter num identifies the number of data items to be received.

The data type depends on the used data format (see Data Format Identifiers):

  • uint8_t: AUDIO_DATA_8_MONO and AUDIO_DATA_8_STEREO
  • uint16_t: AUDIO_DATA_16_MONO and AUDIO_DATA_16_STEREO
  • uint32_t: AUDIO_DATA_32_MONO and AUDIO_DATA_32_STEREO

Data in stereo modes consists of two consecutive data items (L and R channel).

After all the data has been received the AUDIO_EVENT_RECEIVE_COMPLETE event is signaled by the Audio_SignalEvent callback function.

int32_t Audio_Resume ( uint8_t  stream)

Resume Audio stream.

Parameters
[in]streamstream identifier
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_Resume resumes data transfer for an audio stream that was paused by Audio_Pause.

The parameter stream specifies the stream (see Stream Identifiers).

int32_t Audio_SendData ( const void *  data,
uint32_t  num 
)

Prepare for sending data to Audio output stream.

Parameters
[in]datapointer to buffer with data to send
[in]numnumber of data items to send
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_SendData registers data to be sent to the audio output stream. Actual transfer of data is started by calling the Audio_Start function. Active transfer can be paused by calling the Audio_Pause function and resumed by calling the Audio_Resume function. Active transfer can be also canceled by calling the Audio_Stop function.

When transfer is active and no data is registered to be sent, the AUDIO_EVENT_TX_UNDERFLOW event is signaled by the Audio_SignalEvent callback function.

The parameter data is a pointer to the buffer containing the audio data. The parameter num identifies the number of data items to be sent.

The data type depends on the used data format (see Data Format Identifiers):

  • uint8_t: AUDIO_DATA_8_MONO and AUDIO_DATA_8_STEREO
  • uint16_t: AUDIO_DATA_16_MONO and AUDIO_DATA_16_STEREO
  • uint32_t: AUDIO_DATA_32_MONO and AUDIO_DATA_32_STEREO

Data in stereo modes consists of two consecutive data items (L and R channel).

After all the data has been sent the AUDIO_EVENT_SEND_COMPLETE event is signaled by the Audio_SignalEvent callback function.

int32_t Audio_SetDataFormat ( uint8_t  stream,
uint8_t  format 
)

Set Audio data format.

Parameters
[in]streamstream identifier
[in]formatdata format
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_SetDataFormat sets the audio stream data format.

The parameter stream specifies the stream (see Stream Identifiers).

The parameter format specifies the data format (see Data Format Identifiers).

int32_t Audio_SetFrequency ( uint8_t  stream,
uint32_t  frequency 
)

Set Audio stream frequency.

Parameters
[in]streamstream identifier
[in]frequencyAudio frequency in Hz
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_SetFrequency sets the audio stream sampling frequency.

The parameter stream specifies the stream (see Stream Identifiers).

The parameter frequency specifies the audio sampling frequency in Hz.

int32_t Audio_SetMute ( uint8_t  stream,
uint8_t  channel,
bool  mute 
)

Set mute state for Audio stream.

Parameters
[in]streamstream identifier
[in]channelchannel identifier
[in]mutemute state
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_SetMute sets the audio stream mute state for specified channel.

The parameter stream specifies the stream (see Stream Identifiers).

The parameter channel specifies the channel (see Channel Identifiers).

The parameter mute is the mute state and can have the values true - mute on or false - mute off.

int32_t Audio_SetVolume ( uint8_t  stream,
uint8_t  channel,
uint8_t  volume 
)

Set volume level for Audio stream.

Parameters
[in]streamstream identifier
[in]channelchannel identifier
[in]volumevolume level (0..100)
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_SetVolume sets the audio stream volume for a specified channel.

The parameter stream specifies the stream (see Stream Identifiers).

The parameter channel specifies the channel (see Channel Identifiers).

The parameter volume is the volume level and can have values between [0..100]. Some development boards support an automatic gain control (AGC) feature. To use it, OR volume with AUDIO_VOLUME_AUTO_GAIN. If this feature is not supported, the function will return an error.

Code Example

Audio_SetVolume(AUDIO_STREAM_IN, 0, 10 | AUDIO_VOLUME_AUTO_GAIN);
void Audio_SignalEvent ( uint32_t  event)

Signal Audio Events.

Parameters
[in]eventnotification mask
Returns
none

The function Audio_SignalEvent is called by the audio driver to notify the application about Audio Events. The function is registered through the function Audio_Initialize.

The argument event represents the notification mask of the events.

Each event is coded in a separate bit; therefore it is possible to signal multiple events in the event callback function. The following callback notifications are generated:

BitEvent Description
0 AUDIO_EVENT_SEND_COMPLETE Occurs after the specified number of data items by function Audio_SendData have been sent.
1 AUDIO_EVENT_RECEIVE_COMPLETE Occurs after the specified number of data items by function Audio_ReceiveData have been received.
2 AUDIO_EVENT_TX_UNDERFLOW Occurs during active output stream transfer and no data is registered to be sent.
3 AUDIO_EVENT_RX_OVERFLOW Occurs during active input stream transfer and no data is registered to be received.
int32_t Audio_Start ( uint8_t  stream)

Start Audio stream.

Parameters
[in]streamstream identifier
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_Start starts data transfer for an audio stream.

The parameter stream specifies the stream (see Stream Identifiers).

int32_t Audio_Stop ( uint8_t  stream)

Stop Audio stream.

Parameters
[in]streamstream identifier
Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_Stop stops data transfer for an audio stream. It also cancels any data registered by Audio_SendData function (for output stream) or by Audio_ReceiveData (for input stream).

The parameter stream specifies the stream (see Stream Identifiers).

int32_t Audio_Uninitialize ( void  )

De-initialize Audio Interface.

Returns
  • 0: function succeeded
  • -1: function failed

The function Audio_Uninitialize de-initializes the audio interface. It is called when the middleware component stops operation and releases the software resources used by the interface.