超声波模块Python API完全参考：HCSR04类从构造到distance

超声波模块Python API完全参考：HCSR04类从构造到distance_cm()全解析（附示例代码）

【免费下载链接】CupCode_HC-SR04超声波传感器模块源师兄扩展项目: 超声波模块 | 由源师兄组织创建项目地址: https://gitcode.com/yuanshixiong/ultrasonic-module

源师兄出品的CupCode_HC-SR04 超声波传感器模块是一个基于源师兄主控板的超声波测距扩展：只需 Trig / Echo 两根数字引脚连线，即可测量前方障碍物的距离，并按厘米或毫米输出读数。整个驱动核心就是 library/sonar.py 里的一个HCSR04类——本文带你从构造函数到distance_cm()测距方法，完整掌握这份超声波模块 Python API，新手也能一次上手 📡

一、HC-SR04 超声波模块是什么？如何接线 🔌

HC-SR04 是一款四线数字测距传感器（不是 I²C 设备）：向传感器发一个触发脉冲，它发出超声波并接收回波，用「高电平持续时间」换算出距离。接线只需 4 根线：

传感器引脚	接法
VCC	5V 电源
GND	GND（务必与主控共地，否则回波无法计时）
Trig	数字引脚（积木可选 P0 / P1 / P2 / P8 / P12~P16）
Echo	另一个数字引脚（可选范围同上）

⚠️ 两个易踩的坑：① Trig 与 Echo不可接反（Trig 是输出、Echo 是输入）；② Echo 输出为 5V 高电平，若主控引脚不耐 5V，建议先经电平转换再接入。

二、构造 HCSR04 实例：2 个必选参数 + 1 个可选

打开 library/sonar.py 可以看到构造函数签名：

from sonar import HCSR04 sonar = HCSR04(0, 1) # Trig=P0，Echo=P1 sonar = HCSR04(0, 1, echo_timeout_us=30000) # 显式指定回波超时

参数	说明
`trigger_pin`	触发引脚编号（数字引脚，如`0`对应 P0），内部设为输出，初始化时拉低
`echo_pin`	回波引脚编号，内部设为输入
`echo_timeout_us`（可选）	回波超时时间（微秒），默认 30000 µs，约对应 5 m 量程；超时则判定「超出测量范围」

构造完成后，你就有了一个可以反复调用测距的HCSR04实例。

三、核心方法 distance_cm()：一次调用拿到厘米距离 🎯

d = sonar.distance_cm() # 例如返回 23.45（厘米）

这一行背后做了三件事：

触发：Trig 引脚输出 10 µs 高电平脉冲，启动一次测距；
计时：测量 Echo 引脚高电平的持续时间（time_pulse_us）；
换算：按声速 343 m/s（即 0.0343 cm/µs）计算，因声波是往返传播所以除以 2，最后保留两位小数返回。

返回值的三种情况要记牢：

返回值	含义
浮点数（如`23.45`）	有效距离，单位厘米
`0`	有回波但距离无效
`None`	回波超时：超出量程（默认约 5 m）、目标表面倾斜或为吸音材料

💡 需要毫米读数？直接sonar.distance_cm() * 10即可，但必须先判断返回值不是None，否则乘法会抛异常。

四、示例代码：连续测距 + 避障判断 🤖

把上面两部分组合起来，就是一个最常用的超声波测距程序：

from sonar import HCSR04 import utime sonar = HCSR04(0, 1) # Trig=P0，Echo=P1 while True: d = sonar.distance_cm() if d is not None and d < 20: print("⚠️ 前方有障碍物！距离:", d, "cm") else: print("当前距离:", d) utime.sleep_ms(500) # 每 0.5 秒测一次

把d < 20的阈值改大改小，就能快速实现不同灵敏度的超声波避障逻辑。

五、零代码方案：一块「超声波距离值」积木搞定

如果你用图形化积木编程，category.json 中注册的超声波分类下自带一块积木，无需手写任何代码：

只需三个下拉选择：

单位：厘米/毫米；
Trig 为/Echo 为：必须与实际接线一一对应。

积木生成的 Python 代码定义在 blocksdef.js 中，等价于：

from sonar import HCSR04 ultra_1 = HCSR04(0, 1) # 以 Echo 引脚命名实例，如 ultra_1 ultra_1.distance_cm() # 选「毫米」时自动 * 10

可见积木与手写 API 是完全同源的——理解了HCSR04，也就完全看懂了积木底层在做什么。

六、一分钟排障：读数不对怎么办？🔍

现象	原因与对策
读数一直为 0	检查 Trig/Echo 是否接反、积木引脚选择是否与接线一致；确认 5V 已供电、GND 已共地
返回`None`	超出测量范围：默认 30000 µs 超时效应约 5 m 量程，缩短距离或更换测量目标；也可调小`echo_timeout_us`
毫米模式报错	超量程时`distance_cm()`返回`None`，`None * 10`会抛异常，取毫米值前先判空
读数跳动明显	超声波对角度、表面材质敏感，属正常现象；建议多次测量取平均，或固定传感器避免抖动
引脚冲突	请从下拉提供的 P0 / P1 / P2 / P8 / P12~P16 中选择，避免与板上其他功能冲突

七、项目文件速查表 📁

文件	作用
library/sonar.py	核心源码：`HCSR04`类（构造 +`distance_cm()`）
README.md	硬件接线、积木与 Python API 完整文档
blocksdef.js	积木定义及其生成的 Python 代码
category.json	积木分类「超声波」注册配置
config.json	扩展名称、描述等元信息
images/ohcode_extend_1.png	「超声波距离值」积木示意图