Voltage Sensor Configuration (Divider ADC)

1. Feature Overview

Voltage sensors use a resistor voltage divider network to reduce voltages higher than the ESP32 ADC range (3.3V) to a safe range, then the ADC collects the value and restores the actual voltage through the divider ratio.

Application Scenarios

• Battery voltage monitoring (3.7V/7.4V/12V/24V lithium batteries)
• Solar panel voltage detection
• Power supply voltage monitoring
• Industrial sensor 0_5V/010V signal acquisition

Working Principle

Vin ─── R1 ──┬── R2 ─── GND
              │
              └── ADC Pin (Vout)

Vout = Vin × R2 / (R1 + R2)
Vin = Vout × (R1 + R2) / R2 = Vout × ratio
ratio = (R1 + R2) / R2

Common Divider Ratios

R1	R2	ratio	Max Measurable Voltage (ADC full scale 3.3V)
30KΩ	7.5KΩ	5.0	16.5V
100KΩ	10KΩ	11.0	36.3V
47KΩ	10KΩ	5.7	18.8V
10KΩ	10KΩ	2.0	6.6V

Features

• 10-sample averaging to reduce ADC noise
• 200ms minimum read interval caching
• Lazy initialization; ADC auto-configured on first call (12-bit/11dB attenuation)
• Supports custom divider ratio and reference voltage parameters

Voltage collection belongs to ADC input. Before wiring, verify that the divided voltage does not exceed the ESP32 ADC range. During debugging, record both the raw ADC value and the converted actual voltage simultaneously.

2. Wiring Instructions

Measured Voltage Source (Vin)
    │
    ├── R1 (e.g., 30KΩ)
    │
    ├──────────────── GPIO34 (ESP32 ADC pin)
    │
    ├── R2 (e.g., 7.5KΩ)
    │
    └── GND ─────── ESP32 GND

Notes:
- R1 + R2 form a voltage divider, Vout = Vin × R2/(R1+R2)
- Ensure Vout ≤ 3.3V, otherwise ESP32 will be damaged
- A 100nF capacitor in parallel between the ADC pin and GND is recommended for filtering
- GPIO34/35/36/39 are recommended (input-only, better ADC accuracy)

Commercial Voltage Detection Modules

Common DC 0-25V voltage detection modules have built-in divider circuits (typically ratio=5.0):

Voltage Detection Module       ESP32
┌─────────────┐
│  VCC (+)    │───────── Measured voltage positive (≤25V)
│  GND (-)    │───────── Measured voltage negative + ESP32 GND
│  S (Signal) │───────── GPIO34 (ADC pin)
└─────────────┘

3. Configuration Methods

Method 1: Web Interface Configuration (Recommended)

Verify ADC pin, divider ratio, and maximum input voltage before saving the voltage sensor.

Step 1: Navigate to Peripheral Management Page

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

Step 2: Add Voltage Sensor Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	voltage_01 or battery_12v	Unique identifier
   Name	Voltage Detection (0-25V) or 12V Battery Voltage	Display name
   Peripheral Type	GPIO Analog Input (type: 15)	ADC collection
   Pin Configuration	34 or 35	ADC pin (34-39 recommended)
   Attenuation	3	11dB(0-3.3V)
   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. View real-time voltage data

💡 Tip: Calculate the divider ratio based on actual resistors; commercial modules typically have ratio=5.0

---

Method 2: JSON Configuration File Import

{
  "id": "voltage_01",
  "name": "Voltage Detection (0-25V)",
  "type": 15,
  "enabled": false,
  "pinCount": 1,
  "pins": [34, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleRate": 5
  }
}

12V Battery Monitoring Configuration

{
  "id": "battery_12v",
  "name": "12V Battery Voltage",
  "type": 15,
  "enabled": false,
  "pinCount": 1,
  "pins": [35, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleRate": 5
  }
}

4. Peripheral Execution Linkage

Web Interface Configuration Steps

Create Voltage Collection Rule

1. Switch to the Peripheral Execution Management tab
2. Click the Add Rule button
3. Configure the timer trigger:
   • Trigger Type: Timer Trigger
   • Execution Interval: 30 seconds
4. Add action:
   • Action Type: Sensor Read
   • Target Peripheral: voltage_01
   • Data Field: voltage
   • Divider Ratio: 5.0 (adjust according to actual values)
5. Enable Report Data After Execution
6. Click Save

Create Battery Under-Voltage Alarm Rule

1. Create a new rule
2. Configure event trigger:
   • Trigger Type: Event Trigger
   • Event ID: ds:battery_12v_voltage
   • Comparison Operation: Less Than
   • Comparison Value: 10.5 (V)
3. Add actions:
   • Action 1: Trigger low battery event
     • Action Type: Trigger Event
     • Event ID: low_battery
   • Action 2: Disconnect load
     • Action Type: Low Level
     • Target Peripheral: load_relay
4. Click Save

💡 Tip: The under-voltage protection threshold for 12V lithium batteries is typically 10.5V

---

JSON Configuration Examples

Voltage Timed Collection Rule

{
  "id": "exec_voltage_read",
  "name": "Voltage Timed Collection",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 30
    }
  ],
  "actions": [
    {
      "targetPeriphId": "voltage_01",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"voltage_01\",\"sensorCategory\":\"voltage\",\"dataField\":\"voltage\",\"sensorLabel\":\"Voltage\",\"unit\":\"V\",\"decimalPlaces\":2,\"ratio\":5.0,\"vRef\":3.3,\"adcMax\":4095}"
    }
  ],
  "reportAfterExec": true
}

actionValue Format

The voltage sensor's actionValue uses a JSON string to pass read target and calibration parameters:

{
  "periphId": "voltage_01",
  "sensorCategory": "voltage",
  "dataField": "voltage",
  "sensorLabel": "Voltage",
  "unit": "V",
  "decimalPlaces": 2,
  "ratio": 5.0,
  "vRef": 3.3,
  "adcMax": 4095
}

Parameter	Description	Example
ratio	Divider ratio (R1+R2)/R2	5.0 (30K/7.5K)
vRef	ADC reference voltage (V)	3.3
adcMax	ADC maximum value	4095

Low Voltage Alarm Rule (Battery Under-Voltage Protection)

{
  "id": "exec_low_voltage",
  "name": "Battery Under-Voltage Alarm",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ds:battery_12v_voltage",
      "operatorType": 3,
      "compareValue": "10.5"
    }
  ],
  "actions": [
    {
      "targetPeriphId": "",
      "actionType": 21,
      "actionValue": "low_battery"
    },
    {
      "targetPeriphId": "load_relay",
      "actionType": 1,
      "actionValue": ""
    }
  ],
  "reportAfterExec": true
}

5. Calibration Methods

Method 1: Known Resistor Values

Direct calculation: ratio = (R1 + R2) / R2

Method 2: Measured Calibration

1. Apply a known voltage (e.g., measured with a multimeter)
2. Read the ESP32's raw ADC value
3. Measured Vout = ADC * 3.3 / 4095
4. ratio = Vin_known / Measured Vout

Accuracy Optimization Tips

• Use 1% precision resistors (metal film resistors)
• Connect a 100nF ceramic capacitor in parallel at the divider output
• ESP32 ADC has non-linearity; segmented calibration or lookup tables are recommended
• Multiple sample averaging (driver has built-in 10-sample averaging)

6. Precautions

1. Over-Voltage Protection: Ensure divided voltage ≤ 3.3V; a 20% margin is recommended
2. Input Impedance: R1+R2 total resistance should be 10K~100K; too low wastes current, too high is affected by ADC input impedance
3. Isolation Safety: High-voltage detection (e.g., mains power) must use an isolated voltage transformer; direct division is not safe
4. Temperature Drift: Metal film resistors have low temperature coefficients (±50ppm/°C); carbon film resistors have higher temperature coefficients
5. Pin Selection: GPIO34-39 are input-only pins with the most stable ADC characteristics
6. Common Ground Reference: The measured voltage GND must be connected to ESP32 GND

7. FAQ

Q: Readings have significant deviation?

• ESP32 ADC non-linearity error can reach ±3%; calibrate ratio with actual measurements
• Check if resistors are precise (measure actual resistance with a multimeter)
• Ensure ADC input is not floating (always have the divider connected to GND)

Q: Readings fluctuate noticeably?

• Add a 100nF filter capacitor at the divider output
• Increase sampling count (software has built-in 10-sample averaging)
• Check if the power supply is stable

Q: How to detect negative voltages?

• ESP32 ADC does not support negative voltage input
• Use an op-amp to offset the signal to the positive voltage range
• Or use a differential ADC module (e.g., ADS1115)

Q: How to connect 0~10V industrial signals?

• Use ratio=3.33 (e.g., R1=23.3K, R2=10K)
• Ensure at maximum input 10V, Vout = 10/3.33 = 3.0V < 3.3V