DYSV17Fmp3.h

Go to the documentation of this file.

/**
 * @file DYSV17Fmp3.h
 * @brief DY-SV17F MP3 Player Control Class
 * 
 * This class provides an interface to control the DY-SV17F MP3 player module.
 * It supports playing tracks by number or by filename/path, setting volume,
 * and monitoring busy status.
 */
 
#ifndef DYSV17FMP3_H
#define DYSV17FMP3_H
 
#include <Arduino.h>
 
/**
 * @class DYSV17Fmp3
 * @brief Controls a DY-SV17F MP3 player module
 * 
 * The DYSV17Fmp3 class manages communication with the DY-SV17F MP3 player module.
 * It handles sending commands, calculating checksums, and processing responses.
 * The class is designed to work with any Stream object (HardwareSerial, SoftwareSerial, etc.)
 */
class DYSV17Fmp3 {
public:
    /**
     * @brief Construct a new DYSV17Fmp3 object
     * 
     * @param stream Reference to the Stream object for communication with the MP3 module
     * @param busyPin Arduino pin number connected to the MP3 module's busy output
     */
    DYSV17Fmp3(Stream& stream, uint8_t busyPin);
    
    /**
     * @brief Initialize the MP3 player module
     * 
     * Sets up the busy pin as input and sends initial configuration commands
     * including volume setting. Should be called once during setup.
     */
    void begin();
    
    /**
     * @brief monitors the busy line to produce debug output
     * 
     */
    void update();
    
    /**
     * @brief sends the software reset command
     * 
     */
    void reset();
    
    /**
     * @brief Stops the current playback
     * 
     */
    void stop();
    
    /**
     * @brief Set the volume of the MP3 player
     * 
     * @param volume Volume level (0-30 typical range for DY-SV17F)
     */
    void setVolume(uint8_t volume);
    
    /**
     * @brief Play a track by its number/index
     * 
     * @param songNumber Track number to play (0-63 typical range)
     * @return true if command was sent successfully
     * @return false if command failed
     */
    bool playNumber(uint8_t songNumber);
    
    /**
     * @brief Play a track by its filename or path
     * 
     * @param path Filename or path to the track (max 16 characters)
     * @return true if command was sent successfully
     * @return false if path was invalid
     */
    bool playString(const char* path);
    
    /**
     * @brief Play a track by its filename or path and waits for busy
     * 
     * @param path Filename or path to the track (max 16 characters)
     * @return true if command was sent successfully and module is busy
     * @return false if command failed or path was invalid
     */
    bool playStringWait(const char* path);
    
    /**
     * @brief Get the current busy state of the MP3 player
     * 
     * @return true if MP3 player is busy (playing or processing)
     * @return false if MP3 player is idle
     */
    bool isBusy();
    
    /**
     * @brief Wait for busy state to change or timeout
     * 
     * Blocks until the busy pin state changes or timeout occurs.
     * Useful for waiting for command completion.
     * 
     * @param timeoutMs Maximum time to wait in milliseconds
     * @return true if state changed, false if timeout occurred
     */
    bool waitForBusyChange(uint32_t timeoutMs = 250);
 
private:
    Stream& _stream;        ///< Reference to the communication stream
    uint8_t _busyPin;       ///< Pin number for busy status input+
 
    bool lastBusy = false;  // previously read busy state
    uint32_t busyTimer = 0; // time of last busy line change or command sent
    
    /**
     * @brief Calculate checksum for a command buffer
     * 
     * @param buf Pointer to the command buffer
     * @param len Length of the buffer (excluding checksum byte)
     * @return uint8_t Calculated checksum value
     */
    uint8_t calculateChecksum(uint8_t* buf, uint8_t len);
    
    /**
     * @brief Send a command to the MP3 player
     * 
     * Automatically calculates and appends the checksum byte.
     * Waits for busy state change after sending.
     * 
     * @param txbuf Pointer to the command buffer (including space for checksum)
     * @param txlen Length of the command buffer including checksum byte location
     */
    void sendCommand(uint8_t* txbuf, uint8_t txlen);
    
    /**
     * @brief Send a command to the MP3 player
     * 
     * Automatically calculates and appends the checksum byte.
     * Waits for appropriate busy state before and after sending.
     * 
     * @param txbuf Pointer to the command buffer (including space for checksum)
     * @param txlen Length of the command buffer including checksum byte location
     * @return true if command was sent and module became busy
     * @return false if command failed
     */
    bool sendCommandWait(uint8_t* txbuf, uint8_t txlen);
};
 
#endif // DYSV17FMP3_H