基于YOLOv5与ESP32的智能垃圾分类系统：从AI视觉到硬件控制的完整实践

1. 项目概述与核心价值

每次看到小区里颜色各异的垃圾桶，以及旁边依然混杂着各种垃圾的投放口，我就在想，如果扔垃圾这件事能像过马路看红绿灯一样直观就好了。这个念头，加上手头闲置的ESP32开发板和一台旧笔记本，催生了这个智能垃圾分类系统的原型。本质上，这是一个将AI视觉识别与嵌入式硬件控制相结合的AIoT项目，核心目标不是开发一个全新的算法，而是如何高效、稳定地将现有的成熟技术（YOLOv5物体检测）与低成本硬件（ESP32）串联起来，形成一个可演示、可扩展的完整闭环。

这个系统的核心逻辑非常清晰：摄像头（笔记本自带或USB外接）作为系统的“眼睛”，持续捕捉画面；运行在VIAM平台上的YOLOv5模型作为“大脑”，负责识别画面中的垃圾属于可回收物、厨余垃圾、有害垃圾还是其他垃圾；识别结果通过无线网络发送给作为“执行器”的ESP32，由其控制一条RGB LED灯带，用不同颜色或点亮模式来指示对应的垃圾桶。比如，识别到塑料瓶，灯带的某一段亮起蓝色，告诉你应该扔进蓝色的可回收物垃圾桶。整个过程在本地局域网内完成，延迟低，且无需将图像数据上传至云端，兼顾了实时性与隐私。

它的价值在于提供了一个完整的“感知-决策-执行”框架。对于初学者，你可以通过它学习如何将Python环境的AI模型与C++环境的嵌入式开发联动；对于开发者，它展示了如何用VIAM这类机器人开发平台快速集成视觉服务与硬件控制，大幅降低全栈开发的复杂度；对于环保或物联网领域的应用探索者，这更是一个可以直接拿来验证想法、进行场景化改造的基石。接下来，我将拆解整个构建过程，从硬件选型、软件配置到代码联调，分享其中每一个关键步骤的实现细节与避坑经验。

2. 核心硬件选型与连接方案

硬件是项目的骨架，选型不当会导致后续开发困难重重甚至项目失败。本系统的硬件分为视觉处理单元、控制执行单元和指示单元三部分。

2.1 视觉处理单元：计算设备的选择

原始方案中使用的是“一台能运行viam-server的电脑”。这里有几个关键点需要展开。VIAM Server是一个后台服务，负责管理机器人组件（如摄像头）和服务（如视觉模型），并提供远程调用接口。它对系统资源有一定要求。

计算设备选型解析：

1. 个人电脑（Mac/Linux）：这是最快捷的开发调试环境。你的笔记本或台式机直接承担了运行VIAM Server、YOLOv5模型推理和运行控制脚本的三重任务。优点是性能强、调试方便，适合原型开发。缺点是设备不固定、功耗高，不适合最终部署。
2. 单板计算机（SBC）：如树莓派4B（4GB或8GB内存）、Jetson Nano甚至性能更强的Jetson Orin Nano。这是产品化部署的更优选择。它们体积小、功耗低、可长期稳定运行。特别注意：必须选择64位Linux系统。32位系统（如旧版Raspbian）无法运行VIAM Server。对于树莓派，推荐使用官方64位Bullseye或Bookworm系统。

注意：如果使用树莓派，务必确认其摄像头模块已正确启用（通过sudo raspi-config>Interface Options>Legacy Camera启用）。USB摄像头则通常即插即用，兼容性更好。

性能考量：YOLOv5模型有多个版本（n, s, m, l, x），模型越大精度越高，但所需计算资源也越多。对于树莓派4B，yolov5n或yolov5s是更现实的选择，推理速度可能在1-3秒/帧。如果使用keremberke/yolov5m-garbage这个中等模型，在树莓派上可能会非常慢（>10秒/帧），严重影响体验。建议在开发电脑上测试通过后，在SBC上尝试更小的模型或进行模型量化优化。

2.2 控制与执行单元：ESP32及其外围电路

ESP32是本项目的“小脑”和“手”，负责接收网络指令并控制LED灯带。

ESP32型号选择：市面上ESP32开发板众多，对于本项目，任何一款带有Wi-Fi功能的ESP32（如ESP32 DevKitC、NodeMCU-32S）都完全足够。无需选择带摄像头或蓝牙高级功能的型号，基础款即可。

电源方案设计：这是硬件连接中最容易出问题的一环。ESP32和LED灯带绝不能仅靠电脑USB口（5V/0.5A）同时供电，尤其是当LED灯带较长（如150颗灯珠）时。瞬间点亮所有白色灯珠的电流可能超过2A，会烧毁USB口或导致系统不稳定。

正确的供电方案如下：

1. 独立供电：为LED灯带准备一个独立的5V直流电源适配器，其额定电流需足够。一个保守的计算方法是：每颗WS2812B灯珠在白色全亮时最大电流约60mA。对于150颗灯珠，最大理论电流为9A。实际上我们很少全白全亮，但电源适配器至少应提供5V/3A以上的能力以确保稳定。一个5V/5A的电源是稳妥的选择。
2. 共地处理：将ESP32的GND、LED灯带的GND与外部5V电源的GND必须连接在一起。这是保证信号电平基准一致的关键，否则控制信号会紊乱。
3. 信号连接：ESP32的GPIO引脚（代码中用的GPIO 13）连接到LED灯带的DI（数据输入）引脚。注意，ESP32的引脚输出是3.3V电平，而WS2812B灯带通常要求5V信号。虽然很多时候3.3V也能驱动，但长距离或灯珠多时可能不稳定。一个简单的解决方案是在数据线上加一个电平转换电路（如使用74HCT125芯片），或者选择一个逻辑电平为3.3V兼容的灯带型号。

连接示意图（文字描述版）：

• 外部5V电源：正极（+）接LED灯带的+5V，负极（-）接LED灯带的GND，并同时连接到ESP32开发板的GND引脚。
• ESP32：GPIO13接 LED灯带的DI。
• ESP32：其VIN或5V引脚可以从外部电源取电（需确认开发板支持），或者继续由USB供电（仅给ESP32芯片供电，电流很小）。更推荐ESP32也由外部5V电源通过其VIN引脚供电，实现一套电源供电整个系统。

2.3 指示单元：RGB LED灯带选型与使用

本项目选用的是WS2812B智能RGB LED灯带，其最大特点是单线控制，只需一个数据引脚即可控制上百颗灯珠的颜色，极大简化了布线。

灯带使用要点：

1. 方向性：WS2812B灯带有明确的输入（DI）和输出（DO）端。数据必须从控制器的DI端流入，从第一颗灯珠的DO端流到下一颗的DI端，不能接反。
2. 电容的重要性：在LED灯带的电源正负极之间，强烈建议并联一个1000μF 6.3V或10V的电解电容。这个电容靠近灯带电源接入点放置，可以吸收开关电源和灯珠快速变化时产生的电流尖峰，防止电压跌落导致ESP32复位或灯珠显示异常。
3. 电阻的考虑：在ESP32的GPIO与灯带DI之间，串联一个220Ω至470Ω的电阻，有助于阻尼信号反射，提高长距离传输的稳定性。虽然短距离测试可能不用也能工作，但加上它是良好的工程实践。

3. VIAM平台视觉服务配置详解

VIAM平台的核心价值在于它抽象了硬件和AI服务，让我们可以通过配置和API调用的方式快速集成，而无需从零搭建深度学习推理环境。

3.1 基础环境搭建与机器注册

首先，你需要在 app.viam.com 注册一个账户。VIAM采用“云控制台+本地代理”的模式。我们在云控制台配置机器人和服务，而viam-server则作为一个本地代理（安装在你的电脑或树莓派上），负责执行这些配置并与真实硬件通信。

安装viam-server：根据你的操作系统，在VIAM文档中找到对应的安装命令。对于Linux/macOS，通常是一行curl命令。安装完成后，viam-server会作为后台服务运行，并自动尝试连接云端。你需要在VIAM控制台创建一个“机器”，并按照指引获取一个“位置密钥”，在安装过程中或之后配置它，使你的本地机器与云控制台上的这个“机器”实体绑定。

关键状态确认：在VIAM App的机器页面，确保机器状态显示为“Live”。这表示你的本地viam-server与云端建立了稳定连接，可以进行远程配置和调试。

3.2 摄像头组件配置

在VIAM的语境中，一切硬件都是“组件”。我们首先添加摄像头组件。

1. 在机器配置页面，点击“+ CREATE COMPONENT”。
2. 类型选择“camera”，子类型选择“webcam”。名称填一个易记的，如my-camera。
3. 关键配置在于video_path。对于Linux系统，通常是/dev/video0或/dev/video1。你可以通过命令v4l2-ctl --list-devices来列出可用的摄像头设备。对于macOS，路径可能是0或1这样的索引数字。如果不确定，可以尝试0。
4. 保存配置。VIAM会自动将配置下发给本地运行的viam-server，后者会尝试按照配置启动摄像头。

测试摄像头：切换到“CONTROL”标签页，找到你的摄像头组件，点击展开面板，你会看到一个“View my-camera”的开关。打开它，如果配置正确，你应该能实时看到摄像头的视频流。如果是一片漆黑或报错，请检查video_path是否正确，以及摄像头是否被其他程序（如Zoom、Cheese）占用。

3.3 视觉服务配置：集成YOLOv5模型

这是AI能力的核心。VIAM内置了多种视觉服务类型，我们使用vision服务下的MLModel类型来加载YOLOv5模型。

1. 点击“+ CREATE SERVICE”。
2. 类型选择“vision”，子类型选择“MLModel”。
3. 命名服务，例如yolo_trash_detector。
4. 在Model Type中选择tflite_cpu（如果你在x86电脑上）或tflite_cpu（如果是在ARM架构的树莓派上，但需要注意模型格式兼容性）。更通用的方式是使用vision类型下的“MLModel”，并在属性中指定模型路径。
5. 在Model Path中，我们需要引用一个预训练的模型。VIAM支持从Hugging Face等模型库直接加载。配置如下：

   { "model_info": { "type": "tflite", "model_path": "https://huggingface.co/keremberke/yolov5m-garbage/resolve/main/model_float32.tflite?download=true", "label_path": "https://huggingface.co/keremberke/yolov5m-garbage/raw/main/labels.txt" }, "parameters": { "confidence_threshold": 0.5, "num_threads": 4 } }

   • model_path：指向Hugging Face模型仓库中的TFLite模型文件。VIAM服务器会自动下载并缓存它。
   • label_path：指向模型的标签文件，告诉VIAM每个类别ID对应什么垃圾名称。
   • confidence_threshold：置信度阈值，高于此值的检测结果才被采纳。0.5是一个平衡点。
   • num_threads：推理使用的线程数，可以调整以优化速度。

模型加载的注意事项：第一次配置保存时，VIAM会从网络下载模型，这可能需要几分钟，取决于模型大小和网络速度。请耐心等待，并在机器的日志中查看进度。如果长时间失败，可能是网络问题，可以考虑先将模型文件下载到本地，然后通过file://路径引用。

3.4 对象过滤与可视化配置

原始方案中提到了objectfilter组件，它的作用是对原始视觉服务的检测结果进行后处理，比如过滤特定标签、绘制检测框等。但在VIAM的最新架构中，更常见的做法是直接使用视觉服务，或者在自定义代码中处理过滤逻辑。

一种更直接的测试方法：在“CONTROL”标签页，找到你刚创建的yolo_trash_detector视觉服务，它通常会提供一个get_detections的方法测试面板。你可以上传一张图片或使用摄像头的实时流进行测试。如果模型加载成功，你会看到返回的JSON数据，包含了检测到的物体类别、置信度和边界框坐标。这是验证AI部分是否正常工作的最快途径。

4. ESP32 Web服务器固件开发与调试

ESP32在这里扮演了一个HTTP服务器的角色，监听特定的URL请求，并根据请求参数控制LED灯带。我们将深入代码的每一个部分。

4.1 开发环境与库依赖

使用Arduino IDE进行开发。

1. 安装ESP32开发板支持：在Arduino IDE的“文件”->“首选项”->“附加开发板管理器网址”中，添加https://espressif.github.io/arduino-esp32/package_esp32_index.json。然后在“工具”->“开发板”->“开发板管理器”中搜索esp32并安装。
2. 安装必要的库：
   • WebServer：ESP32内置，无需额外安装。
   • Adafruit_NeoPixel：用于控制WS2812B灯带。可以通过“项目”->“加载库”->“管理库”搜索Adafruit NeoPixel进行安装。

4.2 代码逐段解析与优化

让我们仔细审视并优化原始提供的代码。

网络连接与服务器初始化：

#include "WiFi.h" #include <Adafruit_NeoPixel.h> #include <WebServer.h> const char* ssid = "your_wifi"; const char* password = "your_password"; #define LED_PIN 13 #define NUM_LEDS 150 Adafruit_NeoPixel strip = Adafruit_NeoPixel(NUM_LEDS, LED_PIN, NEO_GRB + NEO_KHZ800); WebServer server(80);

• Wi-Fi凭证：务必修改为你的网络信息。对于需要网页认证的网络（如企业网络），此方法可能不适用。
• LED_PIN：GPIO13是常用选择，但注意某些ESP32开发板上的GPIO13可能连接了板载LED，使用时可能会冲突。如果出现问题，可以换到其他空闲的GPIO，如4、15、18等。
• NUM_LEDS：务必与你实际购买的灯带灯珠数量一致，否则程序会访问不存在的内存区域，导致崩溃。

Setup函数中的关键点：

void setup() { Serial.begin(115200); WiFi.begin(ssid, password); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } Serial.println("\nWiFi connected. IP address: "); Serial.println(WiFi.localIP()); strip.begin(); strip.show(); // 初始化，关闭所有LED strip.setBrightness(50); // 新增：设置亮度，避免过亮和电流过大 server.on("/trash/command", handleCommand); // 使用独立的处理函数，提高可读性 server.on("/trash/off", handleLEDOff); server.onNotFound(handleNotFound); // 新增：处理未知请求 server.begin(); Serial.println("HTTP server started"); }

• 亮度控制：strip.setBrightness(50)非常重要。WS2812B在最大亮度（255）下非常刺眼，且电流极大。设置为50-100之间的值，既能看清又安全。
• 路由处理优化：将处理函数独立出来，而不是使用Lambda表达式内联，使代码结构更清晰，便于维护和调试。

核心控制函数setLEDColors的优化： 原始代码的逻辑是将灯带分成三段，根据垃圾类型点亮其中一段。但代码中的数组索引计算有误（oneThird+4,oneThird+6等），这会导致灯珠控制错位或遗漏。

void setLEDColors(String command) { strip.clear(); // 先清空所有灯珠 uint32_t color; int startLed = 0; int endLed = 0; // 定义每种垃圾类型对应的颜色和点亮区域 if (command == "biodegradable") { color = strip.Color(0, 255, 0); // 绿色 startLed = 0; endLed = NUM_LEDS / 3; } else if (command == "metal") { color = strip.Color(255, 255, 0); // 黄色，更符合金属的常见标识色 startLed = NUM_LEDS / 3; endLed = 2 * NUM_LEDS / 3; } else if (command == "plastic") { color = strip.Color(0, 0, 255); // 蓝色 startLed = 2 * NUM_LEDS / 3; endLed = NUM_LEDS; } else if (command == "glass") { color = strip.Color(128, 0, 128); // 紫色，用于区分 startLed = 0; // 可以自定义区域 endLed = NUM_LEDS / 4; } else { // 未知类型或错误指令，点亮红色警示 color = strip.Color(255, 0, 0); startLed = 0; endLed = NUM_LEDS; } for (int i = startLed; i < endLed; i++) { strip.setPixelColor(i, color); } strip.show(); }

• 逻辑清晰：明确计算每段的起止索引，避免硬编码的偏移量导致错误。
• 颜色定义：参考常见的垃圾分类颜色标识（如绿色厨余、蓝色可回收、红色有害、灰色其他），使系统更直观。黄色常用于金属。
• 错误处理：对未知命令提供默认的红色警示。

独立的HTTP请求处理函数：

void handleCommand() { if (server.hasArg("type")) { String commandType = server.arg("type"); Serial.printf("Received command: %s\n", commandType.c_str()); setLEDColors(commandType); server.send(200, "text/plain", "OK: " + commandType); } else { server.send(400, "text/plain", "ERROR: Missing 'type' parameter"); } } void handleLEDOff() { strip.clear(); strip.show(); server.send(200, "text/plain", "LEDs OFF"); } void handleNotFound() { String message = "File Not Found\n\n"; server.send(404, "text/plain", message); }

• 日志输出：在处理函数中加入Serial.printf打印接收到的命令，这对于网络调试至关重要。
• 规范的HTTP响应：返回恰当的HTTP状态码（200成功，400客户端错误，404未找到）和描述信息。

4.3 上传、测试与网络调试

1. 编译上传：在Arduino IDE中选择正确的开发板型号（如ESP32 Dev Module）和端口，点击上传。
2. 查看IP地址：上传成功后，打开串口监视器（波特率115200），重启ESP32。你将看到它尝试连接Wi-Fi，成功后打印出获得的IP地址，例如192.168.1.159。记下这个IP。
3. 基础功能测试：
   • 打开电脑浏览器，访问http://[ESP32_IP]/trash/off。如果一切正常，整个LED灯带应该会熄灭（或变成红色，取决于你的handleLEDOff实现）。
   • 访问http://[ESP32_IP]/trash/command?type=plastic。灯带对应的三分之一段应该亮起蓝色。
   • 这些测试验证了ESP32的Web服务器和LED控制功能完全正常，为与VIAM的联动扫清了障碍。

实操心得：网络稳定性：在后续与VIAM脚本联调时，偶尔会出现ESP32“失联”的情况。除了检查Wi-Fi信号强度，一个有用的技巧是在ESP32的loop()函数中加入一个简单的“看门狗”机制，定期打印状态信息到串口，或者实现一个简单的ping端点(/ping)，方便VIAM脚本在发送关键指令前先检查ESP32是否在线。

5. VIAM自动化脚本的深度剖析与优化

VIAM的Python SDK让我们能够编写强大的自动化脚本，作为连接“AI大脑”和“硬件执行器”的桥梁。原始脚本提供了一个很好的起点，但存在一些可以改进和深入理解的地方。

5.1 环境准备与依赖安装

首先，确保你的电脑（或树莓派）上安装了Python（3.7以上）。然后，安装VIAM的Python SDK：

pip install viam-sdk

脚本中还使用了aiohttp用于异步HTTP请求，也需要安装：

pip install aiohttp

5.2 脚本逻辑拆解与强化

让我们重构并增强这个脚本，使其更健壮、更易调试。

连接与资源发现：

import asyncio import aiohttp from collections import deque from viam.robot.client import RobotClient from viam.components.camera import Camera from viam.services.vision import VisionClient async def connect_to_viam(): """ 连接到VIAM机器人实例。 使用API密钥和地址进行认证。 """ # 替换为你的实际API密钥和地址 api_key = "your-actual-api-key" api_key_id = "your-actual-api-key-id" robot_address = "your-robot-address.viam.cloud" # 或本地地址如 "localhost:8080" opts = RobotClient.Options.with_api_key(api_key=api_key, api_key_id=api_key_id) try: robot = await RobotClient.at_address(robot_address, opts) print(f"[INFO] Successfully connected to robot at {robot_address}") # 打印所有可用资源，用于确认摄像头和视觉服务名称 print(f"[INFO] Available resources: {[r.name for r in await robot.get_resource_names()]}") return robot except Exception as e: print(f"[ERROR] Failed to connect to Viam: {e}") raise

• 关键信息替换：api_key,api_key_id,robot_address必须从你的VIAM控制台获取。在机器人的“CODE SAMPLE”标签页，选择Python，即可看到这些信息。
• 错误处理：使用try-except包裹连接过程，避免脚本因网络波动等原因直接崩溃。
• 资源确认：连接成功后打印所有资源名称，这是一个非常重要的调试步骤，可以确认你在配置中命名的my-camera和yolo_trash_detector是否可用，名称是否完全匹配。

与ESP32 Web服务器通信：

class ESP32Controller: def __init__(self, ip_address: str): self.base_url = f"http://{ip_address}" self.session = None async def __aenter__(self): # 使用aiohttp的ClientSession最佳实践，管理连接池 self.session = aiohttp.ClientSession() return self async def __aexit__(self, exc_type, exc_val, exc_tb): if self.session: await self.session.close() async def send_command(self, trash_type: str): """发送指令控制LED""" if not self.session: raise RuntimeError("Session not initialized. Use 'async with' context manager.") url = f"{self.base_url}/trash/command" params = {'type': trash_type} try: async with self.session.post(url, params=params, timeout=aiohttp.ClientTimeout(total=3)) as resp: if resp.status == 200: print(f"[INFO] Successfully set LED for {trash_type}") return await resp.text() else: text = await resp.text() print(f"[ERROR] ESP32 returned error: {resp.status} - {text}") return None except asyncio.TimeoutError: print(f"[ERROR] Timeout when communicating with ESP32 at {url}") return None except aiohttp.ClientError as e: print(f"[ERROR] Network error communicating with ESP32: {e}") return None async def turn_off_led(self): """关闭所有LED""" url = f"{self.base_url}/trash/off" try: async with self.session.post(url, timeout=aiohttp.ClientTimeout(total=2)) as resp: return resp.status == 200 except Exception as e: print(f"[WARN] Failed to turn off LED: {e}") return False

• 类封装：将ESP32控制逻辑封装成一个类，结构更清晰，符合OOP原则。
• 连接管理：使用async with和ClientSession来管理HTTP会话，这是aiohttp的推荐做法，能高效复用TCP连接。
• 超时与错误处理：为网络请求设置超时（如3秒），并捕获可能发生的超时、连接错误等异常。在实际部署中，网络不稳定是常见问题，健壮的错误处理至关重要。
• 状态检查：检查HTTP响应状态码，只有200才认为是成功。

核心检测与决策循环： 这是脚本的大脑，原始逻辑是“连续三帧检测到同一类别才触发动作”，这是一个有效的防抖策略。

async def main_detection_loop(robot, esp32_ip): """ 主检测循环。 """ # 1. 获取组件和服务的客户端对象 try: my_camera = Camera.from_robot(robot, "my-camera") # 名称必须与配置完全一致 vision_svc = VisionClient.from_robot(robot, "yolo_trash_detector") except Exception as e: print(f"[ERROR] Failed to acquire resources: {e}. Check resource names.") return # 2. 初始化检测历史队列和ESP32控制器 detection_history = deque(maxlen=3) # 只保留最近3次有效检测 cooldown_seconds = 5 # 触发一次动作后的冷却时间，防止频繁触发 async with ESP32Controller(esp32_ip) as esp32: last_trigger_time = 0 print("[INFO] Starting main detection loop. Press Ctrl+C to stop.") while True: try: # 3. 捕获并分析图像 print("[DEBUG] Capturing image...") image = await my_camera.get_image() detections = await vision_svc.get_detections(image) current_detection = None highest_confidence = 0.0 # 4. 找出当前帧中置信度最高的有效垃圾检测 for d in detections: # 过滤掉低置信度和非目标类别的检测 if d.confidence > 0.5 and d.class_name in ["biodegradable", "glass", "metal", "plastic"]: if d.confidence > highest_confidence: highest_confidence = d.confidence current_detection = d.class_name # 5. 更新检测历史 if current_detection: print(f"[DETECT] Frame: {current_detection} (conf: {highest_confidence:.2f})") detection_history.append(current_detection) else: print("[DETECT] Frame: No valid detection") # 可选：如果连续多帧无检测，可以清空历史，避免历史遗留导致误触发 # if not any(detections): # detection_history.clear() print(f"[HISTORY] Current queue: {list(detection_history)}") # 6. 决策逻辑：检查历史队列是否满足触发条件 current_time = asyncio.get_event_loop().time() if (len(detection_history) == detection_history.maxlen and current_time - last_trigger_time > cooldown_seconds): # 检查最近3次检测是否相同 if len(set(detection_history)) == 1: # 集合中元素唯一，说明3次都相同 target_class = detection_history[0] print(f"[ACTION] Triggering action for: {target_class}") # 7. 触发ESP32动作 result = await esp32.send_command(target_class) if result: last_trigger_time = current_time # 动作完成后，清空历史，进入冷却，并关闭LED detection_history.clear() await asyncio.sleep(3) # 保持LED点亮3秒 await esp32.turn_off_led() print(f"[ACTION] Action completed for {target_class}. Cooldown started.") else: print("[ACTION] Failed to communicate with ESP32. Action aborted.") else: # 历史不一致，移除最旧的一个，等待新数据 detection_history.popleft() # 7. 循环间隔，避免过高CPU占用 await asyncio.sleep(0.1) # 100ms的间隔，约10FPS except asyncio.CancelledError: print("[INFO] Detection loop cancelled.") break except Exception as e: print(f"[ERROR] Unexpected error in main loop: {e}") await asyncio.sleep(1) # 出错后等待1秒再继续

• 资源获取的异常处理：获取摄像头和视觉服务客户端时加入try-except，避免因名称拼写错误导致脚本启动失败。
• 检测逻辑优化：
  • 不仅检查置信度>0.5，还通过d.class_name in [...]明确过滤我们关心的垃圾类别，避免模型检测到其他物体（如“人”、“手”）的干扰。
  • 选择置信度最高的检测结果作为当前帧的代表，而不是第一个结果，决策更准确。
• 防抖与冷却机制：
  • deque(maxlen=3)：固定长度的队列，自动丢弃旧数据。
  • cooldown_seconds：在触发一次动作后，设置一个冷却时间（如5秒），在此期间即使再次满足条件也不触发，防止因物体持续在镜头前而导致的灯光频繁闪烁。
  • len(set(detection_history)) == 1：这是一个判断队列中所有元素是否相同的简洁方法。
• 动作执行与清理：触发动作后，先发送指令点亮LED，等待3秒让用户看到，然后发送关闭指令，最后清空检测历史。这是一个完整的用户交互闭环。
• 循环间隔：在循环末尾加入await asyncio.sleep(0.1)，控制检测频率，避免无意义地疯狂抓图，占用大量CPU和网络带宽。10FPS对于这个应用足够了。
• 全面的异常捕获：在主循环内部用try-except包裹，确保即使某一次图像获取或推理出错，循环也不会崩溃，而是打印错误后继续运行。

主函数入口：

async def main(): ESP32_IP = "192.168.1.159" # 替换为你的ESP32实际IP try: robot = await connect_to_viam() await main_detection_loop(robot, ESP32_IP) except KeyboardInterrupt: print("\n[INFO] Program interrupted by user.") except Exception as e: print(f"[CRITICAL] Main function error: {e}") finally: # 确保机器人客户端被关闭 if 'robot' in locals(): await robot.close() print("[INFO] Program finished.") if __name__ == "__main__": asyncio.run(main())

6. 系统集成、调试与性能优化实战

当硬件、固件、AI服务和联动脚本都准备就绪后，真正的挑战在于让它们稳定地协同工作。这个阶段会暴露出许多在独立测试时不会遇到的问题。

6.1 分步集成与联调策略

不要试图一次性让整个系统跑起来。遵循以下步骤，像剥洋葱一样层层调试：

1. 第一步：验证视觉管道。

   • 在VIAM的“CONTROL”页，单独测试摄像头，确保画面清晰、方向正确。
   • 然后，使用视觉服务的get_detections方法，用实物（一个塑料瓶、一个易拉罐）在摄像头前测试。观察返回的JSON数据，确认class_name和confidence是否符合预期。这是整个项目的基石，必须首先调通。

2. 第二步：验证执行单元。

   • 确保ESP32已上电，并连接到与运行VIAM脚本的电脑同一个局域网。
   • 在电脑上使用浏览器或curl命令，手动测试ESP32的所有HTTP端点（/trash/command?type=plastic,/trash/off），观察LED灯带反应是否准确、迅速。

3. 第三步：运行“静默”脚本。

   • 先修改你的Python脚本，在main_detection_loop函数中，注释掉await esp32.send_command(target_class)和await esp32.turn_off_led()这两行实际控制硬件的代码。
   • 运行脚本。此时，脚本应该能正常连接VIAM，捕获图像，进行AI识别，并在控制台打印出检测到的垃圾类别和历史队列。这一步验证了“感知-决策”链路的通畅性，且不会因为硬件问题导致脚本崩溃。

4. 第四步：全链路联调。

   • 将脚本中注释的硬件控制代码恢复。
   • 再次运行脚本。现在，当你在摄像头前稳定地展示一个塑料瓶超过3帧时，你应该能同时在控制台看到触发日志，并且LED灯带对应的区段亮起蓝色，持续3秒后熄灭。

6.2 常见问题排查速查表

6.3 性能优化与扩展思路

当基础功能跑通后，可以考虑以下优化和扩展，让系统更实用、更强大：

1. 模型优化：

   • 模型轻量化：在树莓派等资源受限的设备上，考虑使用更小的YOLOv5模型（如yolov5n或yolov5s），或者将模型转换为TensorFlow Lite格式并进行量化（INT8），可以大幅提升推理速度。
   • 模型微调：如果针对特定场景（如办公室垃圾、厨房垃圾），可以收集自己的图片数据，在预训练模型keremberke/yolov5m-garbage的基础上进行微调，提升识别准确率。

2. ESP32固件优化：

   • OTA升级：实现ESP32的无线（Over-The-Air）固件升级功能，这样以后修复bug或增加功能就无需再插线烧录。
   • 状态反馈：让ESP32除了接收命令，还能主动上报状态（如网络状态、LED状态）到一个服务端，实现双向通信。
   • 多执行器控制：不仅可以控制LED，还可以扩展为控制舵机打开对应的垃圾桶盖，或者通过语音模块播报垃圾类别。

3. 系统架构扩展：

   • 引入消息队列：在VIAM脚本和ESP32之间加入一个轻量级消息队列（如MQTT）。VIAM脚本将识别结果发布到MQTT主题，ESP32订阅该主题。这样做的好处是解耦，允许多个ESP32订阅同一指令，也方便未来接入其他类型的执行器。
   • 增加本地UI：使用Flask或FastAPI在运行VIAM的电脑上搭建一个简单的Web界面，实时显示摄像头画面、检测结果、系统状态日志，并提供一个手动控制面板。
   • 数据持久化：将每次识别的垃圾类型、时间戳记录到本地数据库（如SQLite）或文件中，用于后续统计和分析，了解垃圾投放的分布情况。

构建这个系统的过程，远比最终看到LED灯按预期点亮那一刻要复杂。它涉及了嵌入式开发、网络通信、计算机视觉和云平台配置多个领域的知识。最大的收获不是做出了一个玩具，而是打通了从“软件智能”到“物理动作”的完整路径。当你看到AI识别出的一个名词，能通过网络驱动几米外的硬件做出反应时，那种感觉就像在数字世界和物理世界之间架起了一座桥。这个项目框架具有很强的可塑性，你可以把“垃圾”换成“零件”，“LED指示”换成“机械臂抓取”，其核心的“看见-判断-行动”模式，正是无数智能化项目的基础原型。