1. 代码开发工具链先跑通:Jetson Nano 上的 NCNN 检测与 GPIO 报警
代码开发工具链在边缘板子上跑不通时,目标检测代码写得再漂亮也只能停在编译窗口。我拿到一块 Jetson Nano,要做的事情很具体:用 OpenCV 接摄像头,用 NCNN 跑 yolo-fastest,把画面里的 dog 检出来,然后往 GPIO79 写电平,对应板子 pin12 的报警脚。模型不是重点,CMake、OpenCV、NCNN 静态库、GStreamer 管道、sysfs GPIO,这几样才是当天能不能跑起来的关键。
反直觉的地方在于,计算机视觉Demo最耗时的往往不是调模型,而是工程骨架没搭对:头文件路径差一层、模型文件路径写死、摄像头管道和 USB 索引同时定义、GPIO export 重复执行。这些点单看都不难,凑在一个代码开发工具链里就会连环翻车。这篇按“目录与 CMake → 摄像头与推理 → 输出解析与 GPIO → 避坑 → 验证”的顺序写,适合刚把板子刷好、准备把检测结果落到硬件管脚上的读者。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链的工程骨架:CMake 把 NCNN 与 OpenCV 接进来
先把工程目录稳定下来。这个例子不把 NCNN 源码拖进项目,而是把编译好的 libncnn.a 当静态库导入,CMake 只负责三件事:找到 NCNN 的头文件和静态库、找到 OpenCV、把 main.cpp 链成可执行文件。目录稳定之后,后面换模型、换摄像头、改 GPIO 都只动局部,不会把编译脚本越改越乱。
2.1 目录结构:头文件、静态库、模型各放各的位置
材料里的工程结构是 build、include/ncnn、lib/libncnn.a、main.cpp、model/yolo-fastest.param 和 model/yolo-fastest.bin。这个划分值得保留:include 只放头文件,lib 只放静态库,model 只放运行时加载的模型文件。编译期需要的是前两者,运行期需要的是 model 目录,三者不要混在一个文件夹里。
bash复制# 工程目录只保留编译入口、NCNN 头文件/静态库和模型
tree -L 2
.
├── build
│ ├── CMakeCache.txt
│ ├── CMakeFiles
│ ├── cmake_install.cmake
│ ├── main
│ └── Makefile
├── CMakeLists.txt
├── include
│ └── ncnn
├── lib
│ ├── cmake
│ └── libncnn.a
├── main.cpp
└── model
├── yolo-fastest.bin
└── yolo-fastest.param
build 是外部构建目录,cmake .. 生成的 Makefile 和中间文件都落在这里,源码目录保持干净。include/ncnn 下放 net.h、cpu.h、gpu.h、datareader.h 这些头文件,源码里写 #include "net.h" 时,编译器就是靠 CMake 里的 include_directories 找到它。lib/libncnn.a 是静态库,链接时直接进可执行文件,不依赖运行时再找 .so。model 下的 .param 是网络结构,.bin 是权重,这两个文件不参与编译,只参与运行,所以 CMake 不负责拷贝它们。
这一步最容易出现的误会是“CMake 编过了,程序就一定能跑”。编译只检查头文件和符号,模型路径是运行时才打开的。后面第 4 章会把路径问题单独拆开讲,这里先把目录边界定死:include 对编译,lib 对链接,model 对运行。
2.2 CMakeLists.txt 的最小闭环:静态库导入与 OpenCV 查找
CMake 文件不需要写得很花,能把 NCNN 静态库、OpenCV 库和 C++ 标准定清楚就够了。下面这段来自材料,我补了注释,方便看清每一行在做什么:
cmake复制cmake_minimum_required(VERSION 3.10)
project(untitled3)
# NCNN 的静态库和部分实现会用到 OpenMP,C 和 C++ 编译选项都带上
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fopenmp")
# 让源码里的 #include "net.h" 能找到 include/ncnn 下的头文件
include_directories(${CMAKE_SOURCE_DIR}/include/ncnn/)
# 把 lib/libncnn.a 当作已编译好的静态库导入
add_library(libncnn STATIC IMPORTED)
set_target_properties(libncnn PROPERTIES
IMPORTED_LOCATION ${CMAKE_SOURCE_DIR}/lib/libncnn.a)
# OpenCV 用 find_package 找,不手写一堆 include 和 lib 路径
find_package(OpenCV REQUIRED)
set(CMAKE_CXX_STANDARD 11)
add_executable(main main.cpp)
target_link_libraries(main libncnn ${OpenCV_LIBS})
cmake_minimum_required(VERSION 3.10) 给 CMake 一个最低版本,project(untitled3) 是工程名,不影响功能。CMAKE_CXX_FLAGS 和 CMAKE_C_FLAGS 都追加 -fopenmp,是因为 NCNN 静态库在链接阶段可能还需要 OpenMP 符号;只给 C++ 加、不给 C 加,某些环境下仍会在链接时缺符号。include_directories 指向 ${CMAKE_SOURCE_DIR}/include/ncnn/,所以源码里可以直接写 #include "net.h",不需要写成 #include "ncnn/net.h"。
add_library(libncnn STATIC IMPORTED) 表示这不是本项目编译出来的库,而是外部已经存在的静态库;IMPORTED_LOCATION 必须指向真实的 libncnn.a。这里用 ${CMAKE_SOURCE_DIR} 而不是相对路径,是为了避免在 build 目录里执行 cmake .. 时相对路径基准变化。find_package(OpenCV REQUIRED) 找到 OpenCV 后,${OpenCV_LIBS} 会展开成需要链接的库列表;如果系统里装了 OpenCV 但 CMake 找不到,问题在 OpenCV_DIR 或开发包,不在 main.cpp。
set(CMAKE_CXX_STANDARD 11) 对应 NCNN 示例的 C++11 用法。add_executable(main main.cpp) 只编译一个入口文件,target_link_libraries(main libncnn ${OpenCV_LIBS}) 把静态库和 OpenCV 按顺序接上。链接顺序上,main 依赖 libncnn,libncnn 又可能需要 OpenCV 和 OpenMP,所以 libncnn 放在 ${OpenCV_LIBS} 前面更稳。
2.3 构建命令与运行目录:模型路径不要照抄示例机器
构建时进入 build 目录,让 CMake 在外部目录生成 Makefile:
bash复制# 在工程根目录执行,build 目录已存在时直接进入
mkdir -p build
cd build
cmake ..
make -j
cmake .. 读取上一级的 CMakeLists.txt,make -j 并行编译。编译产物是 build/main,但运行时不建议在 build 里直接双击,因为模型路径可能是相对工程根目录写的。材料里的源码用 detector.load_param(".../model/yolo-fastest.param") 和 detector.load_model(".../model/yolo-fastest.bin") 加载模型,这两个字符串是运行时路径,不是 CMake 变量。把示例里的绝对路径换成自己机器上的实际路径,或者从工程根目录运行并写成 model/yolo-fastest.param、model/yolo-fastest.bin,先 ls model 确认两个文件都在,再启动程序。
还有一个细节:源码里同时出现了 <opencv4/opencv2/opencv.hpp> 和 <opencv2/core/core.hpp> 两类写法。前者依赖系统 include 前缀,后者依赖 find_package(OpenCV) 给出的 include 目录。如果编译时报 opencv2/...: No such file,先看 CMake 是否真的找到了 OpenCV,再检查系统里 OpenCV 头文件的安装位置,不要一上来就改源码里的 include 路径。代码开发工具链的麻烦通常出在路径配置,不是出在业务代码。
3. 从摄像头到 GPIO:NCNN 推理循环里的预处理、输出解析与电平动作
工程能编过之后,主循环要按固定顺序走:取一帧、缩放到 320×320、BGR 转 RGB、减均值除归一化、输入 data、取出 output、按行解析检测框、命中 dog 时写 GPIO79。每一段都有明确参数,参数不对时现象也很直接:画面颜色不对、框位置偏移、程序卡在加载模型、GPIO 不动作。下面按这个顺序拆。
3.1 GStreamer 管道与摄像头选择:CSI 和 USB 只能二选一
CSI 摄像头用 GStreamer 管道,USB 摄像头用设备索引。材料里把两种写法都写出来了,但 cv::VideoCapture cap 只能定义一次,实际工程里必须注释掉另一行。先看管道函数:
cpp复制string gstreamer_pipeline(int capture_width, int capture_height,
int display_width, int display_height,
int framerate, int flip_method)
{
return "nvarguscamerasrc ! video/x-raw(memory:NVMM), width=(int)" + to_string(capture_width) +
", height=(int)" + to_string(capture_height) +
", format=(string)NV12, framerate=(fraction)" + to_string(framerate) +
"/1 ! nvvidconv flip-method=" + to_string(flip_method) +
" ! video/x-raw, width=(int)" + to_string(display_width) +
", height=(int)" + to_string(display_height) +
", format=(string)BGRx ! videoconvert ! video/x-raw, format=(string)BGR ! appsink";
}
capture_width 和 capture_height 设成 1280×720,display_width 和 display_height 也设成 1280×720,framerate 是 60,flip_method 是 0。nvarguscamerasrc 取 CSI 摄像头,memory:NVMM 表示帧在 NVMM 内存里,NV12 是采集格式;nvvidconv 做转换,flip-method=0 表示不翻转;后面转成 BGRx,再 videoconvert 成 BGR,最后 appsink 交给 OpenCV。CAP_GSTREAMER 是 OpenCV 的采集后端,OpenCV 编译时没有带 GStreamer 支持就会打不开这个管道。
调用时这样选摄像头:
cpp复制int capture_width = 1280;
int capture_height = 720;
int display_width = 1280;
int display_height = 720;
int framerate = 60;
int flip_method = 0;
string pipeline = gstreamer_pipeline(capture_width, capture_height,
display_width, display_height,
framerate, flip_method);
// CSI 摄像头:走 GStreamer 管道
cv::VideoCapture cap(pipeline, CAP_GSTREAMER);
// USB 摄像头:用设备索引,和上面这行二选一,不能同时定义 cap
// cv::VideoCapture cap(1);
如果画面倒置,改 flip_method 再试;如果 CSI 打不开,先确认管道字符串和 CAP_GSTREAMER 后端,再换 USB 的 cap(1) 做对照。USB 摄像头不一定编号是 1,换口或换设备时索引会变,先用系统工具确认设备节点。这里不要同时保留两行 cap,否则编译期就会报重定义,后面第 4 章会展开。
3.2 NCNN 预处理:320×320、BGR2RGB、均值与归一化
取到帧之后,NCNN 的输入不是原始 cv::Mat,而是 ncnn::Mat。材料里的预处理是:
cpp复制int detector_size_width = 320;
int detector_size_height = 320;
ncnn::Mat in = ncnn::Mat::from_pixels_resize(
bgr.data, ncnn::Mat::PIXEL_BGR2RGB,
bgr.cols, bgr.rows,
detector_size_width, detector_size_height);
const float mean_vals[3] = {0.f, 0.f, 0.f};
const float norm_vals[3] = {1/255.f, 1/255.f, 1/255.f};
in.substract_mean_normalize(mean_vals, norm_vals);
ncnn::Extractor ex = detector.create_extractor();
ex.set_num_threads(8);
ex.input("data", in);
ncnn::Mat out;
ex.extract("output", out);
from_pixels_resize 一次完成缩放和通道转换,PIXEL_BGR2RGB 是因为 OpenCV 默认读出来是 BGR,而模型输入通常按 RGB 组织。detector_size_width 和 detector_size_height 都设 320,必须和模型训练/导出时的输入尺寸一致;改成别的尺寸不是不行,但输出坐标还原和精度都会变,先按 320×320 跑通。mean_vals 三个 0,norm_vals 三个 1/255.f,表示只做 0 到 1 的归一化,不减均值。这个组合要和模型本身匹配,换模型时不能照搬。
ex.set_num_threads(8) 是推理线程数,示例给 8;ex.input("data", in) 里的 "data" 是输入层名字,ex.extract("output", out) 里的 "output" 是输出层名字。这两个名字来自 .param 文件,换模型后名字可能变,不能想当然。out 是一个二维结构,后面按 out.h 行数遍历,每一行取 values。
3.3 输出解析:values[0..5] 与坐标越界处理
输出解析是检测循环里最需要看清下标的一段。材料里的每个检测结果占一行,values[0] 是类别编号,values[1] 是分数,values[2] 到 values[5] 是归一化后的 x1、y1、x2、y2。还原到原图坐标要乘 img_w 和 img_h,画框前还要把越界坐标夹回画面内:
cpp复制static const char* class_names[] = {
"background", "aeroplane", "bicycle", "bird", "boat",
"bottle", "bus", "car", "cat", "chair",
"cow", "diningtable", "dog", "horse", "motorbike",
"person", "pottedplant", "sheep", "sofa", "train", "tvmonitor"
};
for (int i = 0; i < out.h; i++) {
const float* values = out.row(i);
int label = values[0];
float score = values[1];
float x1 = values[2] * img_w;
float y1 = values[3] * img_h;
float x2 = values[4] * img_w;
float y2 = values[5] * img_h;
// 坐标越界会把框画到画面外,先夹回图像范围
if (x1 < 0) x1 = 0;
if (y1 < 0) y1 = 0;
if (x2 < 0) x2 = 0;
if (y2 < 0) y2 = 0;
if (x1 > img_w) x1 = img_w;
if (y1 > img_h) y1 = img_h;
if (x2 > img_w) x2 = img_w;
if (y2 > img_h) y2 = img_h;
cv::rectangle(image, cv::Point(x1, y1), cv::Point(x2, y2),
cv::Scalar(255, 255, 0), 1, 1, 0);
char text[256];
sprintf(text, "%s %.1f%%", class_names[label], score * 100);
int baseLine = 0;
cv::Size label_size = cv::getTextSize(text, cv::FONT_HERSHEY_SIMPLEX,
0.5, 1, &baseLine);
cv::putText(image, text, cv::Point(x1, y1 + label_size.height),
cv::FONT_HERSHEY_SIMPLEX, 0.5, cv::Scalar(0, 0, 0));
}
out.h 是当前帧输出的行数,out.row(i) 拿到第 i 行的指针。label 直接当 class_names 的下标用,所以类别表顺序必须和模型一致;score * 100 只是显示成百分比,不改变判断。cv::rectangle 的线宽是 1,颜色是 (255,255,0);putText 的字号是 0.5。坐标夹取要在画框之前做,否则 x2 大于 img_w 时框会画到图像外,调试时看起来像“检测框漂移”。
材料里的示例没有在画框前加分数过滤,这意味着低分结果也会被画出来,甚至继续触发后面的 GPIO 判断。实际工程里要在 label 和 score 取出来后加一行判断,分数阈值按你的误报容忍度调,不要照搬别人的数值;先让框只画高置信结果,再决定 GPIO 是否动作。
3.4 GPIO 初始化与 dog 报警:export、direction、value 三步
GPIO 部分用的是 sysfs 接口,路径是 /sys/class/gpio。材料里 GPIO79 对应板子 pin12,初始化只做一次:export 出 79 号,direction 设成 out。检测循环里命中 dog 时写 value:
cpp复制// 只初始化一次:GPIO79 对应板子 pin12
system("echo 79 > /sys/class/gpio/export");
system("echo out > /sys/class/gpio/gpio79/direction");
// 检测到 dog 时输出短脉冲
if (class_names[label] == "dog") {
system("echo 1 > /sys/class/gpio/gpio79/value");
system("echo 0 > /sys/class/gpio/gpio79/value");
}
echo 79 > export 让内核创建 gpio79 目录,echo out > direction 把引脚设为输出,echo 1 > value 拉高,echo 0 > value 拉低。材料里的报警动作是“拉高后立刻拉低”,形成短脉冲;如果外接的是继电器或需要保持电平的报警器,这种写法可能只看到一闪,甚至完全看不到动作。要保持就写 1 后根据业务延时或状态机再写 0,不要在这个判断里立刻写 0。
system() 每次都会启动 shell,放在每帧循环里开销不小,做验证可以,做长期运行要换成文件写入或 GPIO 库。还有,export 和 direction 不应该每帧执行;材料里把它们放在 test_cam() 初始化阶段,这个位置是对的。system() 的返回值也建议检查,写失败时至少能在终端看到,不要让它静默失败。
4. 代码开发工具链避坑:五条从现象到解决的排查记录
这一章只写能从这个工程里直接推出来的坑。现象、原因、解决都按实际排查顺序来,先编译期,再运行期,最后检测逻辑。很多问题不是代码写错,而是工具链的路径、生命周期和电平时序没对齐。
4.1 编译期:cap 重复定义与 CMake 找不到库
现象: make 时报 redefinition of 'cap',或者提示 cv::VideoCapture cap 同一作用域重复定义。
原因: CSI 摄像头和 USB 摄像头两行都保留了:一行是 cv::VideoCapture cap(pipeline, CAP_GSTREAMER);,另一行是 cv::VideoCapture cap(1);。材料里本来是想展示两种接法,但 C++ 同一作用域不能有两个同名变量。
解决: 按实际摄像头二选一,注释掉另一行;如果要在运行时切换,用两个不同变量名或把采集封装成函数,不要在同一段里重复定义。改完先只编译,不接摄像头,确认编译通过再处理运行问题。
现象: CMake 配置阶段报 Could NOT find OpenCV,或者链接阶段提示找不到 libncnn.a。
原因: find_package(OpenCV REQUIRED) 找不到 OpenCV 的开发包;IMPORTED_LOCATION 指向的 lib/libncnn.a 不存在,或者路径相对基准不对。
解决: 先确认 lib/libncnn.a 真实存在,include/ncnn 下有 net.h;CMake 里用 ${CMAKE_SOURCE_DIR} 拼绝对路径。OpenCV 侧先看系统是否装了开发包,再看 find_package 的输出;不要在源码里临时加一堆 -I 和 -L 掩盖问题。链接顺序保持 main → libncnn → OpenCV_LIBS,OpenMP 的 -fopenmp 在 C 和 C++ 编译选项里都保留。
4.2 运行期:模型路径与 GPIO 生命周期
现象: 程序启动后没有检测窗口,或者刚运行就退出,终端没有进入摄像头循环。
原因: detector.load_param() 和 detector.load_model() 用了示例机器上的绝对路径,换目录后 .param 或 .bin 不存在。编译阶段不会检查这个路径,所以 CMake 编过了不代表模型能加载。
解决: 从工程根目录运行,把路径改成 model/yolo-fastest.param 和 model/yolo-fastest.bin,先 ls model 确认两个文件;如果必须用绝对路径,确认路径中没有多余空格和转义。加载后检查返回值,失败就打印实际路径,不要只看“程序没反应”。
现象: 终端反复出现 GPIO 写失败,或者 gpio79 目录已经存在但程序还在执行 export。
原因: echo 79 > /sys/class/gpio/export 只需要执行一次;重复 export 会返回忙或权限类错误。另一个常见原因是当前用户没有写 /sys/class/gpio 的权限,或者引脚已经被别的进程占用。
解决: 初始化阶段先判断 /sys/class/gpio/gpio79 是否存在,不存在再 export;export 后写 direction 为 out,然后再进入循环。权限问题用有权限的用户运行,排查时先手动执行下面三条,确认硬件和权限都通,再让程序接管:
bash复制# 手动验证 GPIO79 的 export、方向和电平
echo 79 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio79/direction
echo 1 > /sys/class/gpio/gpio79/value
echo 0 > /sys/class/gpio/gpio79/value
手动能点亮/拉高,程序里不动作,问题就在程序的执行路径或时序;手动也不动作,先查引脚编号、外围电路和权限,不要继续改检测代码。
4.3 检测逻辑:dog 打印了但执行器只闪一下
现象: 串口或终端已经打印 dog,但外接的灯/继电器只闪一下,甚至看不到动作。
原因: 材料里的报警动作是 echo 1 后立刻 echo 0,脉冲宽度极短;如果执行器有响应时间,或者 system() 启动 shell 的时间比脉冲还长,看起来就像没动作。另一个原因是 system() 在每帧循环里调用,帧率一高,写文件的节奏会抖动。
解决: 先区分“需要短脉冲”还是“需要保持电平”。需要保持就把写 1 和写 0 拆开,用状态变量记录当前是否已报警,命中后保持,离开目标或超时再复位;需要短脉冲就查执行器的最小响应时间,不要把 1 和 0 挤在同一行逻辑里。验证时先手动写 1、延时、写 0,确认硬件能响应,再回到程序里调时序。
补充排查: 如果画面里没有 dog 也触发 GPIO,检查输出循环是否在 score 判断之前就执行了 class_names[label] == "dog"。材料里的示例没有分数过滤,低分结果也会走到 GPIO 分支;在画框和 GPIO 之前加分数判断,阈值按误报容忍度调,先观察一段时间再定。
5. 代码开发工具链的验证与参数收口:先手动点亮 GPIO,再让检测循环接管
验证顺序建议固定成三步:先手动验证 GPIO,再跑静态图/单帧推理,最后接摄像头跑循环。这样出问题时能快速定位是硬件、模型还是采集。参数先按下面这张表收口,别一上来就改一堆:
| 项目 | 示例值 | 说明 |
|---|---|---|
| 检测输入尺寸 | 320×320 | detector_size_width / detector_size_height |
| 推理线程数 | 8 | ex.set_num_threads(8) |
| CSI 采集分辨率 | 1280×720 | capture_width / capture_height |
| 显示分辨率 | 1280×720 | display_width / display_height |
| 帧率 | 60 | framerate |
| 翻转 | 0 | flip_method,画面倒置时再调 |
| GPIO 编号 | 79 | 对应板子 pin12 |
| 模型文件 | model/yolo-fastest.param、model/yolo-fastest.bin |
运行时加载,不参与编译 |
手动验证 GPIO 的代码就是上一章那三条 echo,先确认 export、direction、value 都能写成功,再跑 build/main。程序跑起来后,先看终端有没有打印类别和分数,再看画框位置是否贴合,最后看 GPIO 是否在 dog 出现时动作。如果框位置偏,先查 values[2..5] 乘的是不是原图宽高;如果类别不对,先查 class_names 顺序和模型输出层名字;如果 GPIO 不动,先回到手动写值,不要同时改模型和硬件。
我自己的习惯是:每次换板子或换摄像头,都先手动 export/direction/value 走一遍,再跑检测循环;模型路径也先 ls 确认,不把示例里的绝对路径带进新工程。血泪经验是,代码开发工具链里最贵的不是写代码的时间,而是把编译通过误当成运行通过。从那以后我每次把检测结果接到 GPIO 之前,都强制先做一遍手动电平验证,再让程序接管。希望帮到你。
