Interface Driver to the VS10xx chip on the SPI. More...

#include <SFEMP3Shield.h>

Classes
union	sci_bass_m
	A handler for accessing nibbles of the SCI_BASS word. More...

Public Member Functions
uint8_t	begin ()
	Initialize the MP3 Player shield. More...

void	end ()
	Disables the MP3 Player shield. More...

uint8_t	vs_init ()
	Initialize the VS10xx Audio Decoder Chip. More...

void	setBitRate (uint16_t)
	Force bit rate. More...

uint8_t	ADMixerLoad (char *)
	Initially load ADMixer patch and configure line/mic mode. More...

void	ADMixerVol (int8_t)
	Set ADMixer's attenuation of input to between -3 and -31 dB otherwise disable. More...

void	SendSingleMIDInote ()
	Play hardcoded MIDI file. More...


void	setVolume (uint8_t, uint8_t)
	Store and Push member volume to VS10xx chip. More...

void	setVolume (uint16_t)
	Overload function of SFEMP3Shield::setVolume(leftchannel, rightchannel) More...

void	setVolume (uint8_t)
	Overload function of SFEMP3Shield::setVolume(leftchannel, rightchannel) More...

uint16_t	getVolume ()
	Get the current volume from the VS10xx chip. More...


uint16_t	getTrebleFrequency ()
	Get the current Treble Frequency limit from the VS10xx chip. More...

int8_t	getTrebleAmplitude ()
	Get the current Treble Amplitude from the VS10xx chip. More...

uint16_t	getBassFrequency ()
	Get the current Bass Frequency limit from the VS10xx chip. More...

int8_t	getBassAmplitude ()
	Get the current Bass boost amplitude from the VS10xx chip. More...

void	setTrebleFrequency (uint16_t)
	Set the current treble frequency limit in VS10xx chip. More...

void	setTrebleAmplitude (int8_t)
	Set the current Treble Amplitude in VS10xx chip. More...

void	setBassFrequency (uint16_t)
	Set the current Bass Boost Frequency limit cutoff in VS10xx chip. More...

void	setBassAmplitude (uint8_t)
	Set the current Bass Boost amplitude in VS10xx chip. More...


void	setPlaySpeed (uint16_t)
	Set the current playSpeed of the VS10xx chip. More...

uint16_t	getPlaySpeed ()
	Get the current playSpeed from the VS10xx chip. More...


uint8_t	getEarSpeaker ()
	Get the current Spatial EarSpeaker setting from the VS10xx chip. More...

void	setEarSpeaker (uint16_t)
	Set the current Spatial EarSpeaker setting of the VS10xx chip. More...


state_m	getState ()
	Get the current state of the device. More...

uint8_t	playTrack (uint8_t)
	Begin playing a mp3 file, just with a number. More...

uint8_t	playMP3 (char *, uint32_t timecode=0)
	Begin playing a mp3 file by its filename. More...

void	stopTrack ()
	Gracefully close track and cancel refill. More...

uint8_t	isPlaying ()
	Inidicate if a song is playing? More...

uint8_t	skip (int32_t)
	Skips to a duration in the track. More...

uint8_t	skipTo (uint32_t)
	Skips to a certain point in the track. More...

uint32_t	currentPosition ()
	Current timecode in ms. More...

void	pauseDataStream ()
	Pause streaming data to the VSdsp. More...

void	resumeDataStream ()
	Unpause streaming data to the VSdsp. More...

void	pauseMusic ()
	Pause music. More...

bool	resumeMusic ()
	Resume music from where it was paused. More...

uint8_t	resumeMusic (uint32_t)
	Resume music from pause at new location. More...


uint16_t	getMonoMode ()
	Get the current Stereo/Mono setting of the VS10xx output. More...

void	setMonoMode (uint16_t)
	Set the current Stereo/Mono setting of the VS10xx output. More...


void	setDifferentialOutput (uint16_t)
	Set the current SM_DIFF setting of the VS10xx chip. More...

uint8_t	getDifferentialOutput ()
	Get the current SM_DIFF setting from the VS10xx chip. More...


uint8_t	enableTestSineWave (uint8_t)
	Generate Test Sine wave. More...

uint8_t	disableTestSineWave ()
	Disable Test Sine wave. More...

uint16_t	memoryTest ()
	Perform Memory Test. More...

Static Public Member Functions
static void	available ()
	Public interface of refill. More...

Private Member Functions
uint8_t	VSLoadUserCode (char *)
	load VS1xxx with patch or plugin from file on SDcard. More...

Static Private Member Functions
static void	refill ()
	Refill the VS10xx buffer with new data. More...

static void	flush_cancel (flush_m)
	flush the VSdsp buffer and cancel More...

static void	spiInit ()
	Initialize the SPI for VS10xx use. More...

static void	cs_low ()
	Select Control Channel. More...

static void	cs_high ()
	Deselect Control Channel. More...

static void	dcs_low ()
	Select Data Channel. More...

static void	dcs_high ()
	Deselect Data Channel. More...

static void	Mp3WriteRegister (uint8_t, uint8_t, uint8_t)
	Write a value a VSDsp's register. More...

static void	Mp3WriteRegister (uint8_t, uint16_t)
	uint16_t Overload of SFEMP3Shield::Mp3WriteRegister More...

static uint16_t	Mp3ReadRegister (uint8_t)
	Read a VS10xx register. More...

static uint16_t	Mp3ReadWRAM (uint16_t)
	Read a VS10xx WRAM Location. More...

static void	Mp3WriteWRAM (uint16_t, uint16_t)
	Write a VS10xx WRAM Location. More...

static void	enableRefill ()
	Enable the Interrupts for refill. More...

static void	disableRefill ()
	Disable the Interrupts for refill. More...

Private Attributes
uint8_t	bitrate
	contains a local value of the beleived current bit-rate. More...

uint32_t	start_of_music
	contains a filehandles offset to the begining of the current file. More...

uint8_t	VolL
	contains a local value of the VSdsp's master volume left channels More...

uint8_t	VolR
	contains a local value of the VSdsp's master volume Right channels More...

Static Private Attributes
static SdFile	track
	Initializer for the instance of the SdCard's static member. More...

static state_m	playing_state
	Boolean flag indicating if filehandle is streaming. More...

static uint16_t	spi_Read_Rate
	Rate of the SPI to be used with communicating to the VSdsp. More...

static uint16_t	spi_Write_Rate

static uint8_t	mp3DataBuffer [32]
	Buffer for moving data between Filehandle and VSdsp. More...

void	trackTitle (char *)
	Get Track's Title. More...

void	trackArtist (char *)
	Get Track's Artist. More...

void	trackAlbum (char *)
	Get Track's Album. More...

void	getAudioInfo ()
	Display various Audio information from the VSdsp. More...

int8_t	getVUmeter ()
	get the status of the VSdsp VU Meter More...

int8_t	setVUmeter (int8_t)
	enable VSdsp VU Meter More...

int16_t	getVUlevel ()
	get current measured VU Meter More...

void	getTrackInfo (uint8_t, char *)
	Fetch ID3 Tag information. More...

void	getBitRateFromMP3File (char *)
	Read the Bit-Rate from the current track's filehandle. More...

Detailed Description

Interface Driver to the VS10xx chip on the SPI.

Definition at line 665 of file SFEMP3Shield.h.

Member Function Documentation

◆ ADMixerLoad()

uint8_t SFEMP3Shield::ADMixerLoad ( char * fileName )

Initially load ADMixer patch and configure line/mic mode.

Parameters

[out] fileName pointer of a char array (aka string), contianing the filename

Loads a patch file of Analog to Digital Mixer. Current available options are as follows:

"admxster.053" Takes both ADC channels and routes them to left and right outputs.
"admxswap.053" Swaps both Left and Right ADC channels and routes them to left and right outputs.
"admxleft.053" MIC/LINE1 routed to both left and right output
"admxrght.053" LINE2 routed to both left and right output
"admxmono.053" mono version mixes both left and right inputs and plays them using both left and right outputs.

And subsequently returns the following result codes.

Returns

Any Value other than zero indicates a problem occured.

0 indicates that upload was successful.
1 indicates the upload can not be performed while currently streaming music.
2 indicates that desired file was not found.
3 indicates that the VSdsp is in reset.

Definition at line 2198 of file SFEMP3Shield.cpp.

◆ ADMixerVol()

void SFEMP3Shield::ADMixerVol ( int8_t ADM_volume )

Set ADMixer's attenuation of input to between -3 and -31 dB otherwise disable.

Parameters

[in] ADM_volume -3 through -31 dB of attentuation.

Will range check the requested value and for values out of range the VSdsp's ADMixer will be disabled. While valid ranges will write to VSdsp's current operating volume and enable the the ADMixer.

Warning: If file patch not applied this call will lock up the VS10xx. need to add interlock to avoid.

Definition at line 2235 of file SFEMP3Shield.cpp.

◆ available()

void SFEMP3Shield::available ( )

static

Public interface of refill.

Serves as a helper as to correspondingly run either the timer service or run the refill() direclty, depending upon the configured means for refilling.

Definition at line 1953 of file SFEMP3Shield.cpp.

◆ begin()

uint8_t SFEMP3Shield::begin ( )

Initialize the MP3 Player shield.

Execute this function before anything else, typically during setup(). It will bring the VS10xx out of reset, initialize the connected pins and then ready the VSdsp for playback, with vs_init().

Returns: Any Value other than zero indicates a problem occured. where value indicates specific error

See also: end() for low power mode; Error Codes

Warning: Will disrupt playback, if issued while playing back.

Note: The SdFat::begin() function is required to be executed prior, as to define the volume for the tracks (aka files) to be operated on.

Definition at line 132 of file SFEMP3Shield.cpp.

◆ cs_high()

void SFEMP3Shield::cs_high ( )

staticprivate

Deselect Control Channel.

Primative function to Deselect the VS10xx's Control Chip Select as per defined by MP3_XCS.

Definition at line 1756 of file SFEMP3Shield.cpp.

◆ cs_low()

void SFEMP3Shield::cs_low ( )

staticprivate

Select Control Channel.

Primative function to configure the SPI's Mode and rate control to that of the current VX10xx. Then select the VS10xx's Control Chip Select as per defined by MP3_XCS.

Warning: This uses spiInit() which sets the rate fast for write, too fast for reading. In the case of a subsequent SPI.transfer that is reading back data followup with a SPI.setClockDivider(spi_Read_Rate); as not to get gibberish.

Definition at line 1744 of file SFEMP3Shield.cpp.

◆ currentPosition()

uint32_t SFEMP3Shield::currentPosition ( )

Current timecode in ms.

Reads the currenty position from the VSdsp's decode time and converts the value to milliseconds.

Returns: the milliseconds offset of stream played.

Note: SCI_DECODE_TIME is cleared during SFEMP3Shield::playMP3, as to restart the position for each file stream. Erasing prior streams weight.

Warning: Not very accurate, rounded off to second. And Variable Bit-Rates are completely inaccurate.

Definition at line 1390 of file SFEMP3Shield.cpp.

◆ dcs_high()

void SFEMP3Shield::dcs_high ( )

staticprivate

Deselect Data Channel.

Primative function to Deselect the VS10xx's Control Data Select as per defined by MP3_XDCS.

Definition at line 1782 of file SFEMP3Shield.cpp.

◆ dcs_low()

void SFEMP3Shield::dcs_low ( )

staticprivate

Select Data Channel.

Primative function to configure the SPI's Mode and rate control to that of the current VX10xx. Then select the VS10xx's Data Chip Select as per defined by MP3_XDCS.

Warning: This uses spiInit() which sets the rate fast for write, too fast for reading. In the case of a subsequent SPI.transfer that is reading back data followup with a SPI.setClockDivider(spi_Read_Rate); as not to get gibberish.

Definition at line 1770 of file SFEMP3Shield.cpp.

◆ disableRefill()

void SFEMP3Shield::disableRefill ( )

staticprivate

Disable the Interrupts for refill.

Depending upon the means selected to request refill of the VSdsp's data stream buffer, this routine will disable the corresponding service.

Definition at line 2101 of file SFEMP3Shield.cpp.

◆ disableTestSineWave()

uint8_t SFEMP3Shield::disableTestSineWave ( )

Disable Test Sine wave.

Disable and report the generation of Test Sine Wave as per specified. As specified by Data Sheet Section 9.12.1

Returns

-1 indicates the test can not be performed while currently streaming music or chip is reset.
0 indicates the test is not previously enabled and skipping disable.
1 indicates that test was disabled.

See also: Error Codes

Definition at line 440 of file SFEMP3Shield.cpp.

◆ enableRefill()

void SFEMP3Shield::enableRefill ( )

staticprivate

Enable the Interrupts for refill.

Depending upon the means selected to request refill of the VSdsp's data stream buffer, this routine will enable the corresponding service.

Definition at line 2082 of file SFEMP3Shield.cpp.

◆ enableTestSineWave()

uint8_t SFEMP3Shield::enableTestSineWave ( uint8_t freq )

Generate Test Sine wave.

Parameters

[in] freq specifies the output frequency sine wave.

Enable and/or report the generation of Test Sine Wave as per specified. As specified by Data Sheet Section 9.12.1

Returns

-1 indicates the test can not be performed while currently streaming music or chip is reset.
1 indicates that test has begun successfully.
2 indicates that test is already in progress.

See also: Error Codes

Note: 9.12.5 New Sine and Sweep Tests was not implemented.

Definition at line 389 of file SFEMP3Shield.cpp.

◆ end()

void SFEMP3Shield::end ( )

Disables the MP3 Player shield.

Places the VS10xx into low power hard reset, after polity closing files after releasing interrupts and or timers.

Warning: Will stop any playing tracks. Check isPlaying() prior to executing, as not to stop on a track.

Note: use begin() to reinitialize the VS10xx, for use.

Definition at line 187 of file SFEMP3Shield.cpp.

◆ flush_cancel()

void SFEMP3Shield::flush_cancel ( flush_m mode )

staticprivate

flush the VSdsp buffer and cancel

Parameters

[in] mode is an enumerated value of flush_m

Typically called after a filehandlers' stream has been stopped, as to gracefully flush any buffer contents still playing. Along with issueing a SM_CANCEL to the VSdsp's SCI_MODE register.

post - will flush vx10xx's 2K buffer after cancelled, typically with stopping a file, to have immediate affect.
pre - will flush buffer prior to issuing cancel, typically to allow completion of file
both - will flush before and after issuing cancel
none - will just issue cancel. Not sure if this should be used. Such as in skipTo().

Note: if cancel fails the vs10xx will be reset and initialized to current values.

Definition at line 2128 of file SFEMP3Shield.cpp.

◆ getAudioInfo()

void SFEMP3Shield::getAudioInfo ( )

Display various Audio information from the VSdsp.

Read numerous attributes from the VSdsp's registers about either the currently or prior played stream and display in a column format for easy reviewing.

This may be called while playing a current stream.

Note: this suspends currently playing streams and returns afterwards. Restoring the file position to where it left off, before resuming.

Definition at line 1502 of file SFEMP3Shield.cpp.

◆ getBassAmplitude()

int8_t SFEMP3Shield::getBassAmplitude ( )

Get the current Bass boost amplitude from the VS10xx chip.

Returns: int16_t of bass bost amplitude in dB.

Note: Any value greater then zero enables the Bass Enhancer VSBE is a powerful bass boosting DSP algorithm, which tries to take the most out of the users earphones without causing clipping.

Definition at line 683 of file SFEMP3Shield.cpp.

◆ getBassFrequency()

uint16_t SFEMP3Shield::getBassFrequency ( )

Get the current Bass Frequency limit from the VS10xx chip.

Returns: int16_t of bass frequency limit in Hertz.

Definition at line 665 of file SFEMP3Shield.cpp.

◆ getBitRateFromMP3File()

void SFEMP3Shield::getBitRateFromMP3File ( char * fileName )

private

Read the Bit-Rate from the current track's filehandle.

Parameters

[out] fileName pointer of a char array (aka string), contianing the filename

locate the MP3 header in the current file and from there determine the Bit-Rate, using bitrate_table located in flash. And return the position to the prior location.

Note: the bitrate will be updated, as read back from the VS10xx when needed.

Warning: This feature only works on MP3 files. It will LOCK-UP on other file formats, looking for the MP3 header.

true if Version 1, !false version 2 and 2.5

Definition at line 1587 of file SFEMP3Shield.cpp.

◆ getDifferentialOutput()

uint8_t SFEMP3Shield::getDifferentialOutput ( )

Get the current SM_DIFF setting from the VS10xx chip.

Read the VS10xx SCI_MODE register bits SM_DIFF for current SM_DIFF and return its results as a composite integer. To indicate if the Left Channel is either normal or differential output. As specified by Data Sheet Section 8.7.1

Returns

0 for Normal and 1 is Differential Output.

0 Normal in-phase audio output of left and right speaker signals.
1 Left channel output is the invert of the right channel.

See also: setDifferentialOutput()

Definition at line 928 of file SFEMP3Shield.cpp.

◆ getEarSpeaker()

uint8_t SFEMP3Shield::getEarSpeaker ( )

Get the current Spatial EarSpeaker setting from the VS10xx chip.

Read the VS10xx SCI_MODE register bits SM_EARSPEAKER_LO and SM_EARSPEAKER_HIGH for current EarSpeaker and return its results as a composite integer. As specified by Data Sheet Section 8.7.1 and 8.4

Returns: result between 0 and 3. Where 0 is OFF and 3 is maximum.

Definition at line 864 of file SFEMP3Shield.cpp.

◆ getMonoMode()

uint16_t SFEMP3Shield::getMonoMode ( )

Get the current Stereo/Mono setting of the VS10xx output.

Read the VS10xx WRAMADDR bit 0 of para_MonoOutput] for the current Stereo/Mono and return its results as a byte. As specified by VS1053B PATCHES AND FLAC DECODER Data Sheet Section 1.2 Mono output mode.

Returns: result between 0 and 3. Where 0 is OFF and 3 is maximum.

Warning: This feature is only available when composite patch 1.7 or higher is loaded into the VSdsp.

Definition at line 982 of file SFEMP3Shield.cpp.

◆ getPlaySpeed()

uint16_t SFEMP3Shield::getPlaySpeed ( )

Get the current playSpeed from the VS10xx chip.

Read the VS10xx extra parameter memory for playSpeed register and return its results. As specified by Data Sheet Section 9.11.1

Returns: multipler of current playspeed versus normal speed. Where 0 and/or 1 are normal 1x speed. e.g. 4 to playSpeed will play the song four times as fast as normal, if you are able to feed the data with that speed.

Warning: Excessive playspeed beyond the ability to stream data between the SdCard, Arduino and VS10xx may result in erratic behavior.

Definition at line 824 of file SFEMP3Shield.cpp.

◆ getState()

state_m SFEMP3Shield::getState ( )

Get the current state of the device.

Reports the current operational status of the device from the list of possible states enumerated by state_m

Returns: the value held by SFEMP3Shield::playing_state

Definition at line 1161 of file SFEMP3Shield.cpp.

◆ getTrackInfo()

void SFEMP3Shield::getTrackInfo	(	uint8_t	offset,
		char *	infobuffer
	)

private

Fetch ID3 Tag information.

Parameters

[in]	offset	for the desired information desired.
[out]	infobuffer	pointer char array of filename to be read.

Read current filehandles offset of track ID3 tag information. Then strip all non readible (ascii) characters.

Note: this suspends currently playing streams and returns afterwards. Restoring the file position to where it left off, before resuming.

Definition at line 1463 of file SFEMP3Shield.cpp.

◆ getTrebleAmplitude()

int8_t SFEMP3Shield::getTrebleAmplitude ( )

Get the current Treble Amplitude from the VS10xx chip.

Returns: int16_t of amplitude (from -8 to 7).

Definition at line 652 of file SFEMP3Shield.cpp.

◆ getTrebleFrequency()

uint16_t SFEMP3Shield::getTrebleFrequency ( )

Get the current Treble Frequency limit from the VS10xx chip.

Returns: int16_t of frequency limit in Hertz.

Definition at line 638 of file SFEMP3Shield.cpp.

◆ getVolume()

uint16_t SFEMP3Shield::getVolume ( )

Get the current volume from the VS10xx chip.

Read the VS10xx SC_VOL register and return its results As specified by Data Sheet Section 8.7.11

Returns: uint16_t of both channels of master volume. Where the left channel is in the upper byte and right channel is in the lower byte.

Note: Input values are -1/2dB. e.g. 40 results in -20dB.; Cast the output to the union of twobyte.word to access individual channels, with twobyte.byte[1] and [0].

Definition at line 620 of file SFEMP3Shield.cpp.

◆ getVUlevel()

int16_t SFEMP3Shield::getVUlevel ( )

get current measured VU Meter

Returns the calculated peak sample values from both channels in 3 dB increaments through. Where the high byte represent the left channel, and the low bytes the right channel.

Values from 0 to 31 are valid for both channels.

Warning: This feature is only available with patches that support VU meter.

Definition at line 1696 of file SFEMP3Shield.cpp.

◆ getVUmeter()

int8_t SFEMP3Shield::getVUmeter ( )

get the status of the VSdsp VU Meter

Returns: responds with the current value of the SS_VU_ENABLE bit of the SCI_STATUS register indicating if the VU meter is enabled.

See data patches data sheet VU meter for details.

Warning: This feature is only available with patches that support VU meter.

Definition at line 1653 of file SFEMP3Shield.cpp.

◆ isPlaying()

uint8_t SFEMP3Shield::isPlaying ( )

Inidicate if a song is playing?

Public method for determining if a file is streaming to the VSdsp.

Returns

0 indicates NO file is currently being streamed to the VSdsp.
1 indicates that a file is currently being streamed to the VSdsp.
3 indicates that the VSdsp is in reset.

Definition at line 1138 of file SFEMP3Shield.cpp.

◆ memoryTest()

uint16_t SFEMP3Shield::memoryTest ( )

Perform Memory Test.

Perform the internal memory test of the VSdsp core processor and resources. As specified by Data Sheet Section 9.12.4

Returns

-1 indicates the test can not be performed while currently streaming music or chip is reset.
1 indicates that test has begun successfully.
2 indicates that test is already in progress.

See also: Error Codes

Definition at line 495 of file SFEMP3Shield.cpp.

◆ Mp3ReadRegister()

uint16_t SFEMP3Shield::Mp3ReadRegister ( uint8_t addressbyte )

staticprivate

Read a VS10xx register.

Parameters

[in] addressbyte of the VSdsp's register to be read

Returns: result read from the register

Primative function to suspend playing and directly communicate over the SPI to the VSdsp's registers.

Definition at line 1856 of file SFEMP3Shield.cpp.

◆ Mp3ReadWRAM()

uint16_t SFEMP3Shield::Mp3ReadWRAM ( uint16_t addressbyte )

staticprivate

Read a VS10xx WRAM Location.

Parameters

[in] addressbyte of the VSdsp's WRAM to be read

Returns: result read from the WRAM

Function to communicate to the VSdsp's registers, indirectly accessing the WRAM. As per data sheet the result is read back twice to verify. As it is not buffered.

Definition at line 1904 of file SFEMP3Shield.cpp.

◆ Mp3WriteRegister() [1/2]

void SFEMP3Shield::Mp3WriteRegister	(	uint8_t	addressbyte,
		uint8_t	highbyte,
		uint8_t	lowbyte
	)

staticprivate

Write a value a VSDsp's register.

Parameters

[in]	addressbyte	of the VSdsp's register to be written
[in]	highbyte	to writen to the register
[in]	lowbyte	to writen to the register

Primative function to suspend playing and directly communicate over the SPI to the VSdsp's registers. Where the value write is Big Endian (MSB first).

Definition at line 1813 of file SFEMP3Shield.cpp.

◆ Mp3WriteRegister() [2/2]

void SFEMP3Shield::Mp3WriteRegister	(	uint8_t	addressbyte,
		uint16_t	data
	)

staticprivate

uint16_t Overload of SFEMP3Shield::Mp3WriteRegister

Parameters

[in]	addressbyte	of the VSdsp's register to be written
[in]	data	to writen to the register

Forces the input value into the Big Endian Corresponding positions of Mp3WriteRegister as to be written to the addressed VSdsp's registers.

Definition at line 1796 of file SFEMP3Shield.cpp.

◆ Mp3WriteWRAM()

void SFEMP3Shield::Mp3WriteWRAM	(	uint16_t	addressbyte,
		uint16_t	data
	)

staticprivate

Write a VS10xx WRAM Location.

Parameters

[in]	addressbyte	of the VSdsp's WRAM to be read
[in]	data	written to the VSdsp's WRAM

Function to communicate to the VSdsp's registers, indirectly accessing the WRAM.

Definition at line 1940 of file SFEMP3Shield.cpp.

◆ pauseDataStream()

void SFEMP3Shield::pauseDataStream ( )

Pause streaming data to the VSdsp.

Public method for disabling the refill with disableRefill().

Definition at line 1171 of file SFEMP3Shield.cpp.

◆ pauseMusic()

void SFEMP3Shield::pauseMusic ( )

Pause music.

Public method for pausing the play of music.

Note: This is currently equal to pauseDataStream() and is a place holder to pausing the VSdsp's playing and DREQ's.

Definition at line 1209 of file SFEMP3Shield.cpp.

◆ playMP3()

uint8_t SFEMP3Shield::playMP3	(	char *	fileName,
		uint32_t	timecode = `0`
	)

Begin playing a mp3 file by its filename.

Parameters

[out]	fileName	pointer of a char array (aka string), contianing the filename
[in]	timecode	(optional) milliseconds from the begining of the file. Only works with mp3 files, otherwise do nothing.

Skip, if already playing. Otherwise initialize the SdCard track to desired filehandle. Reset the ByteRate and Play position and set playing to indicate such. If the filename extension is MP3, then pre-read the byterate from the file. And initially fill the VSDsp's buffer, then enable refilling.

Returns: Any Value other than zero indicates a problem occured. where value indicates specific error

See also: Error Codes

Note

Currently bitrate to calculate time offset is determined by either playing files or by reading MP3 headers. Hence only the later is doable without actually playing files. Hence other formats are not available, yet.
enableRefill() will enable the appropiate interrupt to match the corresponding means selected.
use SdFat::chvol() command prior, to select desired SdCard volume, if multiple cards are used.

Definition at line 1066 of file SFEMP3Shield.cpp.

◆ playTrack()

uint8_t SFEMP3Shield::playTrack ( uint8_t trackNo )

Begin playing a mp3 file, just with a number.

Parameters

[in] trackNo integer value between 0 and 9, corresponding to the track to play.

Formats the input number into a corresponding filename, from track001.mp3 through track009.mp3. Then executes the track by calling SFEMP3Shield::playMP3(char* fileName)

Returns: Any Value other than zero indicates a problem occured. where value indicates specific error

See also: Error Codes

Definition at line 1025 of file SFEMP3Shield.cpp.

◆ refill()

void SFEMP3Shield::refill ( )

staticprivate

Refill the VS10xx buffer with new data.

This the primative function to refilling the VSdsp's buffers. And is typically called as an interrupt to the rising edge of the VS10xx's DREQ. Where if the DREQ is indicating not full, it will read 32 bytes from the filehandle's track and send them via SPI to the VSdsp's data stream buffer. Repeating until the DREQ indicates it is full.

When the filehandle's track indicates it is at the end of file. The track is closed, the playing indicator is set to false, interrupts for refilling are disabled and the VSdsp's data stream buffer is flushed appropiately.

Definition at line 1975 of file SFEMP3Shield.cpp.

◆ resumeDataStream()

void SFEMP3Shield::resumeDataStream ( )

Unpause streaming data to the VSdsp.

Public method for re-enabling the refill with enableRefill(). Where skipped if not currently playing.

Definition at line 1188 of file SFEMP3Shield.cpp.

◆ resumeMusic() [1/2]

bool SFEMP3Shield::resumeMusic ( )

Resume music from where it was paused.

Public method for resuming the play of music from a specific file location.

Returns

0 indicates the position was changed.
1 indicates no action, in lieu of any current file stream.

Note: This is effectively equal to resumeDataStream() and is a place holder to resuming the VSdsp's playing and DREQ's.

Definition at line 1254 of file SFEMP3Shield.cpp.

◆ resumeMusic() [2/2]

uint8_t SFEMP3Shield::resumeMusic ( uint32_t timecode )

Resume music from pause at new location.

Parameters

[in] timecode (optional) milliseconds from the begining of the file.

Public method for resuming the play of music from a specific file location.

Returns

0 indicates the position was changed.
1 indicates no action, in lieu of any current file stream.
2 indicates failure to skip to new file location.

Note: This is effectively equal to resumeDataStream() and is a place holder to resuming the VSdsp's playing and DREQ's.

Definition at line 1229 of file SFEMP3Shield.cpp.

◆ SendSingleMIDInote()

void SFEMP3Shield::SendSingleMIDInote ( )

Play hardcoded MIDI file.

This the primative function to fill the VSdsp's buffers quicly. The intention is to send a quick MIDI file of a single note on and off. This can be used responses to buttons and such. Where the MIDI file is short enough to be stored into an array that can be delivered via SPI to the VSdsp's data stream buffer. Waiting for DREQ every 32 bytes.

Definition at line 2036 of file SFEMP3Shield.cpp.

◆ setBassAmplitude()

void SFEMP3Shield::setBassAmplitude ( uint8_t amplitude )

Set the current Bass Boost amplitude in VS10xx chip.

Parameters

[in] amplitude to Bass Boost amplitude in dB (0dB to 15dB).

Note: Any value greater then zero enables the Bass Enhancer VSBE is a powerful bass boosting DSP algorithm, which tries to take the most out of the users earphones without causing clipping.; The upper and lower limits of this parameter is checked.

Definition at line 784 of file SFEMP3Shield.cpp.

◆ setBassFrequency()

void SFEMP3Shield::setBassFrequency ( uint16_t frequency )

Set the current Bass Boost Frequency limit cutoff in VS10xx chip.

Parameters

[in] frequency of Bass Boost frequency cutoff limit in Hertz (20Hz to 150Hz).

Note: The upper and lower limits of this parameter is checked.

Definition at line 752 of file SFEMP3Shield.cpp.

◆ setBitRate()

void SFEMP3Shield::setBitRate ( uint16_t bitr )

Force bit rate.

Parameters

[in] bitr new bit-rate

Public method for forcing the percieved bit-rate to a desired value. Useful if auto-detect failed

Definition at line 1712 of file SFEMP3Shield.cpp.

◆ setDifferentialOutput()

void SFEMP3Shield::setDifferentialOutput ( uint16_t DiffMode )

Set the current SM_DIFF setting of the VS10xx chip.

Parameters

[in] DiffMode integer value between 0 and 1.

The input value is mapped onto the SM_DIFF of the SCI_MODE register, preserving the remainder of SCI_MODE. For stereo playback streams this creates a virtual sound, and for mono streams this creates a differential left/right output with a maximum output of 3V.

As specified by Data Sheet Section 8.7.1

See also: getDifferentialOutput()

Definition at line 952 of file SFEMP3Shield.cpp.

◆ setEarSpeaker()

void SFEMP3Shield::setEarSpeaker ( uint16_t EarSpeaker )

Set the current Spatial EarSpeaker setting of the VS10xx chip.

Parameters

[in] EarSpeaker integer value between 0 and 3. Where 0 is OFF and 3 is maximum.

The input value is mapped onto SM_EARSPEAKER_LO and SM_EARSPEAKER_HIGH bits and written the VS10xx SCI_MODE register, preserving the remainder of SCI_MODE. As specified by Data Sheet Section 8.7.1 and 8.4

Definition at line 888 of file SFEMP3Shield.cpp.

◆ setMonoMode()

void SFEMP3Shield::setMonoMode ( uint16_t StereoMode )

Set the current Stereo/Mono setting of the VS10xx output.

Write the VS10xx WRAMADDR para_MonoOutput bit 0 to configure the current Stereo/Mono. As specified by VS1053B PATCHES AND FLAC DECODER Data Sheet Section 1.2 Mono output mode. While preserving the other bits.

Warning: This feature is only available when composite patch 1.7 or higher is loaded into the VSdsp.

Definition at line 998 of file SFEMP3Shield.cpp.

◆ setPlaySpeed()

void SFEMP3Shield::setPlaySpeed ( uint16_t data )

Set the current playSpeed of the VS10xx chip.

Write the VS10xx extra parameter memory for playSpeed register with the desired multipler.

Where 0 and/or 1 are normal 1x speed. e.g. 4 to playSpeed will play the song four times as fast as normal, if you are able to feed the data with that speed. As specified by Data Sheet Section 9.11.1

Warning: Excessive playspeed beyond the ability to stream data between the SdCard, Arduino and VS10xx may result in erratic behavior.

Definition at line 844 of file SFEMP3Shield.cpp.

◆ setTrebleAmplitude()

void SFEMP3Shield::setTrebleAmplitude ( int8_t amplitude )

Set the current Treble Amplitude in VS10xx chip.

Parameters

[in] amplitude Treble in dB from -8 to 7.

Note: The upper and lower limits of this parameter is checked.

Definition at line 725 of file SFEMP3Shield.cpp.

◆ setTrebleFrequency()

void SFEMP3Shield::setTrebleFrequency ( uint16_t frequency )

Set the current treble frequency limit in VS10xx chip.

Parameters

[in] frequency Treble cutoff limit in Hertz.

Note: The upper and lower limits of this parameter is checked.

Definition at line 697 of file SFEMP3Shield.cpp.

◆ setVolume() [1/3]

void SFEMP3Shield::setVolume	(	uint8_t	leftchannel,
		uint8_t	rightchannel
	)

Store and Push member volume to VS10xx chip.

Parameters

[in]	leftchannel	writes the left channel master volume
[in]	rightchannel	writes the right channel master volume

Updates the VS10xx SCI_VOL register's left and right master volume level in -0.5 dB Steps. Where maximum volume is 0x0000 and total silence is 0xFEFE. As specified by Data Sheet Section 8.7.11

Note: input values are -1/2dB. e.g. 40 results in -20dB.

Definition at line 598 of file SFEMP3Shield.cpp.

◆ setVolume() [2/3]

void SFEMP3Shield::setVolume ( uint16_t data )

Overload function of SFEMP3Shield::setVolume(leftchannel, rightchannel)

Parameters

[in] data packed with left and right master volume

calls SFEMP3Shield::setVolume expecting the left channel in the upper byte and right channel in the lower byte.

As specified by Data Sheet Section 8.7.11

Definition at line 564 of file SFEMP3Shield.cpp.

◆ setVolume() [3/3]

void SFEMP3Shield::setVolume ( uint8_t data )

Overload function of SFEMP3Shield::setVolume(leftchannel, rightchannel)

Parameters

[in] uint8_t to be placed into both Left and Right

calls SFEMP3Shield::setVolume placing the input into both the left channel and right channels.

As specified by Data Sheet Section 8.7.11

Definition at line 581 of file SFEMP3Shield.cpp.

◆ setVUmeter()

int8_t SFEMP3Shield::setVUmeter ( int8_t enable )

enable VSdsp VU Meter

Parameters

[in] enable when set will enable the VU meter

Writes the SS_VU_ENABLE bit of the SCI_STATUS register to enable VU meter on board to the VSdsp.

See data patches data sheet VU meter for details.

Warning: This feature is only available with patches that support VU meter.
The VU meter takes about 0.2MHz of processing power with 48 kHz samplerate.

Definition at line 1673 of file SFEMP3Shield.cpp.

◆ skip()

uint8_t SFEMP3Shield::skip ( int32_t timecode )

Skips to a duration in the track.

Parameters

[in] timecode offset milliseconds from the current location of the file.

Repositions the filehandles track location to the requested offset. As calculated by the bitrate multiplied by the desired ms offset.

Returns

0 indicates the position was changed.
1 indicates no action, in lieu of any current file stream.
2 indicates failure to skip to new file location.

Warning: Limited to +/- 32768ms, since SdFile::seekCur(int32_t);

Definition at line 1278 of file SFEMP3Shield.cpp.

◆ skipTo()

uint8_t SFEMP3Shield::skipTo ( uint32_t timecode )

Skips to a certain point in the track.

Parameters

[in] timecode offset milliseconds from the begining of the file.

Repositions the filehandles track location to the requested offset. As calculated by the bitrate multiplied by the desired ms offset.

Returns

0 indicates the position was changed.
1 indicates no action, in lieu of any current file stream.
2 indicates failure to skip to new file location.

Warning: Limited to first 65535ms, since SdFile::seekSet(int32_t);

Definition at line 1334 of file SFEMP3Shield.cpp.

◆ spiInit()

void SFEMP3Shield::spiInit ( )

staticprivate

Initialize the SPI for VS10xx use.

Primative function to configure the SPI's BitOrder, DataMode and ClockDivider to that of the current VX10xx.

Warning: This sets the rate fast for write, too fast for reading. In the case of a subsequent SPI.transfer that is reading back data followup with a SPI.setClockDivider(spi_Read_Rate); as not to get gibberish.

Definition at line 1727 of file SFEMP3Shield.cpp.

◆ stopTrack()

void SFEMP3Shield::stopTrack ( )

Gracefully close track and cancel refill.

Skip if already not playing. Otherwise Disable the refill means, then set playing to false, close the filehandle track instance. And finally flush the VSdsp's stream buffer.

Definition at line 1110 of file SFEMP3Shield.cpp.

◆ trackAlbum()

void SFEMP3Shield::trackAlbum ( char * infobuffer )

Get Track's Album.

Parameters

[out] infobuffer pointer char array to be updated with result

Extract the Album from the current filehandles track ID3 tag information.

Warning: ID3 Tag information may not be present on all source files. Otherwise may result in non-sense. It is possible to add it with common tools outside of this project.

Definition at line 1446 of file SFEMP3Shield.cpp.

◆ trackArtist()

void SFEMP3Shield::trackArtist ( char * infobuffer )

Get Track's Artist.

Parameters

[out] infobuffer pointer char array to be updated with result

Extract the Artist from the current filehandles track ID3 tag information.

Warning: ID3 Tag information may not be present on all source files. Otherwise may result in non-sense. It is possible to add it with common tools outside of this project.

Definition at line 1414 of file SFEMP3Shield.cpp.

◆ trackTitle()

void SFEMP3Shield::trackTitle ( char * infobuffer )

Get Track's Title.

Parameters

[out] infobuffer pointer char array to be updated with result

Extract the Title from the current filehandles track ID3 tag information.

Warning: ID3 Tag information may not be present on all source files. Otherwise may result in non-sense. It is possible to add it with common tools outside of this project.

Definition at line 1430 of file SFEMP3Shield.cpp.

◆ vs_init()

uint8_t SFEMP3Shield::vs_init ( )

Initialize the VS10xx Audio Decoder Chip.

Reset and initialize the VS10xx chip's internal registers such as clock for normal operation with the SFEMP3Shield class's members. Along with uploading corresponding accumilative patch file, if present.

Returns

Any Value other than zero indicates a problem occured.

0 indicates that upload was successful.
1 thru 3 are omitted, as not to overlap with other errors.
4 indicates other than default values were found in the SCI_MODE register.
5 indicates SCI_CLOCKF did not read back and verify the configured value.

Note: returned Error codes are typically passed and therefore need to avoid overlap.

See also: Error Codes

Definition at line 220 of file SFEMP3Shield.cpp.

◆ VSLoadUserCode()

uint8_t SFEMP3Shield::VSLoadUserCode ( char * fileName )

private

load VS1xxx with patch or plugin from file on SDcard.

Parameters

[out] fileName pointer of a char array (aka string), contianing the filename

Loads the VX10xx with filename of the specified patch, if present. This can be used to load various VSdsp apps, patches and plug-in's. Providing many new features and updates not present on the default firmware.

The file format of the plugin is raw binary, in VLSI's interleaved and RLE compressed format, as extracted from the source plugin file (.plg). A perl script vs_plg_to_bin.pl is provided to convert the .plg file in to the binary filename.053. Where the extension of .053 is a convention to indicate the VSdsp chip version.

Note: by default all plug-ins are expected to be in the root of the SdCard.

Returns

Any Value other than zero indicates a problem occured.

0 indicates that upload was successful.
1 indicates the upload can not be performed while currently streaming music.
2 indicates that desired file was not found.
3 indicates that the VSdsp is in reset.

See also

Definition at line 327 of file SFEMP3Shield.cpp.

Member Data Documentation

◆ bitrate

uint8_t SFEMP3Shield::bitrate

private

contains a local value of the beleived current bit-rate.

Definition at line 752 of file SFEMP3Shield.h.

◆ mp3DataBuffer

uint8_t SFEMP3Shield::mp3DataBuffer

staticprivate

Buffer for moving data between Filehandle and VSdsp.

Definition at line 749 of file SFEMP3Shield.h.

◆ playing_state

state_m SFEMP3Shield::playing_state

staticprivate

Boolean flag indicating if filehandle is streaming.

Initializer for the instance of the SdCard's static member.

Definition at line 742 of file SFEMP3Shield.h.

◆ spi_Read_Rate

uint16_t SFEMP3Shield::spi_Read_Rate

staticprivate

Rate of the SPI to be used with communicating to the VSdsp.

Initializer for the instance of the SdCard's static member.

Definition at line 745 of file SFEMP3Shield.h.

◆ spi_Write_Rate

uint16_t SFEMP3Shield::spi_Write_Rate

staticprivate

Definition at line 746 of file SFEMP3Shield.h.

◆ start_of_music

uint32_t SFEMP3Shield::start_of_music

private

contains a filehandles offset to the begining of the current file.

Definition at line 755 of file SFEMP3Shield.h.

◆ track

SdFile SFEMP3Shield::track

staticprivate

Initializer for the instance of the SdCard's static member.

Definition at line 720 of file SFEMP3Shield.h.

◆ VolL

uint8_t SFEMP3Shield::VolL

private

contains a local value of the VSdsp's master volume left channels

Definition at line 758 of file SFEMP3Shield.h.

◆ VolR

uint8_t SFEMP3Shield::VolR

private

contains a local value of the VSdsp's master volume Right channels

Definition at line 761 of file SFEMP3Shield.h.

The documentation for this class was generated from the following files:

SFEMP3Shield/SFEMP3Shield.h
SFEMP3Shield/SFEMP3Shield.cpp

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ ADMixerLoad()

◆ ADMixerVol()

◆ available()

◆ begin()

◆ cs_high()

◆ cs_low()

◆ currentPosition()

◆ dcs_high()

◆ dcs_low()

◆ disableRefill()

◆ disableTestSineWave()

◆ enableRefill()

◆ enableTestSineWave()

◆ end()

◆ flush_cancel()

◆ getAudioInfo()

◆ getBassAmplitude()

◆ getBassFrequency()

◆ getBitRateFromMP3File()

◆ getDifferentialOutput()

◆ getEarSpeaker()

◆ getMonoMode()

◆ getPlaySpeed()

◆ getState()

◆ getTrackInfo()

◆ getTrebleAmplitude()

◆ getTrebleFrequency()

◆ getVolume()

◆ getVUlevel()

◆ getVUmeter()

◆ isPlaying()

◆ memoryTest()

◆ Mp3ReadRegister()

◆ Mp3ReadWRAM()

◆ Mp3WriteRegister() [1/2]

◆ Mp3WriteRegister() [2/2]

◆ Mp3WriteWRAM()

◆ pauseDataStream()

◆ pauseMusic()

◆ playMP3()

◆ playTrack()

◆ refill()

◆ resumeDataStream()

◆ resumeMusic() [1/2]

◆ resumeMusic() [2/2]

◆ SendSingleMIDInote()

◆ setBassAmplitude()

◆ setBassFrequency()

◆ setBitRate()

◆ setDifferentialOutput()

◆ setEarSpeaker()

◆ setMonoMode()

◆ setPlaySpeed()

◆ setTrebleAmplitude()

◆ setTrebleFrequency()

◆ setVolume() [1/3]

◆ setVolume() [2/3]

◆ setVolume() [3/3]

◆ setVUmeter()

◆ skip()

◆ skipTo()

◆ spiInit()

◆ stopTrack()

◆ trackAlbum()

◆ trackArtist()

◆ trackTitle()

◆ vs_init()

◆ VSLoadUserCode()

Member Data Documentation

◆ bitrate

◆ mp3DataBuffer