1. 项目概述树莓派上的超声波测距与显示系统如果你手头有一块树莓派 4B想用它来做点既实用又能直观看到结果的硬件项目那么这个超声波测距与显示系统绝对是个绝佳的选择。它本质上是一个微型雷达利用超声波传感器测量前方障碍物的距离并将实时数据清晰地显示在一块屏幕上。这听起来像是机器人避障或者智能小车的基础模块没错但它能做的远不止于此。你可以把它变成一个桌面上的“电子尺”用来测量小物件的尺寸或者改装成一个简易的液位监测器甚至结合摄像头做一个带距离感知的安防监控探头。这个项目的魅力在于它完美融合了硬件连接、GPIO控制、数据采集和软件界面开发是学习嵌入式系统和物联网IoT入门的经典实践。对于刚接触树莓派的朋友这个项目能让你快速上手GPIO通用输入输出引脚的使用理解传感器如何与计算机“对话”。对于有一定经验的开发者你可以深入探索如何优化测量精度、设计更美观的图形界面或者将数据上传到云端。整个过程涉及的核心技术点非常清晰树莓派 4B作为控制大脑HC-SR04超声波传感器作为“眼睛”一块LCD或OLED屏幕作为“嘴巴”来告诉我们它“看”到了什么。接下来我会带你从零开始一步步拆解每个环节包括硬件怎么连、代码怎么写、界面如何设计以及我踩过哪些坑、如何让测量更稳定。你会发现用树莓派玩转硬件其实并没有想象中那么复杂。2. 核心硬件选型与连接原理2.1 主控与传感器为什么是树莓派 4B 和 HC-SR04选择树莓派 4B作为核心控制器主要看中它几个无可替代的优势。首先是强大的通用性其40针的GPIO接口标准且丰富足以驱动各类传感器和执行器。其次是充沛的计算能力四核Cortex-A72处理器在处理传感器数据、运行显示界面乃至轻量级AI推理时都游刃有余这比传统的单片机如Arduino在复杂逻辑和多媒体处理上强得多。最后是生态树莓派拥有最庞大的社区和教程资源任何问题几乎都能找到解决方案这对学习和项目迭代至关重要。超声波传感器方面HC-SR04几乎是行业标准。它价格低廉通常不到10元、原理简单、易于使用。其工作原理是典型的“回声定位”控制端发出一个至少10微秒的高电平触发信号传感器会自动发射8个40kHz的超声波脉冲并开始计时。当超声波遇到障碍物反射回来传感器接收到回波后会输出一个高电平脉冲脉冲的宽度与超声波往返的时间成正比。我们只需要用树莓派测量这个高电平脉冲的持续时间就能计算出距离。计算公式为距离 (声速 × 时间) / 2。在标准大气压下声速约为343米/秒或34300厘米/秒。这里除以2是因为时间是往返时间。注意HC-SR04的测量范围官方标称是2cm到400cm但实际有效范围通常在3cm到200cm之间且测量精度受温度、湿度、障碍物表面材质影响较大。对于绝对精度要求高的场景这不是最佳选择但对于大多数定性或相对测量应用它完全够用。2.2 显示单元选型从字符屏到高清屏的权衡显示部分的选择直接决定了项目的交互体验和复杂度。常见的有以下几种方案16x2字符LCD屏这是最经典、最简单的选择。通过I2C转接板连接只需要占用树莓派两个GPIOSDA, SCL编程简单功耗低。缺点是只能显示两行英文或数字信息展示有限且视觉效果比较“复古”。OLED显示屏如0.96寸或1.3寸SSD1306驱动这是我个人非常推荐的选择。它同样是I2C接口但显示效果是自发光的像素点对比度高可视角度好可以显示图形和自定义字体。虽然尺寸小但用来显示一个动态的距离数字和简单的条形图或波形图科技感十足。HDMI接口的显示器或电视直接利用树莓派的HDMI输出配合图形化桌面环境如Raspbian Desktop或图形库如Tkinter, PyGame创建窗口应用。优点是显示面积大界面可以做得非常华丽可以同时显示距离曲线、历史数据、摄像头画面等。缺点是系统资源占用高且项目无法脱离大型显示器独立运行。SPI接口的TFT彩屏如ILI9341驱动这类屏幕色彩鲜艳分辨率较高可以通过SPI接口驱动刷新率比I2C高适合需要动态图形界面的场合。但接线和驱动相对复杂一些。对于本项目为了平衡易用性、视觉效果和独立性我将以I2C接口的0.96寸OLED屏SSD1306作为主要示例进行讲解。它能让整个系统保持小巧、低功耗并且编程模型清晰。2.3 硬件连接实战与电路图解析让我们开始动手连接。你需要准备树莓派 4B、HC-SR04超声波传感器、0.96寸OLED屏带I2C接口、若干杜邦线母对母。接线图与原理组件引脚连接到树莓派 GPIO说明HC-SR04VCCPin 2 (5V)提供5V工作电压。注意树莓派GPIO逻辑电平是3.3V而HC-SR04的Echo脚输出是5V电平不能直接接HC-SR04TrigPin 11 (GPIO 17)触发引脚。树莓派从此脚输出一个脉冲信号触发传感器发射超声波。HC-SR04EchoPin 13 (GPIO 27)回波引脚。传感器从此脚输出高电平脉冲。必须分压HC-SR04GNDPin 6 (GND)接地。OLED屏VCCPin 1 (3.3V)OLED屏通常工作电压为3.3V。OLED屏GNDPin 9 (GND)接地。OLED屏SDAPin 3 (SDA1)I2C数据线。OLED屏SCLPin 5 (SCL1)I2C时钟线。关键安全步骤5V至3.3V电平转换这是新手最容易烧毁树莓派的地方。HC-SR04的Echo脚输出是5V TTL电平而树莓派GPIO的耐受电压是3.3V直接连接可能损坏GPIO。因此必须在Echo脚和树莓派GPIO 27之间加入一个分压电路。 最简单的方案是使用两个电阻组成分压器一个1kΩ电阻连接在Echo脚和GPIO 27之间一个2kΩ电阻连接在GPIO 27和GND之间。这样5V输入会在GPIO 27上被分压到大约3.33V5V * (2k/(1k2k))处于安全范围。你也可以直接购买现成的逻辑电平转换模块。连接完成后硬件部分就准备好了。在通电前务必再三检查接线特别是电源和地线不要接反电平转换电路是否正确。3. 软件环境配置与核心库安装3.1 操作系统准备与基础设置首先确保你的树莓派已经安装了操作系统。推荐使用官方的Raspberry Pi OS原Raspbian并建议使用带桌面环境的版本方便初期调试。你可以使用Raspberry Pi Imager工具将系统烧录到MicroSD卡。系统启动并完成基本设置语言、网络等后第一件事是启用I2C和SPI接口因为我们的OLED屏需要通过I2C通信。打开终端运行sudo raspi-config。选择Interface Options-I2C 选择“是”以启用ARM I2C接口。同样在Interface Options下也可以启用SPI虽然本项目未使用但为未来扩展方便。选择“Finish”并重启树莓派。重启后可以通过命令ls /dev/i2c-*来检查I2C是否启用成功。如果看到/dev/i2c-1说明成功。3.2 Python库依赖安装我们将使用Python进行编程因为它对树莓派GPIO的支持非常好且库丰富。确保你的系统已安装Python3Raspberry Pi OS通常预装。打开终端依次安装以下必需的库RPi.GPIO这是控制树莓派GPIO引脚的标准库。sudo apt update sudo apt install python3-rpi.gpiosmbus2或smbus用于I2C通信的库。sudo apt install python3-smbusPillow一个强大的图像处理库用于在OLED上绘制图形和文字。sudo apt install python3-pilAdafruit SSD1306 和 Adafruit GPIO这是Adafruit公司提供的、用于驱动SSD1306 OLED屏的Python库。虽然可以通过pip安装但通过系统包管理器安装依赖更简单。sudo apt install python3-pip sudo pip3 install adafruit-circuitpython-ssd1306这个库会依赖adafruit-blinka它是一个兼容CircuitPython的硬件API层能自动识别我们在树莓派上运行。安装完成后你可以通过一个简单的I2C扫描程序来确认OLED屏是否被正确识别。创建一个名为i2c_scan.py的文件import board import busio i2c busio.I2C(board.SCL, board.SDA) while not i2c.try_lock(): pass try: print(I2C addresses found:, [hex(device_address) for device_address in i2c.scan()]) finally: i2c.unlock()运行python3 i2c_scan.py。如果OLED屏连接正常你应该会看到一个地址通常是0x3c。这确认了硬件和基础软件通道是畅通的。4. 超声波测距的核心代码实现与优化4.1 基础测距函数从脉冲宽度到厘米距离有了硬件和库的支持我们现在可以编写最核心的测距函数。这个函数要完成三件事发送触发信号、监听回波脉冲、计算脉冲宽度并转换为距离。import RPi.GPIO as GPIO import time # 设置GPIO模式为BCM编号 GPIO.setmode(GPIO.BCM) # 定义引脚 TRIG_PIN 17 ECHO_PIN 27 # 设置引脚模式 GPIO.setup(TRIG_PIN, GPIO.OUT) GPIO.setup(ECHO_PIN, GPIO.IN) def measure_distance(): 执行一次超声波测距返回以厘米为单位的距离。 如果超时或测量无效返回 None。 # 确保触发引脚先保持低电平 GPIO.output(TRIG_PIN, False) time.sleep(0.01) # 短暂稳定 # 发送10微秒的高电平触发脉冲 GPIO.output(TRIG_PIN, True) time.sleep(0.00001) # 10微秒 GPIO.output(TRIG_PIN, False) # 等待回波引脚变为高电平超声波发出 pulse_start time.time() timeout pulse_start 0.04 # 设置40ms超时对应约6.8米 while GPIO.input(ECHO_PIN) 0 and pulse_start timeout: pulse_start time.time() # 等待回波引脚变为低电平超声波返回 pulse_end time.time() while GPIO.input(ECHO_PIN) 1 and pulse_end timeout: pulse_end time.time() # 计算脉冲持续时间 pulse_duration pulse_end - pulse_start # 计算距离声速取34300 cm/s除以2是往返距离 distance pulse_duration * 17150 # 34300 / 2 17150 # 简单的有效性检查在传感器量程内2cm - 400cm if 2 distance 400: return round(distance, 2) else: return None # 测试代码 if __name__ __main__: try: while True: dist measure_distance() if dist: print(f距离: {dist} cm) else: print(测量无效或超时) time.sleep(1) # 每秒测量一次 except KeyboardInterrupt: print(测量停止) GPIO.cleanup()这段代码是测距的核心。measure_distance函数严格按照HC-SR04的时序要求编写。这里有几个关键细节time.sleep(0.00001)这是10微秒的精确触发。time.sleep函数在Linux下精度有限但对于10微秒这个量级在树莓派上基本可用。如果追求极高精度可以考虑使用GPIO.wait_for_edge或硬件PWM但对于本项目软件延时已足够。超时机制两个while循环都加入了超时判断pulse_start timeout。这是至关重要的防卡死设计。如果传感器故障或前方没有障碍物回波引脚可能永远不会变化程序就会永远卡在循环里。40ms的超时对应大约6.8米的测量距离上限是合理的。声速与单位公式distance pulse_duration * 17150是计算的核心。17150是声速34300 cm/s的一半。结果单位是厘米。4.2 提高测量稳定性滤波与多采样平均直接使用单次测量结果往往噪声很大读数会跳动。在实际应用中我们必须对数据进行滤波处理。最常用且有效的方法是多采样取中值或平均值。def measure_distance_stable(sample_times5): 进行多次采样去除异常值后取平均值提高稳定性。 :param sample_times: 采样次数 :return: 稳定的距离值厘米或 None distances [] for _ in range(sample_times): dist measure_distance() # 调用基础测距函数 if dist: # 只收集有效数据 distances.append(dist) time.sleep(0.02) # 每次采样间隔20ms给传感器恢复时间 if not distances: return None # 去除可能的最大最小值一种简单的去噪 if len(distances) 2: distances.remove(max(distances)) distances.remove(min(distances)) # 计算平均值 stable_distance sum(distances) / len(distances) return round(stable_distance, 2)这个改进函数做了两件事首先它快速连续测量5次可调其次它去除了这5次中的最大值和最小值假设它们是偶然的异常跳动然后对剩下的数据取平均。这种方法能有效平滑数据让显示的数字不再频繁跳动用户体验会好很多。实操心得time.sleep(0.02)这个间隔很重要。HC-SR04两次测量之间需要短暂的恢复时间如果连续触发太快会导致测量不准甚至传感器发热。20ms是一个经验值。另外采样次数sample_times不是越多越好。次数太多会导致整体响应变慢。对于实时显示5到7次是一个很好的平衡点。5. OLED显示屏的驱动与界面设计5.1 初始化屏幕与显示基础信息现在我们将稳定的距离数据显示到OLED屏上。首先初始化屏幕然后在一个循环中不断更新显示内容。import board import busio import digitalio from PIL import Image, ImageDraw, ImageFont import adafruit_ssd1306 # 创建I2C总线对象 i2c busio.I2C(board.SCL, board.SDA) # 创建OLED屏幕对象这里假设是128x64分辨率 WIDTH 128 HEIGHT 64 oled adafruit_ssd1306.SSD1306_I2C(WIDTH, HEIGHT, i2c, addr0x3c) # 清空屏幕 oled.fill(0) oled.show() # 创建绘图对象 image Image.new(1, (oled.width, oled.height)) draw ImageDraw.Draw(image) # 加载字体使用PIL的默认字体或指定一个TTF字体文件 # 默认字体较小 font_small ImageFont.load_default() # 如果需要大字体可以加载一个TTF文件需提前放入项目目录 # font_large ImageFont.truetype(/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf, 20) def display_distance(distance_cm): 在OLED屏幕上绘制距离信息 # 每次绘制前清空图像缓冲区用黑色填充 draw.rectangle((0, 0, oled.width, oled.height), outline0, fill0) # 绘制标题 draw.text((10, 0), Ultrasonic Ranging, fontfont_small, fill255) # 绘制一条分隔线 draw.line((0, 15, oled.width, 15), fill255, width1) # 绘制距离数值 - 使用大字体效果这里用默认字体放大位置模拟 # 将距离值转换为字符串并格式化为固定宽度 dist_str f{distance_cm:6.1f} cm # 计算文本位置使其居中这里简单估算 text_x 20 text_y 25 draw.text((text_x, text_y), dist_str, fontfont_small, fill255) # 绘制一个简单的条形图来直观表示距离距离越近条形越长 max_bar_width 100 max_distance 200 # 假设最大显示200cm bar_length int((distance_cm / max_distance) * max_bar_width) if distance_cm max_distance else max_bar_width # 反转距离越近条形越长更危险 bar_length max_bar_width - bar_length draw.rectangle((14, 50, 14 bar_length, 58), outline255, fill255) # 在条形图下方标注 draw.text((10, 40), Proximity:, fontfont_small, fill255) # 将缓冲区图像显示到OLED oled.image(image) oled.show()这段代码构建了一个简单的图形界面。它包含一个标题、一条分隔线、一个居中显示的距离数值带单位、一个表示接近程度的条形图距离越近条形越长和一个标签。ImageDraw提供了丰富的绘图功能你可以轻松地添加更多元素比如历史数据曲线、电池图标等。5.2 主循环与系统集成最后我们把测距和显示两部分结合起来形成一个完整的、持续运行的系统。import time import signal import sys def signal_handler(sig, frame): 捕获CtrlC信号进行清理 print(程序终止...) oled.fill(0) oled.show() GPIO.cleanup() sys.exit(0) # 注册信号处理器 signal.signal(signal.SIGINT, signal_handler) print(超声波测距与显示系统启动。按 CtrlC 停止。) try: while True: # 1. 获取稳定的距离数据 distance measure_distance_stable(sample_times5) # 2. 在终端打印用于调试 if distance: print(f当前距离: {distance} cm) else: print(无法获取有效距离) distance 0 # 显示一个默认值或错误提示 # 3. 更新OLED显示 display_distance(distance if distance else 0) # 4. 控制刷新频率例如每秒2-5次 time.sleep(0.2) except Exception as e: print(f发生错误: {e}) GPIO.cleanup() oled.fill(0) oled.show()主循环的逻辑很清晰测量 - 处理 - 显示 - 等待 - 循环。这里将刷新间隔设置为0.2秒5Hz这个频率对于人眼观察距离变化已经足够流畅同时又不会给树莓派带来太大负担。signal_handler函数确保了当我们按下CtrlC终止程序时GPIO引脚会被正确释放屏幕会被清空这是一个良好的编程习惯。6. 性能优化、故障排查与扩展思路6.1 常见问题与解决方案速查表在实际操作中你几乎一定会遇到下面这些问题。这里我整理了常见故障和解决方法。问题现象可能原因排查步骤与解决方案测量结果始终为0或极小值1. 触发信号太短或未发出。2. Echo引脚一直为高电平可能接线错误或传感器损坏。3. 物体距离太近2cm超出传感器最小量程。1. 用gpio readall或万用表检查Trig引脚是否有10us脉冲。2. 检查Echo引脚接线和电平转换电路。断开Echo线测量传感器Echo脚是否有脉冲输出。3. 将传感器对准远处空旷地方测试。测量结果巨大或不稳定如几百厘米跳动1. 没有收到有效的回波超时函数返回了错误计算值。2. 声波被吸收或散射如对准海绵、窗帘。3. 环境噪声干扰其他超声波源。1. 在代码中增加超时判断和无效值过滤如我们做的if 2 distance 400。2. 确保传感器正对坚硬、平整的物体表面测试。3. 尝试在传感器VCC和GND之间加一个10uF的电解电容稳定电源。OLED屏幕不亮或显示乱码1. I2C地址错误。2. 电源接错OLED是3.3V设备接5V可能烧毁。3. 未正确启用I2C接口。4. 库未正确安装或版本冲突。1. 运行I2C扫描程序确认设备地址通常是0x3c或0x3d。2.立即检查OLED的VCC是否接在3.3V上3. 运行sudo raspi-config确认I2C已启用。4. 尝试重新安装adafruit-circuitpython-ssd1306库。程序报错No module named boardAdafruit Blinka库硬件抽象层未正确安装或环境有问题。运行sudo pip3 install adafruit-blinka。确保在树莓派本地终端运行而不是在虚拟环境中除非你主动配置了虚拟环境。测量有固定偏差声速随温度变化。公式中的17150是20°C下的值。引入温度传感器如DS18B20进行实时温度补偿。修正公式distance pulse_duration * (331.3 0.606 * temperature) * 50其中temperature是摄氏温度结果单位是厘米。6.2 高级优化中断与定时器提升响应速度在主循环中使用time.sleep和轮询Echo引脚的方式会占用CPU并限制系统响应其他事件的能力。一个更高级的优化是使用GPIO中断和硬件定时器。思路将Echo引脚设置为中断触发模式当它从低变高上升沿时开始计时从高变低下降沿时停止计时。这样CPU就不需要忙等待可以去处理其他任务比如更新更复杂的UI。import threading from datetime import datetime class UltrasonicSensor: def __init__(self, trig_pin, echo_pin): self.TRIG trig_pin self.ECHO echo_pin self.distance None self.pulse_start None self.lock threading.Lock() GPIO.setup(self.TRIG, GPIO.OUT) GPIO.setup(self.ECHO, GPIO.IN) GPIO.add_event_detect(self.ECHO, GPIO.BOTH, callbackself._echo_callback) def _echo_callback(self, channel): Echo引脚中断回调函数 if GPIO.input(self.ECHO): # 上升沿超声波发出 self.pulse_start time.time() else: # 下降沿超声波返回 if self.pulse_start: pulse_end time.time() duration pulse_end - self.pulse_start with self.lock: self.distance duration * 17150 # 计算距离 self.pulse_start None def get_distance(self): 触发一次测量并获取距离 with self.lock: self.distance None # 发送触发脉冲 GPIO.output(self.TRIG, False) time.sleep(0.005) GPIO.output(self.TRIG, True) time.sleep(0.00001) GPIO.output(self.TRIG, False) # 等待一小段时间让回调函数完成计算 time.sleep(0.03) with self.lock: return self.distance # 使用示例 sensor UltrasonicSensor(TRIG_PIN17, ECHO_PIN27) while True: dist sensor.get_distance() if dist and 2 dist 400: display_distance(dist) time.sleep(0.1)这种中断方式将测距过程“异步化”提高了系统的并发能力。但请注意中断回调函数中不能做太耗时的操作并且对共享变量如self.distance的访问需要加锁threading.Lock以防止竞态条件。6.3 项目扩展与创意应用这个基础项目可以作为一个平台向多个方向扩展多传感器网络连接多个HC-SR04传感器注意GPIO资源分配实现多角度测距用于机器人全景环境感知。数据可视化与记录使用matplotlib库在树莓派本地或通过VNC远程桌面绘制实时距离-时间曲线图。或者将数据写入CSV文件用于后续分析。阈值报警与自动化控制设置一个距离阈值如20cm当物体接近时让树莓派控制一个LED灯闪烁、蜂鸣器响起或者通过继电器控制其他电器开关。Web界面远程监控使用Flask或FastAPI框架创建一个简单的Web服务器。将距离数据通过网页实时推送给用户你可以在手机或电脑浏览器上远程查看测距情况。与摄像头结合使用树莓派官方摄像头模块在视频画面上实时叠加距离信息。这可以用于智能停车辅助系统或具有深度感知的监控。集成到智能家居平台通过MQTT协议将距离数据发布到Home Assistant或Node-RED等平台当传感器检测到有人靠近工作台时自动打开台灯。这个项目的代码和硬件结构清晰每一步都有明确的物理意义和软件对应。从最基础的引脚控制到中断优化从静态显示到动态交互它为你打开了一扇通往树莓派硬件编程和物联网世界的大门。最重要的是动手去做在调试和解决问题的过程中你的收获会远超这几千字的教程。