diff --git a/components/sensor/images/resistance-downstream.png b/components/sensor/images/resistance-downstream.png new file mode 100644 index 000000000..18e70f9b1 Binary files /dev/null and b/components/sensor/images/resistance-downstream.png differ diff --git a/components/sensor/ntc.rst b/components/sensor/ntc.rst new file mode 100644 index 000000000..2bebaa71b --- /dev/null +++ b/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 ` and :doc:`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 `__ +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 `. + +See Also +-------- + +- :doc:`adc` +- :doc:`resistance` +- :ref:`sensor-filters` +- :apiref:`resistance/resistance_sensor.h` +- :ghedit:`Edit` diff --git a/components/sensor/resistance.rst b/components/sensor/resistance.rst new file mode 100644 index 000000000..0f132be72 --- /dev/null +++ b/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 `) into resistance readings +in Ω (ohm). + +In order to calculate the resistance, the circuit needs to be set up in a +`voltage divider circuit `__. +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 `. + +See Also +-------- + +- :doc:`adc` +- :doc:`ntc` +- :ref:`sensor-filters` +- :apiref:`resistance/resistance_sensor.h` +- :ghedit:`Edit` diff --git a/images/ntc.jpg b/images/ntc.jpg new file mode 100644 index 000000000..d1eb5a80e Binary files /dev/null and b/images/ntc.jpg differ diff --git a/images/omega.svg b/images/omega.svg new file mode 100644 index 000000000..19aff598e --- /dev/null +++ b/images/omega.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index ca5b9ce87..8cb251573 100644 --- a/index.rst +++ b/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 diff --git a/svg2png/crosshairs-gps.png b/svg2png/crosshairs-gps.png new file mode 100644 index 000000000..f66b04489 Binary files /dev/null and b/svg2png/crosshairs-gps.png differ diff --git a/svg2png/espeasy.png b/svg2png/espeasy.png deleted file mode 100644 index 98fef9f0d..000000000 Binary files a/svg2png/espeasy.png and /dev/null differ diff --git a/svg2png/espurna.png b/svg2png/espurna.png deleted file mode 100644 index 289e00fec..000000000 Binary files a/svg2png/espurna.png and /dev/null differ diff --git a/svg2png/omega.png b/svg2png/omega.png new file mode 100644 index 000000000..32ede221d Binary files /dev/null and b/svg2png/omega.png differ diff --git a/svg2png/settings.png b/svg2png/settings.png deleted file mode 100644 index 31e4e627b..000000000 Binary files a/svg2png/settings.png and /dev/null differ