Using the Audio Class Demo Application
- Former user (Deleted)
- WES Admin
Micrium provides a demo application that lets you test and evaluate the class implementation. Source template files are provided.
Note that the demo application provided by Micriµm is only an example and is intended to be used as a starting point to develop your own application.
Configuring Device Application
The audio class provides two demos:
- Microphone demo exercises isochronous IN transfers and consequently the record stream and some class-specific requests.
- Loopback demo exercises isochronous IN and OUT transfers, that is respectively record and playback streams. Loopback demo can be thought as a headset demo.
The demo application files offering the two audio demos are provided for µC/OS-II and µC/OS-III and should be considered as example that you can modify. The files composing the demo application are:
| File | Description | Location |
|---|---|---|
app_cfg.h | Contains a few constants to configure its internal tasks. | Not provided in package. |
app_usbd_cfg.h | Contains constants related to audio class demos. | \Micrium\Software\uC-USB-Device-V4\App\Device\ |
app_usbd_audio.c | Allows to initialize audio class. Refer to section Audio Class Instance Configuration for more details. | \Micrium\Software\uC-USB-Device-V4\App\Device\ |
usbd_audio_drv_simulation.c usbd_audio_drv_simulation.h
| Simulates a microphone and a headset used as a loopback. | \Micrium\Software\uC-USB-Device-V4\App\Device\ |
usbd_audio_drv_simulation_data.c | Defines audio data waveforms samples used by the microphone demo. | \Micrium\Software\uC-USB-Device-V4\App\Device\ |
The use of these constants usually defined in app_cfg.h or app_usbd_cfg.h allow you to use one of the audio demos.
| Constant | Description | Demo | File |
|---|---|---|---|
APP_CFG_USBD_AUDIO_DRV_SIMULATION_PRIO | Priority of the task used by the microphone or loopback demo. Since the microphone or loopback task simulates a hardware behavior, the priority of this task should be greater than the priority of the record, playback and core tasks. Furthermore, the microphone or loopback task uses a 1-ms delay in certain circumstances. You should ensure that the tick rate for µC/OS-II or OS-III is set to 1000 ticks per second. | Both | app_cfg.h |
APP_CFG_USBD_AUDIO_DRV_SIMULATION_STK_SIZE | Stack size of the tasks used by microphone or loopback demo. A default value can be 512. | Both | app_cfg.h |
APP_CFG_USBD_AUDIO_EN | Enables the audio class demo application. Must be set to DEF_ENABLED. | Both | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_SIMULATION_LOOP_EN | Enables microphone or loopback demo. DEF_DISABLED enables the microphone demo and DEF_ENABLED the loopback demo. | Both | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_DRV_SIMULATION_DATA_WAVEFORM | Selects the sound type, that is the waveform used to generate a certain tone. Possible values are:
USBD_AUDIO_DRV_SIMULATION_DATA_WAVEFORM_SINE (default)USBD_AUDIO_DRV_SIMULATION_DATA_WAVEFORM_SQUARE USBD_AUDIO_DRV_SIMULATION_DATA_WAVEFORM_SAWTOOTH USBD_AUDIO_DRV_SIMULATION_DATA_WAVEFORM_BEEP_BEEP | Microphone | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_DRV_SIMULATION_DATA_FREQ | Selects frequency of the waveform. Possible values are:
USBD_AUDIO_DRV_SIMULATION_DATA_FREQ_100_HZ
(default)USBD_AUDIO_DRV_SIMULATION_DATA_FREQ_1000_HZ | Microphone | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_TASKS_Q_LEN | Specifies the queue length for playback & record tasks. | Both | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_RECORD_NBR_BUF | Configures the maximum number of record buffers. | Both | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_RECORD_CORR_PERIOD | Configures the record stream built-in correction period in milliseconds. | Both | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_PLAYBACK_NBR_BUF | Configures the maximum number of playback buffers. | Loopback | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_PLAYBACK_CORR_PERIOD | Configures the playback stream built-in correction period in milliseconds. | Loopback | app_usbd_cfg.h |
APP_CFG_USBD_AUDIO_NBR_ENTITY | Configures the number of entities composing the audio function. | Both | app_usbd_cfg.h |
Stream Correction
It is possible to enable the stream correction for the microphone and loopback demos, that is constants USBD_AUDIO_CFG_RECORD_CORR_EN, USBD_AUDIO_CFG_PLAYBACK_CORR_EN and/or USBD_AUDIO_CFG_PLAYBACK_FEEDBACK_EN. But keep in mind that it does NOT represent a real situation of stream correction usage as both demos simulate the codec behavior using a task and consequently does not represent a real audio timing.
Running the Demo Application
For demos explanation purpose, we will consider the operating system Microsoft Windows 7 or later.
Microphone demo
The microphone demo requires the following components on the host PC side:
- USB or jack headphone, speaker or headset with built-in speaker.
- Sound Manager (accessible via menu Start > Control Panel > Sound).
The microphone demo is built using an audio function topology defined in the file usbd_audio_dev_cfg.c and composed of:
- 1 Input Terminal of type analog mic IN,
- 1 Output Terminal of type USB IN,
- 1 Feature Unit to manage volume and mute controls,
- 1 record AudioStreaming interface associated to the Input Terminal.
Refer to Figure - usbd_audio_dev_cfg.c - Typical Topologies Example for a visual representation of this audio function.
Figure - Microphone Demo shows the principle of the microphone demo.
(1) The Windows audio driver opens the record stream by selecting the first operational AudioStreaming interface. This step is done automatically when the audio device is connected to the PC.
(2) The microphone task detects that the stream is open and starts sending pre-defined record data to the host. The record data corresponds to the waveform selected with the constant APP_CFG_USBD_AUDIO_DRV_SIMULATION_DATA_WAVEFORM. In fact, the audio class record task will take care of submitting record data via isochronous IN transfers (USBD_IsocTxAsync). The host will forward record data to a headphone for instance. You should hear the waveform (sinus, square, sawtooth or beep beep). If the host sends some requests to change the volume or to mute/unmute the stream, the microphone task will apply the volume or mute change on the record data accordingly.
(3) The Windows audio driver closes the stream by selecting the default AudioStreaming interface. This action is done only if you decide to disable the microphone from the Sound Manager.
Upon connection of your audio device, the simulated microphone device should appear in the recording devices list of the Sound Manager as shown in Figure - Sound Manager - Microphone in Recording Devices List. In this example, the recording device is identified as "Micrium Audio Product" (ProductStrPtr field of USBD_DEV_CFG set to this string).
In order to listen to the waveform signal, you need to ensure that:
- the volume level is different from 0 and the microphone is not muted. Select your microphone, click the button "Properties", go to the tab "Levels" and check the settings. It should look like Figure - Sound Manager - Microphone Levels.
- the playthrough feature is enabled. Select your microphone, click the button "Properties", go to the tab "Listen" and select "Listen to this device". Ensure that the Windows audio driver will playback the record data through your headphone by looking at the "Playback through this device" list (cf. Figure - Sound Manager - Microphone Playthrough).
Loopback demo
The loopback demo requires the following components on the host PC side:
- USB or jack headphone, speaker or headset with built-in speaker.
- Music Player (for example, Windows Media Player).
- Sound Manager (accessible via menu Start > Control Panel > Sound).
The loopback demo is built using an audio function topology defined in the file usbd_audio_dev_cfg.c and composed of:
- Two Input terminals of type analog mic IN and USB OUT,
- Two Output terminals of type USB IN and speaker,
- Two Feature units to manage volume and mute controls for microphone and speaker parts.
- Two AudioStreaming interfaces (one record and one playback). Each associated to one of the Input terminals.
Refer to Figure - usbd_audio_dev_cfg.c - Typical Topologies Example for a visual representation of this audio function.
Using the Audio Class Demo Application#Figure - Loopback Demo shows the principle of the loopback demo which can be seen as a simulated headset.
(1) The Windows audio driver opens the record and playback streams by selecting the first operational interface of each AudioStreaming (AS) interface. This step is done automatically for the microphone AS interface when the audio device is connected to the PC. For the speaker AS, you will have to ensure that it is enabled in the Sound Manager (cf. below).
(2) Both streams must be open in order to start the streams communication. The loopback task will basically perform two sequential operations seamlessly: processing playback stream and processing record stream. The loopback task detects that the playback stream is open and retrieves one of the isochronous OUT data buffers stored in the audio class. The playback buffer is stored in a circular buffer. Playback data comes from a music player playing songs. I f the host sends some requests to change the volume or to mute/unmute the playback stream, the loopback task will apply the volume or mute change on the playback data accordingly.
(3) The loopback task continues its execution by processing the record stream. If the record stream is open, it obtains a playback buffer from the circular buffer. This one becomes a record buffer. The loopback task passes the record buffer to the audio class which will take care of submitting record data via isochronous IN transfers . The host will forward record data to a headphone for instance. You should hear the song from the music player (if some settings explained below for the microphone are correct). If the host sends some requests to change the volume or to mute/unmute the record stream, the loopback task will apply the volume or mute change on the record data accordingly.
(4) The Windows audio driver closes streams by selecting the default AudioStreaming interface for the microphone and speaker. This action is done only if you decide to disable the microphone and speaker from the Sound Manager.
Upon connection of your audio device, the simulated headset device should appear in two lists. The microphone should be listed in the recording devices list of the Sound Manager as shown in Using the Audio Class Demo Application#Figure - Sound Manager - Microphone in Recording Devices List, whereas the speaker part should be listed in the playback devices list as shown in Figure - Sound Manager - Speaker in Playback Devices List. In this example, the playback and recording device are identified as "Micrium Audio Product" (ProductStrPtr field of USBD_DEV_CFG set to this string).
In order to listen to the song played by the music player, you need to ensure that:
- Speaker: the speaker appears in the list as the "Default Device" as shown in Using the Audio Class Demo Application#Figure - Sound Manager - Speaker in Playback Devices List. If it is not the case, right-click on the "Micrium Audio Product" speaker and select "Set as Default Device".
- Microphone: the volume level is different from 0 and the microphone is not muted. Refer to Using the Audio Class Demo Application#Figure - Sound Manager - Microphone Levels.
- Microphone: the playthrough feature is enabled. Select your microphone, click the button "Properties", go to the tab "Listen" and select "Listen to this device". Ensure that the Windows audio driver will playback the record data through your headphone by looking at the "Playback through this device" list (cf. Using the Audio Class Demo Application#Figure - Sound Manager - Microphone Playthrough for Loopback Demo). Do not select "Default Playback Device" as it could be the "Micrium Audio Product" speaker. In that case you won't hear anything as the music player and the microphone share the same speaker of your audio device. Explicitly select another speaker device (for example, your jack headphone).
