Revision 2:47ba7e2259cd, committed 2013-11-09

Comitter:

kayekss

Date:

Sat Nov 09 10:23:04 2013 +0000

Parent:

1:00c19f771676

Child:

3:696c8e6744b2

Commit message:

Added API documentation

Changed in this revision

--- a/VS1053.cpp	Fri Nov 08 11:01:00 2013 +0000
+++ b/VS1053.cpp	Sat Nov 09 10:23:04 2013 +0000
@@ -1,4 +1,4 @@
-// ==================================================== Nov 08 2013, kayeks ==
+// ==================================================== Nov 09 2013, kayeks ==
 // VS1053.cpp
 // ===========================================================================
 // Just a simple library for VLSI's mp3/midi codec chip
@@ -7,7 +7,7 @@
 #include "mbed.h"
 #include "VS1053.h"
 
-/** Constructor of class VS1053 */
+/** Constructor of class VS1053. */
 VS1053::VS1053(PinName mosiPin, PinName misoPin, PinName sckPin,
                PinName csPin, PinName bsyncPin, PinName dreqPin,
                PinName rstPin, uint32_t spiFrequency)
@@ -27,11 +27,11 @@
     rst = 1;
 }
 
-/** Destructor of class VS1053 */
+/** Destructor of class VS1053. */
 VS1053::~VS1053() {
 }
 
-/** Do a hardware reset by hitting VS1053's RESET pin */
+/** Make a hardware reset by hitting VS1053's RESET pin. */
 void VS1053::hardwareReset() {
     rst = 0;
     wait(.05);
@@ -39,24 +39,26 @@
     wait(.05);
 }
 
-/** Send a byte to VS1053 */
-void VS1053::sendDataByte(uint8_t b) {
+/** Send a data byte to VS1053. */
+void VS1053::sendDataByte(uint8_t data) {
     while (!dreq);
     bsync = 0;
-    spi.write(b);
+    spi.write(data);
     bsync = 1;
 }
 
-/** Send a data block specified as a pointer to VS1053 */
-size_t VS1053::sendDataBlock(uint8_t* p, size_t length) {
+/** Send a data block specified as a pointer to VS1053.
+ *  @return Data length successfully sent.
+ */
+size_t VS1053::sendDataBlock(uint8_t* pData, size_t length) {
     size_t sizeSent = 0;
     
-    if (!p || !length) return 0;
+    if (!pData || !length) return 0;
     while (length) {
         while (!dreq);
         bsync = 0;
         for (uint8_t i = 0; i < 32 && length--; i++) {
-            spi.write(*p++);
+            spi.write(*pData++);
             sizeSent++;
         }
         bsync = 1;
@@ -64,13 +66,15 @@
     return sizeSent;
 }
 
-/** Change VS1053's PLL setting for speedup */
+/** Change VS1053's PLL setting for speedup. */
 void VS1053::clockUp() {
     // Set CLKI to 43.0-55.3 MHz
     writeReg(SCI_CLOCKF, 0x8800);  // SC_MULT=4 (3.5x), SC_ADD=1 (+1.0x)
 }
 
-/** Send cancel request to VS1053 */
+/** Send cancel request to VS1053.
+ *  @return 0 at failure, 1 at success.
+ */
 bool VS1053::sendCancel() {
     uint16_t reg;
     
@@ -84,7 +88,10 @@
     return 1;
 }
 
-/** Stop playing (CALL AFTER sendCancel SUCCESSES) */
+/** Attempts a termination of play.
+ *  Call this repeatedly during data stream tramsission until it successes.
+ *  @return 0 at failure, 1 at success.
+ */
 bool VS1053::stop() {
     uint16_t reg;
     uint8_t endFillByte;
@@ -116,7 +123,7 @@
     return readReg(SCI_HDAT0) == 0x0000 && readReg(SCI_HDAT1) == 0x0000;
 }
 
-/** Write to an SCI (Serial Control Interface) register entry */
+/** Write to an SCI (Serial Control Interface) register entry. */
 void VS1053::writeReg(uint8_t addr, uint16_t word) {
     // If addr is out-of-range, do nothing
     if (addr > 0x0f) {
@@ -133,7 +140,7 @@
     cs = 1;
 }
 
-/** Read an SCI (Serial Control Interface) register entry */
+/** Read an SCI (Serial Control Interface) register entry. */
 uint16_t VS1053::readReg(uint8_t addr) {
     uint16_t word;
     

--- a/VS1053.h	Fri Nov 08 11:01:00 2013 +0000
+++ b/VS1053.h	Sat Nov 09 10:23:04 2013 +0000
@@ -1,4 +1,4 @@
-// ==================================================== Nov 08 2013, kayeks ==
+// ==================================================== Nov 09 2013, kayeks ==
 // VS1053.h
 // ===========================================================================
 // Just a simple library for VLSI's mp3/midi codec chip
@@ -7,6 +7,7 @@
 #ifndef KAYX_VS1053_H_
 #define KAYX_VS1053_H_
 
+/** Class VS1053. Drives VLSI's mp3/midi codec chip. */
 class VS1053 {
 private:
     SPI spi;
@@ -33,15 +34,37 @@
     static const uint8_t SCI_AICTRL2     = 0x0e;
     static const uint8_t SCI_AICTRL3     = 0x0f;
     
+    /** Constructor of class VS1053. */
     VS1053(PinName mosiPin, PinName misoPin, PinName sckPin,
            PinName cs, PinName bsync, PinName dreq, PinName rstPin,
            uint32_t spiFrequency=1000000);
+    
+    /** Destructor of class VS1053. */
     ~VS1053();
+    
+    /** Make a hardware reset by hitting VS1053's RESET pin. */
     void hardwareReset();
-    void sendDataByte(uint8_t);
-    size_t sendDataBlock(uint8_t*, size_t);
+    
+    /** Send a data byte to VS1053. */
+    void sendDataByte(uint8_t data);
+    
+    /** Send a data block specified as a pointer to VS1053.
+     *  @return Data length successfully sent.
+     */
+    size_t sendDataBlock(uint8_t* pData, size_t length);
+    
+    /** Change VS1053's PLL setting for speedup. */
     void clockUp();
+    
+    /** Send cancel request to VS1053.
+     *  @return 0 at failure, 1 at success.
+     */
     bool sendCancel();
+    
+    /** Attempts "stop playing".
+     *  Call this repeatedly during data stream tramsission until it successes.
+     *  @return 0 at failure, 1 at success.
+     */
     bool stop();
     
 private: