Improve Sound

Firmware/LowLevel/README-Sound, DFPIS5V.md

@@ -0,0 +1,92 @@
+# Sound via "DFPlayer Mini"
+
+> [!IMPORTANT]  
+> Owner of mainboard version 0.13.x need to check if the required R7 and R13
+> resistors got assembled.<br>
+> They're located on the top side of the PCB, underneath the DFPlayer.<br>
+> If not assembled, you need to solder 1k resistors (otherwise all sounds get played continuously)
+
+> [!IMPORTANT]  
+> <a href="../../img/dfplayer-clone_cut-pin.png"><img src="../../img/dfplayer-clone_cut-pin.png" title="Cut-off Pin-11 if DFP-Clone and MoBo <= 0.13.x" width="25%" align="right"></a>
+> Users who use any of the DFPlayer-Clones,<br>
+> in an open-mower-mainboard up to version 0.13.x,<br>
+> should cut off Pin-11 from their DFPlayer-Clone.<br>
+> If not, volume control will not work and always play at 100%!<br><br>
+
+> [!WARNING]
+> Consider about switching your DFPlayer's VCC from 3.3V to 5V
+> (via solder jumper JP1 on your OpenMower MainBoard)
+
+**Explanation:**<br>
+I'm with sound since June 2023.<br>
+In the first month, I killed 2 Picos because his tiny Buck-Boost Converter "RT6150" cracked.<br>
+After a short correspondence with Clemens, he pointed me to the DFPlayer
+as a possible reason.<br>
+Because: By OM default design, the DFPlayer's VCC is 3.3V (via JP1),
+which is provided by the small Buck-Boost Converter on the Pico.<br>
+After I switched my DFPlayer's VCC to 5V (via JP1), I didn't lost any Pico anymore.<br>
+It's not confirmed yet if that really was the reason for my killed Pico's,
+and you're invited to validate the assumption by leaving your DFPlayer on 3.3V. **But be warned**, even if the Pico is cheap, it's awful to replace it! 
+
+### Update 10/13/2023
+
+As I was still in doubt if it's really necessary to switch DFPlayer's VCC to 5V,
+I did some measuring today:
+
+- Placed an 0.2Ω resistor (4W) within Pico's 3V3 output line
+- Measured with an oscilloscope the occuring voltage over the resistor:<br>
+  0.028 V<sub>AVG</sub> => divided by 0.2Ω = 140mA => looks fine<br>
+  0.195 V<sub>PP</sub> => divided by 0.2Ω = 975mA => hugh :-/ but this is V<sub>PP</sub>!
+- Within the Pico Datasheet it's written (somewhere), thats allowed to draw up to 300mA
+- The specs of the Buck-Boost Converter "RT6150" (used on the Pico) say:<br>
+  "*Up to 800mA Continuous Output Current*", as well as<br>
+  "*... current limit.*"
+
+End of October 2023, I discussed my doubts with Clemens and he answered:
+> The short peaks are also what worries me. The overcurrent protection will probably only take effect in the event of a longer overload. That's how you run it above the spec (even if for a short time) and that potentially breaks it at some point
+
+> [!IMPORTANT]  
+> You may run `OM_DFP_IS_5V=true` (to get full sound support), even if **not** switched to 5V, but we worry that you might kill your Pico's PMIC after some time
+
+## Sound Buttons
+
+| Custom CoverUI V1<br>Stock C500(A/B) | Custom CoverUI V2 | RM-ECOW-V1.0.0<br>(NX80i, ...) | RM-EC3-V1.1<br>(NX100i) | SA/SC-Pro<br>(240*160 Pixel) | Function |
+| ------ | -------- | ---- | ---- | --- | --- |
+| <kbd>Mon</kbd> | <kbd>Sun</kbd> | <kbd>4H</kbd> | <kbd>1</kbd> | <kbd>↑</kbd> | Volume up |
+| <kbd>Tue</kbd> | <kbd>Mon</kbd> | <kbd>6H</kbd> | <kbd>2</kbd> | <kbd>↓</kbd> | Volume down
+
+## DFPlayer Module / Clones
+
+Beside the original [DFPlayer by DFRobot](https://www.dfrobot.com/product-1121.html) module, there are a couple of "DFPlayer-Mini" clones in the wild.
+
+If you order a "DFPlayer-Mini" by Amazon or the like, there's a >90% chance that you get one of these clones, instead of the original one.
+
+That's why I tried to adapt the code in that way, that some of these clones get also supported.
+
+Check the larger chip on the backside of the module, to verify if your DFPlayer is supported. The following DFPlayer chips are supported/tested at the moment:
+
+- `DFROBOT LISP3` is the one on my original [DFPlayer by DFRobot](https://www.dfrobot.com/product-1121.html) module
+- `MH2024K-24SS` which is one of the older clones, whose support is okay
+- `AB23A799755` is a newer clone and seem to be supported very well
+- `GD3200B` is also one of the newer clones, but partly fail in support!
+
+The used DFPlayer library also indicate support for `YX5200-24SS` and `MH2024K-16SS`, but I couldn't test these by myself. If you've one of these, give it a try.
+
+## SD-Card
+
+Look like all DFPlayer support a SD-Card size up to 32GB.
+As we don't have a lot soundfiles (<10MB), choose the smallest one you can find, format it with a FAT32 file system and copy all these [files and folder](./soundfiles/) to your SD-Card.
+
+Do not simply delete all files from an ancient SD-Card which you found in a dusty box!<br>
+These tiny DFPlayer beasts are sensitive to SD-Card trash like orphaned files or unclean FAT tables and tend to loop or hang when initialized.<br>
+Always prefer to cleanly format it with a FAT32 partition!
+
+### Folder/Track Structure
+
+Due to some incompatibilities with the libs and the clone chips, we unfortunately can't use DFPlayer's internal "advert" functionality for our usage.
+
+So we had to trick a little bit with the folder structure:
+
+- OM's old original sounds are now (partly) converted, translated, extended and reside now in a 2 digit, language specific subfolder. They're mainly 'advert' tracks as they're typically spoken adverts, which may interrupt background sounds like noises or music.
+- Folder 'mp3' contain background sounds (noises or music), which are hardcoded in the sources.
+- The single soundfile in the root folder, is used/required for DFPlayer "auto-play" detection. If you like to change it, you need to take care that the new file is as least 5 seconds long.

Firmware/LowLevel/include/debug.h

@@ -0,0 +1,50 @@
+// Created by Apehaenger on 02/02/23.
+//
+// This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
+//
+// Feel free to use the design in your private/educational projects, but don't try to sell the design or products based on it without getting my consent first.
+//
+// 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.
+//
+//
+#ifndef _DEBUG_H_
+#define _DEBUG_H_
+
+// Define to stream debugging messages via USB
+//#define USB_DEBUG
+
+#ifdef USB_DEBUG
+
+#define DEBUG_SERIAL Serial
+// #define DfMiniMp3Debug DEBUG_SERIAL // Also output DFPlayer IN/OUT cmd data
+
+// Some bloody simple debug macros which superfluous '#ifdef USB_DEBUG' ...
+#define DEBUG_BEGIN(b)     \
+    DEBUG_SERIAL.begin(b); \
+    while (!DEBUG_SERIAL);
+#define DEBUG_PRINTLN(str) DEBUG_SERIAL.println(str)
+#define DEBUG_PRINTF(fmt, ...)                   \
+    do {                                         \
+        DEBUG_SERIAL.printf(fmt, ##__VA_ARGS__); \
+    } while (0)
+#define PRINTF_BINARY_PATTERN_INT8 "%c%c%c%c%c%c%c%c"
+#define PRINTF_BYTE_TO_BINARY_INT8(i)                                                                                       \
+    (((i) & 0x80ll) ? '1' : '0'), (((i) & 0x40ll) ? '1' : '0'), (((i) & 0x20ll) ? '1' : '0'), (((i) & 0x10ll) ? '1' : '0'), \
+        (((i) & 0x08ll) ? '1' : '0'), (((i) & 0x04ll) ? '1' : '0'), (((i) & 0x02ll) ? '1' : '0'), (((i) & 0x01ll) ? '1' : '0')
+
+#else
+
+#define DEBUG_BEGIN(b)
+#define DEBUG_PRINTLN(str)
+#define DEBUG_PRINTF(fmt, ...)
+#define PRINTF_BINARY_PATTERN_INT8
+#define PRINTF_BYTE_TO_BINARY_INT8(i)
+#endif
+
+#endif  // _DEBUG_H_

Firmware/LowLevel/include/soundsystem.h

@@ -17,53 +17,84 @@
 #ifndef _SOUND_SYSTEM_H_
 #define _SOUND_SYSTEM_H_
 
-//#include <Arduino.h>
+#include <Arduino.h>
 #include <stdint.h>
-#include <list>
-
-#include <pins.h>
-#include <DFPlayerMini_Fast.h>
-#include <soundsystem.h>
-
-
-#define BUFFERSIZE 100
-
-
-class MP3Sound
-{
-
-
-
-
-    public:
-
-                int16_t anzSoundfiles;          // number of files stored on the SD-card
-                bool     playing;
-
-                MP3Sound();
 
-                bool begin();      // init serial stream and soundmodule, anzsoundOnSD : maximum number of available soundfiles on the SD-card
-
-                void playSound(int soundNr);        // play soundfile number. This method writes soundfile nr in a list, the method processSounds() (has to run in loop) will play 
-                                                    // the sounds according to the list
-
-                void playSoundAdHoc(int soundNr);   // play soundfile number immediately whithout waiting until the end of sound
-
-                void setvolume(int vol);            // scales loudness from 0 to 100 %
-
-                int sounds2play();                  // returns the number if sounds to play in the list
-
-                int processSounds();                // play all sounds from the list. This method has to be calles cyclic, e.g. every second.
+#include <list>
+#include <map>
+#include <string>
 
-
-    private:
-                std::list <int> active_sounds;
-                bool sound_available;
-
+#include "datatypes.h"
 
-   
+namespace soundSystem {
 
+enum class TrackType {
+    BACKGROUND = 1,  // Background tracks are stored in folder mp3 and get interrupted/aborted by higher priority sound like advert
+    ADVERT,          // Advert tracks are stored in language specific folder, i.e. "01" US or "49" German, and interrupt/stop background sounds
+};
+struct CardSources {
+    bool origin : 1;         // This sound track is available on origin SD-Card
+    bool improve_sound : 1;  // Available since ImproveSound PR
+};
+struct TrackFlags {
+    bool repeat : 1;           // Repeat this track. This flag is limited to background sounds!
+    bool stop_background : 1;  // Stop replaying of a current running background track after this sound got played
+};
+struct TrackDef {
+    uint16_t num;  // SD-Card's track number
+    TrackType type;
+    CardSources card_sources;
+    TrackFlags track_flags;
+    unsigned long pauseAfter = 0;     // Cosmetic pause in ms, after advert track got played, before the next sound get processed from queue.
+    int32_t repeatDuration = 180000;  // How long (ms) to repeat a background sound. Default to 180 sec. noise pollution (i.e. VdS 2300)
 };
 
-
-#endif // _SOUND_SYSTEM_H_  HEADER_FILE
+// For better reading, let's use track macro names with the detailed track definition
+// clang-format off
+#define SOUND_TRACK_BGD_OM_BOOT              TrackDef{ 2, TrackType::BACKGROUND, CardSources{.improve_sound=true}, TrackFlags{.repeat=true}}
+#define SOUND_TRACK_ADV_HI_IM_STEVE          TrackDef{ 1, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, .pauseAfter=1500}
+#define SOUND_TRACK_ADV_IMU_INIT_FAILED      TrackDef{19, TrackType::ADVERT,     CardSources{.improve_sound=true}, .pauseAfter=500}
+#define SOUND_TRACK_BGD_OM_ALARM             TrackDef{15, TrackType::BACKGROUND, CardSources{.improve_sound=true}, TrackFlags{.repeat=true}, .repeatDuration=20000}
+#define SOUND_TRACK_ADV_EMERGENCY_STOP       TrackDef{ 8, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 500}
+#define SOUND_TRACK_ADV_EMERGENCY_LIFT       TrackDef{ 9, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 500}
+#define SOUND_TRACK_ADV_EMERGENCY_ROS        TrackDef{24, TrackType::ADVERT,     CardSources{.improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 500}
+#define SOUND_TRACK_ADV_EMERGENCY_CLEARED    TrackDef{23, TrackType::ADVERT,     CardSources{.improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 500}
+#define SOUND_TRACK_BGD_EMERGENCY_ALARM      TrackDef{ 9, TrackType::BACKGROUND, CardSources{.improve_sound=true}}
+#define SOUND_TRACK_ADV_OM_STARTUP_SUCCESS   TrackDef{ 2, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, .pauseAfter = 1500}
+#define SOUND_TRACK_ADV_ROS_INIT             TrackDef{ 3, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 500}
+#define SOUND_TRACK_BGD_ROS_BOOT             TrackDef{ 5, TrackType::BACKGROUND, CardSources{.improve_sound=true}, TrackFlags{.repeat=true}}
+#define SOUND_TRACK_ADV_ROS_STARTUP_SUCCESS  TrackDef{16, TrackType::ADVERT,     CardSources{.improve_sound=true}, TrackFlags{.stop_background=true}}
+#define SOUND_TRACK_ADV_ROS_STOPPED          TrackDef{17, TrackType::ADVERT,     CardSources{.improve_sound=true}, TrackFlags{.stop_background=true}}
+#define SOUND_TRACK_ADV_MAP_RECORD_START     TrackDef{ 4, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, TrackFlags{.stop_background=true}}
+#define SOUND_TRACK_ADV_AUTONOMOUS_START     TrackDef{12, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 1500}
+#define SOUND_TRACK_ADV_RAIN                 TrackDef{10, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 3000}
+#define SOUND_TRACK_ADV_RTKGPS_WAIT          TrackDef{ 5, TrackType::ADVERT,     CardSources{.origin=true, .improve_sound=true}, .pauseAfter = 1500}
+#define SOUND_TRACK_ADV_RTKGPS_POOR          TrackDef{20, TrackType::BACKGROUND, CardSources{.improve_sound=true}}
+#define SOUND_TRACK_ADV_RTKGPS_MODERATE      TrackDef{21, TrackType::BACKGROUND, CardSources{.improve_sound=true}}
+#define SOUND_TRACK_ADV_RTKGPS_GOOD          TrackDef{22, TrackType::BACKGROUND, CardSources{.improve_sound=true}}
+#define SOUND_TRACK_BGD_MUSIC_PINK_PANTHER   TrackDef{12, TrackType::BACKGROUND, CardSources{.improve_sound=true}}
+#define SOUND_TRACK_ADV_UP                   TrackDef{21, TrackType::ADVERT,     CardSources{.improve_sound=true}, .pauseAfter = 100}
+#define SOUND_TRACK_ADV_DOWN                 TrackDef{20, TrackType::ADVERT,     CardSources{.improve_sound=true}, .pauseAfter = 100}
+#define SOUND_TRACK_ADV_LANGUAGE             TrackDef{22, TrackType::ADVERT,     CardSources{.improve_sound=true}, .pauseAfter = 100}
+#define SOUND_TRACK_ADV_MOW_DONE_DOCK        TrackDef{11, TrackType::ADVERT,     CardSources{.improve_sound=true}, TrackFlags{.stop_background=true}, .pauseAfter = 3000}
+// clang-format on
+
+bool begin();  // Init serial stream, soundmodule and sound_available_
+
+void playSound(const TrackDef&);       // Play sound trackDef. This method writes sound trackDef in a list, the method processSounds() (has to run in loop) will play the sounds according to the list
+void playSoundAdHoc(const TrackDef&);  // Play sound track number immediately without waiting until the end of sound
+
+void setDFPis5V(const bool t_dfpis5v);  // Set if DFP is set to 5V Vcc
+void setEnableBackground(const bool);   // Set if background sounds shall get played (true) or not (false)
+
+void setLanguage(const iso639_1 language_p, const bool quiet = false);  // Set language to the pointing ISO639-1 (2 char) language code and announce if changed and not quiet
+
+void setVolume(const uint8_t t_vol);  // Set volume (0-100%)
+uint8_t setVolumeUp();                // Scale volume up by VOLUME_STEPS and return new volume (%)
+uint8_t setVolumeDown();              // Scale volume down by VOLUME_STEPS and return new volume (%)
+
+void applyConfig(const ll_high_level_config t_config, const bool quiet);  // Apply the volume specific config options
+
+void processSounds(const ll_status t_ll_state, const bool t_ros_running, const ll_high_level_state t_hl_state);  // This method has to be called cyclic, e.g. every second.
+}  // namespace soundSystem
+#endif  // _SOUND_SYSTEM_H_  HEADER_FILE

Firmware/LowLevel/platformio.ini

@@ -42,79 +42,82 @@ board_build.f_cpu = 133000000L
 lib_ldf_mode = off
 debug_build_flags = -O0 -g -ggdb
 
-build_src_filter = +<*> -<.git/> -<.svn/> -<imu/*> -<soundsystem.cpp>
+build_src_filter = +<*> -<.git/> -<.svn/> -<imu/*>
+
+[sound]
+lib_deps = makuna/DFPlayer Mini Mp3 by Makuna@^1.2.3
 
 [env:0_13_X]
 lib_ignore = JY901_SERIAL,JY901_I2C
 lib_deps = ${env.lib_deps}
+           ${sound.lib_deps}
            stm32duino/STM32duino LSM6DSO@^2.0.3
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
 build_src_filter = ${env.build_src_filter} +<imu/LSM6DSO/>
-build_flags = ${env.build_flags} -DHW_0_13_X
+build_flags = ${env.build_flags} -DHW_0_13_X -DENABLE_SOUND_MODULE
 
 [env:0_12_X]
 lib_ignore = JY901_SERIAL,JY901_I2C
 lib_deps = ${env.lib_deps}
+           ${sound.lib_deps}
            stm32duino/STM32duino LSM6DSO@^2.0.3
            jpiat/PioSPI@^0.0.1
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
-build_src_filter = ${env.build_src_filter} +<imu/LSM6DSO/> +<soundsystem.cpp>
+build_src_filter = ${env.build_src_filter} +<imu/LSM6DSO/>
 build_flags = ${env.build_flags} -DHW_0_12_X -DENABLE_SOUND_MODULE
 
 
 [env:0_11_X_MPU9250]
 lib_ignore = JY901_SERIAL,JY901_I2C
 lib_deps = ${env.lib_deps}
+           ${sound.lib_deps}
            bolderflight/Bolder Flight Systems MPU9250@^1.0.2
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
-build_src_filter = ${env.build_src_filter} +<imu/MPU9250/> +<soundsystem.cpp>
+build_src_filter = ${env.build_src_filter} +<imu/MPU9250/>
 build_flags = ${env.build_flags} -DHW_0_11_X -DENABLE_SOUND_MODULE
 
 [env:0_11_X_WT901]
-build_src_filter = ${env.build_src_filter} +<imu/WT901_I2C/> +<soundsystem.cpp>
+build_src_filter = ${env.build_src_filter} +<imu/WT901_I2C/>
 lib_ignore = JY901_SERIAL
 lib_deps = ${env.lib_deps}
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
+           ${sound.lib_deps}
            JY901_I2C
 build_flags = ${env.build_flags} -DWT901_I2C -DHW_0_11_X -DENABLE_SOUND_MODULE
 
 
 [env:0_10_X_MPU9250]
 lib_ignore = JY901_SERIAL,JY901_I2C
 lib_deps = ${env.lib_deps}
+           ${sound.lib_deps}
            bolderflight/Bolder Flight Systems MPU9250@^1.0.2
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
-build_src_filter = ${env.build_src_filter} +<imu/MPU9250/> +<soundsystem.cpp>
+build_src_filter = ${env.build_src_filter} +<imu/MPU9250/>
 build_flags = ${env.build_flags} -DHW_0_10_X -DENABLE_SOUND_MODULE
 
 [env:0_10_X_WT901]
-build_src_filter = ${env.build_src_filter} +<imu/WT901_I2C/> +<soundsystem.cpp>
+build_src_filter = ${env.build_src_filter} +<imu/WT901_I2C/>
 lib_ignore = JY901_SERIAL
 lib_deps = ${env.lib_deps}
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
+           ${sound.lib_deps}
            JY901_I2C
 build_flags = ${env.build_flags} -DWT901_I2C -DHW_0_10_X -DENABLE_SOUND_MODULE
 
 
 [env:0_9_X_MPU9250]
 lib_ignore = JY901_SERIAL,JY901_I2C
 lib_deps = ${env.lib_deps}
+           ${sound.lib_deps}
            bolderflight/Bolder Flight Systems MPU9250@^1.0.2
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
-build_src_filter = ${env.build_src_filter} +<imu/MPU9250/> +<soundsystem.cpp>
+build_src_filter = ${env.build_src_filter} +<imu/MPU9250/>
 build_flags = ${env.build_flags} -DHW_0_9_X -DENABLE_SOUND_MODULE
 
 [env:0_9_X_WT901_INSTEAD_OF_SOUND]
 lib_ignore = JY901_I2C
-build_src_filter = ${env.build_src_filter} +<imu/WT901_SERIAL/>
+build_src_filter = ${env.build_src_filter} +<imu/WT901_SERIAL/> -<soundsystem.cpp>
 lib_deps = ${env.lib_deps}
            JY901_SERIAL
 build_flags = ${env.build_flags} -DWT901_INSTEAD_OF_SOUND -DHW_0_9_X
 
 [env:0_9_X_WT901]
 lib_ignore = JY901_I2C
-build_src_filter = ${env.build_src_filter} +<imu/WT901_SERIAL/> +<soundsystem.cpp>
+build_src_filter = ${env.build_src_filter} +<imu/WT901_SERIAL/>
 lib_deps = ${env.lib_deps}
+           ${sound.lib_deps}
            JY901_SERIAL
-           powerbroker2/DFPlayerMini_Fast@^1.2.4
 build_flags = ${env.build_flags} -DWT901 -DHW_0_9_X -DENABLE_SOUND_MODULE