#include <MD_YX5300.h>

Classes
struct	cbData

Public Types
enum	status_t { STS_OK = 0x00 , STS_TIMEOUT = 0x01 , STS_VERSION = 0x02 , STS_CHECKSUM = 0x03 , STS_TF_INSERT = 0x3a , STS_TF_REMOVE = 0x3b , STS_FILE_END = 0x3d , STS_INIT = 0x3f , STS_ERR_FILE = 0x40 , STS_ACK_OK = 0x41 , STS_STATUS = 0x42 , STS_VOLUME = 0x43 , STS_EQUALIZER = 0x44 , STS_TOT_FILES = 0x48 , STS_PLAYING = 0x4c , STS_FLDR_FILES = 0x4e , STS_TOT_FLDR = 0x4f }

Public Member Functions
	MD_YX5300 (Stream &S)

	~MD_YX5300 (void)

void	begin (void)

bool	check (void)

Methods for object management.
void	setSynchronous (bool b)

void	setTimeout (uint32_t t)

void	setCallback (void(cb)(const cbData data))

const cbData *	getStatus (void)

status_t	getStsCode (void)

uint16_t	getStsData (void)

Methods for device management.
bool	device (uint8_t devId)

bool	equalizer (uint8_t eqId)

bool	sleep (void)

bool	wakeUp (void)

bool	shuffle (bool b)

bool	repeat (bool b)

bool	reset (void)

Methods for controlling playing MP3 files.
bool	playNext (void)

bool	playPrev (void)

bool	playStop (void)

bool	playPause (void)

bool	playStart (void)

bool	playTrack (uint8_t t)

bool	playTrackRepeat (uint8_t file)

bool	playSpecific (uint8_t fldr, uint8_t file)

bool	playFolderRepeat (uint8_t folder)

bool	playFolderShuffle (uint8_t folder)

Methods for controlling MP3 output volume.
bool	volume (uint8_t vol)

uint8_t	volumeMax (void)

bool	volumeInc (void)

bool	volumeDec (void)

bool	volumeMute (bool b)

bool	volumeQuery (void)

Methods for querying MP3 device parameters.
bool	queryStatus (void)

bool	queryVolume (void)

bool	queryEqualizer (void)

bool	queryFolderFiles (uint8_t folder)

bool	queryFolderCount (void)

bool	queryFilesCount (void)

bool	queryFile (void)

Static Public Attributes
static const uint16_t	SERIAL_BPS = 9600

Detailed Description

Core object for the MD_YX5300 library

Member Enumeration Documentation

◆ status_t

enum MD_YX5300::status_t

Status code enumerated type specification.

Used by the cbData status structure in the code field to identify the type of status data contained.

Enumerator
STS_OK	No error (library generated status)
STS_TIMEOUT	Timeout on response message (library generated status)
STS_VERSION	Wrong version number in return message (library generated status)
STS_CHECKSUM	Device checksum invalid (library generated status)
STS_TF_INSERT	TF Card was inserted (unsolicited)
STS_TF_REMOVE	TF card was removed (unsolicited)
STS_FILE_END	Track/file has ended (unsolicited)
STS_INIT	Initialization complete (unsolicited)
STS_ERR_FILE	Error file not found.
STS_ACK_OK	Message acknowledged ok.
STS_STATUS	Current status.
STS_VOLUME	Current volume level.
STS_EQUALIZER	Equalizer status.
STS_TOT_FILES	TF Total file count.
STS_PLAYING	Current file playing.
STS_FLDR_FILES	Total number of files in the folder.
STS_TOT_FLDR	Total number of folders.

Constructor & Destructor Documentation

◆ MD_YX5300()

MD_YX5300::MD_YX5300 ( Stream & S )

Class Constructor.

Instantiate a new instance of the class. The parameters passed are used to connect the software to the hardware.

The Stream object passed to the constructor must be initialized in the main application. For convenience the constant SERIAL_BPS can be used for consistency when setting the serial interface speed.

Parameters

S	Serial stream to be used for the connection to the device.

◆ ~MD_YX5300()

MD_YX5300::~MD_YX5300 ( void )

Class Destructor.

Release any necessary resources and and does the necessary to clean up once the object is no longer required.

Note that output stream is not managed by this destructor and should be handled in the application.

Member Function Documentation

◆ begin()

void MD_YX5300::begin ( void )

Initialize the object.

Initialize the object data. This needs to be called during setup() to initialize new data for the class that cannot be done during the object creation.

The MP3 device is reset and the TF card set as the input file system, with appropriate delays after each operation.

◆ check()

bool MD_YX5300::check ( void )

Receive and process serial messages.

The check function should be called repeatedly in loop() to allow the library to receive and process device messages. The MP3 device can send messages as a response to a request or unsolicited to inform of state changes, such a track play completing. A true value returned indicates that a message has been received and the status is ready to be processed.

With callbacks disabled, the application should use getStatus() to retrieve and process this status. With callbacks enabled, the check() will cause the callback to be processed before returning to the application.

If synchronous mode is enabled only unsolicited messages will be processed through the call to check(), as the other messages will have been processed synchronously as part of the request.

See also: cbData, setCallback(), setSynchronous(), getStatus()

Returns: true if a message has been received and processed, false otherwise.

◆ device()

bool MD_YX5300::device ( uint8_t devId )

Set the file store device.

Set the file store device to the specified type. Currently the only type available is a TF device (CMD_OPT_TF). The application should allow 200ms for the file system to be initialized before further interacting with the MP3 device.

The TF file system is set at begin() and this method should not need to be called from application code.

See also: check(), getStatus(), setSynchronous()

Parameters

devId the device id for the type of device. Currently only 0x02 (TF).

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ equalizer()

bool MD_YX5300::equalizer ( uint8_t eqId )

Set equalizer mode.

Set the equalizer mode to one of the preset types - 0:Normal, 1:Pop, 2:Rock, 3:Jazz, 4:Classic or 5:Base

See also: check(), getStatus(), setSynchronous()

Parameters

eqId	the equalizer type requested [1..5].

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ getStatus()

const cbData* MD_YX5300::getStatus ( void )

Get the status of last device operation.

Get the status of the last requested operation of the MP3 device. A pointer to the library's status block is returned to the application. The status code is one of the status_t enumerated types and the data component returned will depend status value. The code and data depend on the original request made of the device.

See also: cbData, getStsCode(), getStsData()

Returns: Pointer to the 'last status' data structure.

◆ getStsCode()

status_t MD_YX5300::getStsCode ( void )

Get the status code of last device operation.

Get the status code of the of the last MP3 operation. The status code is one of the status_t enumerated types.

See also: cbData, getStatus(), getStsData()

Returns: The requested status code.

◆ getStsData()

uint16_t MD_YX5300::getStsData ( void )

Get the status data of last device operation.

Get the status data of the of the last MP3 operation. The meaning of the data will depend on the associated status code.

See also: cbData, getStatus(), getStsCode()

Returns: The requested status data.

◆ playFolderRepeat()

bool MD_YX5300::playFolderRepeat ( uint8_t folder )

Control repeat play mode (specific folder).

Set or reset the repeat playing mode for the specified folder. At the end of playing each file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Parameters

folder the folder number containing the files to repeat.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playFolderShuffle()

bool MD_YX5300::playFolderShuffle ( uint8_t folder )

Control shuffle play mode (specific folder).

Set or reset the shuffle playing mode for the specified folder. At the end of playing each file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Parameters

folder the folder number containing the files to repeat.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playNext()

bool MD_YX5300::playNext ( void )

Play the next MP3 file.

Play the next MP3 file in numeric order. At the end of playing the file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playPause()

bool MD_YX5300::playPause ( void )

Pause playing the current MP3 file.

Pause playing playing the current MP3 file. playStart() should follow to restart the same MP3 file. playStop() should be use to stop playing and abort current playing mode.

See also: playPause(), playStart(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playPrev()

bool MD_YX5300::playPrev ( void )

Play the previous MP3 file.

Play the previous MP3 file in numeric order. At the end of playing the file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playSpecific()

bool MD_YX5300::playSpecific	(	uint8_t	fldr,
		uint8_t	file
	)

Play a specific file in a folder.

Play a file by specifying the folder and file to be played. At the end of playing the file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Parameters

fldr	the folder number containing the files.
file	the file within the folder.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playStart()

bool MD_YX5300::playStart ( void )

Restart playing the current MP3 file.

Restart playing playing the current MP3 file after a playPause(). At the end of playing the file the device will send a STS_FILE_END unsolicited message.

See also: playPause(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playStop()

bool MD_YX5300::playStop ( void )

Stop playing the current MP3 file.

Stop playing the current MP3 file and cancel the current playing mode. playPause() should be used for a temporary playing stop.

See also: playPause(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playTrack()

bool MD_YX5300::playTrack ( uint8_t t )

Play a specific file.

Play a file by specifying the file index number. At the end of playing the file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Parameters

t	the file indexed (0-255) to be played.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ playTrackRepeat()

bool MD_YX5300::playTrackRepeat ( uint8_t file )

Play repeat specific track.

Play a track in repeat mode. At the end of playing the file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Parameters

file	the file index.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ queryEqualizer()

bool MD_YX5300::queryEqualizer ( void )

Query the current equalizer setting.

Request the current equalizer setting from the device. The response will be in an unsolicited message following the initial request.

cbData.code is STS_?? (unknown).
cbData.data is the equalizer setting.

See also: check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ queryFile()

bool MD_YX5300::queryFile ( void )

Query the file currently playing.

Request the index of the file currently being played. The response will be in an unsolicited message following the initial request.

cbData.code is STS_PLAYING.
cbData.data is the index of the file currently playing.

See also: check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ queryFilesCount()

bool MD_YX5300::queryFilesCount ( void )

Query the total number of files.

Request the count of files on the TF device. The response will be in an unsolicited message following the initial request.

cbData.code is STS_TOT_FILES.
cbData.data is the count of the files on the file store.

See also: check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ queryFolderCount()

bool MD_YX5300::queryFolderCount ( void )

Query the total number of folders.

Request the count of folder on the TF device. The response will be in an unsolicited message following the initial request.

cbData.code is STS_TOT_FLDR.
cbData.data is the count of the folder on the file store, including the root folder.

See also: check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ queryFolderFiles()

bool MD_YX5300::queryFolderFiles ( uint8_t folder )

Query the number of files in the specified folder.

Request the count of files in the specified folder number. The response will be in an unsolicited message following the initial request.

cbData.code is STS_FLDR_FILES.
cbData.data is the count of the files in the folder.

See also: check(), getStatus(), setSynchronous()

Parameters

folder the folder number whose files are to be counted.

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ queryStatus()

bool MD_YX5300::queryStatus ( void )

Query the current status.

Request the current status setting from the device. The response will be in an unsolicited message following the initial request.

cbData.code is STS_STATUS.
cbData.data high byte is the active file store active (0x02 for TF); low byte 0x00=stopped, 0x01=play, 0x02=paused.

See also: volumeQuery(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ queryVolume()

bool MD_YX5300::queryVolume ( void )

Query the current volume setting.

Request the current volume setting from the device. This is a wrapper alternative for volumeQuery(). The response will be in an unsolicited message following the initial request.

cbData.code is STS_VOLUME.
cbData.data is the volume setting.

See also: volumeQuery(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ repeat()

bool MD_YX5300::repeat ( bool b )

Control repeat play mode (current file).

Set or reset the repeat playing mode for the currently playing track. At the end of each repeat play the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Parameters

b	true to enable mode, false to disable.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ reset()

bool MD_YX5300::reset ( void )

Reset the MP3 player.

Put the MP3 player into reset mode. The payer will return to its power up state. The application should allow 500ms between the rest command and any subsequent interaction with the device.

See also: check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ setCallback()

void MD_YX5300::setCallback ( void(*)(const cbData *data) cb )

Set the status callback.

Set status callback function that will be invoked when a device status serial message is received. The callback will include the status encoded in the serial message. If callback is not required, the callback should be set to nullptr (the default). The callback is invoked when the last character of response message is received from the device.

Callbacks and synchronous mode are set and operate independently.

See also: getStatus(), setSynchronous()

Parameters

cb	the address of the callback function in user code.

Returns: No return value.

◆ setSynchronous()

void MD_YX5300::setSynchronous ( bool b )

Set or clear Synchronous mode.

Set/reset synchronous mode operation for the library. In synchronous mode, the library will wait for device response message immediately after sending the request. On return the status result of the operation will be available using the getStatus() method. If synchronous mode is disabled, then the code must be retrieved using getStatus() when the check() method returns true.

Synchronous mode and callbacks are set and operate independently.

See also: getStatus(), check(), setCallback()

Parameters

b	true to set the mode, false to disable.

Returns: No return value.

◆ setTimeout()

void MD_YX5300::setTimeout ( uint32_t t )

Set serial response timeout.

Set the device response timeout in milliseconds. If a message is not received within this time a timeout error status will be generated. The default timeout is 200 milliseconds.

Parameters

t	timeout in milliseconds

Returns: No return value.

◆ shuffle()

bool MD_YX5300::shuffle ( bool b )

Control shuffle playing mode.

Set or reset the playing mode to/from random shuffle. At the end of playing each file the device will send a STS_FILE_END unsolicited message.

See also: check(), getStatus(), setSynchronous()

Parameters

b	true to enable mode, false to disable.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ sleep()

bool MD_YX5300::sleep ( void )

Set sleep mode.

Enables the MP3 player sleep mode. The device will stop playing but still respond to serial messages. Use wakeUp() to disable sleep mode.

See also: wakeUp(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ volume()

bool MD_YX5300::volume ( uint8_t vol )

Set specified volume.

Set the output volume to the specified level. Maximum volume is volumeMax().

See also: volumeInc(), volumeDec(), check(), getStatus(), setSynchronous()

Parameters

vol	the volume specified [0..MAX_VOLUME].

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ volumeDec()

bool MD_YX5300::volumeDec ( void )

Decrement the volume.

Decrement the output volume by 1.

See also: volume(), volumeInc(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ volumeInc()

bool MD_YX5300::volumeInc ( void )

Increment the volume.

Increment the output volume by 1.

See also: volume(), volumeDec(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ volumeMax()

uint8_t MD_YX5300::volumeMax ( void )

Return the maximum possible volume.

Return the maximum allowable volume level.

See also: volumeInc(), volumeDec(), check(), getStatus(), setSynchronous()

Returns: The maximum volume level.

◆ volumeMute()

bool MD_YX5300::volumeMute ( bool b )

Mute the sound output.

Mute the sound output by suppressing the output from the DAC. The MP3 file will continue playing but will not be heard. To temporarily halt the playing use playPause().

See also: playPause(), check(), getStatus(), setSynchronous()

Parameters

b	true to enable mode, false to disable.

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ volumeQuery()

bool MD_YX5300::volumeQuery ( void )

Query the current volume setting.

Request the current volume setting from the device. This is a wrapper alternative for queryVolume(). The response will be in an unsolicited message following the initial request.

See also: queryVolume(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the request message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

◆ wakeUp()

bool MD_YX5300::wakeUp ( void )

Set awake mode.

Wakes up the MP3 player from sleep mode. Use sleep() to enable sleep mode.

See also: sleep(), check(), getStatus(), setSynchronous()

Returns: In synchronous mode, true when the message has been received and processed. Otherwise ignore the return value and process using callback or check() and getStatus().

Member Data Documentation

◆ SERIAL_BPS

const uint16_t MD_YX5300::SERIAL_BPS = 9600

static

Speed for the serial interfac e on the YX5300

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

src/MD_YX5300.h
src/MD_YX5300.cpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ status_t

Constructor & Destructor Documentation

◆ MD_YX5300()

◆ ~MD_YX5300()

Member Function Documentation

◆ begin()

◆ check()

◆ device()

◆ equalizer()

◆ getStatus()

◆ getStsCode()

◆ getStsData()

◆ playFolderRepeat()

◆ playFolderShuffle()

◆ playNext()

◆ playPause()

◆ playPrev()

◆ playSpecific()

◆ playStart()

◆ playStop()

◆ playTrack()

◆ playTrackRepeat()

◆ queryEqualizer()

◆ queryFile()

◆ queryFilesCount()

◆ queryFolderCount()

◆ queryFolderFiles()

◆ queryStatus()

◆ queryVolume()

◆ repeat()

◆ reset()

◆ setCallback()

◆ setSynchronous()

◆ setTimeout()

◆ shuffle()

◆ sleep()

◆ volume()

◆ volumeDec()

◆ volumeInc()

◆ volumeMax()

◆ volumeMute()

◆ volumeQuery()

◆ wakeUp()

Member Data Documentation

◆ SERIAL_BPS