mirror of
https://github.com/letscontrolit/ESPEasy.git
synced 2026-09-12 09:36:59 +00:00
278 lines
11 KiB
ReStructuredText
278 lines
11 KiB
ReStructuredText
.. include:: ../Plugin/_plugin_substitutions_p00x.repl
|
|
.. _P002_page:
|
|
|
|
|P002_typename|
|
|
==================================================
|
|
|
|
|P002_shortinfo|
|
|
|
|
Plugin details
|
|
--------------
|
|
|
|
Type: |P002_type|
|
|
|
|
Name: |P002_name|
|
|
|
|
Status: |P002_status|
|
|
|
|
GitHub: |P002_github|_
|
|
|
|
Maintainer: |P002_maintainer|
|
|
|
|
Used libraries: |P002_usedlibraries|
|
|
|
|
Description
|
|
-----------
|
|
|
|
All ESP chips have one or more ADCs available to measure an analog signal.
|
|
|
|
* ESP8266: 1x 12-bit ADC on the A0 pin or the supplied voltage (on ``VCC`` Builds)
|
|
* ESP32: 1 Hall Effect sensor + 18 pins which can be configured to read supplied voltage.
|
|
* ESP32-S2: 20 pins which can be configured to read supplied voltage.
|
|
|
|
The ESP32 chips have 2 ADCs.
|
|
Each pin that can be set to read an analog voltage will then be hard-wired to one of both ADCs.
|
|
See below for the limitations on sampling analog values with WiFi active.
|
|
|
|
See the `ESP32 API reference <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/adc.html>`_ for more detailed information on the features and limitations of these pins.
|
|
|
|
Range and Calibration
|
|
---------------------
|
|
|
|
2022/07/11: Added support for Attenuation selection + Factory calibration
|
|
|
|
|
|
The ESP8266 ADC has a fixed range of 0...1V.
|
|
However, almost all boards do have some resistors to act as a voltage divider to extend this range to 3.6V
|
|
|
|
All ESP32 versions allow for changing the range per pin (channel) by setting some attentuation resistor active.
|
|
The default active attentuation is 11 dB, which allows for a maximum input voltage of 3.1V
|
|
Upto roughly 2.5V the ADC does show a nearly linear response.
|
|
|
|
Suggested ranges ESP32:
|
|
|
|
.. code-block:: none
|
|
|
|
+----------+-------------+-----------------+
|
|
| | attenuation | suggested range |
|
|
| SoC | (dB) | (mV) |
|
|
+==========+=============+=================+
|
|
| | 0 | 100 ~ 950 |
|
|
| +-------------+-----------------+
|
|
| | 2.5 | 100 ~ 1250 |
|
|
| ESP32 +-------------+-----------------+
|
|
| | 6 | 150 ~ 1750 |
|
|
| +-------------+-----------------+
|
|
| | 11 | 150 ~ 2450 |
|
|
+----------+-------------+-----------------+
|
|
| | 0 | 0 ~ 750 |
|
|
| +-------------+-----------------+
|
|
| | 2.5 | 0 ~ 1050 |
|
|
| ESP32-S2 +-------------+-----------------+
|
|
| | 6 | 0 ~ 1300 |
|
|
| +-------------+-----------------+
|
|
| | 11 | 0 ~ 2500 |
|
|
+----------+-------------+-----------------+
|
|
|
|
N.B. The ESP32 cannot measure down to 0V. The minimum Voltage depends on the set attenuation.
|
|
|
|
Each (recent) ESP32 chip does have a factory calibration burnt in to compensate for the non-linear behavior of the ADC and to correct for the used internal voltage reference.
|
|
|
|
Only the really early production runs of the ESP32 do not have such factory calibration.
|
|
|
|
.. image:: P002_FactoryCalibration.png
|
|
|
|
N.B. The initial chart on the setup page of an Analog Input task will only show the active attenuation. Others can be shown by clicking on the labels in the chart legend.
|
|
|
|
With ``Apply Factory Calibration`` checked, the Analog Input plugin in ESPEasy will perform the reading in mV.
|
|
|
|
|
|
Oversampling
|
|
------------
|
|
|
|
With ``Oversampling`` selected, the task will take a sample 10x per second.
|
|
These are averaged over the period set by the ``Interval`` timer. (or shorter interval when the task is executed via the ``TaskRun`` command)
|
|
This mode also takes out the highest and lowest sample values to make sure a single fluke measurement is not affecting the output value too much.
|
|
|
|
Binning
|
|
-------
|
|
|
|
Added: 2022/07/11
|
|
|
|
For some use cases, a strict classification of data is needed.
|
|
|
|
A typical use case is the wind vane of a very popular set, the DS-15901.
|
|
|
|
.. image:: P002_DS-15901_wind_vane_schematics.png
|
|
|
|
This wind vane uses a magnet to trigger a number of reed switches which will then activate a resistor.
|
|
What makes this setup rather complex is that for some angles 2 resistors will be active and thus effectively lower the seen resistance between 2 other wind directions.
|
|
|
|
Plot of voltage measured over the wind vane when using a 10k resistor in series with the wind vane:
|
|
|
|
.. image:: P002_voltage_vs_wind_dir.png
|
|
|
|
|
|
For this use case, it is not possible to use oversampling as this may result in very unstable readings.
|
|
We need to map a range of values to a single output value.
|
|
|
|
Plotting the resistance range from the wind vane datasheet:
|
|
|
|
.. image:: P002_range_resistance_per_bin.png
|
|
|
|
As can be seen, the ranges are quite small for some and quite large for others.
|
|
But also the wind direction is not increasing when the resistance increases.
|
|
|
|
Therefore we need a look-up table. (see Multipoint Processing below)
|
|
|
|
What binning does is it tries to match each sample to a specific bin (an entry in the Multipoint Processing table) and simply counts each occurence per bin.
|
|
After a measurement period (the time between 2 calls to "run" the task, typically the "interval") the bin with the highest count is picked and the output value of this bin will be returned as output.
|
|
|
|
|
|
Two Point Calibration
|
|
---------------------
|
|
|
|
The measured sample taken by the ADC (either a raw value, or mV when ESP32 Factory Calibration is enabled) often has to be mapped on a specific range.
|
|
For example when measuring the voltage of a car battery, one needs to have some voltage divider to transform the battery voltage to a range suitable for the ADC.
|
|
|
|
On the output, one may want to see the actual battery voltage again.
|
|
This mapping can be done using the "Two Point Calibration".
|
|
|
|
For this, one must measure 2 known voltages and input the raw ADC value.
|
|
|
|
Example of some Two Point Calibration:
|
|
|
|
.. image:: P002_two_point_calibration.png
|
|
|
|
(Chart option added: 2022/07/11)
|
|
|
|
The values below the chart only taking the Two Point Calibration into account.
|
|
|
|
* The current ADC value with the corresponding output when the set Two Point Calibration is applied.
|
|
* The minimum and maximum values are based on the maximum range which can be measured with the set attenuation.
|
|
* The step size is the minimal step size of the output value.
|
|
|
|
|
|
Multipoint Processing
|
|
---------------------
|
|
|
|
Added: 2022/07/11
|
|
|
|
The values entered in the "Multipoint Processing" section can be considered a look-up table.
|
|
|
|
* For "Binning", these represent the bins and their output values.
|
|
* For just taking samples, these can be seen as an extention to the "Two Point Calibration" to model a more elaborate response curve of a sensor. (e.g. measuring water level in a round tank)
|
|
|
|
Often such curves will be modeled first in a spreadsheet program.
|
|
To simply copy/paste 2 columns of data from a spreadsheet into the task settings, one has to check "Split-Paste Multipoint Fields" first and then paste these columns into the first field.
|
|
By checking this checkbox, some JavaScript will be set active to decode the values and place them in separate fields.
|
|
|
|
|
|
When using "Binning", it can be useful to also have some formula to process the data first before mapping the data to the correct bin.
|
|
|
|
For example the wind vane with a 10k in series, connected to 3.3V.
|
|
To convert the measured voltage into a resistance, one can use this formula: ``(-10000*%value%)/(%value%-3.3)``
|
|
|
|
With the values converted into a resistance, one can simply use the stated values in the sensor datasheet.
|
|
|
|
.. image:: P002_multipoint_binning.png
|
|
|
|
|
|
Processing Order
|
|
----------------
|
|
|
|
All steps between ADC and output of the task are processed in the order they appear on the settings page:
|
|
|
|
* Attenuation (ESP32 only)
|
|
* Factory Calibration (ESP32 only)
|
|
* Two Point Calibration
|
|
* Multipoint Processing ("Binning formula" first when set to Binning)
|
|
* Formula at the bottom, when set.
|
|
|
|
|
|
Hall Effect Sensor (ESP32)
|
|
--------------------------
|
|
|
|
The ESP32 has a Hall Effect Sensor included, to measure a magnetic field.
|
|
|
|
N.B. This value can also be negative, if the polarity of the magnetic field is swapped.
|
|
|
|
Note that even the hall sensor is internal to ESP32, reading from it uses channels 0 and 3 of ADC1 (GPIO 36 and 39).
|
|
Do not connect anything else to these pins and do not change their configuration. Otherwise it may affect the measurement of low value signal from the sensor.
|
|
|
|
|
|
WiFi activity and ADC
|
|
---------------------
|
|
|
|
The ADC on the ESP8266 is also used during WiFi RF calibration.
|
|
This can result in incorrect readings of the ADC while a WiFi connection attempt is in progress.
|
|
|
|
ESP32 has 2 ADCs present.
|
|
``ADC1`` and ``ADC2``
|
|
|
|
Since the ``ADC2`` is shared with the WIFI module, which has higher priority, reading operation of ``adc2_get_raw()`` may fail between ``esp_wifi_start()`` and ``esp_wifi_stop()``.
|
|
|
|
|
|
Use of Formula
|
|
--------------
|
|
|
|
A very typical use case for using the ADC is to measure some resistance.
|
|
The best way to do this, is to have a constant current applied to this resistor.
|
|
This way the measured voltage over the resistor has a linear correlation with the resistance.
|
|
But that makes it somewhat complicated to connect such a sensor and it may also become rather difficult to find a good compromise between resolution and noise when the measured resistor can vary over a wide range.
|
|
|
|
The simplest way to connect such a resistor is by adding a second resistor in series.
|
|
However this makes the measured voltage no longer linear to the measured resistance.
|
|
|
|
Then we only need a way to compute the measured resistance instead of the voltage.
|
|
|
|
For this we first need to make sure the calibration is done so the ADC plugin outputs the correct voltage applied to the configured analog input pin.
|
|
|
|
Then we must derive a formula to convert the voltage into a resistance value.
|
|
|
|
For example the unknown resistor is r1 and the series resistor is r2.
|
|
|
|
With 3V3 applied to both resistors in series, the measured voltage ``v`` is:
|
|
|
|
``v = 3v3 / (r1 + r2) * r1``
|
|
|
|
This can be derived into:
|
|
|
|
``(-1 * r2 * v) / (v - 3v3)``
|
|
|
|
When using 10k as a value for r2, we can use this in the formula field:
|
|
|
|
``(-10000*%value%)/(%value%-3.3)``
|
|
|
|
With proper calibration and this formula present, we now get the measured resistance on the output.
|
|
|
|
|
|
Supported hardware
|
|
------------------
|
|
|
|
|P002_usedby|
|
|
|
|
.. Commands available
|
|
.. ^^^^^^^^^^^^^^^^^^
|
|
|
|
.. .. include:: P002_commands.repl
|
|
|
|
.. Events
|
|
.. ~~~~~~
|
|
|
|
.. .. include:: P002_events.repl
|
|
|
|
Change log
|
|
----------
|
|
|
|
.. versionchanged:: 2.0
|
|
...
|
|
|
|
|improved| 2020-04-25 Added support for ESP32 ADC pins + Hall Effect Sensor.
|
|
|
|
.. versionadded:: 1.0
|
|
...
|
|
|
|
|added|
|
|
Initial release version.
|