diff --git a/wavTrigger.cpp b/wavTrigger.cpp index d16cac4..622f808 100644 --- a/wavTrigger.cpp +++ b/wavTrigger.cpp @@ -10,8 +10,12 @@ #include "wavTrigger.h" - -// ************************************************************** +//**************************************************************************/ +/*! + @brief Call this method to initialize the serial communications. Baud + rate 57600. +*/ +/**************************************************************************/ void wavTrigger::start(void) { uint8_t txbuf[5]; @@ -38,7 +42,47 @@ uint8_t txbuf[5]; WTSerial.write(txbuf, 5); } -// ************************************************************** +//**************************************************************************/ +/*! + @brief Call this method to initialize the serial communications. + @param baud Serial baud rate, 57600 works well. + @param config Serial port address + @param rxPin RX Serial Pin + @param txPin TX Serial Pin +*/ +/**************************************************************************/ +void wavTrigger::start(unsigned long baud, uint32_t config, int8_t rxPin, int8_t txPin) { + +uint8_t txbuf[5]; + + versionRcvd = false; + sysinfoRcvd = false; + WTSerial.begin(baud, config, rxPin, txPin); + flush(); + + // Request version string + txbuf[0] = SOM1; + txbuf[1] = SOM2; + txbuf[2] = 0x05; + txbuf[3] = CMD_GET_VERSION; + txbuf[4] = EOM; + WTSerial.write(txbuf, 5); + + // Request system info + txbuf[0] = SOM1; + txbuf[1] = SOM2; + txbuf[2] = 0x05; + txbuf[3] = CMD_GET_SYS_INFO; + txbuf[4] = EOM; + WTSerial.write(txbuf, 5); +} + +/**************************************************************************/ +/*! + @brief Clears the WAV Trigger communication buffer and resets the + local track status info. +*/ +/**************************************************************************/ void wavTrigger::flush(void) { int i; @@ -55,7 +99,13 @@ uint8_t dat; } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Should be called periodically when reporting is enabled. Doing + so will process any incoming serial messages and keep the track status + up to date. +*/ +/**************************************************************************/ void wavTrigger::update(void) { int i; @@ -160,7 +210,14 @@ uint16_t track; } // while (WTSerial.available() > 0) } -// ************************************************************** +/**************************************************************************/ +/*! + @brief If reporting has been enabled, this function can be used to + determine if a particular track is currently playing. + @param trk Track number. + @returns True or False. +*/ +/**************************************************************************/ bool wavTrigger::isTrackPlaying(int trk) { int i; @@ -174,7 +231,15 @@ bool fResult = false; return fResult; } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Sets the gain of the final output stage to the specified value. + The range for gain is -70 to +4. If audio is playing, you will hear the + result immediately. If audio is not playing, the new gain will be used + the next time a track is started. + @param gain Set volume, -70 to +4. +*/ +/**************************************************************************/ void wavTrigger::masterGain(int gain) { uint8_t txbuf[7]; @@ -191,7 +256,14 @@ unsigned short vol; WTSerial.write(txbuf, 7); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Enable / disable the on-board amplifier. If you’re planning to + use the on-board amplifier, read this first. + http://robertsonics.com/2015/05/16/update-on-wav-trigger-hardware-versions/ + @param enable True or False. +*/ +/**************************************************************************/ void wavTrigger::setAmpPwr(bool enable) { uint8_t txbuf[6]; @@ -205,7 +277,16 @@ uint8_t txbuf[6]; WTSerial.write(txbuf, 6); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Enables / disables track reporting. When enabled, the WAV + Trigger will send a message whenever a track starts or ends, specifying + the track number. Provided you call update() periodically, the library + will use these messages to maintain status of all tracks, allowing you + to query if particular tracks are playing or not. + @param enable True or False. +*/ +/**************************************************************************/ void wavTrigger::setReporting(bool enable) { uint8_t txbuf[6]; @@ -219,7 +300,15 @@ uint8_t txbuf[6]; WTSerial.write(txbuf, 6); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Gets WAV Trigger version string. Requires bi-directional + communication with the WAV Trigger. + @param pDst Pointer to a version string. + @param len Lenght of the version string. Use VERSION_STRING_LEN + @returns TRUE successful, and FALSE not available. +*/ +/**************************************************************************/ bool wavTrigger::getVersion(char *pDst, int len) { int i; @@ -237,68 +326,149 @@ int i; return true; } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Gets number of tracks on the WAV Trigger's microSD card. + Requires bi-directional communication with the WAV Trigger. + @returns Number of tracks available. +*/ +/**************************************************************************/ int wavTrigger::getNumTracks(void) { update(); return numTracks; } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Stops any and all tracks that are currently playing and starts + track number from the beginning. + @param trk Track number. +*/ +/**************************************************************************/ void wavTrigger::trackPlaySolo(int trk) { trackControl(trk, TRK_PLAY_SOLO); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Stops any and all tracks that are currently playing and starts + track number from the beginning. + @param trk Track number. + @param lock Lock, True or False +*/ +/**************************************************************************/ void wavTrigger::trackPlaySolo(int trk, bool lock) { trackControl(trk, TRK_PLAY_SOLO, lock); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Starts track number from the beginning, blending it with any + other tracks that are currently playing, including potentially another + copy of the same track. + @param trk Track number. +*/ +/**************************************************************************/ void wavTrigger::trackPlayPoly(int trk) { trackControl(trk, TRK_PLAY_POLY); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Starts track number from the beginning, blending it with any + other tracks that are currently playing, including potentially another + copy of the same track. + @param trk Track number. + @param lock Lock, True or False +*/ +/**************************************************************************/ void wavTrigger::trackPlayPoly(int trk, bool lock) { trackControl(trk, TRK_PLAY_POLY, lock); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Loads track number and pauses it at the beginning of the track. + Loading muiltiple tracks and then un-pausing them with resumeAllInSync() + function allows for starting multiple tracks in sample sync. + @param trk Track number. +*/ +/**************************************************************************/ void wavTrigger::trackLoad(int trk) { trackControl(trk, TRK_LOAD); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Loads track number and pauses it at the beginning of the track. + Loading muiltiple tracks and then un-pausing them with resumeAllInSync() + function allows for starting multiple tracks in sample sync. + @param trk Track number. + @param lock Lock, True or False +*/ +/**************************************************************************/ void wavTrigger::trackLoad(int trk, bool lock) { trackControl(trk, TRK_LOAD, lock); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Stops track number if it's currently playing. If track is not + playing, this function does nothing. No other tracks are affected. + @param trk Track number. +*/ +/**************************************************************************/ void wavTrigger::trackStop(int trk) { trackControl(trk, TRK_STOP); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Pauses track number if it's currently playing. If track is not + playing, this function does nothing. A paused track is still using one + of the 8 voice slots. A voice allocated to playing a track becomes + free only when that track is stopped or the track reaches the end of + the file (and is not looping). + @param trk Track number. +*/ +/**************************************************************************/ void wavTrigger::trackPause(int trk) { trackControl(trk, TRK_PAUSE); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Resumes track number t if it's currently paused. If track number + is not paused, this function does nothing. + @param trk Track number. +*/ +/**************************************************************************/ void wavTrigger::trackResume(int trk) { trackControl(trk, TRK_RESUME); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Enables or disables the loop flag for track. This command does + not start a track, only determines how it behaves once it is playing + and reaches the end. If the loop flag is set, that track will loop + continuously until it's stopped, in which case it will stop immediately + but the loop flag will remain set, or until the loop flag is cleared, + in which case it will stop when it reaches the end of the track. + @param trk Track number. + @param enable Enable True, disable False. +*/ +/**************************************************************************/ void wavTrigger::trackLoop(int trk, bool enable) { if (enable) @@ -340,7 +510,11 @@ uint8_t txbuf[9]; WTSerial.write(txbuf, 9); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Stops any and all tracks that are currently playing. +*/ +/**************************************************************************/ void wavTrigger::stopAllTracks(void) { uint8_t txbuf[5]; @@ -353,7 +527,13 @@ uint8_t txbuf[5]; WTSerial.write(txbuf, 5); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Resumes all paused tracks within the same audio buffer. Any + tracks that were loaded using the trackLoad() function will start and + remain sample locked (in sample sync) with one another. +*/ +/**************************************************************************/ void wavTrigger::resumeAllInSync(void) { uint8_t txbuf[5]; @@ -366,7 +546,24 @@ uint8_t txbuf[5]; WTSerial.write(txbuf, 5); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Sets the gain of track to the specified value. A value of + 0 (no gain) plays the track at the nominal value in the wav file. + This is the default gain for every track until changed. A value of + -70 is completely muted. If the track is playing, you will hear the + result immediately. If the track is not playing, the gain will be + used the next time the track is started. Every track can have its + own gain. + Because the effect is immediate, large changes can produce ubrupt + results. If you want to fade in or fade out a track, send small + changes spaced out at regular intervals. Increment or decrementing + by 1 every 20 to 50 msecs produces nice smooth fades. Better yet, + usetrackFade() and trackCrossFade() commands. + @param trk Track number. + @param gain Volume target, -70 to +10. +*/ +/**************************************************************************/ void wavTrigger::trackGain(int trk, int gain) { uint8_t txbuf[9]; @@ -385,7 +582,18 @@ unsigned short vol; WTSerial.write(txbuf, 9); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Hardware volume fade on track number if it is currently playing. + The track volume will transition smoothly from the current value to the + target gain in the specified number of milliseconds. + @param trk Track number. + @param gain Volume target. + @param time Fade time in milliseconds. + @param stopFlag If the stopFlag is non-zero, the track will be stopped at + the completion of the fade (for fade-outs.) +*/ +/**************************************************************************/ void wavTrigger::trackFade(int trk, int gain, int time, bool stopFlag) { uint8_t txbuf[12]; @@ -407,7 +615,16 @@ unsigned short vol; WTSerial.write(txbuf, 12); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Sets sample-rate offset, or playback speed / pitch, of the main + output mix. Offset gives 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. + @param offset Offset, -32767 to +32676. +*/ +/**************************************************************************/ void wavTrigger::samplerateOffset(int offset) { uint8_t txbuf[7]; @@ -424,7 +641,12 @@ unsigned short off; WTSerial.write(txbuf, 7); } -// ************************************************************** +/**************************************************************************/ +/*! + @brief Immediately sets the Trigger Bank to the specified value. + @param bank Bank value 1 to 32. +*/ +/**************************************************************************/ void wavTrigger::setTriggerBank(int bank) { uint8_t txbuf[6]; @@ -436,6 +658,4 @@ uint8_t txbuf[6]; txbuf[4] = (uint8_t)bank; txbuf[5] = EOM; WTSerial.write(txbuf, 6); -} - - +} \ No newline at end of file diff --git a/wavTrigger.h b/wavTrigger.h index a89ca72..3e656aa 100644 --- a/wavTrigger.h +++ b/wavTrigger.h @@ -34,8 +34,8 @@ // The following defines are used to control which serial class is // used. Uncomment only the one you wish to use. If all of them are // commented out, the library will use Hardware Serial -#define __WT_USE_ALTSOFTSERIAL__ -//#define __WT_USE_SERIAL1__ +//#define __WT_USE_ALTSOFTSERIAL__ +#define __WT_USE_SERIAL1__ //#define __WT_USE_SERIAL2__ //#define __WT_USE_SERIAL3__ // ================================================================== @@ -104,6 +104,7 @@ class wavTrigger wavTrigger() {;} ~wavTrigger() {;} void start(void); + void start(unsigned long baud, uint32_t config, int8_t rxPin, int8_t txPin); void update(void); void flush(void); void setReporting(bool enable);