ADC Analog Input

Overview

ADC (Analog-to-Digital Converter) is used to collect analog signals such as light intensity, smoke concentration, flame intensity, soil moisture, and other analog sensor output voltages. ESP32 has a built-in 12-bit ADC that can convert 0~3.3V analog voltage to 0~4095 digital values.

Supported Peripheral Types

Type	type Value	Description
GPIO_ANALOG_INPUT	15	GPIO analog input (simple mode)
ADC	26	ADC dedicated mode (with attenuation/resolution parameters)

ADC Parameter Description

Parameter	Description	Options
attenuation	Attenuation coefficient	0=0dB(1.1V), 1=2.5dB(1.5V), 2=6dB(2.2V), 3=11dB(3.3V)
resolution	Resolution (bits)	9, 10, 11, 12
sampleRate	Sample rate	0=Default

Common configuration: attenuation=3 (full scale 3.3V) + resolution=12 (0~4095)

Before connecting ADC, verify input voltage, attenuation, resolution, and WiFi impact on ADC2; when troubleshooting on-site, it is recommended to save raw values, converted values, and sampling intervals simultaneously.

Available Pins

• ESP32 ADC1: GPIO 32-39 (recommended, still available when WiFi is enabled)
• ESP32 ADC2: GPIO 0, 2, 4, 12-15, 25-27 (not available when WiFi is enabled)
• ESP32-C3: GPIO 0-4 (ADC1)
• ESP32-S3: GPIO 1-10 (ADC1), GPIO 11-20 (ADC2)

Important: When using WiFi, only ADC1 channel pins can be used!

Typical Sensor Applications

Sensor	Output Range	Description
Photoresistor	0~3.3V	Lower voltage with stronger light
MQ-2 Smoke	0~3.3V	Higher voltage with higher concentration
Flame Sensor	0~3.3V	Lower voltage when flame is closer
Rain Drop Sensor	0~3.3V	Lower voltage with more rain
Sound Sensor	0~3.3V	Higher voltage with louder sound
Soil Moisture	0~3.3V	Lower voltage with higher moisture

Configuration

Method 1: Web Interface Configuration (Recommended)

Before saving ADC peripherals, verify input pins, range conversion parameters, and whether voltage divider protection is in place.

Step 1: Navigate to Peripheral Management Page

1. Open a browser and navigate to the ESP32 IP address
2. After logging in, click Peripheral Configuration in the left menu

Step 2: Add ADC Analog Input Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	light_sensor or smoke_sensor	Unique identifier
   Name	Light Intensity or MQ-2 Smoke Sensor	Display name
   Peripheral Type	GPIO Analog Input (type: 15) or ADC (type: 26)	Simple mode or dedicated mode
   Pin Configuration	36 or 34	Must use ADC1 pins
   Attenuation	3	3=11dB(0-3.3V full scale)
   Resolution	12	12-bit=0-4095

3. Click Save

Step 3: Verify Configuration

1. Find the newly added peripheral in the peripheral list
2. Click the Enable toggle
3. Check real-time ADC values

⚠️ Important: ADC1 pins (GPIO 32-39) must be used when WiFi is enabled

---

Method 2: JSON Configuration File Import

Add the following configuration to the peripherals array in data/config/peripherals.json:

Light Sensor

{
  "id": "light_sensor",
  "name": "Light Intensity",
  "type": 15,
  "enabled": false,
  "pins": [36],
  "params": {
    "initialState": 0,
    "pwmChannel": 0,
    "pwmFrequency": 1000,
    "pwmResolution": 8,
    "defaultDuty": 0
  }
}

ADC Dedicated Configuration (Smoke Sensor)

{
  "id": "smoke_sensor",
  "name": "MQ-2 Smoke Sensor",
  "type": 26,
  "enabled": false,
  "pins": [34],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleRate": 0
  }
}

Multi-Channel ADC Collection

{
  "id": "adc_multi",
  "name": "Environment Monitoring ADC",
  "type": 26,
  "enabled": false,
  "pins": [36, 39, 34, 35],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleRate": 0
  }
}

Peripheral Execution Integration

As Poll Trigger Data Source

ADC values can be periodically collected by peripheral execution rules via ACTION_SENSOR_READ(19):

{
  "targetPeriphId": "smoke_sensor",
  "actionType": 19,
  "actionValue": "",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

As Platform Trigger Condition

Collected ADC values are reported via MQTT and can be used for platform trigger conditions:

{
  "triggerType": 0,
  "triggerPeriphId": "smoke_sensor",
  "operatorType": 2,
  "compareValue": "2000"
}

Meaning: Trigger rule when smoke sensor ADC value > 2000

Voltage/Current Sensors

For scenarios requiring ADC value conversion to actual physical quantities, refer to:

• Current Sensor — ACS712 and other current measurements
• Voltage Sensor — Voltage divider measurements

Engineering Units and Quality

Industrial AI (analog input) can perform conversion through persistent parameters such as signalMode, conversionEnabled, calibratedVoltage, inputMin/inputMax, and engineeringMin/engineeringMax. The default configuration preserves raw ADC behavior; front-end parameters must match the engineering-unit range, and readings whose quality indicates conversion failure, disconnection, or out-of-range must not be treated as a normal zero value.

Conversion Fields

After selecting 0-10V, 0-20mA, 4-20mA, or custom linear mode, the Web UI automatically enables engineering-unit conversion and fills in common input ranges; advanced calibration items are collapsed by default, and usually only the engineering-unit lower and upper limits need to be filled in.

Field	Default	Description
signalMode	0	0=raw value, 1=0-10V, 2=0-20mA, 3=4-20mA, 4=custom linear
conversionEnabled	false	Whether to output engineering units; when off, raw ADC reporting is kept
inputMin / inputMax	Derived from signal type	Input signal range; 4-20mA defaults to 4/20
engineeringMin / engineeringMax	0/100	Engineering-unit range corresponding to the sensor nameplate
engineeringOffset	0	Field calibration offset of the conversion result
clampEnabled	false	Clamp when out of range; when off, the current reading is invalid and reporting stops
vRef	3.3	ADC reference voltage
voltageRatio	1	Divider restoration ratio for the 0-10V front end
shuntResistance	165	Current-loop shunt resistor, in Ω
inputGain / inputOffset	1/0	Analog front-end gain and voltage offset

The conversion formula is EU=(INPUT-INPUTmin)/(INPUTmax-INPUTmin)×(EUmax-EUmin)+EUmin+engineeringOffset. In 4-20mA mode, the ADC voltage is first converted to mA using the shunt resistor and front-end gain; in 0-10V mode, it is first converted to the input voltage using the divider restoration ratio. ESP32 pins cannot directly accept 10V or a current loop; a suitable divider, isolation, or shunt front end must be used.

The new fields are backward compatible: old configurations lacking the new fields use safe default values and keep their original behavior.

Acquisition Quality and Reporting

After engineering-unit conversion is enabled, the value and the acquisition quality are handled separately:

quality	qualityCode	Meaning
valid	0	Input is within the configured range
low	1	Input is below range but has not reached the 4-20mA disconnection threshold
high	2	Input is above range but has not reached the 4-20mA short/overdrive threshold
disconnected	3	4-20mA input is less than inputMin - 1mA; for the standard range, less than 3mA
short	4	4-20mA input is greater than inputMax + 1mA; for the standard range, greater than 21mA
invalid_config	5	Signal type, range, engineering-unit range, or other configuration is invalid

GET /api/peripherals/read?id=<peripheral ID> returns rawValue, value, valueValid, quality, and qualityCode together. When clamping is off, an abnormal reading has a value of null and valueValid=false; when clamping is on, the original abnormal quality is still kept and only the value is limited to the engineering-unit endpoints. When conversion is enabled and the mode is not raw, periodic MQTT additionally reports a <peripheral ID>_quality property, e.g. ai_soil_temp_quality=disconnected; when abnormal and not clamped, the value property is omitted but the quality property is still reported.

A plain analog read in Peripheral Execution directly reuses the conversion result of the peripheral configuration, so range and calibration parameters are maintained in a single place; the action's own scaleFactor/offset can still be used for a final secondary adjustment.

The legacy read categories for voltage-divider and current sensors have separate action calibration parameters — see Voltage and Current — to avoid double conversion; for NTC thermistor temperature measurement, see NTC Thermistor. For ADC resource lifecycle, sampling failures, and multi-consumer behavior, see the ADC lifecycle document.

Save a disabled draft first, complete the wiring/resource review, then enable the peripheral, read, verify quality, and finally enable the periodic rule. Calibrate using actual measurements from a multimeter or a standard source; raw * 3.3 / 4095 must not be treated as a measured voltage.

Notes

1. WiFi and ADC2 Conflict: ADC2 is not available when WiFi is enabled; production environments must use ADC1 pins
2. ESP32 ADC Non-linearity: ESP32 native ADC has non-linearity at both ends (near 0V and 3.3V), with better accuracy in the middle range
3. Reference Voltage: ESP32 internal reference voltage is approximately 1.1V, expanded range through attenuation coefficient
4. Multi-Channel Collection: Same ADC type peripheral can configure multiple pins, system polls sequentially
5. Sampling Noise: Recommend multiple sample averaging for ADC readings (system has built-in 10-time averaging for current/voltage sensors)