开发环境
Arduino 固件：手动 50Hz PWM + RouterBridge 远程调用；Python 中台：OpenCV HSV 颜色识别 + PID 闭环控制 + EMA 坐标滤波 + Base64 推流；Web 前端：单文件 HTML（赛博朋克风），Socket.IO 双向通信；通信协议：RouterBridge（Python ↔ Arduino）、Socket.IO（浏览器 ↔ Python）
产品参数 · 内容说明
基于 Arduino UNO Q 的 HSV 颜色追踪云台：OpenCV 识别目标颜色 → PID 闭环控制计算误差 → MG996R 舵机实时跟随，同时提供赛博朋克风格 Web 控制台。
产品参数 · 基本信息
| 项目 | 内容 |
|---|---|
| 产品名称 | Color Tracked PTZ（颜色追踪云台 / Visual Tracking Gimbal） |
| 产品定位 | 计算机视觉经典入门项目（颜色追踪可视化闭环控制系统） |
| 开发团队 | APLUX 阿加犀（GitHub：APLUX-Official） |
| 分类 | Monitoring / Tracking / Robotics（Arduino 分类） |
| 开源协议 | Apache License 2.0 |
| 项目案例页 | https://projecthub.arduino.cc/aplux/visual-tracking-gimbal-9a48d9 |
产品参数 · 功能特性
| 功能 | 说明 |
|---|---|
| 动态选色 | Hue 滑条 + 6 色预设（黄/红/绿/蓝/橙/紫），实时切换追踪颜色 |
| PID 自动追踪 | 双轴独立 PID 闭环控制，含死区迟滞、积分 Anti-Windup（±500）、EMA 坐标滤波（α=0.4） |
| PID 在线调参 | Kp / Ki / Kd / 死区四参数滑块 + 4 种预设方案（默认/纯P/保守/激进），实时生效 |
| 手动控制 | Pan 0–180° / Tilt 30–150° 滑块直控 |
| 舵机中位校准 | ±1°/±5° 微调 + 一键回中 90°，方便安装摇臂 |
| 实时视频 | Base64 JPEG 推流（~25fps），浏览器直接显示追踪标记 |
产品参数 · 硬件连接
| 组件 | 引脚 | 说明 |
|---|---|---|
| Pan 舵机（MG996R） | D3 | 水平旋转 0°–180° |
| Tilt 舵机（MG996R） | D11 | 垂直俯仰 30°–150° |
| USB 摄像头 | USB | 320×240 MJPG |
产品参数 · 核心算法
- PID 闭环控制：u(k) = Kp·e(k) + Ki·Σe(j) + Kd·[e(k)-e(k-1)]
- P 比例项：误差越大修正越大，快速响应
- I 积分项：消除稳态偏差（含 Anti-Windup 限幅）
- D 微分项：抑制超调震荡
- 死区迟滞：误差 < 20px 不动作，需超过 26px 重新激活，避免边缘抖动
- EMA 低通滤波：平滑帧间噪声
- 颜色阈值分割：BGR → HSV → inRange 阈值 → 腐蚀/膨胀去噪 → findContours → 最大轮廓 → minEnclosingCircle 质心定位；红色自动处理色相环绕（H≈170°~10° 双 mask 合并）
- 手动 PWM 舵机驱动：不使用 Servo 库，loop() 中手动生成 50Hz 脉冲：pulse = 500 + (angle × 2000 / 180) μs（0°→500μs，90°→1500μs，180°→2500μs）
产品参数 · PID 预设方案
调参速查：响应太慢 → 增大 Kp；抖动/震荡 → 增大 Kd 或减小 Kp；居中但有偏差 → 增大 Ki；中心附近抖动 → 增大死区。
| 预设 | Kp | Ki | Kd | 死区 | 适用场景 |
|---|---|---|---|---|---|
| 默认 | 0.035 | 0.0005 | 0.025 | 20 | 通用平衡 |
| 纯P | 0.08 | 0 | 0 | 10 | 快速响应（有稳态误差） |
| 保守 | 0.02 | 0.002 | 0.03 | 25 | 平稳追踪 |
| 激进 | 0.06 | 0.003 | 0.04 | 10 | 灵敏追踪（可能超调） |
产品参数 · 项目结构
color_tracked_plz/
├── app.yaml # Arduino App 配置
├── assets/
│ └── index.html # 单文件 Web 控制台 (CSS + HTML + JS, ~930行)
├── python/
│ └── main.py # OpenCV 视觉 + PID 控制 + WebUI 服务 (~270行)
└── sketch/
├── sketch.ino # 手动 50Hz PWM 舵机驱动 (~65行)
└── sketch.yaml # Sketch 配置 (Arduino Zephyr UNO Q)产品参数 · 快速上手
舵机校准：点击「开始校准」→ 两轴自动回中 90° → ±1°/±5° 微调至物理中位 → 安装舵机摇臂 → 完成校准。校准时自动追踪被强制关闭。
⚠️ 上电注意：若使用 USB Hub 扩展，建议主板启动完成后再插入摄像头 USB 线。
- 将 sketch/ 编译上传到 UNO Q，按接线图连接两个舵机（D3 / D11）与 USB 摄像头
- 在 Arduino App Lab 中运行项目（或 SSH 执行 arduino-app-cli app start color_tracked_plz）
- 浏览器访问 http://<UNO_Q_IP>:7000，右上角状态灯变绿即连接成功
- 用 Hue 滑条或预设色块选择要追踪的颜色（右下角显示当前 HSV 范围）
- 打开「自动追踪」开关，云台自动跟随目标（Pan/Tilt 滑块自动置灰）
产品参数 · 技术栈
- Arduino 固件：手动 50Hz PWM + RouterBridge 远程调用
- Python 中台：OpenCV HSV 颜色识别 + PID 闭环控制 + EMA 坐标滤波 + Base64 推流
- Web 前端：单文件 HTML（赛博朋克风），Socket.IO 双向通信
- 通信协议：RouterBridge（Python ↔ Arduino）、Socket.IO（浏览器 ↔ Python）
产品参数 · 说明
本页参数依据官方 GitHub README 与 Arduino Project Hub 项目页整理，如有更新以官方发布为准。
BOM清单 · 内容说明
基于 Arduino UNO Q 的 HSV 颜色追踪云台（OpenCV 识别 + PID 闭环控制）可采购硬件 / 配件清单。 > 整理依据：官方 GitHub README、Arduino Project Hub 项目页器件清单（含官方购买链接）。
BOM清单 · 一、可购买硬件 / 配件
| 序号 | 物料名称 | 型号 / 规格 | 数量 | 用途 | 购买链接 |
|---|---|---|---|---|---|
| 1 | 主控开发板 | Arduino® UNO™ Q 2GB | 1 | 核心控制器（Web 服务 / PID / 舵机驱动） | 官方商店：https://store.arduino.cc/products/uno-q |
| 2 | 云台舵机 | MG996R 双轴云台套装 | 1 | Pan 水平旋转（D3，0–180°）；Tilt 垂直俯仰（D11，30–150°） | 天猫：https://detail.tmall.com/item.htm?abbucket=13&id=676877215596&mi_id=0000rFzkzbo297KiYczv5bcZ3GJmcQkpbey52ITjIb-4R_4&ns=1&skuId=5035049867604&spm=a21n57.1.hoverItem.5&utparam=%7B%22aplus_abtest%22%3A%22cd3f7117226dada6c5418e94149c8cea%22%7D&xxc=taobaoSearch |
| 3 | 电池 | 可充电锂电池组 | 1 | 云台供电 | 天猫：https://detail.tmall.com/item.htm?abbucket=13&id=859580860279&mi_id=0000h5us3SGFRomTHBddzAoU2W6ifbnt9Tbz5olxen0Bl_g&ns=1&priceTId=213e032717726071062034070e1a76&skuId=5671592324763&spm=a21n57.1.hoverItem.11&utparam=%7B%22aplus_abtest%22%3A%22d6c44aa15c0b838886e2dabc16828c79%22%7D&xxc=taobaoSearch |
| 4 | USB 摄像头 | Type-A USB 摄像头（建议 320×240 MJPG） | 1 | 颜色识别视频源 | 天猫：https://detail.tmall.com/item.htm?id=775110864301 |
| 5 | USB-C 数据线 | USB-C 转 USB-C，100W 快充 | 1 | 连接扩展板与 USB 摄像头 | Amazon：https://a.co/d/6n3CguQ |
| 6 | 3D 打印件 | 3D 打印结构件（云台支架 / 外壳等） | 1 套 | 机械结构 | 模型目录：https://github.com/APLUX-Official/color_tracked_plz/tree/master/models |
BOM清单 · 二、官方工具与软件清单（Arduino Project Hub）
| 类别 | 名称 | 链接 |
|---|---|---|
| 工具 | 3D 打印机 | — |
| 工具 | 个人电脑（Personal Computer） | — |
| 工具 | 螺丝刀套装 | — |
| 软件 | OpenCV（cv2） | — |
| 软件 | Arduino App Lab（开发环境） | 官方文档：https://docs.arduino.cc/software/app-lab/ |
| 软件 | Python IDE | — |
| 软件 | Chrome 浏览器 | 下载：https://www.google.com.au/chrome/ |
开源协议与链接 · 一、开源协议
备注：GitHub 仓库未附独立 LICENSE 文件，再分发 / 二次开发请遵循 Apache-2.0 条款。
| 适用对象 | 开源协议 | 说明 |
|---|---|---|
| 项目（整体） | Apache License 2.0（Apache-2.0） | 来源：Arduino Project Hub 项目页许可标注（license_type: Apache License 2.0） |
开源协议与链接 · 二、相关链接
| 类型 | 链接 |
|---|---|
| 项目仓库（GitHub） | https://github.com/APLUX-Official/color_tracked_plz |
| 项目案例页（Arduino Project Hub） | https://projecthub.arduino.cc/aplux/visual-tracking-gimbal-9a48d9 |
| 项目博客文档（PDF，官方） | https://projects.arduinocontent.cc/2ed3c1ee-f684-4661-94df-b101834a47a4.pdf |
| 3D 打印模型目录 | https://github.com/APLUX-Official/color_tracked_plz/tree/master/models |
| 电路原理图（PDF） | https://github.com/APLUX-Official/color_tracked_plz/blob/master/Schematic_2026-03-10.pdf |
| Arduino UNO Q（官方商店） | https://store.arduino.cc/products/uno-q |
| Arduino App Lab（开发环境） | https://docs.arduino.cc/software/app-lab/ |
| 开发团队主页 | https://github.com/APLUX-Official |
