企业官网建设流程全解析

超声波模块项目结构剖析：config.json、category.json、blocksdef.js、sonar.py四件套是如何协作的？

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

HC-SR04 超声波传感器是新手入门测距的常用硬件，但「超声波模块」扩展包在背后究竟是怎么工作的？本文以CupCode_HC-SR04 超声波传感器模块扩展项目为例，用通俗易懂的方式带你剖析 config.json、category.json、blocksdef.js 和 library/sonar.py 这四个文件是如何分工协作，把一块积木变成可用的超声波测距工具的，无需深厚编程基础也能看懂。

📁 项目目录一瞥

整个扩展包结构非常精简，核心就是「四件套」加一份文档：

🪪 config.json：模块的「身份名片」

打开 config.json，你会发现它只有寥寥数行：

• Device：标明目标硬件为「大师兄板」
• Name：模块显示名为「HC-SR04超声波」
• Description：一句话功能描述——「获取到障碍物的距离」

它是整个扩展包的「门面」，平台靠它知道这个扩展叫什么、装在哪块开发板上。改名字、换硬件，第一步就是改这里。

📂 category.json：决定积木出现在哪里

category.json 是积木在工具箱中的「注册表」：

• name：分类名「超声波」，也就是积木菜单里显示的分类
• colour：#cc0033，即分类的深红色（后续 blocksdef.js 中积木颜色与它保持一致）
• contents：登记了唯一的积木类型ohcode_extend_1

简单说：config.json 管「模块叫什么」，category.json 管「积木摆在哪」。少了这一步，积木就无处安放。

🧩 blocksdef.js：画出积木并生成 Python 代码

blocksdef.js 是整个扩展包中最「聪明」的文件，它身兼两职：

积木界面定义

在 blocksdef.js 中，平台用 Blockly 描述语言画出「超声波距离值」积木：一个单位下拉框（厘米/毫米）、一个Trig引脚下拉框、一个Echo引脚下拉框（可选 P0 / P1 / P2 / P8 / P12~P16）。用户拖积木、选参数，全部发生在这里。

一键生成 Python 代码

更关键的是 blocksdef.js 中的代码生成器：当用户点击「生成代码」时，积木会被自动翻译成类似下面的 Python 片段——

from sonar import HCSR04 ultra_0 = HCSR04(0, 0) # Trig=P0, Echo=P0 print(ultra_0.distance_cm()) # 毫米模式则为 * 10

注意细节：实例名由Echo 引脚号决定（如ultra_0），选择「毫米」时自动乘以 10。你不需要手写任何一行 Python，积木参数就直接决定了代码内容。

🐍 library/sonar.py：真正的「发动机」

积木生成的代码最终都指向 library/sonar.py 中的HCSR04驱动类，核心原理是「声纳计时」：

1. 向 Trig 引脚发送10 微秒的高电平脉冲触发发射
2. 用time_pulse_us()测量 Echo 引脚回波高电平的持续时间
3. 按声速 343 m/s 换算成距离，除以 2（声波是往返的），保留两位小数返回

几个新手友好的设计（见 sonar.py）：

• 超时保护：默认回波超时 30000 µs，约合 5 米量程，超量程返回None而不是死等
• 单位换算：distance_cm()返回厘米，毫米只需× 10

🔗 四件套协作全景：从点击到测距

把四个文件串起来，一次完整的测距是这样流动的：

1. config.json→ 平台识别出这是「HC-SR04超声波」模块
2. category.json→ 「超声波距离值」积木出现在工具箱的超声波分类
3. blocksdef.js→ 用户选单位、选引脚 → 自动生成HCSR04(...).distance_cm()代码
4. sonar.py→ Trig 触发、Echo 计时 → 算出厘米/毫米距离

四个文件各管一段，互不干扰：改硬件适配改config.json，调分类颜色改category.json，加参数改blocksdef.js，优化测距算法才动sonar.py——这就是模块化设计的魅力。

💡 新手上手小贴士

结合 README.md 的常见问题，记住三点少走弯路：

• 读数一直为 0：先查 Trig/Echo 是否接反、积木里的引脚是否与实际接线一致
• 返回 None：超出量程（默认约 5 米），把障碍物拉近再试
• 毫米模式：超量程时读数无效，使用前先判断是否为None

📚 延伸资料

• 完整接线与积木用法：README.md
• 底层驱动源码：library/sonar.py
• 积木定义与代码生成：blocksdef.js

掌握这套「四件套」协作模式后，你再看其他传感器扩展包，也能一眼读懂它们的门道。

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