鸟语天空

ESP32 超声波传感器(HC-SR04)

作者：追风剑情 发布于：2026-6-9 2:10 分类：物联网

一、安装驱动

idf.py add-dependency "vgerwen/hcsr04^1.0.0"

二、编写代码

hcsr04_control.h

#ifndef HCSR04_CONTROL_H
#define HCSR04_CONTROL_H

#include <stdint.h>

/**
 * @brief 初始化超声波传感器
 */
void hcsr04_init(void);

/**
 * @brief 获取障碍物距离
 * @return 距离（厘米），若测量失败或超出范围则返回 -1.0
 */
float hcsr04_get_distance(void);

#endif // HCSR04_CONTROL_H

hcsr04_control.c

#include "hcsr04_control.h"
#include "hcsr04_driver.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

static const char *TAG = "HCSR04";
static bool is_initialized = false;

// 定义最大测量距离（厘米），用于计算超时
#define MAX_DISTANCE_CM     400

void hcsr04_init(void)
{
    esp_err_t ret;

    // 1. 初始化超声波传感器硬件驱动
    ret = UltrasonicInit();
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "超声波驱动初始化失败: %s", esp_err_to_name(ret));
        is_initialized = false;
        return;
    }

    // 2. 尝试读取一次以验证传感器是否正常响应
    uint32_t distance_mm = 0;
    ret = UltrasonicMeasure(MAX_DISTANCE_CM * 10, &distance_mm);
    if (ret == ESP_OK) {
        ESP_LOGI(TAG, "超声波模块初始化成功。首次读数: %.1f cm", (float)distance_mm);
        is_initialized = true;
    } else if (ret == ESP_ERR_ULTRASONIC_ECHO_TIMEOUT) {
        ESP_LOGW(TAG, "超声波模块初始化：首次测量超时（距离可能超出 %d cm）。", MAX_DISTANCE_CM);
        // 超时也可能是正常情况，比如面前没有障碍物，此处仍认为模块初始化成功
        is_initialized = true;
    } else {
        ESP_LOGE(TAG, "超声波模块初始化失败。请检查接线。错误码: %s", esp_err_to_name(ret));
        is_initialized = false;
    }
}

float hcsr04_get_distance(void)
{
    if (!is_initialized) {
        ESP_LOGE(TAG, "超声波模块未初始化，无法测量距离。");
        return -1.0;
    }

    uint32_t distance_mm = 0;
    // 执行测量，传入最大距离（毫米），测量结果也以毫米为单位
    esp_err_t ret = UltrasonicMeasure(MAX_DISTANCE_CM * 10, &distance_mm);

    if (ret == ESP_OK) {
        // 距离值有效，转换为厘米并返回
        return (float)distance_mm;
    } else if (ret == ESP_ERR_ULTRASONIC_ECHO_TIMEOUT) {
        // 测量超时，通常意味着距离超出范围或前方没有障碍物
        ESP_LOGW(TAG, "测量超时，障碍物可能超出 %d cm。", MAX_DISTANCE_CM);
        return -1.0;
    } else {
        // 其他类型的错误
        ESP_LOGE(TAG, "距离测量失败: %s", esp_err_to_name(ret));
        return -1.0;
    }
}

标签: IoT