Merge pull request #4833 from tonhuisman/feature/RTTTL-documentation-…

…update-and-restore-cancelled-event [RTTTL] Restore Cancelled event, update documentation
letscontrolit · Sep 28, 2023 · 8b76e3e · 8b76e3e
2 parents bcc555e + d8cb848
commit 8b76e3e
Show file tree

Hide file tree

Showing 5 changed files with 83 additions and 17 deletions.
diff --git a/docs/source/Plugin/P000.rst b/docs/source/Plugin/P000.rst
@@ -27,6 +27,21 @@ Supported hardware
 
 |P000_usedby_GPIO|, |P000_usedby_RTTTL|, |P000_usedby_Relay|, |P000_usedby_Servo|, |P000_usedby_LevelConverter|
 
+Switch: :ref:`P001_Switch_page`
+
+Doorswitch: :ref:`P001_Door_switch_page`
+
+Relay: :ref:`P000_Relay_page`
+
+PIR: :ref:`P001_PIR_sensor_page`
+
+Servo: :ref:`P000_Servo_motor_page`
+
+Buzzer: :ref:`P000_Buzzer_page`
+
+Speaker RTTTL: :ref:`P000_Speaker_page`
+
+Piezo element: :ref:`P000_Piezo_element_page`
 
 Commands available
 ------------------

diff --git a/docs/source/Plugin/P000_Buzzer_RTTTL.rst b/docs/source/Plugin/P000_Buzzer_RTTTL.rst
@@ -91,6 +91,11 @@ Commands
 
 .. include:: P001_commands_RTTTL.repl
 
+Events
+------
+
+.. include:: P001_events_RTTTL.repl
+
 Where to buy
 ------------
 

diff --git a/docs/source/Plugin/P001_events_RTTTL.repl b/docs/source/Plugin/P001_events_RTTTL.repl
@@ -0,0 +1,41 @@
+.. csv-table::
+   :header: "Event", "Example"
+   :widths: 30, 20
+
+   "
+   ``RTTTL#Started``
+   Event generated when a melody/song is played using the Async RTTTL method.
+   ","
+
+   .. code-block:: none
+
+        on RTTTL#Started do
+         GPIO,13,1 // Turn on LED while playing a song
+        endon
+
+   "
+   "
+   ``RTTTL#Finished``
+   Event generated when the playback of a melody/song is finished using the Async RTTTL method.
+   ","
+
+   .. code-block:: none
+
+        on RTTTL#Finished do
+         GPIO,13,0 // Turn off LED after playing a song
+         event,nextSong // Select the next song to play
+        endon
+
+   "
+   "
+   ``RTTTL#Cancelled``
+   Event generated when the currently playing melody/song is cancelled by starting a new song using the Async RTTTL method.
+   ","
+
+   .. code-block:: none
+
+        on RTTTL#Cancelled do
+         GPIO,13,0 // Turn off LED
+        endon
+
+   "
diff --git a/docs/source/Reference/Events.rst b/docs/source/Reference/Events.rst
@@ -14,6 +14,12 @@ Plugin based events
 
 Besides the internal events there's also plugin specific events. These are listed here below.
 
+P000 (core) :ref:`P000_Buzzer_page`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: ../Plugin/P001_events_RTTTL.repl
+
+
 .. P001 :ref:`P001_page`
 .. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/src/src/Helpers/Audio.cpp b/src/src/Helpers/Audio.cpp
@@ -39,7 +39,18 @@ static String rtttlMelody;
 void clear_rtttl_melody() {
   // The non-blocking play will read from a char pointer.
   // So we must stop the playing before changing the string as it could otherwise lead to a crash.
-  anyrtttl::nonblocking::stop();
+  if (anyrtttl::nonblocking::isPlaying()) { // If currently playing, cancel that
+    addLog(LOG_LEVEL_INFO, F("RTTTL: Cancelling running song..."));
+    anyrtttl::nonblocking::stop();
+    #   if FEATURE_RTTTL_EVENTS
+
+    if (Settings.UseRules) {
+      eventQueue.add(F("RTTTL#Cancelled"));
+    }
+    rtttlPlaying = false;
+    #   endif // if FEATURE_RTTTL_EVENTS
+  }
+
   rtttlMelody = String();
 }
 
@@ -63,18 +74,6 @@ bool play_rtttl(int8_t _pin, const char *p) {
   anyrtttl::setNoToneFunction(&setInternalGPIOPullupMode);
   #  if FEATURE_ANYRTTTL_ASYNC
 
-  if (anyrtttl::nonblocking::isPlaying()) { // If currently playing, cancel that
-    addLog(LOG_LEVEL_INFO, F("RTTTL: Cancelling running song..."));
-    anyrtttl::nonblocking::stop();
-    #   if FEATURE_RTTTL_EVENTS
-
-    if (Settings.UseRules) {
-      eventQueue.add(F("RTTTL#Cancelled"));
-    }
-    rtttlPlaying = false;
-    #   endif // if FEATURE_RTTTL_EVENTS
-  }
-
   if (!rtttlMelody.isEmpty()) {
     anyrtttl::nonblocking::begin(_pin, rtttlMelody.c_str());
   } else {
@@ -130,10 +129,10 @@ bool play_rtttl(int8_t _pin, const char *p)
   // FIXME: Absolutely no error checking in here
 
   const int notes[] = { 0,
-                        262, 277,   294,   311,  330,   349,  370,  392,  415,  440,  466,  494,
-                        523, 554,   587,   622,  659,   698,  740,  784,  831,  880,  932,  988,
-                        1047,1109,  1175,  1245, 1319,  1397, 1480, 1568, 1661, 1760, 1865, 1976,
-                        2093,2217,  2349,  2489, 2637,  2794, 2960, 3136, 3322, 3520, 3729, 3951
+                        262, 277,   294,   311,   330,  349,   370,  392,  415,  440,  466,  494,
+                        523, 554,   587,   622,   659,  698,   740,  784,  831,  880,  932,  988,
+                        1047,1109,  1175,  1245,  1319, 1397,  1480, 1568, 1661, 1760, 1865, 1976,
+                        2093,2217,  2349,  2489,  2637, 2794,  2960, 3136, 3322, 3520, 3729, 3951
   };