超声波模块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 根线传感器引脚接法VCC5V 电源GNDGND务必与主控共地否则回波无法计时Trig数字引脚积木可选 P0 / P1 / P2 / P8 / P12~P16Echo另一个数字引脚可选范围同上⚠️ 两个易踩的坑① Trig 与 Echo不可接反Trig 是输出、Echo 是输入② Echo 输出为 5V 高电平若主控引脚不耐 5V建议先经电平转换再接入。二、构造 HCSR04 实例2 个必选参数 1 个可选打开 library/sonar.py 可以看到构造函数签名from sonar import HCSR04 sonar HCSR04(0, 1) # TrigP0EchoP1 sonar HCSR04(0, 1, echo_timeout_us30000) # 显式指定回波超时参数说明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) # TrigP0EchoP1 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()返回NoneNone * 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「超声波距离值」积木示意图掌握HCSR04构造函数 distance_cm()这一个方法就掌握了这个超声波模块 Python API 的全部能力三行代码完成构造与测距剩下的只是把距离读数用进你的避障、停车、液位检测等创意项目里吧【免费下载链接】CupCode_HC-SR04超声波传感器模块源师兄扩展项目: 超声波模块 | 由源师兄组织创建项目地址: https://gitcode.com/yuanshixiong/ultrasonic-module创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考