Improve Sound

Firmware/LowLevel/README-Sound, DFPIS5V.md

@@ -0,0 +1,89 @@
+# 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
+- `GD3200B` is 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 (or if it's already formatted, remove all existing files) and copy all these [files and folder](./soundfiles/) to your SD-Card.
+
+### 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 (old/new) SD-Card-Structure detection, as well as for those DFPlayer types (i.e. DFRobot),
+  which start autoplaying directly after power-on, or after reset().<br>
+  You shouldn't change it, unless you take care that your replaced soundfile isn't shorter than the current one.

Firmware/LowLevel/include/debug.h

@@ -0,0 +1,47 @@
+// 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
+#define DEBUG_PREFIX "" // You may define a debug prefix string
+
+#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_PRINTF(fmt, ...)                                \
+    do                                                        \
+    {                                                         \
+        DEBUG_SERIAL.printf(DEBUG_PREFIX fmt, ##__VA_ARGS__); \
+    } while (0)
+#else
+#define DEBUG_BEGIN(b)
+#define DEBUG_PRINTF(fmt, ...)
+#endif
+
+#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')
+
+#endif // _DEBUG_H_

Firmware/LowLevel/include/nv_config.h

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2024 Jörg Ebeling (Apehaenger)
+ *
+ * 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.* Testing/examples for reading/writing flash on the RP2040.
+ *
+ * Heavily inspired, copied from, as well as must-read:
+ * https://github.com/MakerMatrix/RP2040_flash_programming
+ */
+
+#ifndef _NV_CONFIG_H
+#define _NV_CONFIG_H
+
+#include <Arduino.h>
+
+#ifdef ENABLE_SOUND_MODULE
+#include "soundsystem.h"
+#else
+#define VOLUME_DEFAULT 80
+#endif
+
+#include "../src/datatypes.h"
+
+#define NV_CONFIG_MAX_SAVE_INTERVAL 60000UL  // Don't save more often than once a minute
+
+// config_bitmask. Don't mistake with LL_HIGH_LEVEL_CONFIG_BIT. Similar, but not mandatory equal!
+#define NV_CONFIG_BIT_DFPIS5V 1 << 0  // DFP is set to 5V
+
+#define NV_RECORD_ID 0x4F4D4331                   // Record struct identifier "OMC1" for future flexible length Record.config
+#define NV_RECORD_ALIGNMENT (_Alignof(uint32_t))  // Ptr alignment of Record.id for quick in memory access
+
+namespace nv_config {
+#pragma pack(push, 1)
+// This is where our application values should go.
+// It's possible to extended it, but any extension should add an extension related CRC so that an old/last stored Record.config isn't lost.
+// (a new extension-crc isn't valid with a old Record.config. Thus the new extension values may get set i.e. with default values)
+struct Config {
+    // Config bitmask:
+    // Bit 0: DFP is 5V (enable full sound). See NV_CONFIG_BIT_DFPIS5V
+    uint8_t config_bitmask = 0;       // Don't mistake with LL_HIGH_LEVEL_CONFIG_BIT. Similar, but not mandatory equal!
+    uint8_t volume = VOLUME_DEFAULT;  // Sound volume (0-100%)
+    iso639_1 language = {'e', 'n'};   // Default to 'en'
+    uint32_t rain_threshold = 700;    // If (stock CoverUI) rain value < rain_threshold then it rains. Expected to differ between C500, SA and SC types
+
+    /* Possible future config settings
+    uint16_t free;                 // Future config setting
+    uint16_t free_n;               // Future config setting
+    uint16_t crc_n;                // Future config CRC16 (for the new member) for detection if loaded (possibly old) config already has the new member */
+} __attribute__((packed));
+
+// Record(s) get placed sequentially into a flash page.
+// The Record structure shouldn't get changed, because it would make old flash Record's unusable. Instead of, change Record.config
+struct Record {
+    const uint32_t id = NV_RECORD_ID;  // Fixed record identifier, used to identify a possible Record within a flash page. If width get changed, change also NV_RECORD_ALIGNMENT
+    uint32_t num_sector_erase = 0;     // For wear level stats
+    uint32_t num_page_write = 0;       // For informational purposes
+    uint16_t crc;                      // Required to ensure that a found NV_RECORD_ID is really a Record
+    Config config;
+} __attribute__((packed));
+#pragma pack(pop)
+
+Config *get();              // Returned Config pointer hold the data of the last saved Record.config, or a default one. Config member are writable, see delayedSaveChanges()
+void delayedSaveChanges();  // Handle a possible changed nv_config::config member and save it to flash, but only within NV_CONFIG_MAX_SAVE_INTERVAL timeout for wear level protection
+
+}  // namespace nv_config
+
+#endif  // _NV_CONFIG_H