简介pixy2-master.zip 是面向 Arduino 开发者与机器视觉入门者的 Pixy2 视觉模块完整项目资源围绕物体识别、颜色签名与形状追踪等核心能力帮助读者在机器人、自动化分拣等场景中快速完成视觉方案落地。压缩包共 490 个文件约 81.26MB以 138 个 h 头文件、84 个 cpp 源文件、67 个 m 与 30 个 c 实现文件为主体并包含 10 个 ino 示例、多个 makefile 与 ld 链接脚本、py 脚本、hex 固件及 pdf 文档覆盖固件源码、Arduino 示例、上位机工具与硬件资料。已有 903 人学习下载。资源内含颜色签名配置、串口通信、LCD 实时显示等示例代码以及 libusb 动态库、EV3 与 STM32 工程文件便于对照目录结构理解 Pixy2 与 Arduino 的集成方式适合希望系统掌握机器视觉模块开发与排错思路的读者参考。1. 拿到 pixy2-master.zip 之后先别急着解压搞清楚它到底解决什么问题很多人第一次拿到pixy2-master.zip这个包第一反应是双击解压、找README、然后make一把梭。结果往往是编译报错、找不到libusb、或者插上摄像头之后pixymon一片黑屏。问题不在手速在于没搞清楚这个包到底是什么定位。Pixy2 是一套面向嵌入式视觉的硬件加软件方案核心是一块自带图像处理能力的摄像头模块能直接在模块内部完成颜色识别、线段检测、条形码/二维码识别这类任务再把结果通过串口、I2C 或 USB 吐给主控。pixy2-master.zip就是它配套的固件源码、主机端库、示例程序和调试工具的集合。它解决的不是“我要训练一个神经网络”这种问题而是“我一块单片机想快速获得目标坐标但算力跑不动 OpenCV”这种场景。适合做机器人循迹、云台追踪、分拣装置、互动装置的嵌入式开发者也适合想把视觉模块当传感器用的电子爱好者。这一章先把边界划清楚后面才好动手。2. 拆开 pixy2-master.zip目录结构、编译链路与最小可运行路径2.1 包内目录的职责划分解压之后不要急着改代码先花五分钟把目录结构看一遍。不同版本的包在细节上会有差异但主干通常是这样目录/文件作用是否必须动src/固件源码跑在 Pixy2 硬件内部只在改固件时动src/host/主机端库提供libpixy2和通信接口写上位机程序时链接src/host/libpixyusb2/USB 通信实现一般不改src/host/arduino/Arduino 库走 SPI/I2C用 Arduino 时复制到库目录src/host/pixymon/调试与参数整定工具调试阶段必用scripts/构建、烧录、规则文件编译和安装时用examples/各语言的调用示例学习接口用关键认知这个包不是“一个程序”而是“一套工具链”。固件、主机库、调试工具三者的编译方式完全不同混在一起编译必然翻车。2.2 主机端库的编译与安装在 Linux 环境下最常见的做法是先装依赖再编译主机库。下面这套流程是我在多个项目里反复用过的# 安装基础依赖libusb 是 USB 通信的核心 sudo apt-get update sudo apt-get install -y build-essential libusb-1.0-0-dev libboost-all-dev # 进入主机库目录 cd pixy2-master/src/host # 编译并安装 libpixyusb2 make sudo make install # 刷新动态库缓存否则运行时会报找不到 so sudo ldconfig逻辑说明libusb-1.0-0-dev提供 USB 底层访问能力libboost在部分版本里被pixymon用来做线程和文件系统操作。make install会把libpixyusb2.so放到系统库路径ldconfig这一步很多人会漏漏了之后编译示例程序能过一运行就报error while loading shared libraries。参数说明如果你的系统是 64 位但库编译成了 32 位链接阶段会报架构不匹配。这时候要么统一用-m64要么检查Makefile里的CXXFLAGS。另外USB 权限问题很常见普通用户默认没有直接访问 USB 设备的权限需要加一条 udev 规则# 创建 udev 规则让普通用户也能访问 Pixy2 echo SUBSYSTEMusb, ATTR{idVendor}b1ac, MODE0666 | sudo tee /etc/udev/rules.d/99-pixy2.rules sudo udevadm control --reload-rules sudo udevadm trigger这里的idVendor是 Pixy2 的 USB 厂商号不同批次可能不同用lsusb确认后再写。规则写完必须重新插拔设备才生效这是血泪经验。2.3 用 pixymon 验证硬件是否正常在写任何业务代码之前先用pixymon确认硬件和通信链路是通的。编译pixymon的典型命令cd pixy2-master/src/host/pixymon make sudo ./pixymon如果窗口打开后能看到实时图像说明固件、USB 通信、主机库三层都正常。如果黑屏但程序没崩优先检查摄像头排线是否插紧如果程序直接退出看终端输出的错误码常见的是LIBUSB_ERROR_ACCESS权限问题和LIBUSB_ERROR_NOT_FOUND设备没被识别。这一步过了后面才有意义。3. 把 Pixy2 接进自己的程序三种通信方式与代码落地3.1 选 USB、I2C 还是 SPIPixy2 支持三种对外通信方式选错了会让整个项目结构变得别扭。我的经验是USB适合上位机是 Linux/Windows 主机、需要高帧率调试的场景。带宽大但线缆不能太长。I2C适合主控是单片机、引脚紧张、速率要求不高的场景。接线简单但要注意上拉电阻和地址冲突。SPI适合主控是单片机、需要更高吞吐的场景。速度快但占用引脚多时序要求严格。如果你用的是树莓派这类 Linux 单板机直接走 USB 最省事如果是 STM32 或 Arduino优先考虑 I2C代码量最小。3.2 用 libpixyusb2 写一个最小追踪程序下面这段 C 代码演示了如何通过 USB 获取目标块并打印坐标。它是从示例程序里精简出来的保留了最核心的调用链#include Pixy2.h #include stdio.h #include unistd.h int main() { Pixy2 pixy; // 初始化 USB 通信失败直接返回 if (pixy.init() 0) { printf(pixy init failed\n); return -1; } // 设置摄像头为颜色识别模式 pixy.setLamp(1, 1); // 打开上下灯改善光照 pixy.changeProg(color_connected_components); while (1) { pixy.ccc.getBlocks(); // 获取色块 if (pixy.ccc.numBlocks) { for (int i 0; i pixy.ccc.numBlocks; i) { printf(block %d: x%d y%d w%d h%d\n, i, pixy.ccc.blocks[i].m_x, pixy.ccc.blocks[i].m_y, pixy.ccc.blocks[i].m_width, pixy.ccc.blocks[i].m_height); } } usleep(20000); // 20ms 一轮约 50fps } return 0; }逻辑说明pixy.init()完成 USB 枚举和固件版本握手changeProg切换到色块识别程序这一步不做的话默认程序可能不是你要的getBlocks()是一次阻塞式读取返回当前帧里所有符合条件的色块。usleep的时长决定了轮询频率设太小会占满 CPU设太大追踪会滞后。参数说明setLamp(1,1)的两个参数分别控制上下补光灯近距离识别时开灯能显著提升稳定性但远距离或反光物体上开灯反而会干扰。色块识别的阈值不在代码里设而是在pixymon里调好之后保存在模块内部代码只负责读结果。这是很多人绕不过来的点算法参数在硬件里不在你的程序里。3.3 在 Arduino 上用 I2C 读取数据如果主控是 Arduino接线和代码都更简单。典型接法是 SDA、SCL、GND、5V 四根线注意电平匹配#include Pixy2I2C.h Pixy2I2C pixy; void setup() { Serial.begin(115200); pixy.init(); // 初始化 I2C默认地址 0x54 } void loop() { pixy.ccc.getBlocks(); if (pixy.ccc.numBlocks) { Serial.print(detected: ); Serial.println(pixy.ccc.numBlocks); Serial.print(x); Serial.println(pixy.ccc.blocks[0].m_x); } delay(20); }逻辑说明Pixy2I2C是专门为 I2C 封装的类接口和 USB 版基本一致切换通信方式时业务代码几乎不用改。init()默认地址是0x54如果总线上有冲突需要在模块设置里改地址。参数说明I2C 速率默认 100kHz数据量大时可以提到 400kHz但线长超过 20cm 后高速率容易出错。delay(20)同样控制轮询节奏Arduino 上不要用更小的值否则getBlocks会频繁超时。4. 避坑与排查那些让 Pixy2 项目卡住的典型问题4.1 编译时报找不到 libusb 或 boost现象make阶段报fatal error: libusb.h: No such file or directory或链接阶段报undefined reference to boost::...。原因依赖包没装全或者装了但头文件路径没被Makefile找到。部分发行版把 boost 拆成多个子包只装libboost-dev不够。解决按 2.2 节的依赖列表完整安装然后用pkg-config --cflags --libs libusb-1.0确认路径。如果Makefile里写死了旧路径手动改成pkg-config输出。4.2 程序能编译但运行时找不到设备现象pixy.init()返回负值pixymon也连不上。原因三种可能——USB 权限不足、设备被其他程序占用、线缆只供电不传数据。解决先用lsusb确认设备在列表里再检查 udev 规则是否生效然后确认没有其他进程占用pixymon和你的程序不能同时开最后换一根确认能传数据的线。很多廉价 USB 线只有电源线这个坑我踩过不止一次。4.3 色块识别忽有忽无坐标跳动大现象同一物体在画面里有时能识别有时不能坐标来回跳。原因光照变化、阈值设置过窄、物体颜色和背景太接近、补光灯干扰。解决回到pixymon里重新调阈值把Signature的色相范围适当放宽同时观察Overexposure指示。如果开了补光灯试试关掉对比效果。另外摄像头自动增益在光线变化时会引入波动固定曝光参数通常更稳。4.4 I2C 通信随机丢包或返回全零现象Arduino 端偶尔读到numBlocks为 0或者数据明显不对。原因I2C 上拉电阻缺失或阻值不合适、线太长、主从速率不匹配、总线上有其他设备干扰。解决SDA/SCL 各接一个 4.7k 上拉到 3.3V 或 5V按模块电平定线长控制在 20cm 以内速率先降到 100kHz 验证。如果总线上挂了多个设备逐个拔掉排查地址冲突。4.5 固件烧录后模块无响应现象按文档烧录固件后模块不再被识别灯也不亮。原因烧录过程中断电、烧录了不匹配的固件版本、进入 DFU 模式后没正确退出。解决尝试重新上电并按住模块上的按钮进入恢复模式用官方烧录脚本重新写入。烧录时保证供电稳定不要用电脑前置 USB 口。如果模块彻底不认检查是不是把 bootloader 也覆盖了这种情况只能走硬件恢复流程。5. 进阶用法把 Pixy2 当传感器用而不是当摄像头用5.1 用 getBlocks 之外的接口拿更多信息很多人只用了ccc.getBlocks()其实 Pixy2 还提供线段检测、交叉点检测、条形码识别等程序。切换方式就是changeProg换一个名字然后调用对应的读取接口。比如做循迹时line程序返回的线段端点比色块坐标更有用pixy.changeProg(line); pixy.line.getMainFeatures(); if (pixy.line.numVectors) { // 取第一条线段的起点和终点 int x0 pixy.line.vectors[0].m_x0; int y0 pixy.line.vectors[0].m_y0; int x1 pixy.line.vectors[0].m_x1; int y1 pixy.line.vectors[0].m_y1; }逻辑说明getMainFeatures触发一次完整读取numVectors表示当前帧检测到的线段数量。线段数据比色块更适合做路径拟合因为它的方向信息是现成的。参数说明线段检测对光照和对比度更敏感pixymon里的Line选项卡有专门的阈值。如果线断断续续优先调minLineWidth和对比度而不是改代码。5.2 多模块协同与坐标映射当一个 Pixy2 覆盖不了全部视野时可以用多个模块拼接。关键不是硬件堆叠而是坐标统一。我的做法是每个模块单独标定记录各自视野在全局坐标系里的偏移和缩放然后在主控里做一次线性变换。标定用的是一个已知尺寸的标记物在重叠区域里移动记录两组坐标解出变换矩阵。这一步不做两个模块的数据永远对不齐。5.3 一个容易被忽略的验证习惯每次改完阈值或切换程序不要直接跑业务代码先在pixymon里看原始输出。pixymon的Raw视图能显示模块内部实际看到的东西很多“代码问题”其实是参数问题。我现在的习惯是任何视觉相关的异常先开pixymon看十秒再决定要不要动代码。这个习惯帮我省掉了大量无谓的调试时间。希望帮到你。本文还有配套的精品资源点击获取