Add I2S output feature (#91)

VS1053B has built-in support for I2S output, which is disabled by default and uses GPIO4-7.
Adds methods to enable I2S output.

Author: episource

README.md

@@ -88,6 +88,23 @@ Above example and self-explanatory method name tells everything. It simply provi
 
 Optionally available is also `player.clearDecodedTime()` which clears decoded time (sets `SCI_DECODE_TIME` register to `0x00`).
 
+##### Enable I2S output
+
+```
+player.enableI2sOut(/* i2sRate: optional sampling rate, default is 48kHz */);
+player.disableI2sOut();
+```
+I2S output of the VS1053 chip can be enabled/disabled using methods `enableI2sOut` and `disableI2sOut`. When enabled, the gpio lines won't be available for other purposes. On reset the I2S output is disabled. The assignment to I2S lines is according to the table below:
+
+|  VS1053 GPIO | I2S            |
+|--------------|----------------|
+| 4            | LROUT / WSEL   |
+| 5            | MCLCK          |
+| 6            | SCLK / BCLK    |
+| 7            | SDATA / DOUT   |
+
+Refer to the [VS1053 datasheet](https://www.vlsi.fi/fileadmin/datasheets/vs1053.pdf) for details: the pin assignment is specified in section 5.1 on page 12, the I2S DAC interface is described in section 11.14 on page 83.
+
 #### Logging / debugging
 
 The library uses ESP Arduino framework built in logger (Arduino core for [ESP32](https://github.com/espressif/arduino-esp32/issues/893#issuecomment-348069135) and [ESP8266](https://github.com/esp8266/Arduino/blob/master/doc/Troubleshooting/debugging.rst#debug-level)).<br /> 

src/VS1053.cpp

@@ -319,13 +319,45 @@ void VS1053::printDetails(const char *header) {
  * Read more here: http://www.bajdi.com/lcsoft-vs1053-mp3-module/#comment-33773
  */
 void VS1053::switchToMp3Mode() {
-    wram_write(0xC017, 3); // GPIO DDR = 3
-    wram_write(0xC019, 0); // GPIO ODATA = 0
+    wram_write(ADDR_REG_GPIO_DDR_RW, 3); // GPIO DDR = 3
+    wram_write(ADDR_REG_GPIO_ODATA_RW, 0); // GPIO ODATA = 0
     delay(100);
     LOG("Switched to mp3 mode\n");
     softReset();
 }
 
+void VS1053::disableI2sOut() {
+    wram_write(ADDR_REG_I2S_CONFIG_RW, 0x0000);
+
+    // configure GPIO0 4-7 (I2S) as input (default)
+    // leave other GPIOs unchanged
+    uint16_t cur_ddr = wram_read(ADDR_REG_GPIO_DDR_RW);
+    wram_write(ADDR_REG_GPIO_DDR_RW, cur_ddr & ~0x00f0);
+}
+
+void VS1053::enableI2sOut(VS1053_I2S_RATE i2sRate) {
+    // configure GPIO0 4-7 (I2S) as output
+    // leave other GPIOs unchanged
+    uint16_t cur_ddr = wram_read(ADDR_REG_GPIO_DDR_RW);
+    wram_write(ADDR_REG_GPIO_DDR_RW, cur_ddr | 0x00f0);
+
+    uint16_t i2s_config = 0x000c; // Enable MCLK(3); I2S(2)
+    switch (i2sRate) {
+        case VS1053_I2S_RATE_192_KHZ:
+            i2s_config |= 0x0002;
+            break;
+        case VS1053_I2S_RATE_96_KHZ:
+            i2s_config |= 0x0001;
+            break;
+        default:
+        case VS1053_I2S_RATE_48_KHZ:
+            // 0x0000
+            break;
+    }
+
+    wram_write(ADDR_REG_I2S_CONFIG_RW, i2s_config );
+}
+
 /**
  * A lightweight method to check if VS1053 is correctly wired up (power supply and connection to SPI interface).
  *

src/VS1053.h

@@ -40,6 +40,12 @@
 
 #include "patches/vs1053b-patches.h"
 
+enum VS1053_I2S_RATE {
+    VS1053_I2S_RATE_192_KHZ,
+    VS1053_I2S_RATE_96_KHZ,
+    VS1053_I2S_RATE_48_KHZ
+};
+
 class VS1053 {
 private:
     uint8_t cs_pin;                         // Pin where CS line is connected
@@ -70,6 +76,12 @@ class VS1053 {
     const uint8_t SM_TESTS = 5;             // Bitnumber in SCI_MODE for tests
     const uint8_t SM_LINE1 = 14;            // Bitnumber in SCI_MODE for Line input
     const uint8_t SM_STREAM = 6;            // Bitnumber in SCI_MODE for Streaming Mode
+
+    const uint16_t ADDR_REG_GPIO_DDR_RW = 0xc017;
+    const uint16_t ADDR_REG_GPIO_VAL_R = 0xc018;
+    const uint16_t ADDR_REG_GPIO_ODATA_RW = 0xc019;
+    const uint16_t ADDR_REG_I2S_CONFIG_RW = 0xc040;
+
     SPISettings VS1053_SPI;                 // SPI settings for this slave
     uint8_t endFillByte;                    // Byte to send when stopping song
 protected:
@@ -167,6 +179,12 @@ class VS1053 {
     // An optional switch preventing the module starting up in MIDI mode
     void switchToMp3Mode();
 
+    // disable I2S output; this is the default state
+    void disableI2sOut();
+
+    // enable I2S output (GPIO4=LRCLK/WSEL; GPIO5=MCLK; GPIO6=SCLK/BCLK; GPIO7=SDATA/DOUT)
+    void enableI2sOut(VS1053_I2S_RATE i2sRate = VS1053_I2S_RATE_48_KHZ);
+
     // Checks whether the VS1053 chip is connected and is able to exchange data to the ESP
     bool isChipConnected();