onvif-device-rs:把 Rust 程序变成一台 ONVIF 相机
onvif-device-rscrates.io · MIT · Rust 1.80ONVIF设备端server库SOAP Device/Media/Imaging/PTZ 服务、WS-Discovery 应答器、WS-Security 认证。给你的流媒体程序、采集管线、边缘设备接上一个标准的 ONVIF 门面任何 NVR/VMS 都能发现它、从它取流。crateonvif-device-rscrates.io· 仓库mickeyzzc/onvif-rs当前版本0.2.20.3.0 加固版在途许可证MITHTTP 栈tokio 上手写 HTTP/1.1——不依赖 hyper/axum关键依赖tokio、quick-xml、serde、async-trait、sha1、socket2测试157含钉死响应报文的金串测试仓库https://github.com/mickeyzzc/onvif-rs名字的由来一个 crates.io 的故事仓库名叫 onvif-rscrate 却发布为onvif-device-rs——因为 crates.io 上的onvif-rs这个名字被一个 2018 年的废弃占位 crate 占着其 README 自述DO NOT USE而 crates.io 不支持名字回收。为避免与另一个知名的 WSDL 生成式 ONVIF客户端库lumeohq/onvif-rs混淆README 里有正式的消歧义声明仓库保留原名crate 以onvif-device-rs之名发布。打 tag 自动发布到 crates.io依赖它只需一行版本号。ONVIF 设备端要过哪些坎做一个能被 NVR 认出来的 ONVIF 设备难的不是 SOAP,而是生态里约定俗成的兼容性细节。这个库的设计围绕五个坎展开发现WS-Discovery 的 UDP 组播应答要正确且大量客户端还会走 HTTP POST 的 Probe——两条路都得应答字节稳定大量 NVR 不做完整 SOAP 解析而是对报文做原始 local-name 匹配。GetStreamUriResponse → MediaUri → Uri这条元素链的大小写与嵌套必须与官方 WSDL 逐字一致全部是小写ri错一个字母就是发现了但没有视频认证WS-UsernameToken 的 PasswordText 与 PasswordDigest 两种模式都要验比较必须抗时序侧信道命名空间客户端发来的 SOAP 前缀五花八门s:/soap:/soapenv:业务前缀更是随缘解析必须与前缀无关而响应要用规范的显式前缀序列化多网卡XAddrs 回显给对方的必须是从它那边够得着的地址——按请求来源回显而不是写死一个。一次标准的被消费全过程你的程序 onvif-device-rsONVIF 客户端你的程序 onvif-device-rsONVIF 客户端HTTP POST Probe 同样应答WS-Discovery Probe UDP 组播 37021ProbeMatches Types/Scopes/XAddrs2GetSystemDateAndTime 匿名3200 OK4GetDeviceInformation 未带凭证54016GetDeviceInformation WS-UsernameToken7200 OK 厂商/型号/序列号8GetStreamUri9rtsp 取流地址 按请求来源回显10RTSP DESCRIBE / SETUP / PLAY11上手最小设备端[dependencies] onvif-device-rs 0.2.2 # git 方式: onvif-device-rs { git https://github.com/mickeyzzc/onvif-rs.git, tag v0.2.2 }注册动作、启动服务节选自库自带的自检示例examples/device_demo.rsusestd::sync::Arc;useonvif_device_rs::device::{DeviceHandler,DeviceServiceHandlers};useonvif_device_rs::discovery::DiscoveryServer;useonvif_device_rs::media::{GetProfilesHandler,GetSnapshotUriHandler,GetStreamUriHandler,OnvifMediaConfig,VideoEncoding,};useonvif_device_rs::{DeviceConfig,OnvifConfig,OnvifServer};#[tokio::main]asyncfnmain()-Result(),Boxdynstd::error::Error{letport8080;letdevice_ip192.168.1.50.to_string();// SOAP 服务:端口 WS-Security 凭证。fail-closed:password 留空会让// start() 直接报错;要刻意全开放需显式 allow_no_auth true。letmutsoapOnvifServer::new(OnvifConfig{port,username:admin.to_string(),password:secret.to_string(),..Default::default()});// Device 服务:五个动作共用一个 handlerletdeviceArc::new(DeviceServiceHandlers::new(DeviceConfig{name:My Camera.into(),manufacturer:Example.into(),model:Model X.into(),..Default::default()},port,device_ip.clone(),));foractionin[GetSystemDateAndTime,GetDeviceInformation,GetCapabilities,GetServices,GetScopes]{soap.register_handler(action,Box::new(DeviceHandler(Arc::clone(device))));}// 免认证动作:对齐真机行为——时间/能力/服务清单在出示凭证前就要可读,// 这是很多客户端探测设备的标准姿势foractionin[GetSystemDateAndTime,GetCapabilities,GetServices]{soap.register_anonymous_action(action);}// Media 服务:描述你的真实流与快照端点letmediaArc::new(OnvifMediaConfig{camera_width:1280,camera_height:720,camera_fps:25,camera_bitrate:2_500_000,rtsp_port:8554,device_ip:device_ip.clone(),stream_path:/stream.to_string(),snapshot_port:8080,// 设为 0 则 GetSnapshotUri 如实回 fault,不虚报能力snapshot_path:/snapshot.jpg.to_string(),profile_token:main.to_string(),video_source_token:videoSrc0.to_string(),encoder_token:enc0.to_string(),encoding:VideoEncoding::H264,video_source_name:Video Source.to_string(),});soap.register_handler(GetProfiles,Box::new(GetProfilesHandler::new(Arc::clone(media))));soap.register_handler(GetStreamUri,Box::new(GetStreamUriHandler::new(Arc::clone(media))));soap.register_handler(GetSnapshotUri,Box::new(GetSnapshotUriHandler::new(Arc::clone(media))));// WS-Discovery 应答器(UDP 组播)与 SOAP 服务并行运行DiscoveryServer::new(device_ip,port).start().await?;soap.start().await?;Ok(())}架构上这是一个按动作注册的 handler 模型SOAP body 里第一个子元素的 local name 就是路由键OnvifActionHandler只有一个方法#[async_trait]pubtraitOnvifActionHandler:SendSync{asyncfnhandle(self,body:str,request_info:RequestInfo)-ResultString,OnvifError;}RequestInfo携带client_ip、server_ip与认证结果——需要按请求来源定制 XAddrs 或做访问控制时信息是够的。HTTP/1.1 栈是手写在tokio::net::TcpListener上的没有 hyper/axum依赖树短、编译快、行为完全可控这对要跑在嵌入式/边缘设备上的程序不是小事。成像参数ImagingParams 接缝Imaging 是设备端库里最常见的烂尾项这里被设计成一个极小的宿主接缝——把 ONVIF 的参数读写翻译到你的相机参数管理器上useonvif_device_rs::imaging::{ImagingParamError,ImagingParams,register_imaging_actions};pubtraitImagingParams:SendSync{/// 按 ONVIF 名称(如 Brightness)读当前值fnget_param(self,name:str)-Resultf64,ImagingParamError;/// 写入;value 已归一化到 [0.0, 1.0]fnset_param(self,name:str,value:f64)-Result(),ImagingParamError;}错误类型区分三种情况客户端会收到语义正确的 SOAP faultpubenumImagingParamError{/// 参数名不被识别InvalidName(String),/// 请求值超出有效范围OutOfRange{value:f64,min:f64,max:f64},/// 底层存储/设备 I/O 故障Io(String),}一行注册GetImagingSettings/SetImagingSettings/GetOptions三个动作全部就位参数值统一归一化到[0, 1]区间曝光/白平衡模式默认按 AUTO 上报trait 上带默认实现的exposure_mode/white_balance_mode可覆盖register_imaging_actions(mutsoap,Arc::new(MyParams));虚拟云台PtzState没有电机的设备想被云台控制库内置了一个纯状态机PtzState位置/速度/预置位、tick 驱动的运动模拟连续移动按速度积分、绝对移动指数缓动、IDLE/MOVING状态——PtzHandler把 ContinuousMove/AbsoluteMove/RelativeMove/Stop/预置位增删转跳等 11 个 PTZ 动作全部接进这个状态机。examples/ptz_demo演示了全部动词与模拟运动。字节稳定是怎么保证的响应报文的元素名、命名空间前缀、属性形态被明确当作承重契约仓库的 CONTRIBUTING 写明线格式测试是承重墙金串字符串按契约对待157 个测试里有一批直接断言报文内容。以 ProbeMatches 为例节选自src/discovery.rs的测试letxmlString::from_utf8(resp).expect(valid UTF-8);assert!(xml.starts_with(?xml version\1.0\ encoding\UTF-8\?));assert!(xml.contains(a:RelatesTouuid:test-id/a:RelatesTo));assert!(xml.contains(d:ProbeMatch));assert!(xml.contains(onvif://www.onvif.org/Profile/Streaming));assert!(xml.contains(192.168.1.100:8080/onvif/device_service));assert!(xml.contains(tdn:NetworkVideoTransmitter));assert!(xml.contains(d:MetadataVersion1/d:MetadataVersion));GetProfiles 的响应同样被逐字段钉死profile token、分辨率、帧率上限、码率上限。改任何序列化路径这些测试会先红——这正是设备端库该有的偏执。发现本身是双路的UDP 组播socket2 SO_REUSEADDR 组播加入缺省地址 239.255.255.250:3702之外HTTP POST 的 Probe 也由handle_http_probe应答两条路径的 XAddrs 都按请求来源回显。本机多地址环境还提供detect_local_ip兜底。实战这个库是从我们一款 Rust 摄像头固件的 ONVIF 模块整体抽取的宿主侧一次性删掉了五千五百余行含 PTZ 状态机业务代码现在只是一行pub use onvif_device_rs as onvif;的历史路径兼容加少量配置转发——抽取后对 NVR 客户端跑了全链路验证发现 → GetStreamUri → RTSP DESCRIBE → 录像落盘全绿。它每天作为生产摄像头的 ONVIF 门面运行被 NVR 以最苛刻的方式消费——原始 SOAP local-name 匹配。这也是字节稳定是契约这条设计原则的来源不是规范要求是消费端现实。工程质量157 个测试覆盖发现、认证、各服务应答、PTZ 状态机与配置0.3.0 加固版在途分支待发布鉴权 fail-closed、全量 XML 转义、HTTP 请求上限/超时、优雅停机与监听器注入、log门面以及库卫生守卫——README 示例经#[cfg(doctest)]强制可编译CI 三道闸cargo fmt --check、cargo clippy --all-targets -- -D warnings、cargo test另有 MSRV 1.80 实际构建验证与 Windows 交叉检查作业打 tag 自动发布 crates.io三个示例device_demoSOAP 发现自检匿名动作应 200、未带凭证应 401全自动断言、ptz_demo、imaging_demo含越界值触发 OutOfRange fault 的演示。cargorun--exampledevice_demo ----port8080边界与路线README 如实标注接缝ImagingParams、DeviceConfig、媒体配置已趋稳但未冻结服务面为 Device/Media/Imaging/PTZ WS-Discovery没有事件PullPoint服务——按真实消费端的需求取舍DeviceConfig的默认值忠实保留了源产品线的出身Raspberry Pi/OV5647上生产前记得换成你自己的。

相关新闻

gb28181-rs:Rust 的 GB28181 设备端库——两条接缝接入你的采集管线

gb28181-rs:Rust 的 GB28181 设备端库——两条接缝接入你的采集管线

gb28181-rs MIT Rust 1.80 手写 SIP,不依赖任何 SIP 框架 让 Rust 程序以设备身份注册到 GB/T 28181 平台:注册与摘要认证、目录应答、INVITE 点播、RTP/PS 推流、录像回放与下载,全部内置。宿主只需要提供两样东西:视频帧&…

2026/11/19 22:42:54 阅读更多 →
一个 Skill 就能做完整 PPT?PPT Master 来了!

一个 Skill 就能做完整 PPT?PPT Master 来了!

一个 Skill 就能做完整 PPT?PPT Master 来了! 文章目录 一、PPT Master Skill 核心能力二、环境安装三、实际测试任务与 Prompt四、完整操作过程五、最终产物与效果六、实际使用后的判断 最近试了一下开源的 PPT Master Skill。和常见的“一句话直接生…

2026/11/16 3:38:05 阅读更多 →
机器人开发工程化实战:从ROS2核心技能到商业化落地避坑指南

机器人开发工程化实战:从ROS2核心技能到商业化落地避坑指南

如果你是一名机器人开发者,或者正在考虑进入这个领域,最近可能被各种展会、新品和融资新闻刷屏。但热闹背后,我们真正需要关心的是什么?是那些炫酷的Demo,还是能真正落地、解决实际问题的技术? 最近&#…

2026/11/16 3:38:04 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/20 23:27:28 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/20 23:27:28 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/20 23:27:28 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/20 21:55:32 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/20 23:27:28 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/20 22:59:12 阅读更多 →

日新闻

周新闻

月新闻