CommandStation-EX/IO_DFPlayer.h

/*
 *  © 2021, Neil McKechnie. All rights reserved.
 *  
 *  This file is part of DCC++EX API
 *
 *  This is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  It is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with CommandStation.  If not, see <https://www.gnu.org/licenses/>.
 */

/*
 * DFPlayer is an MP3 player module with an SD card holder.  It also has an integrated
 * amplifier, so it only needs a power supply and a speaker.
 * 
 * This driver allows the device to be controlled through IODevice::write() and 
 * IODevice::writeAnalogue() calls.
 * 
 * The driver is configured as follows:
 * 
 *       DFPlayer::create(firstVpin, nPins, Serialn);
 * Where firstVpin is the first vpin reserved for reading the device,
 *       nPins is the number of pins to be allocated (max 5)
 *   and Serialn is the name of the Serial port connected to the DFPlayer (e.g. Serial2).
 * 
 * 
 * Example:
 *   In mySetup function within mySetup.cpp:
 *      DFPlayer::create(3500, 5, Serial2);
 *   Writing a value 0-2999 to the first pin will select a numbered file from the SD card;
 *   Writing a value 0-30 to the second pin will set the volume of the output;
 *   Writing a digital value to the first pin will play or stop the file;
 * 
 * From EX-RAIL, the following commands may be used:
 *   SET(3500)      -- starts playing the first file on the SD card
 *   SET(3501)      -- starts playing the second file on the SD card
 *   etc.
 *   RESET(3500)    -- stops all playing on the player
 *   WAITFOR(3500)  -- wait for the file currently being played by the player to complete
 * 
 * NB The DFPlayer's serial lines are not 5V safe, so connecting the Arduino TX directly 
 * to the DFPlayer's RX terminal will cause lots of noise over the speaker, or worse.
 * A 1k resistor in series with the module's RX terminal will alleviate this.
 */

#ifndef IO_DFPlayer_h
#define IO_DFPlayer_h

#include "IODevice.h"

class DFPlayer : public IODevice {
private: 
  HardwareSerial *_serial;
  bool _playing = false;
  uint8_t _inputIndex = 0;

public:
  DFPlayer(VPIN firstVpin, int nPins, HardwareSerial &serial) {
    _firstVpin = firstVpin;
    _nPins = min(nPins, 3);
    _serial = &serial;
    addDevice(this);
  }
  static void create(VPIN firstVpin, int nPins, HardwareSerial &serial) {
    new DFPlayer(firstVpin, nPins, serial);
  }

protected:
  void _begin() override {
    _serial->begin(9600);
    _display();
  }

  void _loop(unsigned long) override {
    // Check for incoming data on _serial, and update busy flag accordingly.
    // Expected message is in the form "7F FF 06 3D xx xx xx xx xx EF"
    while (_serial->available()) {
      int c = _serial->read();
//      DIAG(F("Received: %x"), c);
      if (c == 0x7E) 
        _inputIndex = 1;
      else if ((c==0xFF && _inputIndex==1) || (c==0x06 && _inputIndex==2) 
            || (c==0x3D && _inputIndex==3) || (_inputIndex >=4 && _inputIndex <= 8))
        _inputIndex++;
      else if (c==0xEF && _inputIndex==9) {
        // End of play
        #ifdef DIAG_IO
        DIAG(F("DFPlayer: Finished"));
        #endif
        _playing = false;
        _inputIndex = 0;
      }
    }
  }

  // Write with value 1 starts playing a song.  The relative pin number is the file number.
  // Write with value 0 stops playing.
  void _write(VPIN vpin, int value) override {
    int pin = vpin - _firstVpin;
    if (value) {
      // Value 1, start playing
      #ifdef DIAG_IO
      DIAG(F("DFPlayer: Play %d"), pin+1);
      #endif
      sendPacket(0x03, pin+1);
      _playing = true;
    } else {
      // Value 0, stop playing
      #ifdef DIAG_IO
      DIAG(F("DFPlayer: Stop"));
      #endif
      sendPacket(0x16);
      _playing = false;
    }
  }

  // WriteAnalogue on first pin uses the nominated value as a file number to start playing, if file number > 0.
  // If value is zero, it stops playing.
  // WriteAnalogue on second pin sets the output volume.
  void _writeAnalogue(VPIN vpin, int value, uint8_t, uint16_t) override { 
    uint8_t pin = _firstVpin - vpin;
    switch (pin) {
      case 0: 
        if (value > 0) {
          // Play global track
          if (value > 2999) return;
          #ifdef DIAG_IO
          DIAG(F("DFPlayer: Play %d"), value);
          #endif
          sendPacket(0x03, value);
          _playing = true;
        } else if (value == 0){
          #ifdef DIAG_IO
          DIAG(F("DFPlayer: Stop"));
          #endif
          sendPacket(0x16);
          _playing = false;
        }
        break;
      case 1:
        // Set volume (0-30)
        if (value > 30) value = 30;
        else if (value < 0) value = 0;
        #ifdef DIAG_IO
        DIAG(F("DFPlayer: Volume %d"), value);
        #endif
        sendPacket(0x06, value);
        break;
      default:
        break;
    }
  }

  bool _isBusy(VPIN vpin) override {
    (void)vpin;  // avoid compiler warning.
    return _playing;
  }

  void _display() override {
    DIAG(F("DFPlayer Configured on Vpins:%d-%d"));
  }
  
private:
  // 7E FF 06 0F 00 01 01 xx xx EF
  // 0	->	7E is start code
  // 1	->	FF is version
  // 2	->	06 is length
  // 3	->	0F is command
  // 4	->	00 is no receive
  // 5~6	->	01 01 is argument
  // 7~8	->	checksum = 0 - ( FF+06+0F+00+01+01 )
  // 9	->	EF is end code

  void sendPacket(uint8_t command, uint16_t arg = 0)
  {
    uint8_t out[] = { 0x7E,
        0xFF,
        06,
        command,
        00,
        static_cast<uint8_t>(arg >> 8),
        static_cast<uint8_t>(arg & 0x00ff),
        00,
        00,
        0xEF };

    setChecksum(out);

    _serial->write(out, sizeof(out));
  }

  uint16_t calcChecksum(uint8_t* packet)
  {
    uint16_t sum = 0;
    for (int i = 1; i < 7; i++)
    {
      sum += packet[i];
    }
    return -sum;
  }

  void setChecksum(uint8_t* out)
  {
    uint16_t sum = calcChecksum(out);

    out[7] = (sum >> 8);
    out[8] = (sum & 0xff);
  }
};

#endif // IO_DFPlayer_h