Is HC-SR04 Ultrasonic Ranging Sensor Module Compatible with Home Assistant (ESPHome)?
Variants covered by this page
ESP32 / ESPHome HC-SR04 Ultrasonic Ranging Sensor Module
Pico W / MicroPython HC-SR04 Ultrasonic Distance Sensor
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Classic ultrasonic distance sensor measuring ranges from 2cm to 400cm with 3mm accuracy.
Wiring HC-SR04 Ultrasonic Ranging Sensor Module to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VCC | 5V | The original HC-SR04 is a 5V part and misreads at 3.3V. The HC-SR04P and RCWL-1601 variants run at 3.3V and need no divider on Echo. |
| GND | GND | |
| Trig | GPIO5 | Accepts a 3.3V pulse directly. |
| Echo | GPIO18 | Through a 1kΩ/2kΩ divider. Echo returns a 5V pulse on the original module. |
Host pins are the ones the configuration on this page uses. Move a pin here and change it in the YAML — they are documented together so they cannot disagree.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | GPIO Pulse / Voltage Divider |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | Distance Measurement (cm) Proximity Alarm State Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Plug-and-Play |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The ESP32 pins there are the ones the configuration uses, so if you move one, change it in both places.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_hcsr04_esphome.yaml and run esphome run emb_esp32_hcsr04_esphome.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
Distance in Home Assistant tracks a book moved towards the sensor down to a couple of centimetres. A permanent NaN is the divider on Echo or a soft target; a value that never changes is Trig.
ESPHome Configuration
Starting configuration for HC-SR04 Ultrasonic Ranging Sensor Module on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for HC-SR04 Ultrasonic Ranging Sensor Module
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_hcsr04_esphome
friendly_name: "HC-SR04 Ultrasonic Ranging Sensor Module"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
sensor:
- platform: ultrasonic
trigger_pin: GPIO5
echo_pin: GPIO18
name: "Distance"
update_interval: 60s
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
What Appears in Home Assistant
In metres, with device class distance. Home Assistant shows it in the unit your profile prefers.
Not in the config: a binary_sensor: platform: template comparing Distance to a threshold is a two-line addition once you know the tank or the parking spot.
Known Problems and Fixes
Echo is 5V
On the original module the Echo pulse is at the supply voltage. The divider is not optional on an ESP32; the pin is not 5V-tolerant. The 3.3V variants exist precisely to skip it.
It cannot see soft or angled things
Fabric, foam and anything at more than about 15° off square absorb or deflect the ping and return nothing. Water surfaces are good targets; a person in a jumper is a poor one. NaN in the log is "no echo", not a fault.
Set the timeout for the range
The component gives up waiting for an echo at the distance in timeout, which defaults to 2m. For a 4m reading raise it; for a 50cm tank, lower it and readings come back faster.
Filter it
Single readings jump by a centimetre or two. A median filter over five samples and an update interval of a second or two, rather than the 60s in the config, is the usual tank-level setup.
Not for damp places
Condensation on the transducers stops them working, and it does not dry out inside a tank. The waterproof JSN-SR04T and A02YYUW exist for that.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for HC-SR04 Ultrasonic Ranging Sensor Module? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-hcsr04-esphome)
Frequently Asked Questions
Does HC-SR04 Ultrasonic Ranging Sensor Module work without an internet connection?
How is HC-SR04 Ultrasonic Ranging Sensor Module powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
JSN-SR04T Waterproof Ultrasonic Sensor
The waterproof version on a cable, for tanks and outdoors.
A02YYUW Waterproof Ultrasonic Sensor
Waterproof, UART output, a narrower beam.
VL53L0X Time-of-Flight Distance Sensor
Laser, millimetre resolution, indifferent to soft targets, up to 2m.
TOF10120 Laser Rangefinder Module
Another laser rangefinder with a UART option.