esphome-docs/components/sensor/adc.rst

99 lines
3.1 KiB
ReStructuredText
Raw Normal View History

2018-05-13 11:37:02 +02:00
Analog To Digital Sensor
========================
2018-11-14 22:12:27 +01:00
.. seo::
:description: Instructions for setting up built-in analog voltage sensors.
:image: flash.png
2018-11-14 22:12:27 +01:00
2018-05-13 11:37:02 +02:00
The Analog To Digital (``adc``) Sensor allows you to use the built-in
ADC in your device to measure a voltage on certain pins. On the ESP8266
only pin A0 (GPIO17) supports this. On the ESP32 pins GPIO32 through
GPIO39 can be used.
2018-06-01 18:10:00 +02:00
.. figure:: images/adc-ui.png
:align: center
:width: 80.0%
2018-05-13 11:37:02 +02:00
.. code-block:: yaml
2018-05-13 11:37:02 +02:00
# Example configuration entry
sensor:
- platform: adc
pin: A0
name: "Living Room Brightness"
2019-01-06 18:56:14 +01:00
update_interval: 60s
2018-05-13 11:37:02 +02:00
Configuration variables:
2018-08-24 22:44:01 +02:00
------------------------
2018-05-13 11:37:02 +02:00
2018-06-01 18:10:00 +02:00
- **pin** (**Required**, :ref:`config-pin`): The pin to measure the voltage on.
2018-06-02 13:42:51 +02:00
Or on the ESP8266 alternatively also ``VCC``, see :ref:`adc-esp8266_vcc`.
2018-06-01 18:10:00 +02:00
- **name** (**Required**, string): The name of the voltage sensor.
- **attenuation** (*Optional*): Only on ESP32. Specify the ADC
attenuation to use. See :ref:`adc-esp32_attenuation`.
- **update_interval** (*Optional*, :ref:`config-time`): The interval
2019-01-06 18:56:14 +01:00
to check the sensor. Defaults to ``60s``.
2018-06-01 18:10:00 +02:00
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
2019-02-17 12:28:17 +01:00
- All other options from :ref:`Sensor <config-sensor>`.
2018-06-01 18:10:00 +02:00
.. note::
This component prints the voltage as seen by the chip pin. On the ESP8266, this is always 0.0V to 1.0V
Some development boards like the Wemos D1 mini include external voltage divider circuitry to scale down
a 3.3V input signal to the chip-internal 1.0V. If your board has this circuitry, add a multiply filter to
get correct values:
.. code-block:: yaml
sensor:
- platform: adc
# ...
filters:
- multiply: 3.3
2018-06-01 18:10:00 +02:00
.. _adc-esp32_attenuation:
2018-05-14 21:15:49 +02:00
ESP32 Attenuation
2018-08-24 22:44:01 +02:00
-----------------
2018-05-14 21:15:49 +02:00
On the ESP32, the voltage measured with the ADC caps out at 1.1V by default as the sensing range
or the attenuation of the ADC is set to ``0db`` by default.
2018-06-01 18:10:00 +02:00
To measure voltages higher than 1.1V, set ``attenuation`` to one of the `following values
<https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/adc.html#_CPPv225adc1_config_channel_atten14adc1_channel_t11adc_atten_t>`__:
2018-06-01 18:10:00 +02:00
- ``0db`` for a full-scale voltage of 1.1V (default)
- ``2.5db`` for a full-scale voltage of 1.5V
- ``6db`` for a full-scale voltage of 2.2V
- ``11db`` for a full-scale voltage of 3.9V
2018-06-02 13:42:51 +02:00
.. _adc-esp8266_vcc:
ESP8266 Measuring VCC
2018-08-24 22:44:01 +02:00
---------------------
2018-06-02 13:42:51 +02:00
2020-12-21 00:48:42 +01:00
On the ESP8266 you can even measure the voltage the *chip is getting*. This can be useful in situations
2018-06-02 13:42:51 +02:00
where you want to shut down the chip if the voltage is low when using a battery.
To measure the VCC voltage, set ``pin:`` to ``VCC`` and make sure nothing is connected to the ``A0`` pin.
2020-12-21 00:48:42 +01:00
.. note::
To avoid confusion: It measures the voltage at the chip, and not at the VCC pin of the board. It should usually be around 3.3V.
.. code-block:: yaml
2018-06-02 13:42:51 +02:00
sensor:
- platform: adc
pin: VCC
name: "VCC Voltage"
2018-06-01 18:10:00 +02:00
See Also
2018-08-24 22:44:01 +02:00
--------
2018-05-14 21:15:49 +02:00
2018-06-01 18:10:00 +02:00
- :ref:`sensor-filters`
- :doc:`ads1115`
- :doc:`max6675`
2019-05-12 22:44:59 +02:00
- :apiref:`adc/adc_sensor.h`
- :ghedit:`Edit`