Merge pull request #16 from gpstar81/queues

Documentation update for GPStar Audio XL

Author: gpstar81

GPStarAudio.ini

@@ -1,15 +1,64 @@
 [gpstarconfig]
-volume_amplifier = 0
-volume_aux = 0
-serial_baud_rate = 57600
-led_off = 0
+volumeAmplifier = 0
+volumeAux = 0
+ledOff = false
 
-[gpstartracks]
-gp1_playback = normal
+[gpstarmode]
+gp1_mode = repeat
+gp2_mode = normal
+gp3_mode = normal
+gp4_mode = repeat
+gp5_mode = repeat
+gp6_mode = normal
+gp7_mode = normal
+gp8_mode = normal
+gp9_mode = normal
+gp10_mode = normal
+
+[gpstartrigger]
 gp1_trigger = press
-gp1_file_number = 1
+gp2_trigger = press
+gp3_trigger = press
+gp4_trigger = press
+gp5_trigger = press
+gp6_trigger = press
+gp7_trigger = press
+gp8_trigger = press
+gp9_trigger = hold
+gp10_trigger = press
+
+[gpstarplayback]
+gp1_playback = stop
+gp2_playback = pause
+gp3_playback = stop
+gp4_playback = restart
+gp5_playback = pause
+gp6_playback = stop
+gp7_playback = stop
+gp8_playback = stop
+gp9_playback = stop
+gp10_playback = pause
+
+[gpstartracks]
+gp1_track = 1
+gp2_track = 100
+gp3_track = 111
+gp4_track = 111
+gp5_track = 111
+gp6_track = 111
+gp7_track = 111
+gp8_track = 111
+gp9_track = 111
+gp10_track = 500
+
+[gpstartrackvolume]
 gp1_volume = 0
-gp2_playback = loop
-gp2_trigger = hold
-gp2_file_number = 1
-gp2_volume = 0
+gp2_volume = 0
+gp3_volume = -5
+gp4_volume = -10
+gp5_volume = -20
+gp6_volume = -30
+gp7_volume = -40
+gp8_volume = -50
+gp9_volume = 0
+gp10_volume = 0

README.md

@@ -179,13 +179,30 @@ Up to 20 triggering pins are availble on the GPStar Audio XL. They have JST-PH 2
 | TX2/RX2 | TX2/RX2 | Alternative serial communication port used for debugging. |
 | TEST |  | A button located on the lower right corner of the board. Pressing this button will play the first track on the micro SD card. |
 
-## Configuration file
+## Configuration file and syntax usage
 A configuration file is not required. However you can configure some settings by placing a `GPStarAudio.ini` configuration file into the root of the micro SD card. An example file can be found in this repository. If a configuration file is not found on the micro SD card the default settings are used.
 
 Many options can be set, such as the default output amplifier gain, serial communication baud rate, LED settings and to how the trigger pins handle playback.
 
 The syntax of the file is very simple, using enclosed square brackets to setup configuration areas.
 
+Example syntax is as follows:
+
+**[gpstarconfig]**
+<br>volume&#95;amplifier = 10
<br>volume&#95;aux = 0
<br>serial&#95;baud&#95;rate = 57600
<br>led&#95;off = 0
+
+**[gpstarmode]**
<br>gp1&#95;mode = repeat
<br>gp2&#95;mode = normal
+
+**[gpstartrigger]**
<br>gp1&#95;trigger = press
<br>gp2&#95;trigger = hold
+
+**[gpstarplayback]**
<br>gp1&#95;playback = stop
<br>gp2&#95;playback = pause
+
+**[gpstartracks]**
<br>gp1&#95;track = 1
<br>gp2&#95;track = 100
+
+**[gpstartrackvolume]**
<br>gp1&#95;volume = 0
<br>gp2&#95;volume = -25
+
+## System configuration
+
 **[gpstarconfig]:** This area can set the general settings of the board. If none of these settings exist in the ini file, then the system will default to the default settings for each option.
 
 **volume&#95;amplifier:** This sets the master gain (in dB) of the stereo speaker amplifier. The range is `-53` (quietest) to `24` (loudest). The default is `0`.
@@ -196,20 +213,22 @@ The syntax of the file is very simple, using enclosed square brackets to setup c
 
 **led&#95;off:** Control whether the onboard status LED flashes or not during playback or non playback. Valid values are 0 for allowing the LED to function or `1` for disabling the LED. The default is `0`.
 
-## Trigger configuration
-Unique to GPStar Audio XL are the trigger pins. These can be setup so you can play sounds without any coding. You can also conigure the behaviour of these pins by setting them up into the GPStarAudio.ini configuration file. Please refer to the example configuration file located in this repository for usage.
+## Triggering configuration
+Unique to GPStar Audio XL are the triggering pins. These can be setup so you can play sounds without any coding. You can also conigure the behaviour of these pins by setting them up into the GPStarAudio.ini configuration file. Please refer to the example configuration file located in this repository for usage.
 
 Note that these do not need to be configured for the trigger pins to operate and if `GPStarAudio.ini` is not on the micro SD card the default settings are loaded for the trigger pins.
 
-**[gpstartracks]:** This area contains playback setup and configuration of the 20 trigger pins. The pins are identified by gp1_ prefix in the ini file. The range is from `gp1_` up to `gp20_`.
+This area contains playback setup and configuration of the 20 triggering pins. The pins are identified by gp1_ prefix in the ini file. The range is from `gp1_` up to `gp20_`.
+
+**[gpstarmode]:** Valid settings for this is `normal`, or `repeat`. Normal plays the track and it stops when it finishes. Repeat will make the track loop forever unless re triggered again to do something else.
 
-**gp#&#95;playback:** Control how the playback is assigned to this trigger. Valid settings are `normal` or `loop`. `normal` will play the file until completion then it stops. `loop` will continuously loop the the audio until the pin is triggered again. Default is `normal`.
+**[gpstartrigger]:** Control how the playback is assigned to this trigger. Valid settings are `press` or `hold`. Press will trigger the pin and play the track. Hold will also trigger the track however releasing the trigger will make it perform an associated action setup with **[gpstarplayback]**.
 
-**gp#&#95;trigger:** Set how the audio is triggered. Valid settings are `press` or `hold`. With `press`, when you make contact between the trigger pin and the ground pin below it the audio file will play and will contiinue to play even when you release the contact between the trigger pin and ground pin. With `hold`, you need to make continuous contact between the trigger pin and ground pin for the audio to play, as releasing the contact will cause it to stop. Default is `press`.
+**[gpstarplayback]:** This sets the what the trigger action will do if the trigger is already playing a track. Valid settings are `stop`, `pause`, `restart`. When pause is used, triggering it again will resume the playback of the track where it left off.
 
-**gp#&#95;file_number:** The track number on the microSD card. The default is the pin number of this trigger. For example, set this to `100` to play the wav file with the `100_` prefix.
+**[gpstartracks]:** The track number on the MicroSD Card. The default is the pin number of this trigger. For example, set this to 100 to play the wav file with the 100_ prefix.
 
-**gp#&#95;volume:** The default volume for the track. Valid ranges are `0` to `-59`, with `0` being the loudest and `-59` being the most quiet. The default is `0`.
+**[gpstartrackvolume]:** The default volume for the individual track playback. Valid ranges are 0 to -59, with 0 being the loudest and -59 being the most quiet. The default is 0.
 
 ## Links
 

library.json

@@ -1,6 +1,6 @@
 {
     "name": "GPStar Audio Serial Library",
-    "version": "1.2.0",
+    "version": "1.2.1",
     "description": "A serial communication control library for the GPStar Audio and GPStar Audio XL series of audio boards from GPStar Technologies.",
     "keywords": "audio, serial, music, wav",
     "authors":
@@ -25,4 +25,4 @@
     "frameworks": "arduino",
     "platforms": "*",
     "examples": "examples/*/*.ino"
-  }
+  }

library.properties

@@ -1,5 +1,5 @@
 name=GPStar Audio Serial Library
-version=1.2.0
+version=1.2.1
 author=Michael Rajotte
 license=GPL-3.0-or-later
 maintainer=Michael Rajotte <michael.rajotte@gpstartechnologies.com>
@@ -8,4 +8,4 @@ paragraph=A serial communication control library for the GPStar Audio and GPStar
 category=Device Control
 architectures=*
 url=https://github.com/gpstar81/GPStarAudio-Serial-Library
-includes=GPStarAudio.h
+includes=GPStarAudio.h