Merge pull request letscontrolit#4802 from tonhuisman/feature/RTTTL-e…

…nable-async-play-and-improvements

[RTTTL] Add Async play and other improvements

docs/source/Plugin/P000_Buzzer_RTTTL.rst

@@ -57,7 +57,7 @@ From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipe
 
 .. code-block:: none
 
-   http://<ESP IP address>/control?cmd=rtttl,14:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
+   http://<ESP IP address>/control?cmd=rtttl,14,:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
 
 This plays a melody on pin 14.
 
@@ -68,7 +68,7 @@ To make a boot-sound on startup, create a rule like this:
 .. code-block:: none
 
    On System#Boot do
-     rtttl,14:d=10,o=6,b=180,c,e,g
+     rtttl,14,:d=10,o=6,b=180,c,e,g
    endon
 
 `A place to find more tunes <http://www.picaxe.com/RTTTL-Ringtones-for-Tune-Command/>`_, all saved as txt files.

docs/source/Plugin/P000_Piezo_element_RTTTL.rst

@@ -54,7 +54,7 @@ From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipe
 
 .. code-block:: none
 
-   http://<ESP IP address>/control?cmd=rtttl,14:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
+   http://<ESP IP address>/control?cmd=rtttl,14,:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
 
 This plays a melody on pin 14.
 
@@ -65,7 +65,7 @@ To make a boot-sound on startup, create a rule like this:
 .. code-block:: none
 
    On System#Boot do
-     rtttl,14:d=10,o=6,b=180,c,e,g
+     rtttl,14,:d=10,o=6,b=180,c,e,g
    endon
 
 `A place to find more tunes <http://www.picaxe.com/RTTTL-Ringtones-for-Tune-Command/>`_, all saved as txt files.

docs/source/Plugin/P000_Speaker_RTTTL.rst

@@ -54,7 +54,7 @@ From ESP Easy v2.0.0 its possible to play melodies via `RTTTL <https://en.wikipe
 
 .. code-block:: none
 
-   http://<ESP IP address>/control?cmd=rtttl,14:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
+   http://<ESP IP address>/control?cmd=rtttl,14,:d=4,o=5,b=112:8a,8a,a,8a,8a,a,8a,8c6,8f.,16g,2a,8a-,8a-,8a-.,16a-,8a-,8a,8a.,16a,8a,8g,8g,8a,g,c6
 
 This plays a melody on pin 14.
 
@@ -65,7 +65,7 @@ To make a boot-sound on startup, create a rule like this:
 .. code-block:: none
 
    On System#Boot do
-     rtttl,14:d=10,o=6,b=180,c,e,g
+     rtttl,14,:d=10,o=6,b=180,c,e,g
    endon
 
 `A place to find more tunes <http://www.picaxe.com/RTTTL-Ringtones-for-Tune-Command/>`_, all saved as txt files.

docs/source/Plugin/P001_commands_RTTTL.repl

@@ -43,4 +43,10 @@ Supported hardware: |P000_usedby_RTTTL| (Ringtones etc.)
   ``rtttl,14,test:d=8,o=5,b=180,c6,b,c6,p,g,g-``
 
   `More RTTTL Ringtone Downloads <http://www.picaxe.com/RTTTL-Ringtones-for-Tune-Command/>`_
+
+  Since 2023-09-15:
+
+  The ``rtttl`` command, by default, now uses the `AnyRtttl library <https://github.com/end2endzone/AnyRtttl>`_, allowing asynchronous handling of the command. This has the advantage of being non-blocking, allowing ESPEasy to handle other tasks while the tune is being played, but comes with the disadvantage of the output possibly being interrupted/delayed by other (possibly blocking) tasks and events, so the music may not play continuously.
+
+  Also, the previous implementation may not have stopped sound correctly after playing a song, but as this has been corrected, so there is no longer a need to turn off the GPIO after playing a song.
   "

lib/AnyRtttl/AUTHORS

@@ -0,0 +1,5 @@
+# This file contains a list of people who've made contribution to 
+# the project.  People who commit code are encouraged to add 
+# their names here.  Please keep the list sorted by first names.
+
+Antoine Beauchamp <[email protected]>

lib/AnyRtttl/CHANGES

@@ -0,0 +1,32 @@
+Changes for 2.3
+
+* Fixed issue #2 - Support for PROGMEM / FLASH melodies in non-blocking mode.
+
+
+Changes for 2.2.1:
+
+* Fixed issue #4: error compiling example code.
+* Fixed issue #5: Refactor build process to use Arduino CLI instead of Arduino IDE.
+
+
+Changes for 2.2.0:
+
+* New feature: Build option `ANYRTTTL_BUILD_EXAMPLES` to enable/disable building AnyRtttl examples.
+* New feature: Changed file/folder structure to be compatible with Arduino Library Manager.
+* New feature: Using RapidAssist 0.5.0 and win32Arduino 2.3.1.
+
+
+Changes for 2.1.229:
+
+* New feature: Implemented support for RTTTL in Program Memory (PROGMEM).
+
+
+Changes for 2.0.179:
+
+* Library converted to AnyRtttl.
+* First github release.
+* Code originally release at http://www.end2endzone.com/anyrtttl-a-feature-rich-arduino-library-for-playing-rtttl-melodies/
+
+
+Changes for 1.0.0:
+* Initial release of NonBlockingRtttl.

lib/AnyRtttl/CMakeLists.txt

@@ -0,0 +1,160 @@
+cmake_minimum_required(VERSION 3.4.3)
+project(AnyRtttl)
+
+# Set the output folder where your program will be created
+set(EXECUTABLE_OUTPUT_PATH ${CMAKE_BINARY_DIR}/bin)
+set(   LIBRARY_OUTPUT_PATH ${CMAKE_BINARY_DIR}/bin)
+
+##############################################################################################################################################
+# Functions
+##############################################################################################################################################
+function(GIT_EXTERNAL DIR REPO_URL TAG)
+  # Find the name of the repository
+  get_filename_component(REPO_NAME ${REPO_URL} NAME_WE)
+
+  # Compute output directory
+  set(REPO_DIR "${DIR}/${REPO_NAME}")
+
+  if (EXISTS "${REPO_DIR}")
+    message(STATUS "Repository ${REPO_NAME} already exists in directory ${DIR}. Skipping git clone command.")
+    return()
+  endif()
+
+  # Clone the repository
+  message(STATUS "git clone ${REPO_URL} ${REPO_DIR}")
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" clone ${REPO_URL} ${REPO_DIR}
+    RESULT_VARIABLE returncode ERROR_VARIABLE error
+    WORKING_DIRECTORY "${DIR}")
+  if(returncode)
+    message(FATAL_ERROR "Clone failed: ${error}\n")
+  endif()
+  message(STATUS "git clone completed")
+
+  # Checking out the required tag
+  message(STATUS "git checkout ${TAG}")
+  execute_process(
+    COMMAND "${GIT_EXECUTABLE}" checkout ${TAG}
+    RESULT_VARIABLE returncode ERROR_VARIABLE error
+    WORKING_DIRECTORY "${REPO_DIR}")
+  if(returncode)
+    message(FATAL_ERROR "Checkout failed: ${error}\n")
+  endif()
+  message(STATUS "git checkout completed")
+
+  # Delete the .git folder to simulate an export of the repository
+  message(STATUS "Deleting ${REPO_DIR}/.git")
+  file(REMOVE_RECURSE "${REPO_DIR}/.git")
+
+endfunction()
+
+function(add_example name)
+  # Create custom example.cpp file which includes the ino sketch file.
+  SET(SOURCE_INO_FILE "${PROJECT_SOURCE_DIR}/examples/${name}/${name}.ino")
+  CONFIGURE_FILE("${CMAKE_CURRENT_SOURCE_DIR}/examples.cpp.in" "${PROJECT_BINARY_DIR}/${name}/examples.cpp")
+
+  add_executable(${name}
+    ${ARDUINO_LIBRARY_SOURCE_FILES}
+    ${SOURCE_INO_FILE}
+    "${PROJECT_BINARY_DIR}/${name}/examples.cpp"
+  )
+
+  target_include_directories(${name} PRIVATE ${PROJECT_SOURCE_DIR}/src ${BITREADER_SOURCE_DIR} win32arduino )
+  target_link_libraries(${name} PRIVATE win32arduino rapidassist)
+
+  set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+  set_target_properties(${name} PROPERTIES FOLDER "examples")
+
+  if(WIN32)
+    # 1>C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\include\ostream(743,1): warning C4530: C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc
+    # 1>D:\dev\AnyRtttl\master\third_parties\win32Arduino\install\include\win32arduino-2.4.0\SerialPrinter.h(202): message : see reference to function template instantiation 'std::basic_ostream<char,std::char_traits<char>> &std::operator <<<std::char_traits<char>>(std::basic_ostream<char,std::char_traits<char>> &,const char *)' being compiled
+    set_target_properties(${name} PROPERTIES COMPILE_FLAGS "/wd4530")
+  endif()
+
+endfunction()
+
+##############################################################################################################################################
+# Dependencies
+##############################################################################################################################################
+find_package(GTest REQUIRED)
+find_package(rapidassist 0.5.0 REQUIRED)
+find_package(win32arduino 2.3.1 REQUIRED)
+find_package(Git REQUIRED)
+
+# Arduino BitReader library dependency
+file(MAKE_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/external")
+GIT_EXTERNAL("${CMAKE_CURRENT_SOURCE_DIR}/external" "http://github.com/end2endzone/BitReader.git" "1.3.0")
+set(BITREADER_SOURCE_DIR "${PROJECT_SOURCE_DIR}/external/BitReader/src")
+
+##############################################################################################################################################
+# Project settings
+##############################################################################################################################################
+
+# Build options
+option(ANYRTTTL_BUILD_EXAMPLES "Build all example projects" OFF)
+
+# Prevents annoying warnings on MSVC
+if (WIN32)
+  add_definitions(-D_CRT_SECURE_NO_WARNINGS)
+endif()
+
+# Find all library source and unit test files
+file( GLOB ARDUINO_LIBRARY_SOURCE_FILES ${PROJECT_SOURCE_DIR}/src/*.cpp   ${PROJECT_SOURCE_DIR}/src/*.h   ${BITREADER_SOURCE_DIR}/*.cpp  ${BITREADER_SOURCE_DIR}/*.h)
+file( GLOB ARDUINO_LIBRARY_TEST_FILES   ${PROJECT_SOURCE_DIR}/test/*.cpp  ${PROJECT_SOURCE_DIR}/test/*.h )
+
+# Create unit test executable
+add_executable(anyrtttl_unittest
+  ${ARDUINO_LIBRARY_SOURCE_FILES}
+  ${ARDUINO_LIBRARY_TEST_FILES}
+)
+
+#include directories
+target_include_directories(anyrtttl_unittest
+  PRIVATE ${PROJECT_SOURCE_DIR}/src       # Arduino Library folder
+  ${GTEST_INCLUDE_DIR}
+  ${BITREADER_SOURCE_DIR}
+  win32arduino
+)
+
+# Unit test projects requires to link with pthread if also linking with gtest
+if(NOT WIN32)
+  set(PTHREAD_LIBRARIES -pthread)
+endif()
+
+#link libraries
+target_link_libraries(anyrtttl_unittest PRIVATE win32arduino rapidassist ${PTHREAD_LIBRARIES} ${GTEST_LIBRARIES} )
+
+if(WIN32)
+  # 1>C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Tools\MSVC\14.29.30133\include\ostream(743,1): warning C4530: C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc
+  # 1>D:\dev\AnyRtttl\master\third_parties\win32Arduino\install\include\win32arduino-2.4.0\SerialPrinter.h(202): message : see reference to function template instantiation 'std::basic_ostream<char,std::char_traits<char>> &std::operator <<<std::char_traits<char>>(std::basic_ostream<char,std::char_traits<char>> &,const char *)' being compiled
+  set_target_properties(anyrtttl_unittest PROPERTIES COMPILE_FLAGS "/wd4530")
+endif()
+
+# Copy `expected_call_stack.log` to expected locations
+configure_file(${PROJECT_SOURCE_DIR}/test/expected_call_stack.log ${PROJECT_BINARY_DIR}/expected_call_stack.log COPYONLY)
+set(TEST_FILES_BINARY_DIR ${EXECUTABLE_OUTPUT_PATH})
+if(WIN32)
+  set(TEST_FILES_BINARY_DIR ${TEST_FILES_BINARY_DIR}/${CMAKE_CFG_INTDIR})
+endif()
+add_custom_command(
+        TARGET anyrtttl_unittest POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy
+                ${PROJECT_SOURCE_DIR}/test/expected_call_stack.log
+                ${TEST_FILES_BINARY_DIR}/expected_call_stack.log)
+
+##############################################################################################################################################
+# Add all samples to the project unless the user has specified otherwise.
+##############################################################################################################################################
+if(ANYRTTTL_BUILD_EXAMPLES)
+  add_example("Basic")
+  add_example("BlockingProgramMemoryRtttl")
+  add_example("BlockingRtttl")
+  add_example("BlockingWithNonBlocking")
+  add_example("NonBlockingProgramMemoryRtttl")
+  add_example("NonBlockingRtttl")
+  add_example("NonBlockingStopBeforeEnd")
+  add_example("Play10Bits")
+  add_example("Play16Bits")
+  add_example("Rtttl2Code")
+endif()
+

lib/AnyRtttl/INSTALL.md

@@ -0,0 +1,105 @@
+# Install #
+
+The library can be found, installed, or updated from the Arduino IDE using the official Arduino Library Manager (available from IDE version 1.6.2).
+
+
+The library can be installed on the system by following the same steps as with other Arduino library.
+
+Refer to [Installing Additional Arduino Libraries](https://www.arduino.cc/en/Guide/Libraries) tutorial for details on how to install a third party library.
+
+
+
+
+# Dependencies #
+
+The AnyRtttl library have no dependencies on other Arduino library. However, some examples of the library requires external dependencies.
+
+The following Arduino Library must be installed on the system to use the library examples:
+
+* [BitReader v1.3.0](https://github.com/end2endzone/BitReader/tree/1.3.0)
+
+
+
+
+# Build #
+
+The library unit tests can be build on Windows/Linux platform to maintain the product stability and level of quality.
+
+This section explains how to compile and build the software and how to get a test environment ready.
+
+
+
+## Prerequisites ##
+
+
+
+### Software Requirements ###
+
+The following software must be installed on the system before compiling unit test source code:
+
+* [Google C++ Testing Framework v1.8.0](https://github.com/google/googletest/tree/release-1.8.0)
+* [RapidAssist v0.5.0](https://github.com/end2endzone/RapidAssist/tree/0.5.0)
+* [win32Arduino v2.3.1](https://github.com/end2endzone/win32Arduino/tree/2.3.1)
+* [CMake](http://www.cmake.org/) v3.4.3 (or newer)
+
+
+
+### Linux Requirements ###
+
+These are the base requirements to build source code:
+
+  * GNU-compatible Make or gmake
+  * POSIX-standard shell
+  * A C++98-standard-compliant compiler
+
+
+
+### Windows Requirements ###
+
+* Microsoft Visual C++ 2010 or newer
+
+
+
+## Build steps ##
+
+The AnyRtttl unit test uses the CMake build system to generate a platform-specific build environment. CMake reads the CMakeLists.txt files, checks for installed dependencies and then generates files for the selected build system.
+
+The following steps show how to build the library:
+
+1) Download the source code from an existing [tags](https://github.com/end2endzone/AnyRtttl/tags) and extract the content to a local directory (for example `c:\projects\AnyRtttl` or `~/dev/AnyRtttl`).
+
+2) Open a Command Prompt (Windows) or Terminal (Linux) and browse to the project directory.
+
+3) Enter the following commands to generate the project files for your build system:
+```
+mkdir build
+cd build
+cmake ..
+```
+
+4) Build the source code.
+
+**Windows**
+```
+cmake --build . --config Release
+```
+
+**Linux**
+```
+make
+```
+
+
+
+
+# Testing #
+
+AnyRtttl comes with unit tests which help maintaining the product stability and level of quality.
+
+Test are build using the Google Test v1.8.0 framework. For more information on how googletest is working, see the [google test documentation primer](https://github.com/google/googletest/blob/release-1.8.0/googletest/docs/V1_6_Primer.md).  
+
+To run tests, open a shell prompt and browse to the `build/bin` folder and run `anyrtttl_unittest` executable. For Windows users, the executable is located in `build\bin\Release`.
+
+Test results are saved in junit format in file `anyrtttl_unittest.release.xml`.
+
+The latest test results are available at the beginning of the [README.md](README.md) file.

lib/AnyRtttl/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Antoine Beauchamp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.