Merge pull request #5453 from tonhuisman/feature/Docs-updates-and-improvements-2025-q4

[Stats] Update min/max stats values, add minp/maxp stats values

Author: TD-er

docs/source/Plugin/_Plugin.rst

@@ -93,15 +93,19 @@ Enabling "Stats" on a task value also extends how task values can be addressed w
 
 For example using just like normal task value data:
 
-* ``[bme#temp.avg]`` Compute the average over the last N samples in the historic buffer (typically: 64 samples on ESP32, 16 on ESP8266)
+* ``[bme#temp.avg]`` Compute the average over the last N samples in the historic buffer (typically: 250 samples on ESP32, 16 on ESP8266)
 * ``[bme#temp.avgX]`` Compute the average over the last X samples (or less if there are less samples available)
-* ``[bme#temp.stddev]`` Compute the standard deviation over the last N samples in the historic buffer (typically: 64 samples on ESP32, 16 on ESP8266)
+* ``[bme#temp.stddev]`` Compute the standard deviation over the last N samples in the historic buffer (typically: 250 samples on ESP32, 16 on ESP8266)
 * ``[bme#temp.stddevX]`` Compute the standard deviation over the last X samples (or less if there are less samples available)
-* ``[bme#temp.max]`` Refer to the maximum recorded sample since the last ``resetpeaks``. N.B. Not all tasks log the min and max peaks.
-* ``[bme#temp.min]`` See ``[bme#temp.max]`` 
+* ``[bme#temp.max]`` Refer to the maximum recorded sample in available samples (rolling maximum)
+* ``[bme#temp.maxX]`` Refer to the maximum recorded sample in the last X samples (or less if there are less samples available)
+* ``[bme#temp.maxp]`` (max-peak) Refer to the maximum recorded sample since the last ``resetpeaks``. N.B. Not all tasks log the min and max peaks.
+* ``[bme#temp.min]`` Refer to the minimum recorded sample in available samples (rolling minimum)
+* ``[bme#temp.minX]`` Refer to the minimum recorded sample in the last X samples (or less if there are less samples available)
+* ``[bme#temp.minp]`` (min-peak) See ``[bme#temp.maxp]``.
 * ``[bme#temp.size]`` Return the number of samples in memory.
-* ``[bme#temp.sample]`` Access the last sample in memory.
-* ``[bme#temp.sampleN]`` Access the N-th last sample in memory.
+* ``[bme#temp.sample]`` Return the number of samples in memory. (Doc. reflects the actual code!)
+* ``[bme#temp.sampleN]`` Access the N-th last sample in memory, negative value accesses N-th value from the *oldest* available sample.
 
 
 Commands on "Stats" data:

src/src/DataStructs/PluginStats.cpp

@@ -369,21 +369,27 @@ bool PluginStats::plugin_get_config_value_base(struct EventStruct *event, String
       break;
     case 'm':
 
-      if (matchedCommand(command, F("min"), nrSamples)) {
+      if (equals(command, F("minp"))) { // [taskname#valuename.minp] Lowest value seen since value reset
+        value   = getPeakLow();
+        success = true;
+      } else if (matchedCommand(command, F("min"), nrSamples)) {
         success = nrSamples != 0;
 
-        if (nrSamples < 0) { // [taskname#valuename.min] Lowest value seen since value reset
-          value = getPeakLow();
+        if (nrSamples < 0) { // [taskname#valuename.min] Lowest value of all recent samples
+          value = getSampleExtreme(getNrSamples(), false);
         } else {             // Check for "minN", where N is the number of most recent samples to use.
           if (nrSamples > 0) {
             value = getSampleExtreme(nrSamples, false);
           }
         }
+      } else if (equals(command, F("maxp"))) { // [taskname#valuename.maxp] Highest value seen since value reset
+        value   = getPeakHigh();
+        success = true;
       } else if (matchedCommand(command, F("max"), nrSamples)) {
         success = nrSamples != 0;
 
-        if (nrSamples < 0) { // [taskname#valuename.max] Highest value seen since value reset
-          value = getPeakHigh();
+        if (nrSamples < 0) { // [taskname#valuename.max] Highest value of all recent samples
+          value = getSampleExtreme(getNrSamples(), true);
         } else {             // Check for "maxN", where N is the number of most recent samples to use.
           if (nrSamples > 0) {
             value = getSampleExtreme(nrSamples, true);