1. 为什么要在 ESP32 上折腾 ONVIF 相机先说清楚这个项目到底在干什么。onvif-c是一个用纯 C 写的、基于 ESP-IDF 的组件目标很明确把一块 ESP32 变成一台能被标准 NVR网络录像机直接添加、自动发现、正常拉流的网络摄像机。注意这里的关键词是能被 NVR 添加——这跟能出图完全是两码事。很多人用 ESP32 摄像头跑通了 HTTP 的 MJPEG 流浏览器里看得挺爽结果一接到海康、大华、群晖 Surveillance Station 上NVR 死活搜不到设备或者搜到了添加失败或者添加成功但一直显示连接中。问题就出在 ONVIF 这套协议栈上。ONVIF 不是单一协议它是一整套基于 SOAP/XML 的规范集合摄像机要跟 NVR 打交道至少得实现三块设备发现WS-Discovery、设备管理Device Management、媒体服务Media Service。NVR 添加一台相机的典型流程是这样的先通过 WS-Discovery 的组播探测拿到设备地址然后调用GetDeviceInformation、GetCapabilities、GetProfiles、GetStreamUri这一串 SOAP 接口最后拿 RTSP 地址去拉流。任何一环返回的 XML 格式不对、命名空间错了、SOAPAction 头缺失NVR 就直接放弃。那为什么非要用 ESP32 做这件事因为便宜、低功耗、体积小而且 ESP-IDF 自带的esp_http_server和 lwIP 协议栈足够撑起一个轻量 ONVIF 服务端。一块 ESP32-S3 核心板加个 OV2640/OV5640 摄像头模组成本压到几十块做出来的东西能进标准安防生态这在做小批量定制监控、DIY 家庭 NVR、边缘 AI 视觉节点的时候非常香。这个组件适合谁看适合已经会 ESP-IDF 基本工程搭建、懂一点 HTTP 和 XML、想把自己的 ESP32 摄像头接入正规 NVR 的开发者。如果你连idf.py build都没跑过建议先把 ESP-IDF 的环境搭起来再回来。我踩过的第一个大坑就是以为 ONVIF 就是个 HTTP 服务器返回几段固定 XML 就行。实际上 NVR 的兼容性测试极其严格尤其是 WS-Discovery 的组播响应格式差一个字节都发现不了。下面我把整个从建工程到被 NVR 成功添加的完整路径拆开讲。2. 整体架构设计与方案选型思路2.1 为什么选纯 C esp_http_server 而不是别的市面上做 ESP32 ONVIF 有几条路一是用 MicroPython 写开发快但性能和内存控制差SOAP 解析容易崩二是用 Arduino 框架生态好但底层网络控制不够细组播和 socket 选项不好调三是纯 ESP-IDF C门槛高但可控性最强。onvif-c 选的是第三条路原因很实在ONVIF 服务端需要长时间稳定运行需要精确控制 socket 的组播加入、需要手动管理 HTTP 的 SOAPAction 头、需要跟 RTSP 服务共享同一套媒体参数这些在纯 C 下最顺手。esp_http_server是 ESP-IDF 自带的 HTTP 服务组件基于 lwIP支持多 URI handler 注册。用它来承载 ONVIF 的 SOAP 端点通常是/onvif/device_service和/onvif/media_service非常合适。它的工作模式是你注册一个 URI绑定一个 handler 函数请求进来后 handler 拿到httpd_req_t自己解析 body、自己拼 XML 响应。ONVIF 的请求都是 POSTbody 是 SOAP 信封所以 handler 里主要干两件事从 XML 里抠出操作名和参数然后按规范拼响应。这里有个设计决策值得说要不要用 XML 解析库。ESP-IDF 里可以塞进 tinyxml2 或者 expat但会吃掉不少 flash 和 RAM。onvif-c 的做法是轻量字符串匹配——因为 ONVIF 请求的操作名都在固定的标签里比如GetStreamUri用strstr定位标签、再截取内容比完整解析整棵树省得多。这个取舍在资源紧张的 ESP32 上是合理的代价是代码里字符串处理要格外小心遇到命名空间前缀变化有的 NVR 用trt:有的用tt:就得做兼容。2.2 三大服务模块的职责划分整个组件按 ONVIF 规范切成三块每块对应一组 SOAP 操作模块对应规范核心操作承载方式设备发现WS-DiscoveryProbe / ProbeMatch / HelloUDP 组播 239.255.255.250:3702设备管理Device ManagementGetDeviceInformation / GetCapabilities / GetSystemDateAndTimeHTTP SOAP媒体服务Media ServiceGetProfiles / GetStreamUri / GetVideoEncoderConfigurationHTTP SOAPWS-Discovery 走的是 UDP 组播跟 HTTP 完全分开这是最容易漏掉的一块。NVR 开机后会往239.255.255.250:3702发一个 Probe 组播包里面带一个wsd:Probe的 SOAP 信封设备收到后必须单播回一个ProbeMatch里面包含自己的 UUID、设备类型tds:Device或tds:NetworkVideoTransmitter和服务地址。很多人的 ESP32 相机 NVR 搜不到90% 是这一步没做或者做错了。设备管理和媒体服务都挂在 HTTP 上但要注意 ONVIF 规范里这两个服务可以放在同一个端口的不同路径也可以分端口。onvif-c 默认用同一个esp_http_server实例注册两个 URI这样省一个 socket也方便共享设备信息。2.3 与 RTSP 服务的关系ONVIF 本身不传视频它只负责告诉 NVR 去哪里拉流。所以GetStreamUri返回的是一个 RTSP URL比如rtsp://192.168.1.100:554/stream1。这意味着你的 ESP32 上还得跑一个 RTSP 服务端把摄像头数据封装成 RTP 包发出去。ONVIF 组件和 RTSP 组件之间通过一个共享的配置结构体通信——分辨率、帧率、编码格式这些参数ONVIF 的GetVideoEncoderConfiguration要能报出来RTSP 的实际推流也要按这个来两边必须一致否则 NVR 拿到的 profile 跟实际流对不上会花屏或者直接拒绝。我的建议是先把 RTSP 推流跑通确认 VLC 能拉到流再上 ONVIF。因为 ONVIF 调试的时候你没法确定问题出在协议层还是流层分开验证能省大量时间。3. 核心细节解析与实操要点3.1 WS-Discovery 的组播实现细节WS-Discovery 是整个项目里最玄学的部分因为它依赖 UDP 组播而组播在不同网络环境下的行为差异很大。实现上要做这几件事第一创建一个 UDP socket绑定到 3702 端口。注意要设置SO_REUSEADDR否则重启程序时端口可能还被占用。第二加入组播组239.255.255.250用IP_ADD_MEMBERSHIP。第三设置 socket 为可接收组播并且要处理SO_BROADCAST相关选项。第四起一个独立任务循环recvfrom收到 Probe 就解析并回 ProbeMatch。// 加入组播组的核心代码示意 struct ip_mreq mreq; mreq.imr_multiaddr.s_addr inet_addr(239.255.255.250); mreq.imr_interface.s_addr htonl(INADDR_ANY); setsockopt(sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, mreq, sizeof(mreq));回 ProbeMatch 的时候有个关键点响应必须单播回发送方的源地址和源端口不能也组播回去。NVR 发 Probe 时用的源端口通常是随机的你要从recvfrom拿到的struct sockaddr_in里取出来原样回过去。另外 ProbeMatch 里的XAddrs字段要填你设备的 HTTP 服务地址NVR 拿到这个地址后才会去调 SOAP 接口。注意ESP32 默认的 lwIP 配置里组播可能是关的需要在menuconfig里确认LWIP_IGMP打开否则IP_ADD_MEMBERSHIP会失败。这个坑我调了一整天才发现。3.2 SOAP 请求的解析与响应拼装ONVIF 的 SOAP 请求长这样简化soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope soap:Body GetStreamUri xmlnshttp://www.onvif.org/ver10/media/wsdl ProfileTokenprofile_1/ProfileToken /GetStreamUri /soap:Body /soap:Envelope解析的时候先找soap:Body之后的内容再找第一个子标签的名字那就是操作名。参数从子标签里抠。响应要按对应命名空间拼比如媒体服务的响应命名空间是http://www.onvif.org/ver10/media/wsdl设备管理是http://www.onvif.org/ver10/device/wsdl。命名空间写错是 NVR 拒绝的第二大原因。响应里还要注意 SOAP 版本。ONVIF 用的是 SOAP 1.2Content-Type 必须是application/soapxml; charsetutf-8而且action参数要带上完整的操作名比如actionhttp://www.onvif.org/ver10/media/wsdl/GetStreamUri。有些 NVR 会检查这个头缺了就直接 400。3.3 设备信息与 Capabilities 的构造GetDeviceInformation要返回制造商、型号、固件版本、序列号、硬件 ID。这些字段虽然是字符串但 NVR 可能会拿来做去重和展示建议填真实有意义的值别全填 test。序列号最好用 ESP32 的 MAC 地址生成保证唯一。GetCapabilities更关键它告诉 NVR 这台设备支持哪些服务、每个服务的地址在哪。响应里要列出 Device、Media、Events如果支持等分类每类给出XAddr。这个地址必须跟实际 HTTP 服务地址一致否则 NVR 后续调用会打到不存在的端口。tds:Capabilities tds:Media tt:XAddrhttp://192.168.1.100/onvif/media_service/tt:XAddr /tds:Media /tds:Capabilities3.4 Profile 与 StreamUri 的对应关系ONVIF 里 Profile 是一路视频配置的抽象包含视频编码、分辨率、帧率、码率以及对应的流地址。GetProfiles返回所有 profile 的列表每个 profile 有个 token比如profile_1。GetStreamUri根据传入的 token 返回对应的 RTSP 地址。对 ESP32 来说通常只支持一路流所以返回一个 profile 就够了。但要注意 profile 里的VideoEncoderConfiguration参数要跟 RTSP 实际推流参数严格一致。我见过有人 profile 里写 1080p实际推的是 VGANVR 拉流后一直花屏查了半天才发现是这里对不上。4. 完整实操流程从建工程到 NVR 添加成功4.1 工程搭建与组件集成先建一个标准 ESP-IDF 工程idf.py create-project esp32_onvif_cam cd esp32_onvif_cam然后把 onvif-c 组件放进components/目录。ESP-IDF 的组件机制会自动扫描components/下的每个子目录只要里面有CMakeLists.txt就会被编译进来。onvif-c 的CMakeLists.txt里要声明依赖idf_component_register(SRCS onvif_device.c onvif_media.c onvif_discovery.c INCLUDE_DIRS include REQUIRES esp_http_server lwip nvs_flash)主工程的CMakeLists.txt里REQUIRES加上onvif-c。摄像头驱动用esp32-camera组件RTSP 服务可以用现成的esp_rtsp或者自己写。这里假设你已经有一路能出图的 RTSP 流。4.2 网络与组播初始化WiFi 连上之后先初始化 ONVIF 的组播监听。这一步要在 HTTP 服务启动之前做因为 NVR 可能先发 Probe 再调 SOAP。void onvif_discovery_start(void) { int sock socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP); struct sockaddr_in addr { .sin_family AF_INET, .sin_port htons(3702), .sin_addr.s_addr htonl(INADDR_ANY) }; bind(sock, (struct sockaddr*)addr, sizeof(addr)); // 加入组播组 struct ip_mreq mreq; mreq.imr_multiaddr.s_addr inet_addr(239.255.255.250); mreq.imr_interface.s_addr htonl(INADDR_ANY); setsockopt(sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, mreq, sizeof(mreq)); xTaskCreate(discovery_task, onvif_disc, 4096, (void*)sock, 5, NULL); }discovery_task里循环recvfrom收到 Probe 就调build_probe_match拼响应然后sendto回源地址。4.3 HTTP 服务与 SOAP 端点注册启动esp_http_server注册两个 URIhttpd_config_t config HTTPD_DEFAULT_CONFIG(); httpd_handle_t server NULL; httpd_start(server, config); httpd_uri_t device_uri { .uri /onvif/device_service, .method HTTP_POST, .handler device_service_handler }; httpd_register_uri_handler(server, device_uri); httpd_uri_t media_uri { .uri /onvif/media_service, .method HTTP_POST, .handler media_service_handler }; httpd_register_uri_handler(server, media_uri);handler 里先读 body判断操作名分发到对应的构造函数。响应通过httpd_resp_send发出去记得设置正确的 Content-Type。4.4 参数计算分辨率与码率的匹配ESP32 的算力和内存有限摄像头分辨率不能盲目拉满。以 ESP32-S3 OV2640 为例实测下来分辨率帧率JPEG 质量内存占用稳定性VGA 640x48015fps12低很稳SVGA 800x60012fps12中稳HD 1280x7208fps10高勉强FHD 1920x10805fps10很高易崩ONVIF profile 里报的参数要跟这个表对齐。如果你报 1080p 但实际只能跑 5fpsNVR 那边可能因为帧率太低判定流异常。建议初期用 VGA 或 SVGA跑稳了再往上调。码率方面MJPEG 的码率约等于分辨率像素数 × 帧率 × 压缩系数。VGA 15fps 大概 2-4 Mbps这个量级在局域网里没问题。RTSP 推流时 RTP 包大小建议 1400 字节左右避免 IP 分片。4.5 NVR 添加实测记录我用群晖 Surveillance Station 和海康 NVR 各测了一遍。群晖的兼容性相对宽松海康更严格。添加流程NVR 自动搜索几秒内应该能看到设备出现在列表里显示为 ONVIF Device 或你填的制造商名。手动添加时填 IP、ONVIF 端口默认 80、用户名密码如果没做鉴权就留空或随便填。添加后 NVR 会调一串 SOAP 接口观察串口日志能看到GetDeviceInformation、GetCapabilities、GetProfiles、GetStreamUri依次进来。全部返回正确后NVR 开始拉 RTSP 流画面上线。第一次测的时候海康一直添加失败串口日志显示GetCapabilities返回后就没下文了。后来抓包发现是 Capabilities 里的XAddr我写成了http://192.168.1.100:80/onvif/media_service多了个:80海康不认。去掉端口号后立刻通过。这种细节就是纯靠踩坑积累的。5. 常见问题与排查技巧实录5.1 NVR 搜不到设备这是最高频的问题。排查顺序确认 ESP32 和 NVR 在同一网段且中间没有隔离组播的交换机或路由器。很多企业级 AP 默认关闭 IGMP snooping 或者隔离客户端组播包根本到不了。用 Wireshark 抓包看 NVR 有没有发 Probe 到 239.255.255.250:3702。如果没发是 NVR 侧问题如果发了但 ESP32 没回是组播加入失败。检查menuconfig里LWIP_IGMP是否开启。检查 ProbeMatch 的XAddrs地址是否是 NVR 能访问到的地址别填成 127.0.0.1 或 AP 的地址。5.2 添加成功但一直连接中通常是 RTSP 流拉不起来。先用 VLC 手动填rtsp://设备IP:554/stream1测试能出图说明流没问题问题在 ONVIF 返回的 URL 上。检查GetStreamUri返回的地址里的 IP 是不是设备真实 IP端口是不是 RTSP 实际监听端口。5.3 画面花屏或卡顿多半是 profile 参数和实际流不一致。检查GetVideoEncoderConfiguration返回的分辨率、帧率是否跟 RTSP 推流参数匹配。另外 RTP 包大小和 MTU 也要注意ESP32 的 lwIP MTU 默认 1500RTP 负载超过这个会分片分片丢失就花屏。5.4 常见问题速查表现象可能原因排查方法NVR 搜不到组播未加入 / IGMP 未开Wireshark 抓 3702 端口添加失败Capabilities XAddr 错误检查地址格式去掉多余端口连接中无画面RTSP URL 错误VLC 手动测试花屏卡顿profile 与实际流不符对比参数一段时间后掉线内存泄漏 / 任务栈溢出看 heap 和任务水位SOAP 返回 400Content-Type 或 action 头错误抓包看请求头5.5 独家避坑经验第一个经验串口日志一定要打全。ONVIF 调试全靠日志每个进来的 SOAP 操作名、每个发出的响应都打出来。我习惯在 handler 入口打一行ONVIF REQ: op_name出问题一眼就能看出卡在哪一步。第二个经验先用手工构造的 SOAP 请求测。别一上来就接 NVR用 curl 或者 Postman 往/onvif/device_service发一个GetDeviceInformation看返回对不对。这样能把协议层和 NVR 兼容性分开调。curl -X POST http://192.168.1.100/onvif/device_service \ -H Content-Type: application/soapxml; charsetutf-8 \ -d soap:Envelope ...GetDeviceInformation//soap:Envelope第三个经验UUID 要固定。WS-Discovery 的 ProbeMatch 里有个EndpointReference的 UUID如果每次重启都变NVR 会认为是新设备导致重复添加或者配置丢失。用 MAC 地址生成一个稳定的 UUID。第四个经验给 HTTP 服务留足任务栈。esp_http_server默认栈可能不够SOAP 响应拼装时字符串操作多栈溢出会直接重启。我把 httpd 的任务栈调到 8192 才稳。6. 性能优化与稳定性加固6.1 内存管理ESP32 的 RAM 是稀缺资源ONVIF 服务端加上 RTSP 推流内存很容易吃紧。几个优化点SOAP 响应用静态缓冲区拼装别频繁 malloc/freeXML 字符串处理用栈上的固定数组别用动态分配摄像头帧缓冲用双缓冲避免推流和采集抢内存。实测 ESP32-S3 带 8MB PSRAM 的话跑 720p 推流加 ONVIF 服务剩余 heap 还能有 100KB 以上比较安全。6.2 长时间运行稳定性ONVIF 服务要 7x24 跑稳定性比功能更重要。我做了几件事给 discovery 任务和 httpd 任务都加了看门狗喂狗socket 操作加了超时避免阻塞定期打印 heap 水位观察有没有缓慢泄漏。跑过连续 72 小时测试没有重启和掉线。6.3 多 NVR 并发如果网络里有多个 NVR 或者客户端同时探测discovery 任务要能并发处理。因为 UDP 是无连接的每个 Probe 独立响应即可问题不大。但 HTTP 这边要注意esp_http_server的并发连接数配置默认可能只支持几个多客户端同时调 SOAP 会排队。在httpd_config_t里把max_open_sockets调大一点。7. 后续可扩展的方向这套东西跑通之后能玩的花样不少。比如加个Events 服务把 ESP32 的 GPIO 触发、移动侦测结果通过 ONVIF 事件推给 NVR这样 NVR 就能做联动录像。再比如接入边缘 AI用 ESP32-S3 的向量指令跑个轻量的人形检测检测到目标时通过 ONVIF 事件通知 NVR 打标签。还有PTZ 控制如果你的云台是舵机驱动的实现 ONVIF 的 PTZ 服务后NVR 界面上就能直接控制转动。我自己下一步打算把 ONVIF 的鉴权WS-UsernameToken加上现在很多 NVR 要求必须带用户名密码虽然可以关掉校验但加上更规范。鉴权的核心是对 nonce、created、password 做 SHA1 摘要ESP-IDF 里有mbedtls可以直接用不算复杂。最后分享一个调试小技巧如果 NVR 的日志不够详细可以在 ESP32 侧把所有 SOAP 交互存到一个环形缓冲区里通过一个额外的 HTTP 接口导出来看。这样即使 NVR 那边不报错你也能知道它到底调了什么、你回了什么定位问题快很多。这套方法帮我省了无数次抓包的时间。 
长河君 · 2026/10/26 17:43:39 · 阅读 1.2k ESP32纯C实现ONVIF相机：从零接入NVR的完整指南
1. 为什么要在 ESP32 上折腾 ONVIF 相机先说清楚这个项目到底在干什么。onvif-c是一个用纯 C 写的、基于 ESP-IDF 的组件目标很明确把一块 ESP32 变成一台能被标准 NVR网络录像机直接添加、自动发现、正常拉流的网络摄像机。注意这里的关键词是能被 NVR 添加——这跟能出图完全是两码事。很多人用 ESP32 摄像头跑通了 HTTP 的 MJPEG 流浏览器里看得挺爽结果一接到海康、大华、群晖 Surveillance Station 上NVR 死活搜不到设备或者搜到了添加失败或者添加成功但一直显示连接中。问题就出在 ONVIF 这套协议栈上。ONVIF 不是单一协议它是一整套基于 SOAP/XML 的规范集合摄像机要跟 NVR 打交道至少得实现三块设备发现WS-Discovery、设备管理Device Management、媒体服务Media Service。NVR 添加一台相机的典型流程是这样的先通过 WS-Discovery 的组播探测拿到设备地址然后调用GetDeviceInformation、GetCapabilities、GetProfiles、GetStreamUri这一串 SOAP 接口最后拿 RTSP 地址去拉流。任何一环返回的 XML 格式不对、命名空间错了、SOAPAction 头缺失NVR 就直接放弃。那为什么非要用 ESP32 做这件事因为便宜、低功耗、体积小而且 ESP-IDF 自带的esp_http_server和 lwIP 协议栈足够撑起一个轻量 ONVIF 服务端。一块 ESP32-S3 核心板加个 OV2640/OV5640 摄像头模组成本压到几十块做出来的东西能进标准安防生态这在做小批量定制监控、DIY 家庭 NVR、边缘 AI 视觉节点的时候非常香。这个组件适合谁看适合已经会 ESP-IDF 基本工程搭建、懂一点 HTTP 和 XML、想把自己的 ESP32 摄像头接入正规 NVR 的开发者。如果你连idf.py build都没跑过建议先把 ESP-IDF 的环境搭起来再回来。我踩过的第一个大坑就是以为 ONVIF 就是个 HTTP 服务器返回几段固定 XML 就行。实际上 NVR 的兼容性测试极其严格尤其是 WS-Discovery 的组播响应格式差一个字节都发现不了。下面我把整个从建工程到被 NVR 成功添加的完整路径拆开讲。2. 整体架构设计与方案选型思路2.1 为什么选纯 C esp_http_server 而不是别的市面上做 ESP32 ONVIF 有几条路一是用 MicroPython 写开发快但性能和内存控制差SOAP 解析容易崩二是用 Arduino 框架生态好但底层网络控制不够细组播和 socket 选项不好调三是纯 ESP-IDF C门槛高但可控性最强。onvif-c 选的是第三条路原因很实在ONVIF 服务端需要长时间稳定运行需要精确控制 socket 的组播加入、需要手动管理 HTTP 的 SOAPAction 头、需要跟 RTSP 服务共享同一套媒体参数这些在纯 C 下最顺手。esp_http_server是 ESP-IDF 自带的 HTTP 服务组件基于 lwIP支持多 URI handler 注册。用它来承载 ONVIF 的 SOAP 端点通常是/onvif/device_service和/onvif/media_service非常合适。它的工作模式是你注册一个 URI绑定一个 handler 函数请求进来后 handler 拿到httpd_req_t自己解析 body、自己拼 XML 响应。ONVIF 的请求都是 POSTbody 是 SOAP 信封所以 handler 里主要干两件事从 XML 里抠出操作名和参数然后按规范拼响应。这里有个设计决策值得说要不要用 XML 解析库。ESP-IDF 里可以塞进 tinyxml2 或者 expat但会吃掉不少 flash 和 RAM。onvif-c 的做法是轻量字符串匹配——因为 ONVIF 请求的操作名都在固定的标签里比如GetStreamUri用strstr定位标签、再截取内容比完整解析整棵树省得多。这个取舍在资源紧张的 ESP32 上是合理的代价是代码里字符串处理要格外小心遇到命名空间前缀变化有的 NVR 用trt:有的用tt:就得做兼容。2.2 三大服务模块的职责划分整个组件按 ONVIF 规范切成三块每块对应一组 SOAP 操作模块对应规范核心操作承载方式设备发现WS-DiscoveryProbe / ProbeMatch / HelloUDP 组播 239.255.255.250:3702设备管理Device ManagementGetDeviceInformation / GetCapabilities / GetSystemDateAndTimeHTTP SOAP媒体服务Media ServiceGetProfiles / GetStreamUri / GetVideoEncoderConfigurationHTTP SOAPWS-Discovery 走的是 UDP 组播跟 HTTP 完全分开这是最容易漏掉的一块。NVR 开机后会往239.255.255.250:3702发一个 Probe 组播包里面带一个wsd:Probe的 SOAP 信封设备收到后必须单播回一个ProbeMatch里面包含自己的 UUID、设备类型tds:Device或tds:NetworkVideoTransmitter和服务地址。很多人的 ESP32 相机 NVR 搜不到90% 是这一步没做或者做错了。设备管理和媒体服务都挂在 HTTP 上但要注意 ONVIF 规范里这两个服务可以放在同一个端口的不同路径也可以分端口。onvif-c 默认用同一个esp_http_server实例注册两个 URI这样省一个 socket也方便共享设备信息。2.3 与 RTSP 服务的关系ONVIF 本身不传视频它只负责告诉 NVR 去哪里拉流。所以GetStreamUri返回的是一个 RTSP URL比如rtsp://192.168.1.100:554/stream1。这意味着你的 ESP32 上还得跑一个 RTSP 服务端把摄像头数据封装成 RTP 包发出去。ONVIF 组件和 RTSP 组件之间通过一个共享的配置结构体通信——分辨率、帧率、编码格式这些参数ONVIF 的GetVideoEncoderConfiguration要能报出来RTSP 的实际推流也要按这个来两边必须一致否则 NVR 拿到的 profile 跟实际流对不上会花屏或者直接拒绝。我的建议是先把 RTSP 推流跑通确认 VLC 能拉到流再上 ONVIF。因为 ONVIF 调试的时候你没法确定问题出在协议层还是流层分开验证能省大量时间。3. 核心细节解析与实操要点3.1 WS-Discovery 的组播实现细节WS-Discovery 是整个项目里最玄学的部分因为它依赖 UDP 组播而组播在不同网络环境下的行为差异很大。实现上要做这几件事第一创建一个 UDP socket绑定到 3702 端口。注意要设置SO_REUSEADDR否则重启程序时端口可能还被占用。第二加入组播组239.255.255.250用IP_ADD_MEMBERSHIP。第三设置 socket 为可接收组播并且要处理SO_BROADCAST相关选项。第四起一个独立任务循环recvfrom收到 Probe 就解析并回 ProbeMatch。// 加入组播组的核心代码示意 struct ip_mreq mreq; mreq.imr_multiaddr.s_addr inet_addr(239.255.255.250); mreq.imr_interface.s_addr htonl(INADDR_ANY); setsockopt(sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, mreq, sizeof(mreq));回 ProbeMatch 的时候有个关键点响应必须单播回发送方的源地址和源端口不能也组播回去。NVR 发 Probe 时用的源端口通常是随机的你要从recvfrom拿到的struct sockaddr_in里取出来原样回过去。另外 ProbeMatch 里的XAddrs字段要填你设备的 HTTP 服务地址NVR 拿到这个地址后才会去调 SOAP 接口。注意ESP32 默认的 lwIP 配置里组播可能是关的需要在menuconfig里确认LWIP_IGMP打开否则IP_ADD_MEMBERSHIP会失败。这个坑我调了一整天才发现。3.2 SOAP 请求的解析与响应拼装ONVIF 的 SOAP 请求长这样简化soap:Envelope xmlns:soaphttp://www.w3.org/2003/05/soap-envelope soap:Body GetStreamUri xmlnshttp://www.onvif.org/ver10/media/wsdl ProfileTokenprofile_1/ProfileToken /GetStreamUri /soap:Body /soap:Envelope解析的时候先找soap:Body之后的内容再找第一个子标签的名字那就是操作名。参数从子标签里抠。响应要按对应命名空间拼比如媒体服务的响应命名空间是http://www.onvif.org/ver10/media/wsdl设备管理是http://www.onvif.org/ver10/device/wsdl。命名空间写错是 NVR 拒绝的第二大原因。响应里还要注意 SOAP 版本。ONVIF 用的是 SOAP 1.2Content-Type 必须是application/soapxml; charsetutf-8而且action参数要带上完整的操作名比如actionhttp://www.onvif.org/ver10/media/wsdl/GetStreamUri。有些 NVR 会检查这个头缺了就直接 400。3.3 设备信息与 Capabilities 的构造GetDeviceInformation要返回制造商、型号、固件版本、序列号、硬件 ID。这些字段虽然是字符串但 NVR 可能会拿来做去重和展示建议填真实有意义的值别全填 test。序列号最好用 ESP32 的 MAC 地址生成保证唯一。GetCapabilities更关键它告诉 NVR 这台设备支持哪些服务、每个服务的地址在哪。响应里要列出 Device、Media、Events如果支持等分类每类给出XAddr。这个地址必须跟实际 HTTP 服务地址一致否则 NVR 后续调用会打到不存在的端口。tds:Capabilities tds:Media tt:XAddrhttp://192.168.1.100/onvif/media_service/tt:XAddr /tds:Media /tds:Capabilities3.4 Profile 与 StreamUri 的对应关系ONVIF 里 Profile 是一路视频配置的抽象包含视频编码、分辨率、帧率、码率以及对应的流地址。GetProfiles返回所有 profile 的列表每个 profile 有个 token比如profile_1。GetStreamUri根据传入的 token 返回对应的 RTSP 地址。对 ESP32 来说通常只支持一路流所以返回一个 profile 就够了。但要注意 profile 里的VideoEncoderConfiguration参数要跟 RTSP 实际推流参数严格一致。我见过有人 profile 里写 1080p实际推的是 VGANVR 拉流后一直花屏查了半天才发现是这里对不上。4. 完整实操流程从建工程到 NVR 添加成功4.1 工程搭建与组件集成先建一个标准 ESP-IDF 工程idf.py create-project esp32_onvif_cam cd esp32_onvif_cam然后把 onvif-c 组件放进components/目录。ESP-IDF 的组件机制会自动扫描components/下的每个子目录只要里面有CMakeLists.txt就会被编译进来。onvif-c 的CMakeLists.txt里要声明依赖idf_component_register(SRCS onvif_device.c onvif_media.c onvif_discovery.c INCLUDE_DIRS include REQUIRES esp_http_server lwip nvs_flash)主工程的CMakeLists.txt里REQUIRES加上onvif-c。摄像头驱动用esp32-camera组件RTSP 服务可以用现成的esp_rtsp或者自己写。这里假设你已经有一路能出图的 RTSP 流。4.2 网络与组播初始化WiFi 连上之后先初始化 ONVIF 的组播监听。这一步要在 HTTP 服务启动之前做因为 NVR 可能先发 Probe 再调 SOAP。void onvif_discovery_start(void) { int sock socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP); struct sockaddr_in addr { .sin_family AF_INET, .sin_port htons(3702), .sin_addr.s_addr htonl(INADDR_ANY) }; bind(sock, (struct sockaddr*)addr, sizeof(addr)); // 加入组播组 struct ip_mreq mreq; mreq.imr_multiaddr.s_addr inet_addr(239.255.255.250); mreq.imr_interface.s_addr htonl(INADDR_ANY); setsockopt(sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, mreq, sizeof(mreq)); xTaskCreate(discovery_task, onvif_disc, 4096, (void*)sock, 5, NULL); }discovery_task里循环recvfrom收到 Probe 就调build_probe_match拼响应然后sendto回源地址。4.3 HTTP 服务与 SOAP 端点注册启动esp_http_server注册两个 URIhttpd_config_t config HTTPD_DEFAULT_CONFIG(); httpd_handle_t server NULL; httpd_start(server, config); httpd_uri_t device_uri { .uri /onvif/device_service, .method HTTP_POST, .handler device_service_handler }; httpd_register_uri_handler(server, device_uri); httpd_uri_t media_uri { .uri /onvif/media_service, .method HTTP_POST, .handler media_service_handler }; httpd_register_uri_handler(server, media_uri);handler 里先读 body判断操作名分发到对应的构造函数。响应通过httpd_resp_send发出去记得设置正确的 Content-Type。4.4 参数计算分辨率与码率的匹配ESP32 的算力和内存有限摄像头分辨率不能盲目拉满。以 ESP32-S3 OV2640 为例实测下来分辨率帧率JPEG 质量内存占用稳定性VGA 640x48015fps12低很稳SVGA 800x60012fps12中稳HD 1280x7208fps10高勉强FHD 1920x10805fps10很高易崩ONVIF profile 里报的参数要跟这个表对齐。如果你报 1080p 但实际只能跑 5fpsNVR 那边可能因为帧率太低判定流异常。建议初期用 VGA 或 SVGA跑稳了再往上调。码率方面MJPEG 的码率约等于分辨率像素数 × 帧率 × 压缩系数。VGA 15fps 大概 2-4 Mbps这个量级在局域网里没问题。RTSP 推流时 RTP 包大小建议 1400 字节左右避免 IP 分片。4.5 NVR 添加实测记录我用群晖 Surveillance Station 和海康 NVR 各测了一遍。群晖的兼容性相对宽松海康更严格。添加流程NVR 自动搜索几秒内应该能看到设备出现在列表里显示为 ONVIF Device 或你填的制造商名。手动添加时填 IP、ONVIF 端口默认 80、用户名密码如果没做鉴权就留空或随便填。添加后 NVR 会调一串 SOAP 接口观察串口日志能看到GetDeviceInformation、GetCapabilities、GetProfiles、GetStreamUri依次进来。全部返回正确后NVR 开始拉 RTSP 流画面上线。第一次测的时候海康一直添加失败串口日志显示GetCapabilities返回后就没下文了。后来抓包发现是 Capabilities 里的XAddr我写成了http://192.168.1.100:80/onvif/media_service多了个:80海康不认。去掉端口号后立刻通过。这种细节就是纯靠踩坑积累的。5. 常见问题与排查技巧实录5.1 NVR 搜不到设备这是最高频的问题。排查顺序确认 ESP32 和 NVR 在同一网段且中间没有隔离组播的交换机或路由器。很多企业级 AP 默认关闭 IGMP snooping 或者隔离客户端组播包根本到不了。用 Wireshark 抓包看 NVR 有没有发 Probe 到 239.255.255.250:3702。如果没发是 NVR 侧问题如果发了但 ESP32 没回是组播加入失败。检查menuconfig里LWIP_IGMP是否开启。检查 ProbeMatch 的XAddrs地址是否是 NVR 能访问到的地址别填成 127.0.0.1 或 AP 的地址。5.2 添加成功但一直连接中通常是 RTSP 流拉不起来。先用 VLC 手动填rtsp://设备IP:554/stream1测试能出图说明流没问题问题在 ONVIF 返回的 URL 上。检查GetStreamUri返回的地址里的 IP 是不是设备真实 IP端口是不是 RTSP 实际监听端口。5.3 画面花屏或卡顿多半是 profile 参数和实际流不一致。检查GetVideoEncoderConfiguration返回的分辨率、帧率是否跟 RTSP 推流参数匹配。另外 RTP 包大小和 MTU 也要注意ESP32 的 lwIP MTU 默认 1500RTP 负载超过这个会分片分片丢失就花屏。5.4 常见问题速查表现象可能原因排查方法NVR 搜不到组播未加入 / IGMP 未开Wireshark 抓 3702 端口添加失败Capabilities XAddr 错误检查地址格式去掉多余端口连接中无画面RTSP URL 错误VLC 手动测试花屏卡顿profile 与实际流不符对比参数一段时间后掉线内存泄漏 / 任务栈溢出看 heap 和任务水位SOAP 返回 400Content-Type 或 action 头错误抓包看请求头5.5 独家避坑经验第一个经验串口日志一定要打全。ONVIF 调试全靠日志每个进来的 SOAP 操作名、每个发出的响应都打出来。我习惯在 handler 入口打一行ONVIF REQ: op_name出问题一眼就能看出卡在哪一步。第二个经验先用手工构造的 SOAP 请求测。别一上来就接 NVR用 curl 或者 Postman 往/onvif/device_service发一个GetDeviceInformation看返回对不对。这样能把协议层和 NVR 兼容性分开调。curl -X POST http://192.168.1.100/onvif/device_service \ -H Content-Type: application/soapxml; charsetutf-8 \ -d soap:Envelope ...GetDeviceInformation//soap:Envelope第三个经验UUID 要固定。WS-Discovery 的 ProbeMatch 里有个EndpointReference的 UUID如果每次重启都变NVR 会认为是新设备导致重复添加或者配置丢失。用 MAC 地址生成一个稳定的 UUID。第四个经验给 HTTP 服务留足任务栈。esp_http_server默认栈可能不够SOAP 响应拼装时字符串操作多栈溢出会直接重启。我把 httpd 的任务栈调到 8192 才稳。6. 性能优化与稳定性加固6.1 内存管理ESP32 的 RAM 是稀缺资源ONVIF 服务端加上 RTSP 推流内存很容易吃紧。几个优化点SOAP 响应用静态缓冲区拼装别频繁 malloc/freeXML 字符串处理用栈上的固定数组别用动态分配摄像头帧缓冲用双缓冲避免推流和采集抢内存。实测 ESP32-S3 带 8MB PSRAM 的话跑 720p 推流加 ONVIF 服务剩余 heap 还能有 100KB 以上比较安全。6.2 长时间运行稳定性ONVIF 服务要 7x24 跑稳定性比功能更重要。我做了几件事给 discovery 任务和 httpd 任务都加了看门狗喂狗socket 操作加了超时避免阻塞定期打印 heap 水位观察有没有缓慢泄漏。跑过连续 72 小时测试没有重启和掉线。6.3 多 NVR 并发如果网络里有多个 NVR 或者客户端同时探测discovery 任务要能并发处理。因为 UDP 是无连接的每个 Probe 独立响应即可问题不大。但 HTTP 这边要注意esp_http_server的并发连接数配置默认可能只支持几个多客户端同时调 SOAP 会排队。在httpd_config_t里把max_open_sockets调大一点。7. 后续可扩展的方向这套东西跑通之后能玩的花样不少。比如加个Events 服务把 ESP32 的 GPIO 触发、移动侦测结果通过 ONVIF 事件推给 NVR这样 NVR 就能做联动录像。再比如接入边缘 AI用 ESP32-S3 的向量指令跑个轻量的人形检测检测到目标时通过 ONVIF 事件通知 NVR 打标签。还有PTZ 控制如果你的云台是舵机驱动的实现 ONVIF 的 PTZ 服务后NVR 界面上就能直接控制转动。我自己下一步打算把 ONVIF 的鉴权WS-UsernameToken加上现在很多 NVR 要求必须带用户名密码虽然可以关掉校验但加上更规范。鉴权的核心是对 nonce、created、password 做 SHA1 摘要ESP-IDF 里有mbedtls可以直接用不算复杂。最后分享一个调试小技巧如果 NVR 的日志不够详细可以在 ESP32 侧把所有 SOAP 交互存到一个环形缓冲区里通过一个额外的 HTTP 接口导出来看。这样即使 NVR 那边不报错你也能知道它到底调了什么、你回了什么定位问题快很多。这套方法帮我省了无数次抓包的时间。