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_SetDataFormat(AUDIO_STREAM_OUT, AUDIO_DATA_16_MONO);
  Audio_SetFrequency (AUDIO_STREAM_OUT,48000);
  Audio_SetMute      (AUDIO_STREAM_OUT, 0, 0);
  Audio_SetDataFormat(AUDIO_STREAM_IN, AUDIO_DATA_16_MONO);
  Audio_SetFrequency (AUDIO_STREAM_IN, 48000);
  Audio_SetVolume    (AUDIO_STREAM_IN, 0, 10 | AUDIO_VOLUME_AUTO_GAIN);
  Audio_SetMute      (AUDIO_STREAM_IN, 0, 0);
  
  while (1) {
    Audio_SetVolume(AUDIO_STREAM_OUT, 0, volume | AUDIO_VOLUME_AUTO_GAIN);
    switch (Command) {
      case START_REC:
        Audio_ReceiveData(nextdata, SAMP_NUM);
        Audio_Start (AUDIO_STREAM_IN);
        break;
      case STOP_CMD:
        Audio_Stop(AUDIO_STREAM_IN);
        Audio_Stop(AUDIO_STREAM_OUT);
        break;
      case START_PLY:
        Audio_SendData(lastdata, SAMP_NUM);
        Audio_Start(AUDIO_STREAM_OUT);
        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_event pointer 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] stream stream 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]	data	pointer to buffer for data to receive
[in]	num	number 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] stream stream 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]	data	pointer to buffer with data to send
[in]	num	number 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]	stream	stream identifier
[in]	format	data 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]	stream	stream identifier
[in]	frequency	Audio 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]	stream	stream identifier
[in]	channel	channel identifier
[in]	mute	mute 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]	stream	stream identifier
[in]	channel	channel identifier
[in]	volume	volume 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] event notification 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:

Bit	Event	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] stream stream 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] stream stream 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.

Content

Functions

Description

Function Documentation