Add 'map_linear' and 'clamp' sensor filters (#3039)

components/sensor/index.rst

@@ -184,6 +184,12 @@ Multiplies each value by a constant value.
 
 Calibrate your sensor values by using values you measured with an accurate "truth" source.
 
+Configuration variables:
+
+- **method** (*Optional*, string): The method for calculating the linear function(s).
+  One of ``least_squares`` or ``exact``. Defaults to ``least_squares``.
+- **datapoints** (**Required**): The list of datapoints.
+
 First, collect a bunch of values of what the sensor shows and what the real value should be.
 For temperature, this can for example be achieved by using an accurate thermometer. For other
 sensors like power sensor this can be done by connecting a known load and then writing down
@@ -198,14 +204,21 @@ the value the sensor shows.
         name: "DHT22 Temperature"
         filters:
           - calibrate_linear:
-              # Map 0.0 (from sensor) to 0.0 (true value)
+             method: least_squares
-              - 0.0 -> 0.0
+             datapoints:
+              # Map 0.0 (from sensor) to 1.0 (true value)
+              - 0.0 -> 1.0
               - 10.0 -> 12.1
 
-The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``. ESPHome will
+The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``. Depending on
-then fit a linear equation to the values (using least squares). So you need to supply at least
+the ``method`` ESPHome will then either fit a linear equation to the values (using least squares)
-two values. If more than two values are given a linear solution will be calculated and may not
+or connect the values exactly using multiple linear equations. You need to supply at least two
-represent each value exactly.
+values. When using ``least_squares`` and more than two values are given a linear solution will be
+calculated and may not represent each value exactly.
+
+.. figure:: images/sensor_filter_calibrate_linear.png
+    :align: center
+    :width: 50.0%
 
 .. _sensor-calibrate_polynomial:
 
@@ -246,6 +259,17 @@ degree with a least squares solver.
       filters:
         - filter_out: 85.0
 
+``clamp``
+*********
+
+Limits the value to the range between ``min_value`` and ``max_value``. If ``min_value`` is not set, there is
+no lower bound, if ``max_value`` is not set there is no upper bound.
+
+Configuration variables:
+
+- **min_value** (*Optional*, float): The lower bound of the range.
+- **max_value** (*Optional*, float): The upper bound of the range.
+
 ``quantile``
 ************