当前位置：首页 > news >正文

US-016模拟电压输出超声波测距传感器在衡山派开发板上的RT-Thread驱动移植与测试

news 2026/5/11 22:13:53

US-016模拟电压输出超声波测距传感器在衡山派开发板上的RT-Thread驱动移植与测试

最近在衡山派（HSPI）开发板上做项目，需要用到非接触式测距功能，US-016这款模拟电压输出的超声波传感器正好符合要求。它量程有2cm到3米，输出是线性的模拟电压，和单片机连接起来特别方便。今天我就把整个驱动移植和测试的过程，手把手地分享给大家，从硬件连接到软件配置，再到代码编写和实际测试，保证你跟着做一遍就能用起来。

1. 认识US-016传感器

US-016是一款市面上比较少见的、采用模拟电压输出的超声波测距模块。它最大的特点就是输出一个和测量距离成正比的模拟电压信号，这样我们只需要用一个单片机的ADC（模数转换器）引脚去读取这个电压值，再通过公式换算就能得到距离，省去了处理复杂数字协议（如I2C、UART）的麻烦，特别适合快速集成。

1.1 核心特性与参数

咱们先看看这个模块的基本情况，了解它的“脾气”才好用它。

工作原理：模块发射超声波，遇到障碍物后反射回来，模块根据回波时间计算出距离，并将这个距离值线性地转换成一个0到Vcc（供电电压）之间的模拟电压，从OUT引脚输出。
量程切换：模块上有一个Range引脚，可以用来切换量程。
- 当Range引脚悬空或接高电平时，量程为3米。
- 当Range引脚接低电平时，量程为1米。
关键参数：根据原始资料，它的主要规格如下：

参数	规格
工作电压	3.3V - 5V
工作电流	3.8mA
感应角度	< 15度
可测距离	2cm - 300cm (3米)
测量精度	0.3cm + 1%
输出方式	模拟电压
引脚数量	4 Pin (VCC, GND, OUT, Range)

1.2 距离换算公式

这是驱动开发的核心。模块输出的电压Vout与距离L成正比，与供电电压Vcc有关。

当量程为1米时（Range接低电平）：距离 L (单位: mm) = 1024 * (Vout / Vcc)当Vout = 0V时，对应距离0m；当Vout = Vcc时，对应距离1.024m。
当量程为3米时（Range悬空或接高电平）：距离 L (单位: mm) = 3072 * (Vout / Vcc)当Vout = 0V时，对应距离0m；当Vout = Vcc时，对应距离3.072m。

注意：在咱们的驱动代码里，默认将Range引脚悬空，所以使用的是3米量程的公式。如果你需要1米量程的高精度模式，记得把Range引脚接到开发板的GND上，并且修改代码中的宏定义。

2. 硬件连接与引脚选择

硬件连接很简单，一共就4根线。咱们以衡山派开发板为例进行连接。

接线表：

US-016模块引脚	衡山派开发板引脚	说明
VCC	3.3V 或 5V	模块供电，接3.3V或5V都可以，注意代码中`Vcc`参数要对应修改。
GND	GND	共地。
OUT	GPAI_CH6 (ADC通道6)	模拟信号输出，连接到ADC输入引脚。代码中固定使用了GPAI的通道6。
Range	悬空	量程选择。悬空即为3米量程。如需1米量程，则接GND。

提示：GPAI是衡山派芯片的通用ADC接口。确保你选择的引脚支持ADC功能。这里我们按原始代码，使用通道6。

3. 驱动移植与工程配置

接下来是重头戏，把驱动代码集成到你的RT-Thread工程里。我一般会把这个过程分为三步：放代码、改配置、编译烧录。

3.1 获取并放置驱动文件

首先，你需要拿到驱动源码。根据原始资料，驱动文件包可以在相关下载中心找到（资料下载链接已包含在原始内容中）。

假设你已经下载并解压了驱动包，里面应该包含以下几个关键文件：

bsp_us016.c- 传感器底层驱动（ADC读取、距离计算）
bsp_us016.h- 驱动头文件
Kconfig- RT-Thread的图形化配置菜单选项
SConscript- SCons构建系统的脚本
test_us_016_sensor.c- 测试线程和MSH命令示例

操作步骤：

在你的衡山派RT-Thread工程目录下（例如luban-lite/application/rt-thread/helloworld/），找到一个名为user-bsp的文件夹。这是专门存放用户自己移植的板级支持包（BSP）代码的地方。
在user-bsp文件夹下，新建一个文件夹，例如us-016-sensor。
将上述驱动文件全部复制到这个us-016-sensor文件夹内。

3.2 修改Kconfig文件

为了让我们的驱动选项出现在RT-Thread的menuconfig配置菜单里，需要修改工程的Kconfig文件。

用VSCode或其他编辑器打开你工程中的Kconfig文件，路径通常是：application/rt-thread/helloworld/Kconfig。
在这个文件的末尾，endif语句之前，添加一行，引入我们刚才放的驱动包的Kconfig路径。

# US-016超声波测距传感器 source "application/rt-thread/helloworld/user-bsp/us-016-sensor/Kconfig"

这行代码的作用是告诉构建系统：“嘿，去us-016-sensor文件夹里找找，那里还有别的配置选项”。

3.3 使用 menuconfig 启用驱动

现在，我们可以通过图形化界面来启用这个驱动了。

打开命令行，进入你的工程根目录（例如luban-lite）。
运行环境配置脚本（例如win_env.bat，根据你的系统而定），然后输入以下命令进入配置菜单：
```
scons --menuconfig
```
在出现的配置界面中，使用方向键导航。首先找到并进入Porting code using the LCKFB module这个菜单。
在这个子菜单里，你应该能看到一个选项叫USing us016 sensor。
按Y键选中它（前面会出现一个*号）。
按左右方向键选择<Save>保存配置，然后一路退出(<Exit>)即可。

小技巧：在menuconfig里，按Y是编译进内核，按N是排除，按M是编译成模块。这里我们选Y。

3.4 编译与烧录

配置保存好后，就可以编译了。

在工程根目录下，运行编译命令。为了加快速度，可以用-j参数指定并行编译的线程数（比如你的CPU是8核16线程，可以用-j16）。
```
scons -j16
```
编译成功后，会在输出目录（例如output/d13x_JLC_rt-thread_helloworld/images/）下生成一个镜像文件，如d13x_JLC_v1.0.0.img。
使用烧录工具（如PhoenixSuit，Allwinner系列常用）将这个img文件烧录到衡山派开发板中。

4. 驱动代码解析与测试

烧录完成，硬件也接好了，现在上电，通过串口工具（如MobaXterm, Putty）连接到开发板的控制台（Shell）。串口波特率默认是115200。

4.1 核心驱动函数解析

咱们来看看bsp_us016.c这个文件里都干了啥。理解了原理，出问题才好调试。

初始化US016_Init：这个函数负责找到并打开ADC设备（名字是”gpai”），然后使能我们用的第6通道。代码里加了200ms的延时，是为了让ADC模块稳定下来。

int US016_Init(void) { // 1. 查找ADC设备 adc_dev = (struct rt_adc_device *)rt_device_find(ADC_DEVICE_NAME); if (adc_dev == RT_NULL) { LOG_E("Failed to open %s device", ADC_DEVICE_NAME); return RT_ERROR; } // 2. 使能ADC通道 int ret = rt_adc_enable(adc_dev, ADC_CHANNEL); if(ret != RT_EOK) { LOG_E("Failed to [rt_adc_enable] !!!"); return RT_ERROR; } aicos_mdelay(200); // 延时等待稳定 return RT_EOK; }

读取电压值US016_Get_Value（静态函数）：这是内部函数，负责从ADC读取原始的数值，并转换成实际的电压值。

多次采样：连续读取5次ADC值，只累加有效值（0到4095之间，12位ADC）。
计算平均：用有效值的总和除以有效次数，得到平均ADC值，减少偶然误差。
换算电压：根据公式电压 = (参考电压 / 4095) * ADC平均值。衡山派开发板的ADC参考电压VREF_ADC_HSPI是2.5V。
电压还原：因为硬件设计可能对电压进行了分压，所以最后乘以2得到传感器输出的真实电压。这里是个关键点，如果你的板子电路不同，这个系数可能需要调整。

获取距离US016_Get_distance：这是给上层应用调用的主要函数。

调用US016_Get_Value()获取电压Vadc。
根据RANGE宏的定义（代码中定义为0，代表3米量程），选择对应的公式计算距离。
- 3米量程：距离(mm) = 3072 * (Vadc / Vcc)
- 1米量程：距离(mm) = 1024 * (Vadc / Vcc)
注意：代码中的Vcc固定写成了3.3。如果你的传感器实际供电是5V，一定要把这里的3.3改成5.0，否则计算出的距离会错！

4.2 使用MSH命令进行测试

驱动包里已经写好了一个测试程序test_us_016_sensor.c，它创建了一个线程来循环读取距离，并且导出了两个MSH命令，用起来非常方便。

在串口终端里，输入以下命令启动传感器测试线程：
```
test_us016_sensor
```
提示：输入test_us后按TAB键可以自动补全命令。
如果一切正常，你会看到终端开始周期性地（默认1秒1次）打印出测量的距离，单位是厘米，格式类似：
```
Read Distance = 25.36cm
```
当循环显示约100次后，程序会提示你可以输入退出命令。
要停止测试，输入以下命令：
```
test_exit_us016_sensor
```
这个命令会删除测试线程并反初始化传感器。

4.3 常见问题与调试心得

读数全是0或者非常大/小：
- 检查硬件连接：VCC、GND是否接好？OUT线是否接到了正确的ADC引脚（GPAI_CH6）？
- 检查供电电压：确认US016_Get_distance函数里计算时使用的Vcc值（代码里是3.3）是否和实际给传感器供电的电压一致。
- 检查ADC参考电压：确认代码中VREF_ADC_HSPI（2.5V）是否与你的开发板ADC参考电压一致。
读数跳动大：
- 超声波容易受到环境干扰。确保传感器前方没有柔软的、不平整的障碍物。
- 尝试在US016_Get_Value函数中增加采样次数（修改count变量），并适当增加每次采样间的延时（aicos_mdelay(5)）。
命令找不到：
- 确认menuconfig配置已正确保存并生效。
- 确认编译没有错误，并且烧录的是新编译的镜像。
- 在MSH中输入list_device命令，查看是否有”gpai”这个ADC设备。