AVR32 UC3 Audio Decoder Over USB

Atmel provides detailed source code for an MP3 decoder that runs on its AVR32 UC3 MCU. This article explains in detail how to configure and use it.

This article will help the reader to use the AVR32® UC3 Audio Decoder over USB software. This software includes a software MP3 decoder, a file system, and USB host mass storage class support.

For more information about the AVR32 architecture, please refer to the appropriate documents available at http://www.atmel.com/avr32.

License

The MP3 audio decoder (MAD) is distributed under the terms of the GPL. The JPEG decoder (IJG) license can be found in the file /SERVICES/PICTURES/JPG/IJG/license.txt. The memory manager (dlmalloc) license can be found in the file /SERVICES/MEMORY/MEMORY_MANAGER/DLMALLOC/license.txt.

Requirements

The software referenced in this article requires several components:

• A computer running Microsoft® Windows® 2000/XP/Vista or Linux®
• AVR32 Studio and the GNU toolchain (GCC) or IAR Embedded Workbench® for the AVR32 compiler
• A JTAGICE mkII or AVROne! debugger

Theory of operation

Overview

Today, embedded MP3 decoders are everywhere for consumers listening to audio content on mobile devices.

MP3

MPEG-1 Audio Layer III, more commonly referred to as MP3, is a digital audio encoding format using a form of lossy data compression. Several bit rates are specified in the MPEG-1 Audio Layer III standard: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, and 320 Kbps. The available sampling frequencies are 32, 44.1, and 48 KHz, and a sample rate of 44.1 KHz is almost always used. 128 Kbps bitrate files are slowly being replaced with higher bitrates such as 192 Kbps, with some being encoded up to the MP3 maximum of 320 Kbps.

A tag, in a compressed audio file, is a section of the file which contains metadata such as the title, artist, album, track number, or other information about the file's contents.

The chosen MP3 decoder here is MAD (libmad), a high-quality MPEG audio decoder. It currently supports MPEG-1 and the MPEG-2 extension to lower sampling frequencies, as well as the so-called MPEG 2.5 format. All three audio layers (Layer I, Layer II, and Layer III) are fully implemented. MAD does not yet support MPEG-2 multichannel audio (although it should be backward compatible with such streams).

Block diagram

Figure 1 shows the UC3 interfacing to the USB stick, and outputting the audio stream from the key to the external DAC. The user can control the player using a keypad, or running a customizable Human Machine Interface (HMI).


Software architecture
Figure 2 shows the basic software architecture of the application.


The application does not require any operating system to run. The main() function is in charge of calling the software tasks (using a scheduler) that make audio decoding, HMI, and USB management possible. There are five tasks:

• The Communication Task contains the HMI of the application. This task holds the real intelligence of the user application and interfaces directly with the Audio Interface (AI). This is the task that the user should modify for their own application.
• Audio Interface Task: This task handles dynamic support for any newly plugged-in device types. For example, if a new device, using another class than the mass storage class, is plugged in, and if this class is supported by the application, then this task will tell the Audio Interface to link the Audio Interface API to a low level API that supports this class. All the mechanisms in place to dynamically link an API to this abstract API are located in the file: /SERVICES/AUDIO/AUDIO_PLAYER/audio_interface.[c|h]. In this application, only the USB mass storage class is implemented. Therefore, this function is not used.
• The last task is a macro used for feature tasks. In the MP3 audio player using USB, the modules involved will be the MP3 decoder, the USB stack, and the host mass storage task:
  • The MP3 Codec Task: This task is in charge of Audio Decoding management.
  • The USB Task: This task handles the USB stack and events.
  • The Host Mass Storage Task: This task will check for newly connected devices and initialize them using the USB mass storage class.

The main loop of the application is a simple free-running task scheduler:

The Audio Interface can also support iPod audio decoding through the USB audio class. Please refer to the application note AVR32730: AVR32 UC3 iPod Support Over USB for more information.

Audio Interface API

The audio player is a generic audio player interface and is designed to support multiple audio formats besides MP3.

Overview

The Audio Interface manages disk navigation, audio navigation, and audio control. Thus, the user does not have to directly interface with the file system and audio control APIs. This greatly simplifies the software architecture.

The Audio Interface can be used in two ways:

• Using asynchronous functions, the results or effects of which may not be produced in a single iteration, usually leads to the use of state machines in the user firmware (since one must wait for the completion of a command before launching a new one), and has the advantage of reducing the risk of audio underrun. Asynchronous functions always have the "ai_async" prefix.
  Note that only one asynchronous function can be used at a time.
• Using synchronous functions, which are executed immediately, this drastically simplifies the user firmware architecture (no use of state machines since the synchronous AI functions are immediately executed), but may produce audio underruns since the execution time of these functions may be too long. Synchronous functions just have the "ai_" prefix.

All functions of the Audio Interface have a synchronous and asynchronous interface. For example, the command which returns the number of drives is:

• ai_async_nav_drive_nb() in the asynchronous interface
• ai_nav_drive_nb() in the synchronous interface

Using asynchronous functions shall be the preferred solution in order to avoid audio underruns.

Audio Interface (AI) architecture

The AI commands to interface the audio player are divided into three categories (See Figure 3):

• Disk navigation (Disk Nav) to browse into the tree architectures of the USB device
• Audio navigation (Audio Nav) to manage a list of playable songs
• Audio control (Audio CTRL) to control the audio stream (such as play, pause, and fast forward)

Disk Navigator: "Browse into the tree architectures of the mass storage device"

The Disk Navigator is similar to a file explorer. It is used to navigate in the tree architectures of the connected USB device. It will hide all files whose extension differs from *.mp3, *.pls, *.smp, or *.m3u. The file extension filtering is automatically updated according to the modules selected (such as MP3 and playlists).

The Disk Navigator is totally independent from the Audio Navigator.

The commands associated with this module are used to navigate into the disks/directories, and to synchronize the selected file/folder with the Audio Nav module. This synchronization is made with two commands: ai_nav_getplayfile and ai_audio_nav_playfile. See the "Disk Navigation" section later in this article for a complete list of commands.

Audio Navigator: "Manage a list of playable songs"

The Audio Navigator deals with a list of files. This list is defined once an ai_audio_nav_playfile command is executed. This command sets the list of files to be played according to the current selection in the Disk Navigator and to the Audio Navigator ai_audio_nav_expmode_set option.

When the ai_audio_nav_playfile command is executed:

• If the Disk Navigator is currently pointing to a playlist (*.m3u), then only the files of this playlist will be included in the Audio Navigator file list.
• If the Disk Navigator is currently pointing to a disk or a file, then the file list will depend on the audio explorer mode (set by the ai_audio_nav_expmode_set command) (See Table 1).
• If the Disk Navigator is currently pointing to a folder, the Audio Navigator will not enter into it. It will look for the first file that is in the current directory and build its file list according to the previous rules.
• If the Disk Navigator is not pointing to any files or folders (which is the case after a mount or a goto) when a directory or a playlist is selected, then it will select the first file of the file list.

Explorer Mode	Behavior
AUDIO_EXPLORER_MODE_DISKS	Builds a file list off all playable songs of all disks, and starts playing from the selected file.
AUDIO_EXPLORER_MODE_DISK	Builds a file list off all playable songs of the current disk only, and starts playing from the selected file.
AUDIO_EXPLORER_MODE_DIRONLY	Builds a file list of all playable songs that are contained in the current directory, and starts playing from the selected file. Sub directories are ignored.
AUDIO_EXPLORER_MODE_DIRSUB	Builds a file list off all playable songs that are contained in the current directory and its sub-directories, and starts playing from the selected file.

Note that the playing order can be changed at compilation time by enabling a define. This is fully explained in the "Example 3 — Change the playing order" section later in this article.

Once the file list is set, two main commands are available to navigate into it:

• ai_audio_nav_next (select next file).
• ai_audio_nav_previous (select previous file).

Options can also be defined for the Audio Navigator (to change the repeat mode, or enable/disable the shuffle mode).

To synchronize the Disk Navigator with the Audio Navigator, i.e., to make the Disk Navigator select the file played by the Audio Navigator, the command ai_nav_getplayfile can be used. See the "Audio Navigation" section later in this article for a complete list of commands.

Audio Control: "control the audio stream
(play/pause/fast forward/...)"

This module controls the audio stream of the selected file (selected by the Audio Navigator). Commands like play, pause, stop, fast forward, and fast rewind are available. See the "Audio Control" section later in this article for a complete list of commands (See Table 2).

Limitations
Speed

Speed navigation (such as file browsing) in directories may be affected if:

• A high-bitrate file is played at the same time.
• Directories have many files.
• The playlist includes many files.

Disk navigation

The exploration is based on a selector displacement. The file list is the list of the files in the current directory according to the extension filter (i.e., .mp3, .m3u, .pls, and .smp).

The file list:

• Is updated when you exit or enter a directory or a disk
• Starts with the directories then the files
• Is sorted in the creation order

Command Name	Input	Output		Description
		Return	Extra Result
ai_get_product_id	–	Product ID	–	Returns the product identifier (USB PID) of the connected device (if available).
ai_get_vendor_id	–	Vendor ID	–	Returns the vendor identifier (USB VID) of the connected device (if available).
ai_get_serial_number	–	Length of the serial number in bytes	Serial number	Returns the serial number of the connected device (if available).
ai_nav_drive_nb	–	Number of drive	–	Returns the serial number of disk available.
ai_nav_drive_set	Drive Number	True or false	–	Selects the disk but does not mount it: (0 for drive 0, 1 for drive 1...). Returns false in case of error.
ai_nav_drive_get	–	Drive Number	–	Returns the selected disk number.
ai_nav_drive_mount	–	True or false	–	Mounts the selected disk. Returns false in case of error.
ai_nav_drive_total_space	–	Capacity of the drive	–	Returns the total space, in bytes and available on the device.
ai_nav_drive_free_space	–	Free space on the drive	–	Returns the free space, in bytes, available on the device.
ai_nav_dir_root	–	True or false	–	Initializes the file list on the root directory. Return false in case of error.
ai_nav_dir_cd	–	True or false	–	Enters in the current directory selected in file list. Return false in case of error.
ai_nav_dir_gotoparent	–	True or False	–	Exits current directory and goes to the parent's directory. Then selects the folder from which it just exits, rather than selecting the first file of the parent directory. This simplifies navigation since the user firmware does not have to memorize the information. Returns false in case of error.
ai_nav_file_isdir	–	True or false	–	Returns true if the selected file is a directory, otherwise returns false.
ai_nav_file_goto	Position in the list	True or false	–	Goes to a position in file list (0 for position 0, 1 for position 1...). Returns false in case of error.
ai_nav_file_pos	–	File position	–	Returns the file position of the selected file in the current directory. Returns FS_NO_SEL if no file is selected.
ai_nav_file_nb	–	Number of audio files	–	Returns the number of audio files in the file list. Audio files are all the files which extensions matches *.mp3 or *.wma (it depends on the file format supported). There is a specific command for playlist files, see below.
ai_nav_dir_nb	–	Number of directories	–	Returns the number of directories in the file list.
ai_nav_playlist_nb	–	Number of playlists	–	Returns the number of playlists in the file list. The playlists are all the files matching with the extension *m3u, *.pls and *.smp.
ai_nav_dir_name	–	Length of the string in bytes	UNICODE name	Returns the name of the current directory.
ai_nav_file_name	–	Length of the string in bytes	UNICODE name	Returns the name of the selected file.
ai_nav_file_info_type	–	File type	–	Returns the type of the audio file selected.
ai_nav_file_info_version	–	Version number	–	Returns the version of the metadata storage method used for the selected audio file if available, otherwise, returns 0.
ai_nav_file_info_title	–	Length of the string in bytes	UNICODE title	Returns the title of the selected audio file if available, otherwise, returns an empty string.
ai_nav_file_info_artist	–	Length of the string in bytes	UNICODE artist	Returns the artist's name of the selected audio file if available, otherwise, returns an empty string.
ai_nav_file_info_album	–	Length of the string in bytes	UNICODE album	Returns the album's name of the selected audio file if available, otherwise, returns an empty string.
ai_nav_file_info_year	–	Year	–	Returns the year of the selected audio file if available, otherwise, returns 0.
ai_nav_file_info_track	–	Length of the string in bytes	UNICODE info	Returns the track information of the selected audio file if available, otherwise, returns an empty string.
ai_nav_file_info_genre	–	Length of the string in bytes	UNICODE genre	Returns genre of the selected audio file if available, otherwise, returns an empty string.
ai_nav_file_info_duration	–	Duration of the track	–	Returns the total time of the selected audio file in milliseconds if available, otherwise, returns 0.
ai_nav_file_image	Max image size	Image size	-True or false -A pointer on the image data	Returns information and a pointer on the bitmap of the embedded cover art of the selected audio file. Returns false in case of error.
ai_nav_getoplayfile	–	True or false	–	Selects the file selected by the navigator. This command is the only link between these two navigators. Returns false in case of error.

Audio navigation

This navigator sets the list of files to be played. It can be seen as a playlist. Before accessing this navigator, an ai_audio_nav_playfile command must be issued.

Command Name	Input	Output		Description
		Return	Extra Result
ai_audio_nav_playfile	—	True or false	—	This command sets the audio file list according to the current mode of the audio navigator and plays (or sets to pause) the file selected in the disk navigator. In other words, it synchronizes the audio navigator with the disk navigator and plays (or sets to pause) the selected file from the disk navigator. Note that this command returns immediately and does not wait until the current track is completely played. This command does not change the current options (repeat/random/expmode). It is the opposite of the command ai_nav_getplayfile. Returns false in case of error.
ai_audio_context_save	—	Structure context	—	— True or false — The length of the structure in bytes
ai_audio_context_restore	Structure Context	True or false	—	Restores an audio context (eventually restart playing).
ai_audio_nav_next	—	True or false	—	Jump to next audio file available in the list. The next song file is chosen according to the current options (repeat/random/mode).
ai_audio_nav_previous	—	True or false	—	Jumps to previous audio file available in the list. The next song file is chosen according to the current options (repeat/random/mode).
ai_audio_nav_eof_occur	—	True or false	—	This routine must be called once a track ends. It will choose, according to the options (repeat/random/expmode), the next file to play.
ai_audio_nav_nb	—	Number of audio files present in the list	—	Returns the number of audio files present in the list.
ai_audio_nav_getpos	—	File position	—	Returns the file position of the selected file in the list.
ai_audio_nav_setpos	File position	True or false	—	Goes to a position in the list.
ai_audio_nav_repeat_get	—	Ai_repeat_mode	—	Returns the current repeat mode (no repeat, repeat single, repeat folder, repeat all).
ai_audio_nav_repeat_set	Ai_repeat_mode	—	—	Sets the current repeat mode (no repeat single, repeat folder, repeat all).
ai_audio_nav_shuffle_get	—	Ai_shuffle_mode	—	Returns the current shuffle mode (no shuffle, shuffle folder, shuffle all).
ai_audio_nav_shuffle_set	Ai_shuffle_mode	—	—	Sets the current shuffle mode (no shuffle, shuffle folder, shuffle all).
ai_audio_nav_expmode_get	—	Ai_explorer_mode	—	Returns the current explorer mode (all disks, one disk, directory only, directory + sub directories).
ai_audio_nav_expmode_set	Ai_explorer_mode	—	—	Sets the current explorer mode (all disks, one disk, directory only, directory + sub directories). This mode cannot be changed while an audio file is being played.
ai_audio_nav_getname	—	Length of the string in bytes	UNICODE name	Returns the name of selected file.
ai_audio_nav_file_info_type	—	File type	—	Returns the type of the audio file selected.
ai_audio_nav_file_info_version	—	Version number	—	Returns the version of the metadata storage method used for the selected audio file if available, otherwise, returns 0.
ai_audio_nav_file_info_title	—	Length of the string in bytes	UNICODE title	Returns the title of the selected audio file if available, otherwise, returns and empty string.
ai_audio_nav_file_artist	—	Length of the string in bytes	UNICODE artist	Returns the artist's name of the selected audio file if available, otherwise, returns an empty string.
ai_audio_nav_file_info_album	—	Length of string in bytes	UNICODE album	Returns the albums name of the selected audio file if available, otherwise, returns an empty string.
ai_audio_nav_file_info_year	—	Year	—	Returns the year of the selected audio file if available, otherwise, returns 0.
ai_audio_nav_file_info_track	—	Length of the string in bytes	UNICODE info	Returns the track information of the selected audio file if available, otherwise, returns an empty string.
ai_audio_nav_file_info_genre	—	Length of the string in bytes	UNICODE genre	Returns the genre of the selected audio file if available, otherwise, returns an empty string.
ai_audio_nav_file_info_duration	—	Duration of the track	—	Returns the total time of the selected audio file in milliseconds if available, otherwise, returns 0.
ai_audio_nav_file_info_image	Max image size	Image size	—True or false — A pointer on the image data	Returns information and a pointer on a bitmap of the embedded cover art of the selected audio file. Returns false in case of error.

Modes used by the interface

Ai_repeat_mode defines the repeat mode:

—	AUDIO_REPEAT_OFF: no repeat
—	AUDIO_REPEAT_TRACK: repeat the current track
—	AUDIO_REPEAT_FOLDER: repeat the current folder
—	AUDIO_REPEAT_ALL: repeat the list of files

Ai_shuffle_mode defines the shuffle/random mode:

—	AUDIO_SHUFFLE_OFF: no shuffle
—	AUDIO_SHUFFLE_FOLDER: shuffle into the current folder
—	AUDIO_SHUFFLE_ALL: shuffle into the list of files

Ai_explorer_mode defines the explorer mode (see the "Example 3 — Change the playing order" section later in this article for more information).

Audio Control

The audio controller is used to control the audio stream of the audio file selected by the Audio Navigator.

Command Name	Input	Output		Description
		Return	Extra Result
ai_audio_ctrl_stop	—	True or false	—	Stops the audio.
ai_audio_ctrl_resume	—	True or false	—	Plays or resumes play after an ai_audio_ctrl_pause or an ai_audio_ctrl_stop command.
ai_audio_ctrl_pause	—	True or false	—	Pauses the audio.
ai_audio_ctrl_time	—	Elapsed time	—	Returns the elapsed time of the audio track being played.
ai_audio_ctrl_status	—	Status	—	Returns the status of the audio controller (stop, play, pause, a new audio file is being played, the current folder has changed).
ai_audio_ctrl_ffw	Skip time	True or false	—	Fast forwards the audio until the skip time has been reached. Then, it will continue to play the rest of the audio file. The skip time passed in parameter is in second.
ai_audio_ctrl_frw	Skip time	True or false	—	Fast rewinds the audio until the skip time has been reached. Then, it will set the audio player in play mode. The skip time passed in parameter is in second.
ai_audio_ctrl_start_ffw	—	True or false	—	Sets the audio player into fast forward mode. Function not implemented yet.
ai_audio_ctrl_start_frw	—	True or false	—	Sets the audio player into fast rewind mode. Function not implemented yet.
ai_audio_stop_ffw_frw	—	True or false	—	Stops fast forwarding/rewinding and set the audio player into the previous mode (play or resume). Function not yet implemented.

Using asynchronous or synchronous API

Using synchronous functions is straightforward. Once finished, synchronous functions return, with or without a result. Using asynchronous functions is more complicated; they may not produce the requested task in a single shot. Thus, these functions need some other functions to operate properly:

• void ai_async_cmd_task (void): This function is the entry point of all asynchronous commands. It must be called to execute the current state of the internal state machine of the current asynchronous function.
• Bool is_ai_async_cmd_finished (void): This function returns TRUE if the last command is finished.
• U8 ai_async_cmd_out_status (void): Returns the status of the last executed command (CMD_DONE, CMD_EXECUTING or CMD_ERROR).
• U32 ai_async_cmd_out_u32 (void): If the last executed command should return a 32-bit result or less, this function will return this value.
• U64 ai_async_cmd_out_u64 (void): If the last executed command should return a 64-bit result, this function will return this value.
• 16 ai_async_cmd_out_SizeArrayU8 (void): If the last executed command should return an extra result (e.g., a song name), this function returns the size in bytes of the extra result (no size limit).
• U8 ai_async_cmd_out_PtrArrayU8 (void): Returns a pointer to the extra result (assuming that the last executed command returns an extra result). This pointer can be freed by the application with the ai_async_cmd_out_free_ArrayU8() function.
• void ai_async_cmd_out_free_ArrayU8 (void): This function may be called to free the allocated buffer that holds the extra result. Note that the Audio Interface will automatically do this before executing a new command that needs extra results. This ensures that the application will not have memory leakage. Allowing the application calling this function to free the extra results sooner and improve allocated memory usage. Figure 4 shows the flow of the asynchronous function use.

Examples

The code for the next a three examples can be found in the following directories:


Let's take this disk as disk number 0 for the system.

Example 1 - Play "file1.mp3"

Command Order	Command Name
0	ai_nav_drive_nb(): returns 1 disk.
1	ai_nav_drive_set(0): selects the disk 0.
2	ai_nav_drive_mount(): mounts the select disk 0.
3	ai_nav_file_goto(0): goes to file position 0
4	ai_nav_file_name(): returns the name dir1
5	ai_nav_file_isdir(): returns true, the current file is a directory.
6	ai_nav_file_goto(1): goes to file position 1
7	ai_nav_file_name(): returns the name dir2
8	ai_nav_file_goto(2): goes to file position 2
9	ai_nav_file_name():returns the name file1.mp3
10	ai_audio_nav_playfile(): selects the file selected by the file nagivator (file1.mp3)
11	ai_audio_ctrl_resume(): plays the selected file.
12	Wait for 10 seconds to listen to the beginning of the playback.
13	ai_nav_file_goto(3): goes to file position 3
14	ai_nav_file_name(): returns the name file2.wma

Example 2 — Play while browsing

Command Order	Command Name
0	ai_nav_drive_nb(): returns 1 disk.
1	ai_nav_drive_set(0): selects the disk 0.
2	ai_nav_drive_mount(): mounts the select disk 0.
3	ai_audio_nav_playfile(): selects a file in the audio navigator. By default it will seek inside the directories to play the first file which is "file5.wma" in our case.
4	ai_audio_ctrl_resume (): plays the selected file.
5	ai_nav_getplayfile(): synchronizes the disk navigator with the audio navigator. Now the disk navigator is pointing on the "file5.wma" file.
6	ai_nav_file_nb()+ai_nav_dir_nb()+ai_nav_playlist_nb(): gets the total number of entries (files+folder+playlist) in the current directory (dir3).
7	ai_nav_file_goto(0): goes to the file position 0
8	ai_nav_file_name(): returns the name "file5.wma". (Notice the difference with Table 5 - step #4)
9	ai_nav_file_goto(1): goes to file position 1
10	ai_nav_file_name(): returns the name "file6.mp3"
11	ai_audio_ctrl_stop(): stops the audio

Example 3 — Change the playing order

The playing order can be changed at compilation time by enabling the NAV_AUTO_FILE_IN_FIRST define (see the "Project Configuration" section later in this article).

Command Order	Command Name
0	ai_nav_drive_nb(): returns 1 disk.
1	ai_nav_drive_set(0): selects the disk 0.
2	ai_nav_drive_moutn(): mounts the select disk 0.
3	ai_audio_nav_playfile(): selects a file in the audio player.
4	ai_audio_ctrl_resume(): plays the selected file.

If the NAV_AUTO_FILE_IN_FIRST define is not set, the sequence will play audio files in the order shown in Table 8.

Command Order	Command Name	Parent directory path
0	file5.wma	/dir1/dir3/
1	file6.mp3	/dir1/dir3/
2	file4.mp3	/dir1/
3	file7.mp3	/dir2/
4	file1.mp3	/
5	file2.wma	/
6	file3.wma	/

If this define is set, the sequence will play audio files starting with files on the root, as shown in Table 9.

Command Order	Command Name	Parent directory path
0	file1.mp3	/
1	file2.wma	/
2	file3.wma	/
3	file4.mp3	/dir1/
4	file5.wma	/dir1/dir3/
5	file5.mp3	/dir1/dir3/
6	file7.mp3	/dir2/

Source code architecture

Package

AUDIO-PLAYER-<board(s)>-<feature(s)>-<version>.zip contains projects for GCC (or AVR32 Studio) and IAR.

The default hardware configuration of the project is to run on Atmel® AVR32 UC3 Evaluation Kits, although any board can be used (refer to the "Board Definition Files" section later in this article).

Documentation

For full source code documentation, please refer to the auto-generated Doxygen source code documentation found in:

• /APPLICATIONS/AUDIO-PLAYER/readme.html

Projects/compiler

The IAR project is located in:

• APPLICATIONS/AUDIO-PLAYER/<part>-<board>-vfeature(s)>/IAR/

The GCC makefile is located in:

• /APPLICATIONS/AUDIO-PLAYER/<part>-<board>-<feature(s)>/GCC/

An AVR32 Studio project can be easily created by following the steps in the application note AVR32769: How to Compile the standalone AVR32 Software Framework in AVR32 Studio V2.

Implementation details

This section describes the code implementation of the MP3 audio player running on the EVK1105. Other available packages are similar, so you will find useful information here that applies to every project configuration.

Main()

The main() function of the program is located in the file:

• //APPLICATIONS/AUDIO-PLAYER/main.c

This function will:

• Initialize audio output — refer to the "Audio Rendering Interface" section later in this article.
• Do the clock configuration.
• Call the USB Task — refer to the "USB" section later in this article.
• Call the USB Host Mass Storage Task. This task will check for newly connected devices and initialize them using the USB mass storage protocol.
• Call the Communication Task (HMI) — refer to the "HMI Communication Task Example" section later in this article.
• Call the Decoder Task to perform MP3 decoding — refer to the following section "MP3 Decoder."

The /APPLICATIONS/AUDIO-PLAYER/ contains the following files:

• ./main.c: Contains the main() function.
• ./com_task.c,h: HMI core. See the "HMI Communication Task Example" section later in this article for more details.
• ./USER_INTERFACE/CONTROLLER/joystick_controller.c: HMI using a joystick interface as a controller.
• ./USER_INTERFACE/GUI/et024006dhu_gui.c: HMI using an LCD screen as a display.
• ./codec_mp3_task.c: Handles the MP3 decoding task.
• ./CONF/*.h and ./<part>-<board>-<features>/conf_audio_player.h: Configuration file for audio, communication interface, memory and navigation explorer. Please refer to the "Project Configuration" section later in this article for more information on the configuration files.

MP3 decoder

The MP3 decoder source files are located in:

• /SERVICES/AUDIO/MP3/LIBMAD/: AVR32 port of LibMAD MP3 decoder.

A library of the decoder is provided in /UTILS/LIBS/LIBMAD/AT32UC/.

ID3 is supported up to version 2.4. The ID3 reader source is located in:

• /SERVICES/AUDIO/MP3/ID3/reader_id3.c,h.

Audio player API

The Audio Interface API is located in:

• /SERVICES/AUDIO/AUDIO_PLAYER/audio_interface.h

The Mass Storage Audio Interface can be found in:

• /SERVICES/AUDIO/AUDIO_PLAYER/AI_USB_MS/
  • ./ai_usb_ms.c,h: Mass Storage Audio interface.
  • ./ai_usb_ms_mp3_support.c,h: Adds support to the MP3 file format in the audio interface.
  • ./host_mass_storage_task.c,h: USB host mass storage task.

Refer to the "Audio Interface API" section earlier in this article for more details.

HMI communication task example

The included firmware implements an HMI example using a joystick and an SPI-driven LCD (source code is located under /APPLICATIONS/AUDIO-PLAYER-MASS-STORAGE/USER_INTERFACE/).

All the HMI is based on a pair of files, com_task.[c|h], which implement all mechanisms used to communicate between the internal APIs of the audio player and the user's HMI. An abstraction layer is used to easily attach all kinds of controller and graphical user interfaces to this communication task. This has been done to easily port the application to another board.

Controller
The controller is the module that makes the link between the driver and the abstraction layer, and is used to ensure compatibility with the communication task. It is based mainly on two API groups: "setup" and "events." All the APIs are defined in the file /APPLICATIONS/AUDIO- PLAYER/USER_INTERFACE/CONTROLLER/controller.h.

The function controller_init is used to initialize the controller. It may or may not be used, depending on the controller implementation.

All the other functions are Boolean functions, returning TRUE if an event has been raised or FALSE otherwise. Their names are explicit and follow the following naming convention:

Bool controller_<view>_<event>(void);

where <view> corresponds to the current view when the event should be taken into account. If no value is set for this field, the event is applied to all views.

The <event> is a short name describing the current event to which the function applies.

This example uses a joystick controller. The source code relative to this module is available in the file /APPLICATIONS/AUDIO-PLAYER/USER_INTERFACE/CONTROLLER/joystick_controller.c.

Graphical user interface
This module is used to display the high level audio player data to the user. It acts as a display and, when combined with the controller, it provides the user full control of the application.

This module is similar to the controller in terms of API groups.

The initialization function is called gui_init and includes all the parameters and frequencies needed to initialize the display.

This function is called at every occurrence of the main loop, at which point it resets the parameter flags which indicate parts of the view that need to be updated. Resetting these flags enables the GUI module to update the display asynchronously without having to update every component at once.

The example provides a graphical LCD display module that implements both a navigation and a playback view. All the code is based on the files /APPLICATIONS/AUDIO-PLAYER/USER_INTERFACE/GUI/[et024006dhu_gui.c|sdram_loader.c].

AT32UC3A drivers

The firmware uses the AVR32 UC3 driver library available in:

• //UTILS/LIBS/DRIVERS/AT32UC3A/.

The source code can be found in /DRIVERS.

USB

The USB low level driver is located in:

• /DRIVERS/USB/.

The USB mass storage service is located in:

• /SERVICES/USB/CLASS/MASS_STORAGE/.

FAT file system

The FAT12/16/32 files are located in the directory /SERVICES/FAT/.

Board definition files

The application is designed to run on Atmel Evaluation Kits. All projects are configured with the following define: BOARD=EVKxxxx. The EVKxxxx definition can be found in the /BOARDS/EVKxxxx directory.

Board customization

• For an IAR project, open the project options (Project —> Options), choose the "C/C++ Compiler," then "Preprocessor." Modify the "BOARD=EVKxxxx" definition by "BOARD=USER_BOARD."
• For GCC, just modify in the "config.mk" file (/APPLICATIONS/AUDIO-PLAYER/--/GCC/) the DEFS definition with "-D BOARD=USER_BOARD."
• For AVR32 Studio, open the project properties (Project —>Properties), go in the "C/C++ build," then "Settings," "tool settings" and "Symbols." Modify the "BOARD=EVKxxxx" definition by "BOARD=USER_BOARD."

The HMI can be easily changed. See the "HMI Communication Task Example" section earlier in this article for more details.

Audio rendering interface

The audio DAC mixer source code is located in /SERVICES/AUDIO/AUDIO_MIXER/audio_mixer.c,h.

I2S using the SSC module
The /COMPONENTS/AUDIO/CODEC/TLV320AIC23B/ directory contains the driver for the external DAC TLV320AIC23B.

The UC3 communicates with the TLV320AIC23B with the Two Wire Interface (TWI). The UC3 is the TWI master.

The AVR32 SSC module generates I2S frames using internal DMA (PDCA) to free CPU cycles for audio decoding.

Each time a new song is played, the SSC module is configured corresponding to the sample rate of the new song. The SSC clocks are composed of a bit clock and a frame sync:

• The bit clock is the clock used to transmit a bit from the audio stream. For a 44.1 KHz sample rate, the bit clock will be 44,100 x 2 (stereo) x 16 (bits per channel), i.e., 1.411 MHz.
• The frame sync is equal to the sample rate frequency, i.e., 44.1 KHz, taking the same example.

The TLV320AIC23B uses a master clock (MCLK) of 11.2896 MHz, outputted by the UC3 through a generic clock. Then, the generic clock output (PA07) is connected to the MCLK of the TLV320AIC23B.

The SSC clock divider in the CMR register is given by:



The real frequency sample rate outputted by the SSC is given by:



Note: NumberChannel = 2, BitsPerSamples = 16, FPBA = 62.0928 MHz.
The music interval in semitones is:

Sample Rate Set Point (Hz)	Actual Sample Rate (Hz)	Relative Error (%)	Music Interval (semitones)
8000	8018	0.23	0.04
11025	11025	0.00	0.00
16000	15095	-0.59	-0.10
22050	22050	0.00	0.00
32000	32340	1.06	0.18
44100	44100	0.00	0.00
48000	48510	1.06	0.18

For further information, please refer to the application note AVR32788: AVR®32 How to use the SSC in I2S mode. ABDAC
The ABDAC driver is located in /DRIVERS/ABDAC.

The external amplifier driver (TPA6 13 0A) is located in /COMPONENTS/AUDIO/AMP/TPA6130A.

The AVR32 ABDAC module uses the internal DMA (PDCA) to free CPU cycles for audio decoding.

To get accurate audio frequency samples, the two external 12 MHz (OSC1) and 11.2896 MHz (OSC0) oscillators are used to source (directly or through a PLL) the ABDAC generic clock.

Sample Rate Set Point (Hz)	ABDAC Generic clock input frequency	Actual Sample Rate (Hz)	Relative Error (%)	Music Interval (semitones)
8000	PLL0	8085	1.06	0.18
11025	OSC1	11025	0.00	0.00
16000	PLL1	15625	-2.34	-0.41
22050	OSC1	22050	0.00	0.00
32000	PLL1	31250	-2.34	-0.41
44100	OSC1	44100	0.00	0.00
48000	PLL1	46875	-2.34	-0.41

The PLL0 output frequency is 62.0928 MHz. The PLL1 output frequency is 48 MHz (used for USB).

When used, the ABDAC generic clock divider is given by:



Refer to /DRIVERS/ABDAC/abdac.c for the configuration of the ABDAC generic clock.

SDRAM loader

Graphical data, such as images, consumes a lot of space in RAM and flash which could be used by the application instead. Because of that, the images used by the audio player application's GUI are stored in DataFlash and are loaded to SDRAM upon startup. The reason for having the data in the SDRAM, rather than in flash, is the speed improvement which leads to faster updates of the display with new content.

The SDRAM loader module uses a memory manager to manage the SDRAM memory space. This memory manager can also be used in the application to allocate memory from SDRAM, instead of the internal SRAM.

The following sections give a short introduction to the parts involved in the SDRAM loader module.

The SDRAM loader source code is located in /APPLICATIONS/AUDIO-PLAYER/USER_INTERFACE_GUI/sdram_loader.c,h.

DataFlash

The DataFlash is formatted with a FAT16 file system, and it currently contains graphical data used by the audio player application in the GUI implementation. The graphical data is stored as BMP files and the format is RGB565. This can be used directly on the display when swapped from little endian to big endian. Other BMP formats are currently not implemented but this could be extended, if needed.

The FAT file system makes it easy for developers to upgrade the content with new files or even use it for other applications such as a web server. An upgrade of the content can be done by using a mass storage example application.

The BMP pictures used in the application are stored in the /PICTURES directory.

To customize the GUI, the bitmap files can be updated and must be saved to the Windows bitmap image format using 16-bit R5 G6 B5 encoding. This can be done using GIMP, the GNU Image Manipulation Program (see http://www.gimp.org/).

Loading process

The SDRAM loader consists of two files, sdram_loader.c and sdram_loader.h, in the directory APPLICATIONS/AUDIO-PLAYER/ USER_INTERFACE/GUI. In these files, the images that should be loaded to SDRAM and how they should be converted are specified. A configuration that loads three images to SDRAM could look like this:

typedef struct {
const wchar_t *name;
void *start_addr;
} ram_file_t;
…
#define STARTUP_IMAGE 0
#define DISK_NAV_IMAGE 1
#define AUDIO_PLAYER_IMAGE 2
#define NUMBER_OF_IMAGES 13
ram_file_t ram_files[NUMBER_OF_IMAGES] = {
	{ .name = L"/AVR32_start_320x240_RGB565.bmp"},
	{ .name = L"/disk_nav_320x240_RGB565.bmp"},
	{ .name = L"/audio_player.bmp"}
};

The ram_files array is used throughout the GUI to get access to the image data. In order to load other data than RGB565 BMP data to SDRAM, the module needs to be modified.

The SDRAM loader module is called once during the initialization of the graphical user interface. When called, it initializes the SDRAM interface and reads the raw image data from specified BMP files into SDRAM. To get the raw image data, the BMP header must be read to get the image size and the offset of the data in the file. The copy process also does a conversion from little endian to the big endian data ordering, thus the final image data can be dumped directly into the display buffer.

A single call to the SDRAM module is enough to do the initialization and load process:


The sole parameter is the HSB frequency in hertz, which is needed to initialize the SDRAM timings. The load_sdram_data function is called starting from main in the following order:


SDRAM memory management

The images could be placed at specified locations in SDRAM, making memory management unneeded, but it is often better to do memory management to remove the task of keeping track of the data in memory from the developer.

The audio player uses a separate memory manager to manage SDRAM memory (this memory manager can also replace the default memory manager in the Newlib library if needed).

The source files of the memory manager are located in /SERVICES/MEMORY/MEMORY_MANAGER/DLMALLOC/ and the additional configuration of it is /APPLICATIONS/AUDIO-PLAYER/CONF/conf_dlmalloc.h.

The memory manager is initialized in the SDRAM loader module and it is configured to use the whole SDRAM memory. After the initialization, memory can be allocated from the SDRAM with the mspace_malloc call. Memory from the internal SRAM can be allocated with the default malloc call.

JPEG decoder

The JPEG decoder is used for MP3 cover art file support.

The source code of the IJG JPEG decoder is located under /SERVICES/PICTURES/JPG/IJG/. Documentation for the library can be found in /SERVICES/PICTURES/JPG/IJG/libjpeg.doc and an overview is located in the README file.

The IJG license text can be found in /SERVICES/PICTURES/JPG/IJG/license.txt.

The JPEG decoder application source files are located under /APPLICATIONS/AUDIO-PLAYER/JPG/. This is a layer that handles the data input and output of the JPEG library. It also handles the error handling to jump out of the library in case of a critical error. Since the JPEG decoding is done in SDRAM, the memory management backend of the library, which normally would be included in the library itself, is located here. The memory management backend is modified to use SDRAM with the DLMALLOC memory manager (in /SERVICES/MEMORY/MEMORY_MANAGER/DLMALLOC/) instead of the standard malloc implementation.

Project configuration

There are two different configuration files. The one related to the audio player itself, located under /APPLICATIONS/AUDIOPLAYER/<part>-<board>-<feature(s)>/conf_audio_player.h, is mostly a high level configuration file, but can be customized to support certain configurations or enable/disable audio player features. The rest of the configuration files are located under the /APPLICATIONS/AUDIO-PLAYER/CONF/ directory and should be modified to change, separately, the audio player's module configurations.

Configuration files are not linked to IAR, GCC, or AVR32 Studio projects. The user can alter any of them, then rebuild the entire project in order to reflect the new configuration.

High level configuration file: /APPLICATIONS/AUDIO-PLAYER/<part>-<board>- <feature(s)>conf_audio_player.h

• DEFAULT_DACS specifies the default audio DAC used for the audio output. Three values are possible: AUDIO_MIXER_DAC_AIC23B for the I2S interface, AUDIO_MIXER_DAC_ABDAC for the internal DAC (ABDAC module), and AUDIO_MIXER_DAC_PWM_DAC to use PWM channels (an external low-pass filter is required).
• E_AUDIO_PLAYER_BUFFERIZATION, set to "ENABLED" to support the navigation while playing feature, will use extra memory to buffer decoded samples in order to prevent audio blips while the user navigates in the disk architecture, for example. The memory address and size can be configured in the file "conf_buff_player.h." Note that using the audio sample bufferization will not ensure that every audio blip will be covered. It will always depend on the speed of the USB device connected, its file system, and the operations requested. The default buffer size is set to 128 Kbytes.
• SUPPORT_MP3, SUPPORT_PLAYLISTS, SUPPORT_EMBEDDED_COVER_ARTS is a set of defines which can be enabled or disabled to reduce audio player features. Note that the use of the embedded cover art requires RAM in order to decode embedded JPEG pictures. Therefore, an external memory is needed to handle this feature.

Low-level configuration files: /APPLICATIONS/AUDIO-PLAYER/CONF/*.h

conf_access.h – This file contains the possible external configuration of the memory access control. It configures the abstract layer between the memory and the application, and specifies the commands used in order to access the memory. For example, this file will define the functions to be called for SD/MMC memory access.

conf_audio_interface.h – A set of configuration flags to enable/disable internal features of the audio player.

conf_audio_mixer.h – Configures all parameters relative to the audio DACs. This file is made to support multiple configurations, and can be easily upgraded to handle new DACs.

conf_buff_player.h – Defines the starting address and the size of the memory used to bufferize audio samples (if the feature is enabled).

conf_dmalloc.h – Configuration of malloc/free functions.

conf_explorer.h – It defines the configuration used by the FAT file system. The configuration is also applied to the playlist handler and the file navigation. The main parameters are:

• NAV_AUTO_FILE_IN_FIRST: Must be defined in order to play first the files at the root of a directory instead of the ones inside the subdirectories.
• FS_NAV_AUTOMATIC_NBFILE: This flag can be set to DISABLE in order to speed up the response of the ai_audio_nav_playfile command. On the other hand, the three commands ai_audio_nav_getpos, ai_audio_nav_getpos, and ai_audio_nav_nb will not be available anymore. It will also affect the use of the explorer modes, if different from "all disks" and "one disk."

conf_jepg_decoder — Configuration of the JPEG decoder.

conf_pwm_dac.h — Configuration of the PWM DAC (which PWM channel is used, which pins are concerned).

conf_tlv320aic23b.h — Configuration of the external I2S DAC (which pins and which configuration interface are used).

conf_usb.h — Configuration file used for the USB.

conf_version.h — Internal version of the firmware.

Compiling the application

The following steps show you how to build the embedded firmware according to your environment.

If you are using AVR32 Studio:

• Please refer to the application note AVR32769: How to Compile the standalone AVR32 Software Framework in AVR32 Studio V2.

If you are using the standalone GCC with the AVR32 GNU Toolchain:

• Open a shell, go to the /APPLICATIONS/AUDIO-PLAYER/<partf>-<board>-<feature(s)>/GCC/ directory and type: make rebuild program run.

If you are using IAR Embedded Workbench for Atmel AVR32:

• Open IAR and load the associated IAR project of this application (located in the directory /APPLICATIONS/AUDIO-PLAYER/<part>-<board>-<feature(s)>/IAR/).
• Press the "Debug" button at the top right of the IAR interface.

The project should compile. The generated binary file is then downloaded to the microcontroller to switch to the debug mode.

• Click on the "Go" button in the "Debug" menu or press F5.

FAQ

Q: What is the maximum number of playlist links supported?
A: The file system supports up to 65,535 links inside a playlist.

Q: What are the supported text formats?
A: The file system supports the ASCII, UTF8 and UNICODE (UTF16LE & UTF16BE) text formats.

Q: How are the directories and files sorted inside the disk?
A: The logical structure is the same as an explorer view. Directory and files are sorted using their creation order.

Q: Which file systems are supported?
A: FAT12/16/32.

Q: What is the maximum number of files supported in a directory?
A: There is no limitation in the firmware for the supported number of files and directories. The only limitation is due to the FAT file system:

• for FAT12/16 root directory only: up to 256 files (short names).
• or FAT12/16/32 up to 65,535 files (short names) per directory.

Q: What is the minimum RAM requirement to run this application?
A: The default application is using external SDRAM to support all features. This application can run with 64 kbytes of RAM (internal size on AT32UC3A0512) by disabling the audio bufferization and the cover art support. Audio blips will be present if the user tries to navigate in the disk while a track is played. The SDRAM loader also uses external SDRAM memory for graphical data.

Q: What kind of license applies to the software?
A: Atmel provides the audio decoder software library free of charge. But some digital audio formats, including MP3 and WMA, contain technology that is patented, and a license for these patents must be obtained before the library can be used.