Current Sensor Configuration (ACS712 etc.)

1. Overview

Current sensors convert the current in a wire into a proportional voltage signal through the Hall effect. ESP32 collects this voltage through ADC, then converts it to actual current value through linear calibration.

Supported Sensor Models

Model	Range	Sensitivity	Zero-Current Output
ACS712-5A	±5A	185 mV/A	VCC/2 (1.65V@3.3V)
ACS712-20A	±20A	100 mV/A	VCC/2 (1.65V@3.3V)
ACS712-30A	±30A	66 mV/A	VCC/2 (1.65V@3.3V)

Working Principle

1. ACS712 internal Hall sensor detects wire current
2. Output voltage = VCC/2 + current × sensitivity
3. ESP32 ADC collects output voltage (12-bit, 0~4095)
4. Software conversion: I = (V_adc - V_offset) / sensitivity

Features

• 10-time multi-sample averaging to reduce ADC noise
• 200ms minimum read interval cache
• Lazy initialization, auto-configures ADC on first call
• Supports custom calibration parameters (sensitivity, zero offset, reference voltage)

When debugging current modules, first calibrate zero-current output, then gradually apply load; if readings drift, prioritize checking common ground, reference voltage, ADC attenuation, and sampling average parameters.

2. Wiring Instructions

ACS712 Module              ESP32
┌─────────────┐
│  VCC        │───────── 5V (module power)
│  GND        │───────── GND
│  OUT        │───────── GPIO34 (ADC pin)
│  IP+ / IP-  │───────── Current passes through
└─────────────┘

Notes:
- ACS712 module requires 5V power, but OUT output range is 0~VCC
- ESP32 ADC input maximum is 3.3V; if module is powered at 5V, a voltage divider is needed
- Recommend using 3.3V powered ACS712 modules, or add a voltage divider circuit
- Recommend GPIO34/35/36/39 (input-only pins, best ADC performance)

3. Configuration

Method 1: Web Interface Configuration (Recommended)

Before saving current sensor configuration, verify ADC pin, zero offset, sensitivity, and range protection.

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 Current Sensor Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	current_01	Unique identifier
   Name	ACS712 Current Detection	Display name
   Peripheral Type	GPIO Analog Input (type: 15)	ADC collection
   Pin Configuration	34	ADC pin (recommend 34-39)
   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. Check real-time current data

💡 Tip: ACS712 modules recommend 3.3V power; 5V modules need a voltage divider

---

Method 2: JSON Configuration File Import

Current sensors use GPIO_ANALOG_INPUT (type ID=15) or ADC (type ID=26) type to configure pins.

Peripheral Configuration Example (ADC Pin)

{
  "id": "current_01",
  "name": "ACS712 Current Detection",
  "type": 15,
  "enabled": false,
  "pinCount": 1,
  "pins": [34, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "attenuation": 3,
    "resolution": 12,
    "sampleRate": 5
  }
}

Field Description

Field	Meaning	Values
type	Peripheral type	15 (GPIO_ANALOG_INPUT) or 26 (ADC)
pins[0]	ADC pin	34/35/36/39 (input only) or other ADC-capable pins
params.attenuation	Attenuation coefficient	0=0dB, 1=2.5dB, 2=6dB, 3=11dB(3.3V)
params.resolution	Resolution	9~12 bits

4. Peripheral Execution Integration

Current sensors collect data via ACTION_SENSOR_READ (actionType=19) with SensorCategory::SENSOR_CURRENT(7).

Web Interface Configuration Steps

Create Current Collection Rule

1. Click Peripheral Execution in the left menu
2. Click the Add Rule button
3. Configure timer trigger:
   • Trigger Type: Timer Trigger
   • Execution Interval: 10 seconds
4. Add action:
   • Action Type: Sensor Read
   • Target Peripheral: current_01
   • Data Field: current
   • Sensitivity: 0.100 (ACS712-20A)
   • Zero Offset: 1.65
5. Enable Report Data After Execution
6. Click Save

Create Overcurrent Alarm Rule

1. Create a new rule
2. Configure event trigger:
   • Trigger Type: Event Trigger
   • Event ID: ds:current_01_current
   • Comparison: Greater Than
   • Comparison Value: 15.0 (A)
3. Add actions:
   • Action 1: Turn off relay
     • Action Type: Low Level
     • Target Peripheral: relay_01
   • Action 2: Trigger overcurrent event
     • Action Type: Trigger Event
     • Event ID: over_current
4. Click Save

💡 Tip: Sensitivity and zero offset must be calibrated based on actual sensor model

---

JSON Configuration Example

Current Collection Rule Configuration

{
  "id": "exec_current_read",
  "name": "Current Timed Collection",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 10
    }
  ],
  "actions": [
    {
      "targetPeriphId": "current_01",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"current_01\",\"sensorCategory\":\"current\",\"dataField\":\"current\",\"sensorLabel\":\"Current\",\"unit\":\"A\",\"decimalPlaces\":3,\"sensitivity\":0.100,\"zeroOffset\":1.65,\"vRef\":3.3,\"adcMax\":4095}"
    }
  ],
  "reportAfterExec": true
}

actionValue Format

Current sensor actionValue uses JSON string to pass read target and calibration parameters:

{
  "periphId": "current_01",
  "sensorCategory": "current",
  "dataField": "current",
  "sensorLabel": "Current",
  "unit": "A",
  "decimalPlaces": 3,
  "sensitivity": 0.100,
  "zeroOffset": 1.65,
  "vRef": 3.3,
  "adcMax": 4095
}

Parameter	Description	Example
sensitivity	Sensitivity (V/A)	0.100 (ACS712-20A)
zeroOffset	Zero offset voltage (V)	1.65 (VCC/2@3.3V)
vRef	ADC reference voltage (V)	3.3
adcMax	ADC maximum value	4095

Overcurrent Alarm Rule

{
  "id": "exec_current_alarm",
  "name": "Overcurrent Alarm",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ds:current_01_current",
      "operatorType": 2,
      "compareValue": "15.0"
    }
  ],
  "actions": [
    {
      "targetPeriphId": "relay_01",
      "actionType": 1,
      "actionValue": ""
    },
    {
      "targetPeriphId": "",
      "actionType": 21,
      "actionValue": "over_current"
    }
  ],
  "reportAfterExec": true
}

5. Calibration Methods

Zero Calibration

1. Disconnect the measured current (no current flowing)
2. Read the ADC value and convert to voltage
3. This voltage is the offset value (theoretical value VCC/2)

Sensitivity Calibration

1. Pass a known current (e.g., measure with a multimeter)
2. Record the voltage corresponding to the ADC reading
3. sensitivity = (V_measured - offset) / I_known

Common Calibration Parameter Quick Reference

Sensor Model	sensitivity	offset	Description
ACS712-5A @3.3V	0.185	1.65	Highest sensitivity
ACS712-20A @3.3V	0.100	1.65	Most commonly used
ACS712-30A @3.3V	0.066	1.65	High current scenarios
ACS712-20A @5V+divider	0.100	1.0	Adjust offset by divider ratio

6. Notes

1. ADC Accuracy: ESP32 ADC has significant non-linear error; recommend determining parameters through actual calibration
2. Noise Suppression: Driver has built-in 10-time sampling average; can appropriately increase sample count
3. 5V Modules: If module is powered at 5V, output may exceed 3.3V; must add voltage divider to protect ESP32
4. Wiring Distance: Keep analog signal lines as short as possible, away from interference sources
5. Safety Isolation: ACS712 has built-in isolation, but high-voltage/high-current scenarios still require safety attention
6. Power-On Stability: Sensor needs 5~10ms to stabilize after power-on; first read is already handled in the driver

7. FAQ

Q: Readings are not zero when no current flows?

• ACS712 zero offset may deviate from theoretical value due to imprecise supply voltage
• Obtain actual offset value through zero calibration

Q: Readings fluctuate significantly?

• Caused by ADC noise; can add hardware filter capacitor (100nF between OUT and GND)
• Software already does 10-time averaging, sufficient for most scenarios

Q: How to detect AC current?

• ACS712 supports AC/DC detection
• AC current requires sampling over a complete cycle and calculating RMS value
• Recommend sampling rate ≥ 20 × power frequency (50Hz → 1000Hz)