Merge pull request #11 from nomakewan/docupdate

Documentation, function updates

Author: gpstar81

README.md

@@ -64,18 +64,22 @@ Example code to demonstrate some of the GPStar Audio's features can be found in
 
 **GPStarAudio.resumeAllInSync()** - This will resume all tracks which are currently paused at the exact same time.
 
-**GPStarAudio.samplerateOffset(uint16_t offset)** - This sets the sample-rate offset of the main output mix. The range for the offset is `-32767` to `32676`, giving a speed range of 1/2x to 2x or a pitch range of down one octave to up one octave. If audio is playing you will hear the result immediately. If audio is not playing, the new sample-rate offset will be used the next time a track is started.
+**GPStarAudio.samplerateOffset(int16_t offset)** - This sets the sample-rate offset of the main output mix. The range for the offset is `-32767` to `32676`, giving a speed range of 1/2x to 2x or a pitch range of down one octave to up one octave. If audio is playing you will hear the result immediately. If audio is not playing, the new sample-rate offset will be used the next time a track is started.
 
 **GPStarAudio.setLED(bool status)** - You can turn off the LED status indicator by setting `status` to `false`. Passing `true` enables the LED again. By default the LED on GPStar Audio flashes and blinks to provide various status updates.
 
 **GPStarAudio.gpstarShortTrackOverload(bool status)** - Enabled by default. GPStar Audio will detect mulitple versions of the same sound playing in succession and prevent it from overloading and taking too many audio channels, instead replaying the file to save system resources.
 
 **GPStarAudio.gpstarTrackForce(bool status)** - Disabled by default. When enabled, GPStar Audio will forcibly take a audio channel when requested to play a new track even if all channels in use and locked.
 
-**GPStarAudio.trackPlayingStatus(uint16_t trk)** - This will ask GPStar Audio if the provided track number is playing. After calling this method, call the `GPStarAudio.currentTrackStatus(uint16_t trk)` method to find out if the track is playing or not.
+**GPStarAudio.trackPlayingStatus(uint16_t trk)** - This will ask GPStar Audio if the provided track number is playing. After calling this method, call the `GPStarAudio.currentTrackStatus(uint16_t trk)` method to find out if the track is playing or not. If the provided track number is not currently playing, this function will also set the internal track counter flag to `false` (see `isTrackCounterReset()`).
 
 **GPStarAudio.currentTrackStatus(uint16_t trk)** - This will retrieve the status of a the provided track number if it is playing. You will want to use the `GPStarAudio.trackPlayingStatus(uint16_t trk)` method first to ask if the provided track is playing, then call this method soon after to retrieve the response.
 
+**GPStarAudio.resetTrackCounter()** - Call this function to reset the state of the internal track counter flag. This is useful, for example, when you want to identify when a specific track has finished playing (such as for music playback). It is recommended to call this right before you start playing the track you intend to have the GPStar Audio follow the status of.
+
+**GPStarAudio.isTrackCounterReset()** - Call this function to see if the internal track counter flag has been reset. This will return `true` if the internal track counter flag has been reset by `resetTrackCounter()`. It will return `false` if `resetTrackCounter()` has never been called or if `trackPlayingStatus(trk)` was called on a track that is not currently playing.
+
 **GPStarAudio.setReporting(bool enable)** - Provided for backwards compatibility with existing polyphonic audio boards, but has no effect on GPStar Audio (which always has track reporting enabled).
 
 **GPStarAudio.setAmpPwr(bool enable)** - Provided for backwards compatibility with existing polyphonic audio boards, but has no effect on GPStar Audio (which uses a headphone sense circuit to dynamically switch between the headphone and speaker amplifiers).

examples/example.ino

@@ -20,7 +20,7 @@
  *   1. Download and install AltSoftSerial library.
  *   2. Copy the wav files from the example folder to a Micro SD Card.
  *   3. Connect 4 wires from the UNO or Nano to the GPStar UART connector / pins:
- 
+
  *   UNO / Nano            GPStar Audio
  *   ----------            ------------
  *      GND      <----->       GND
@@ -81,7 +81,7 @@ void loop() {
     // Play track 2 at 100% volume. The track will stop playing after it has ended.
     gpstar.trackGain(2, 0);
     gpstar.trackPlay(2);
-    
+
     delay(5000);
 
     // Fade in track 3 over 4 seconds to 100% volume, and let it loop

library.properties

@@ -3,7 +3,7 @@ version=1.0.0
 author=Michael Rajotte
 maintainer=Michael Rajotte <[email protected]>
 sentence=Control your GPStar Audio boards with serial communication commands.
-paragraph=A serial communication control library for the GPStar Audio and GPStar Audio XL series of audio boards from GPStar Technologies. 
+paragraph=A serial communication control library for the GPStar Audio and GPStar Audio XL series of audio boards from GPStar Technologies.
 category=Audio
 architectures=*
 url=https://github.com/gpstar81/GPStarAudio-Serial-Library

src/GPStarAudio.cpp

@@ -115,13 +115,14 @@ void gpstarAudio::update(void) {
 
           // 0 = not playing. 1 = playing.
           if(rxMessage[3] == 0) {
-            b_currentTrackStatus = false;
+            bCurrentTrackStatus = false;
           }
           else {
-            b_currentTrackStatus = true;
+            bCurrentTrackStatus = true;
           }
 
-          resetTrackCounter(false);
+          // Set trackCounter to false to reset it.
+          trackCounter = false;
         break;
 
         case RSP_TRACK_REPORT:
@@ -174,20 +175,34 @@ void gpstarAudio::update(void) {
 
 bool gpstarAudio::currentTrackStatus(uint16_t trk) {
   if(trk == currentTrack) {
-    if(b_currentTrackStatus) {
+    if(bCurrentTrackStatus) {
       return true;
     }
   }
 
   return false;
 }
 
+__attribute__((deprecated("trackCounterReset() is deprecated. Please use isTrackCounterReset() instead.")))
 bool gpstarAudio::trackCounterReset() {
+  return isTrackCounterReset();
+}
+
+bool gpstarAudio::isTrackCounterReset() {
+  // trackCounter is reset if it is true.
   return trackCounter;
 }
 
+__attribute__((deprecated("resetTrackCounter(bool) is deprecated and will always reset to true. Please use resetTrackCounter() without passing a parameter instead.")))
 void gpstarAudio::resetTrackCounter(bool bReset) {
-  trackCounter = bReset;
+  // Ignore the passed parameter and reset trackCounter.
+  (void)bReset;
+  resetTrackCounter();
+}
+
+void gpstarAudio::resetTrackCounter() {
+  // Resetting the variable means to set it to true.
+  trackCounter = true;
 }
 
 void gpstarAudio::trackPlayingStatus(uint16_t trk) {

src/GPStarAudio.h

@@ -102,7 +102,9 @@ class gpstarAudio
   void trackPlayingStatus(uint16_t trk);
   bool currentTrackStatus(uint16_t trk);
   bool trackCounterReset(void);
-  void resetTrackCounter(bool bReset);  
+  void resetTrackCounter(bool bReset);
+  bool isTrackCounterReset(void);
+  void resetTrackCounter(void);
   void serialFlush(void);
   void requestVersionString(void);
   void requestSystemInfo(void);
@@ -131,6 +133,6 @@ class gpstarAudio
   bool sysInfoRcvd;
   bool gpsInfoRcvd;
   uint16_t currentTrack;
-  bool b_currentTrackStatus;
+  bool bCurrentTrackStatus;
   bool trackCounter;
 };