esphome-docs/components/sensor/resistance.rst
Petr Kejval d1e7907930
Update resistance.rst (#2725)
* Update resistance.rst

Spent many hours to figure it out why my NTC reading are incorrect. Found out that ADC readings must be multiplied by 3.3 because built-in voltage divider on ADC pin on some boards.

* Update resistance.rst
2023-03-06 20:23:01 +01:00

82 lines
2.6 KiB
ReStructuredText

Resistance Sensor
=================
.. seo::
:description: Instructions for setting up resistance sensors in ESPHome
:image: omega.svg
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
Note:
------------------------
Some boards like NodeMCUv2 needs to multiply ADC reading by 3.3 to provide accurate result because they have built-in voltage divider on ADC pin (https://arduino.stackexchange.com/a/71952)
.. code-block:: yaml
# Example source sensor:
- platform: adc
id: source_sensor
pin: A0
filters:
- multiply: 3.3
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`