Improve Sound

.github/workflows/ci.yaml

@@ -1,6 +1,6 @@
 name: CI
 
-on: [push]
+on: [push, pull_request]
 
 jobs:
  erc-drc-checks:
@@ -110,7 +110,6 @@ jobs:
  cp Firmware/LowLevel/.pio/build/0_9_X_WT901_IGNORE_CHARGING_CURRENT/firmware.elf ./artifacts/0_9_X_WT901_IGNORE_CHARGING_CURRENT
  cp Firmware/LowLevel/.pio/build/0_9_X_WT901_IGNORE_CHARGING_CURRENT/firmware.uf2 ./artifacts/0_9_X_WT901_IGNORE_CHARGING_CURRENT
 
-
  - name: Step 3 - Use the Upload Artifact GitHub Action
  uses: actions/upload-artifact@v3
  with:
@@ -175,7 +174,7 @@ jobs:
 
  pre-release-latest-firmware:
  runs-on: ubuntu-latest
- if: github.ref_type != 'tag'
+ if: github.ref_type != 'tag' && github.event_name != 'pull_request'
  needs: firmware
  steps:
  - uses: actions/checkout@v3

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