phlangone/hc_sr04

readme

# HC-SR04 ESP-IDF Driver

HC-SR04 ultrasonic distance sensor driver for ESP-IDF.

This component provides a small, blocking, GPIO-based driver for measuring distance with the HC-SR04 ultrasonic sensor.

The driver uses GPIO for the trigger/echo signals and `esp_timer_get_time()` for pulse-width measurement. It does not install a GPIO ISR service and does not use global driver state.

## Supported ESP-IDF Versions

- ESP-IDF v4.4+
- ESP-IDF v5.x

Tested target:

- ESP32

## Installation

Add the component to your ESP-IDF project:

```bash
idf.py add-dependency "phlangone/hc_sr04^2.0.0"
```

Or add it manually to your project's `idf_component.yml`:

```yaml
dependencies:
  phlangone/hc_sr04: "^2.0.0"
```

## Hardware Notes

The HC-SR04 ECHO pin usually outputs 5 V.

ESP32 GPIOs are not 5 V tolerant. Use a voltage divider or level shifter between the HC-SR04 ECHO pin and the ESP32 input GPIO.

On ESP32, GPIOs 34 to 39 are input-only. They can be used as `echo_pin`, but they cannot be used as `trigger_pin`.

## Basic Usage

```c
#include "hc_sr04.h"

hc_sr04_handle_t sensor = NULL;

hc_sr04_config_t config =
{
    .trigger_pin = GPIO_NUM_4,
    .echo_pin = GPIO_NUM_5,
    .timeout_us = 30000,
    .sound_speed_cm_per_us = 0.0f
};

ESP_ERROR_CHECK(hc_sr04_new_sensor(&config, &sensor));

float distance_cm = 0.0f;
esp_err_t ret = hc_sr04_read_cm(sensor, &distance_cm);

if (ret == ESP_OK)
{
    // Use distance_cm
}
```

For complete examples, see the `examples/` directory.


## API

```c
esp_err_t hc_sr04_new_sensor(const hc_sr04_config_t *config, hc_sr04_handle_t *out_handle);
esp_err_t hc_sr04_del_sensor(hc_sr04_handle_t handle);

esp_err_t hc_sr04_read_cm(hc_sr04_handle_t handle, float *out_distance_cm);
esp_err_t hc_sr04_read_pulse_us(hc_sr04_handle_t handle, uint32_t *out_pulse_us);
```

### Configuration

```c
typedef struct
{
    gpio_num_t trigger_pin;
    gpio_num_t echo_pin;
    uint32_t timeout_us;
    float sound_speed_cm_per_us;
} hc_sr04_config_t;
```

Use `timeout_us = 0` to select the default timeout.

Use `sound_speed_cm_per_us = 0.0f` to select the default speed of sound.


## Error Handling

All public functions return `esp_err_t`.

Common return values:

- `ESP_OK`
- `ESP_ERR_INVALID_ARG`
- `ESP_ERR_NO_MEM`
- `ESP_ERR_TIMEOUT`
- `ESP_FAIL`

Example:

```c
float distance_cm = 0.0f;
esp_err_t ret = hc_sr04_read_cm(sensor, &distance_cm);

if (ret == ESP_OK)
{
    ESP_LOGI(TAG, "distance: %.2f cm", distance_cm);
}
else
{
    ESP_LOGW(TAG, "measurement failed: %s", esp_err_to_name(ret));
}
```

## Blocking Behavior

`hc_sr04_read_cm()` and `hc_sr04_read_pulse_us()` are blocking functions.

Do not call them from ISR context.

Avoid calling them from high-priority or timing-critical tasks.


## License

MIT