Add NTC/resistance sensor docs

Ref esphome/esphome#560

components/sensor/ntc.rst

@@ -0,0 +1,91 @@
+NTC Sensor
+==========
+
+.. seo::
+    :description: Instructions for setting up NTC thermistor sensor in ESPHome
+    :image: ntc.jpg
+
+The ``ntc`` platform is a helper sensor that allows you to convert resistance readings
+from a NTC thermistor to temperature readings.
+
+First, you need to get resistance readings from the sensor - you can set this up with the
+:doc:`resistance <resistance>` and :doc:`adc <adc>` sensors.
+
+This platform will then convert the resistance values to temperature readings.
+It also requires calibration parameters for this conversion. There are two
+ways of obtaining these values: By looking at the datasheet or manual calculation.
+
+If you have the datasheet of the thermistor, you can look at its "B-constant" and
+reference temperature/resistance. For example `this product <https://www.adafruit.com/product/372>`__
+would have the following calibration configuration.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: ntc
+        # ...
+        calibration:
+          b_constant: 3950
+          reference_temperature: 25°C
+          reference_resistance: 10kOhm
+
+If you don't have access to the datasheet or want to calculate these values yourself,
+you have to first measure three resistance values at different temperatures.
+Heat/cool the NTC to three different temperatures (best if temperatures are far apart)
+and write down the resistance readings at those temperatures. Then enter these values in the
+calibration parameter:
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: ntc
+        # ...
+        calibration:
+          - 10.0kOhm -> 25°C
+          - 27.219kOhm -> 0°C
+          - 14.674kOhm -> 15°C
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: ntc
+        sensor: resistance_sensor
+        calibration:
+          b_constant: 3950
+          reference_temperature: 25°C
+          reference_resistance: 10kOhm
+        name: NTC Temperature
+
+      # Example source sensors:
+      - platform: resistance
+        id: resistance_sensor
+        sensor: source_sensor
+        configuration: DOWNSTREAM
+        resistor: 5.6kOhm
+        name: Resistance Sensor
+      - platform: adc
+        id: source_sensor
+        pin: A0
+
+Configuration variables:
+------------------------
+
+- **name** (**Required**, string): The name for the sensor.
+- **sensor** (**Required**, :ref:`config-id`): The sensor to read the resistance values from
+  to convert to temperature readings.
+- **calibration** (**Required**, float): The calibration parameters of the sensor - see above
+  for more details.
+- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+- All other options from :ref:`Sensor <config-sensor>`.
+
+See Also
+--------
+
+- :doc:`adc`
+- :doc:`resistance`
+- :ref:`sensor-filters`
+- :apiref:`resistance/resistance_sensor.h`
+- :ghedit:`Edit`

components/sensor/resistance.rst

@@ -0,0 +1,68 @@
+Resistance Sensor
+=================
+
+.. seo::
+    :description: Instructions for setting up resistance sensors in ESPHome
+    :image: omega.png
+
+The ``resistance`` platform is a helper sensor that allows you to convert readings
+from a voltage sensor (such as the :doc:`ADC Sensor <adc>`) into resistance readings
+in Ω (ohm).
+
+In order to calculate the resistance, the circuit needs to be set up in a
+`voltage divider circuit <https://learn.sparkfun.com/tutorials/voltage-dividers/all>`__.
+This consists of three parts:
+
+ - A voltage reference, usually this is connected to 3.3V (VCC). For example in the image
+   below it is 5V (though on ESPs you should not use that voltage)
+ - A reference resistor with constant resistance. For example below it is R₁ with a value
+   of 5.6kOhm.
+ - The variable resistor we wish the read the resistance of. Here R₂.
+
+There are two kinds of configurations for this circuit: Either the variable resistor
+is close to GND (DOWNSTREAM) or it is closer to VCC (UPSTREAM).
+
+.. figure:: images/resistance-downstream.png
+    :align: center
+    :width: 25.0%
+
+    Example voltage divider configuration of type "DOWNSTREAM" and a voltage
+    reference of 5V.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    sensor:
+      - platform: resistance
+        sensor: source_sensor
+        configuration: DOWNSTREAM
+        resistor: 5.6kOhm
+        name: Resistance Sensor
+
+    # Example source sensor:
+      - platform: adc
+        id: source_sensor
+        pin: A0
+
+Configuration variables:
+------------------------
+
+- **name** (**Required**, string): The name for the sensor.
+- **sensor** (**Required**, :ref:`config-id`): The sensor to read the voltage values from
+  to convert to resistance readings.
+- **configuration** (**Required**, string): The type of circuit, one of ``DOWNSTREAM`` or
+  ``UPSTREAM``.
+- **resistor** (**Required**, float): The value of the resistor with a constant value.
+
+- **reference_voltage** (*Optional*, float): The reference voltage. Defaults to ``3.3V``.
+- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas.
+- All other options from :ref:`Sensor <config-sensor>`.
+
+See Also
+--------
+
+- :doc:`adc`
+- :doc:`ntc`
+- :ref:`sensor-filters`
+- :apiref:`resistance/resistance_sensor.h`
+- :ghedit:`Edit`

index.rst

@@ -118,9 +118,11 @@ Sensor Components
     MPU6050, components/sensor/mpu6050, mpu6050.jpg
     MQTT Subscribe, components/sensor/mqtt_subscribe, mqtt.png
     MS5611, components/sensor/ms5611, ms5611.jpg
+    NTC Thermistor, components/sensor/ntc, ntc.jpg
     PMSX003, components/sensor/pmsx003, pmsx003.svg
     Pulse Counter, components/sensor/pulse_counter, pulse.svg
     Pulse Width, components/sensor/pulse_width, pulse.svg
+    Resistance, components/sensor/resistance, omega.svg
     Rotary Encoder, components/sensor/rotary_encoder, rotary_encoder.jpg
     SDS011 Sensor, components/sensor/sds011, sds011.jpg
     SHT3X-D, components/sensor/sht3xd, sht3xd.jpg