From 35f09681fbe5dd936011adc342d31ae562ef07f5 Mon Sep 17 00:00:00 2001 From: thejobbitt Date: Mon, 29 Aug 2022 11:00:11 -0400 Subject: [PATCH 1/2] Added Documentation Blocks --- wavTrigger.cpp | 249 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 219 insertions(+), 30 deletions(-) diff --git a/wavTrigger.cpp b/wavTrigger.cpp index d16cac4..b3fc100 100644 --- a/wavTrigger.cpp +++ b/wavTrigger.cpp @@ -11,14 +11,22 @@ #include "wavTrigger.h" -// ************************************************************** -void wavTrigger::start(void) { +//**************************************************************************/ +/*! + @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(57600); + WTSerial.begin(baud, config, rxPin, txPin); flush(); // Request version string @@ -38,7 +46,12 @@ uint8_t txbuf[5]; 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 +68,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 +179,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 +200,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 +225,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 +246,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 +269,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 +295,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 +479,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 +496,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 +515,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 +551,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 +584,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 +610,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 +627,4 @@ uint8_t txbuf[6]; txbuf[4] = (uint8_t)bank; txbuf[5] = EOM; WTSerial.write(txbuf, 6); -} - - +} \ No newline at end of file From 65e3f43c57786b2eb61b58a415e6fe5d0799c28d Mon Sep 17 00:00:00 2001 From: thejobbitt Date: Mon, 29 Aug 2022 11:47:04 -0400 Subject: [PATCH 2/2] Docu Blocks and Override --- wavTrigger.cpp | 37 ++++++++++++++++++++++++++++++++++--- wavTrigger.h | 5 +++-- 2 files changed, 37 insertions(+), 5 deletions(-) diff --git a/wavTrigger.cpp b/wavTrigger.cpp index b3fc100..622f808 100644 --- a/wavTrigger.cpp +++ b/wavTrigger.cpp @@ -10,10 +10,41 @@ #include "wavTrigger.h" +//**************************************************************************/ +/*! + @brief Call this method to initialize the serial communications. Baud + rate 57600. +*/ +/**************************************************************************/ +void wavTrigger::start(void) { + +uint8_t txbuf[5]; + + versionRcvd = false; + sysinfoRcvd = false; + WTSerial.begin(57600); + 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 Call this method to initialize the serial communications. + @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 @@ -48,7 +79,7 @@ uint8_t txbuf[5]; /**************************************************************************/ /*! - @brief Clears the WAV Trigger communication buffer and resets the + @brief Clears the WAV Trigger communication buffer and resets the local track status info. */ /**************************************************************************/ @@ -70,7 +101,7 @@ uint8_t dat; /**************************************************************************/ /*! - @brief Should be called periodically when reporting is enabled. Doing + @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. */ 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);