Merge pull request #5190 from tonhuisman/feature/Add-map-math-function

[Functions] Add 'map' function

Author: TD-er

docs/source/Rules/Rules.rst

@@ -1420,6 +1420,8 @@ Basic Math Functions
 * ``round(x)`` Rounds to the nearest integer, but rounds halfway cases away from zero (instead of to the nearest even integer). 
 * ``^`` The caret is used as the exponentiation operator for calculating the value of x to the power of y (x\ :sup:`y`). 
 
+* ``map(value:fromLow:fromHigh:toLow:toHigh)`` Maps value x in the fromLow/fromHigh range to toLow/toHigh values. Similar to the Arduino map() function. See examples below. (Using a colon as an argument separator to not interfere with regular argument processing)
+
 Rules example:
 
 .. code-block:: none  
@@ -1454,6 +1456,24 @@ Called with event ``eventname2=1.234,100``
  213379 : Info   : ACT : LogEntry,'pow of 1.234^100 = 1353679866.79107'
  213382 : Info   : pow of 1.234^100 = 1353679866.79107
 
+Examples using the ``map()`` function. Map does not constrain the values within the given range, but uses extrapolation when the input value goes outside the ``fromLow`` / ``fromHigh`` range.
+
+Missing values for the map function default to 0.
+
+.. code-block:: none
+
+ on ds1#temp do
+   let,1,%eventvalue1|20% // use default of 20 degrees
+   let,2,map(%v2%:-10:40:1:60) // Convert a temperature range -10..40 to a 60 pixel LED stripe
+   NeoPixelLine,1,%v2%,255,255,255 // Draw a white line on the LED strip
+ endon
+
+.. code-block:: none
+
+ on eventname3 do
+   let,1,map(%eventvalue1|10%:0:100:100:0) // Reverse mapping of a value, 0..100 will output 100..0
+   LogEntry,'Input value %eventvalue1|10% mapped to: %v1%'
+ endon
 
 
 Trigonometric Functions

src/src/Helpers/ESPEasy_math.cpp

@@ -331,4 +331,18 @@ double sqrt(const double x)
 
 
 
-#endif
+#endif
+
+ESPEASY_RULES_FLOAT_TYPE mapADCtoFloat(ESPEASY_RULES_FLOAT_TYPE float_value,
+                                       ESPEASY_RULES_FLOAT_TYPE adc1,
+                                       ESPEASY_RULES_FLOAT_TYPE adc2,
+                                       ESPEASY_RULES_FLOAT_TYPE out1,
+                                       ESPEASY_RULES_FLOAT_TYPE out2)
+{
+  if (!approximatelyEqual(adc1, adc2))
+  {
+    const ESPEASY_RULES_FLOAT_TYPE normalized = (float_value - adc1) / (adc2 - adc1);
+    float_value = normalized * (out2 - out1) + out1;
+  }
+  return float_value;
+}

src/src/Helpers/ESPEasy_math.h

@@ -59,5 +59,11 @@ bool essentiallyZero(const double& a);
 #endif
 bool essentiallyZero(const float& a);
 
+ESPEASY_RULES_FLOAT_TYPE mapADCtoFloat(ESPEASY_RULES_FLOAT_TYPE float_value,
+                                       ESPEASY_RULES_FLOAT_TYPE adc1,
+                                       ESPEASY_RULES_FLOAT_TYPE adc2,
+                                       ESPEASY_RULES_FLOAT_TYPE out1,
+                                       ESPEASY_RULES_FLOAT_TYPE out2);
+
 
 #endif // HELPERS_ESPEASY_MATH_H

src/src/Helpers/Hardware.cpp

@@ -336,21 +336,6 @@ int espeasy_analogRead(int pin) {
 
 #endif // ifdef ESP8266
 
-float mapADCtoFloat(float float_value,
-                    float adc1,
-                    float adc2,
-                    float out1,
-                    float out2)
-{
-  if (!approximatelyEqual(adc1, adc2))
-  {
-    const float normalized = (float_value - adc1) / (adc2 - adc1);
-    float_value = normalized * (out2 - out1) + out1;
-  }
-  return float_value;
-}
-
-
 #ifdef ESP32
 
 // ESP32 ADC calibration datatypes.

src/src/Helpers/Hardware.h

@@ -34,12 +34,6 @@ extern int lastADCvalue; // Keep track of last ADC value as it cannot be read wh
 int   espeasy_analogRead(int pin);
 #endif // ifdef ESP8266
 
-float mapADCtoFloat(float float_value,
-                    float adc1,
-                    float adc2,
-                    float out1,
-                    float out2);
-
 
 #ifdef ESP32
 void  initADC();

src/src/Helpers/Rules_calculate.cpp

@@ -4,6 +4,7 @@
 #include "../ESPEasyCore/ESPEasy_Log.h"
 #include "../Globals/RamTracker.h"
 #include "../Helpers/ESPEasy_math.h"
+#include "../Helpers/Hardware.h"
 #include "../Helpers/Numerical.h"
 #include "../Helpers/StringConverter.h"
 
@@ -71,6 +72,14 @@ bool RulesCalculate_t::is_unary_operator(char c)
   */
 }
 
+// quinary = 5-argument functions
+bool RulesCalculate_t::is_quinary_operator(char c)
+{
+  const UnaryOperator op = static_cast<UnaryOperator>(c);
+
+  return op == UnaryOperator::Map;
+}
+
 CalculateReturnCode RulesCalculate_t::push(ESPEASY_RULES_FLOAT_TYPE value)
 {
   if (sp != sp_max) // Full
@@ -261,6 +270,22 @@ ESPEASY_RULES_FLOAT_TYPE RulesCalculate_t::apply_unary_operator(char op, ESPEASY
   return ret;
 }
 
+ESPEASY_RULES_FLOAT_TYPE RulesCalculate_t::apply_quinary_operator(char op, 
+                                                                  ESPEASY_RULES_FLOAT_TYPE first,
+                                                                  ESPEASY_RULES_FLOAT_TYPE second,
+                                                                  ESPEASY_RULES_FLOAT_TYPE third,
+                                                                  ESPEASY_RULES_FLOAT_TYPE fourth,
+                                                                  ESPEASY_RULES_FLOAT_TYPE fifth)
+{
+  ESPEASY_RULES_FLOAT_TYPE ret{};
+  const UnaryOperator qu_op = static_cast<UnaryOperator>(op);
+
+  if (UnaryOperator::Map == qu_op) {
+    return mapADCtoFloat(first, second, third, fourth, fifth);
+  }
+  return ret;
+}
+
 /*
    char * RulesCalculate_t::next_token(char *linep)
    {
@@ -295,6 +320,16 @@ CalculateReturnCode RulesCalculate_t::RPNCalculate(char *token)
 
 // FIXME TD-er: Regardless whether it is an error, all code paths return ret;
 //    if (isError(ret)) { return ret; }
+  } else if (is_quinary_operator(token[0]) && (token[1] == 0))
+  {
+    ESPEASY_RULES_FLOAT_TYPE fifth  = pop();
+    ESPEASY_RULES_FLOAT_TYPE fourth = pop();
+    ESPEASY_RULES_FLOAT_TYPE third  = pop();
+    ESPEASY_RULES_FLOAT_TYPE second = pop();
+    ESPEASY_RULES_FLOAT_TYPE first  = pop();
+
+    ret = push(apply_quinary_operator(token[0], first, second, third, fourth, fifth));
+
   } else {
     // Fetch next if there is any
     ESPEASY_RULES_FLOAT_TYPE value{};
@@ -352,6 +387,8 @@ unsigned int RulesCalculate_t::op_arg_count(const char c)
   if (is_unary_operator(c)) { return 1; }
 
   if (is_operator(c)) { return 2; }
+
+  if (is_quinary_operator(c)) { return 5; }
   return 0;
 }
 
@@ -399,7 +436,7 @@ CalculateReturnCode RulesCalculate_t::doCalculate(const char *input, ESPEASY_RUL
       }
 
       // If the token is an operator, op1, then:
-      else if (is_operator(c) || is_unary_operator(c))
+      else if (is_operator(c) || is_unary_operator(c) || is_quinary_operator(c))
       {
         *(TokenPos) = 0; // Mark end of token string
         error       = RPNCalculate(token);
@@ -443,6 +480,14 @@ CalculateReturnCode RulesCalculate_t::doCalculate(const char *input, ESPEASY_RUL
         ++sl;
       }
 
+      // Process the token at a colon (separator)
+      else if (c == ':')
+      {
+        *(TokenPos) = 0; // Mark end of token string
+        error       = RPNCalculate(token);
+        TokenPos    = token;
+      }
+
       // If the token is a left parenthesis, then push it onto the stack.
       else if (c == '(')
       {
@@ -609,6 +654,8 @@ const __FlashStringHelper* toString(UnaryOperator op)
       return F("atan");
     case UnaryOperator::ArcTan_d:
       return F("atan_d");
+    case UnaryOperator::Map:
+      return F("map");
   }
   return F("");
 }
@@ -644,6 +691,7 @@ String RulesCalculate_t::preProces(const String& input)
     ,UnaryOperator::Tan
     ,UnaryOperator::Tan_d
     #endif // if FEATURE_TRIGONOMETRIC_FUNCTIONS_RULES
+    ,UnaryOperator::Map
 
   };
 

src/src/Helpers/Rules_calculate.h

@@ -53,7 +53,8 @@ enum class UnaryOperator : uint8_t {
   ArcCos,    // Arc Cosine (radian)
   ArcCos_d,  // Arc Cosine (degree)
   ArcTan,    // Arc Tangent (radian)
-  ArcTan_d   // Arc Tangent (degree)
+  ArcTan_d,  // Arc Tangent (degree)
+  Map,       // Map (value, lowFrom, highFrom, lowTo, highTo) (not really unary...)
 };
 
 void   preProcessReplace(String      & input,
@@ -78,6 +79,8 @@ class RulesCalculate_t {
 
   bool                is_unary_operator(char c);
 
+  bool                is_quinary_operator(char c);
+
   CalculateReturnCode push(ESPEASY_RULES_FLOAT_TYPE value);
 
   ESPEASY_RULES_FLOAT_TYPE              pop();
@@ -89,6 +92,13 @@ class RulesCalculate_t {
   ESPEASY_RULES_FLOAT_TYPE apply_unary_operator(char   op,
                               ESPEASY_RULES_FLOAT_TYPE first);
 
+  ESPEASY_RULES_FLOAT_TYPE apply_quinary_operator(char op, 
+                                                  ESPEASY_RULES_FLOAT_TYPE first,
+                                                  ESPEASY_RULES_FLOAT_TYPE second,
+                                                  ESPEASY_RULES_FLOAT_TYPE third,
+                                                  ESPEASY_RULES_FLOAT_TYPE fourth,
+                                                  ESPEASY_RULES_FLOAT_TYPE fifth);
+
   //  char              * next_token(char *linep);
 
   CalculateReturnCode RPNCalculate(char *token);