Add support for reading and clearing decoded time by SCI_DECODE_TIME #41 (#42)

* Add support for check and reset decoding time by SCI_DECODE_TIME

Implemented handling for SCI_DECODE_TIME register according to VS1053b
Datasheet specification (v1.20). When decoding correct data,
current decoded time is shown in this register in full seconds.
Extended API with two methods. One provides estimation of decoding
time using SCI_DECODE_TIME. The other one allows to clear the value of
mentioned register.

Update documentation and bumped version for release.

Author: baldram

README.md

@@ -63,6 +63,25 @@ Please note that `player.switchToMp3Mode()` is an optional switch. Some of VS105
 You can modify the board, but there is a more elegant way without soldering. For more details please read a discussion here: [http://www.bajdi.com/lcsoft-vs1053-mp3-module/#comment-33773](http://www.bajdi.com/lcsoft-vs1053-mp3-module/#comment-33773).
 <br />No side effects for boards which do not need this switch, so you can call it just in case.
 
+#### Additionall functionality
+
+Below briefly described. For detailed information please see [VS1053b Datasheet specification](http://www.vlsi.fi/fileadmin/datasheets/vs1053.pdf).
+
+##### Test VS1053 chip via `SCI_STATUS`
+To check if the VS1053 chip is connected and able to exchange data to the microcontroller use the `player.isChipConnected()`.
+
+This is a lightweight method to check if VS1053 is correctly wired up (power supply and connection to SPI interface).
+
+For additional information please see [this issue](https://github.com/baldram/ESP_VS1053_Library/issues/24).
+
+##### Check and reset decoding time by `SCI_DECODE_TIME`
+
+`uint16_t seconds = player.getDecodedTime();  `
+
+Above example and self-explanatory method name tells everything. It simply provides current decoded time in full seconds (from `SCI_DECODE_TIME` register value).
+
+Optionally available is also `player.clearDecodedTime()` which clears decoded time (sets `SCI_DECODE_TIME` register to `0x00`).
+
 #### 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 /> 

library.json

@@ -1,6 +1,6 @@
 {
   "name": "ESP_VS1053_Library",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "keywords": "vs1053, esp8266, esp32, nodemcu, codec, mp3",
   "description": "This is a driver library for VS1053 MP3 Codec Breakout adapted for Espressif ESP8266 and ESP32 boards",
     "authors": [

library.properties

@@ -1,5 +1,5 @@
 name=VS1053 Library for ESP8266/ESP32
-version=1.1.1
+version=1.1.2
 author=Baldram
 maintainer=Baldram <[email protected]>
 sentence=This is a driver library for VS1053 MP3 Codec Breakout adapted for Espressif ESP8266 and ESP32 boards

src/VS1053.cpp

@@ -289,3 +289,40 @@ bool VS1053::isChipConnected() {
 
     return !(status == 0 || status == 0xFFFF);
 }
+
+/**
+ * Provides current decoded time in full seconds (from SCI_DECODE_TIME register value)
+ *
+ * When decoding correct data, current decoded time is shown in SCI_DECODE_TIME
+ * register in full seconds. The user may change the value of this register.
+ * In that case the new value should be written twice to make absolutely certain
+ * that the change is not overwritten by the firmware. A write to SCI_DECODE_TIME
+ * also resets the byteRate calculation.
+ *
+ * SCI_DECODE_TIME is reset at every hardware and software reset. It is no longer
+ * cleared when decoding of a file ends to allow the decode time to proceed
+ * automatically with looped files and with seamless playback of multiple files.
+ * With fast playback (see the playSpeed extra parameter) the decode time also
+ * counts faster. Some codecs (WMA and Ogg Vorbis) can also indicate the absolute
+ * play position, see the positionMsec extra parameter in section 10.11.
+ *
+ * @see VS1053b Datasheet (1.31) / 9.6.5 SCI_DECODE_TIME (RW)
+ *
+ * @return current decoded time in full seconds
+ */
+uint16_t VS1053::getDecodedTime() {
+    return read_register(SCI_DECODE_TIME);
+}
+
+/**
+ * Clears decoded time (sets SCI_DECODE_TIME register to 0x00)
+ *
+ * The user may change the value of this register. In that case the new value
+ * should be written twice to make absolutely certain that the change is not
+ * overwritten by the firmware. A write to SCI_DECODE_TIME also resets the
+ * byteRate calculation.
+ */
+void VS1053::clearDecodedTime() {
+    write_register(SCI_DECODE_TIME, 0x00);
+    write_register(SCI_DECODE_TIME, 0x00);
+}

src/VS1053.h

@@ -50,6 +50,7 @@ class VS1053 {
     const uint8_t SCI_STATUS = 0x1;
     const uint8_t SCI_BASS = 0x2;
     const uint8_t SCI_CLOCKF = 0x3;
+    const uint8_t SCI_DECODE_TIME = 0x4;        // current decoded time in full seconds
     const uint8_t SCI_AUDATA = 0x5;
     const uint8_t SCI_WRAM = 0x6;
     const uint8_t SCI_WRAMADDR = 0x7;
@@ -135,6 +136,10 @@ class VS1053 {
     void switchToMp3Mode();
 
     bool isChipConnected();
+
+    uint16_t getDecodedTime();                  // Provides SCI_DECODE_TIME register value
+
+    void clearDecodedTime();                    // Clears SCI_DECODE_TIME register (sets 0x00)
 };
 
 #endif