Ultrasonic Distance Alert Scenario

Scenario Description

Use an HC-SR04 ultrasonic sensor for periodic distance measurement. When an object is detected within a safe distance threshold, trigger a buzzer alarm and report alarm data via MQTT.

Required Peripherals

Peripheral	Type	Description
ultrasonic1	SENSOR(38)	HC-SR04 ultrasonic sensor
buzzer	GPIO_DIGITAL_OUTPUT(12)	Alarm buzzer

Complete Configuration Process

Method 1: Web Interface Configuration (Recommended)

This scenario requires first adding the HC-SR04 and alarm buzzer, then using peripheral execution rules for distance collection, threshold evaluation, and alarm actions.

Step 1: Configure Peripherals

Step 1: Open 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 HC-SR04 Ultrasonic Sensor

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	ultrasonic1	Ultrasonic distance
   Name	Ultrasonic Distance	Display name
   Peripheral Type	Universal Sensor (type: 38)	HC-SR04 driver
   Pin Configuration	5,18	Trig=GPIO5, Echo=GPIO18
   Sensor Category	ULTRASONIC	Ultrasonic
   Collection Interval	500	500ms (minimum 100ms)

3. Click Save

💡 Tip: pins[0]=Trig pin, pins[1]=Echo pin

Step 3: Add Alarm Buzzer

1. Click the Add Peripheral button again

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	buzzer	Alarm buzzer
   Name	Alarm Buzzer	Display name
   Peripheral Type	GPIO Digital Output (type: 12)	Buzzer control
   Pin Configuration	4	IN connected to GPIO4
   Initial State	0	Default off

3. Click Save

---

Step 2: Configure Peripheral Execution Rules

Rule 1: Timed Distance Measurement and Reporting

1. Click Peripheral Execution in the left menu

2. Click the Add Rule button

3. Fill in basic configuration:

   • Rule Name: Timed Distance Measurement
   • Report Data: ✅ Enabled
   • Enable: ✅ Enabled

4. Configure trigger:

   • Trigger Type: Select Timer Trigger
   • Timer Mode: Select Fixed Interval
   • Interval Time: 5 (5 seconds)

5. Configure action:

   • Action Type: Select Sensor Read
   • Target Peripheral: Select ultrasonic1

6. Click Save

---

Rule 2: Too Close Alarm

1. Create rule, name: Too Close Alarm

2. Trigger configuration:

   • Trigger Type: Select Platform Trigger
   • Target Peripheral ID: Enter ultrasonic1
   • Operator: Select Less Than (<)
   • Threshold: 30 (30cm)

3. Action configuration:

   • Action Type: Select Flash
   • Target Peripheral: Select buzzer
   • Flash Interval: 200 (200ms rapid beeping)

4. Click Save

---

Rule 3: Distance Recovered - Dismiss Alarm

1. Create rule, name: Distance Safe Dismiss

2. Trigger configuration:

   • Trigger Type: Select Platform Trigger
   • Target Peripheral ID: Enter ultrasonic1
   • Operator: Select Greater Than (>)
   • Threshold: 50 (50cm)

3. Action configuration:

   • Action Type: Select Low Level
   • Target Peripheral: Select buzzer

4. Click Save

💡 Tip:

• Alarm threshold 30cm, dismiss threshold 50cm, forming a 20cm hysteresis band
• Ultrasonic minimum sampling interval is 100ms; ≥500ms is recommended to avoid echo interference
• HC-SR04 requires 5V power; Echo outputs 5V — be mindful of ESP32 GPIO voltage tolerance (voltage divider recommended)

---

Method 2: JSON Configuration File Import

Distance Measurement Principle

1. Trig pin outputs a 10μs high-level pulse
2. Sensor emits ultrasonic wave and waits for echo
3. Echo pin outputs high level; duration = round-trip time
4. Distance(cm) = Duration(μs) × 0.034 / 2
5. Effective measurement range: 2cm ~ 400cm

Precautions

1. Hysteresis Band: Gap between alarm threshold (30cm) and dismiss threshold (50cm) prevents jitter
2. Sampling Interval: Ultrasonic minimum sampling interval is 100ms; ≥500ms is recommended to avoid echo interference
3. Blind Zone: HC-SR04 is inaccurate at close range (< 2cm)
4. Installation Angle: Sensor must face the target object directly; excessive angle causes no echo return
5. Power: HC-SR04 requires 5V power; Echo outputs 5V — be mindful of ESP32 GPIO voltage tolerance (voltage divider recommended)