简介面向DLNA/UPnP开发与调试的Python工具基于Coherence框架构建UPnP设备和服务分析器适合有一定Python基础、希望深入理解家庭网络协议的开发者。它能枚举网络中的UPnP设备、服务、操作与状态变量调用任意服务操作导出设备及服务描述XML还可作为简单控制点浏览DLNA媒体库并控制播放器对协议学习、设备排错和智能家居调试很有价值。压缩包仅152KB共58个文件以15个py源码和31个png图片为主py负责核心实现png用于界面展示另含说明文档、许可证及桌面启动配置等辅助文件。已有372人学习下载。通过阅读源码可深入理解UPnP协议解析、Coherence事件机制与DLNA媒体控制流程是进阶Python网络编程的实用参考。1. 项目概述UPnP设备分析器到底解决什么问题1.1 一个让我折腾了一周的DLNA电视问题上个月在调试一台支持DLNA的智能电视做手机投屏和媒体共享。电视端能看到媒体服务器目录缩略图也能正常加载但只要一点播放就报错错误码也不直观日志里只有一句“renderer error”。我先后怀疑过媒体服务器转码配置、网络带宽、视频编码格式折腾了整整一周最后用UPnP-Inspector把电视的UPnP服务结构完整拉出来才发现问题出在AVTransport服务的Action列表上——这台电视实现的Action数量比DLNA规范要求的少了好几个我调用的那条“SetAVTransportURI”参数格式也和规范有出入。那一刻我才真正意识到UPnP和DLNA设备虽然遍地都是但真正能把设备服务细节扒开看明白的工具太少了。UPnP-Inspector正是干这件事的。它是一个基于Python的Coherence DLNA/UPnP框架开发的UPnP设备和服务分析器核心能力是扫描局域网内的upnp设备解析每台设备暴露出来的设备描述、服务列表、Action动作和状态变量把通常只能“测到能不能用”的黑盒变成“看得见内部结构”的白盒。对调试DLNA设备的嵌入式工程师、做投屏协议的客户端开发者、智能家居集成商、以及正在学习UPnP协议栈的人来说这几乎是一个必备工具。1.2 从项目标题拆解UPnP-Inspector的本质项目标题信息量很大一块一块拆开看UPnPUniversal Plug and Play通用即插即用协议是DLNA设备之间互相发现、描述、控制的底层协议基础。Inspector检查器、分析器说明这个工具的核心职责不是“播放”也不是“控制”而是“扒开看”。CoherencePython语言实现的DLNA/UPnP框架提供完整的SSDP发现、SOAP控制、GENA事件等协议支持。串起来就是用Coherence框架把UPnP协议的底层细节全部处理掉让开发者把精力放在设备服务的分析与诊断上。换一句更直白的话——UPnP-Inspector解决的核心问题不是“这个设备能不能被发现”而是“设备被发现之后它内部到底提供了哪些服务每个服务能做什么动作这些动作符不符合DLNA规范”。1.3 哪些人需要它我按实际使用场景整理了四类典型用户DLNA媒体服务器开发者自己开发了DMSDigital Media Server需要验证它暴露的服务、Action是否符合DLNA规范能不能被各种品牌的电视、音响正常发现和调用。智能电视与投屏协议调试工程师这类工程师日常面对的就是“电视能看到但不能播”“音箱能连接但没声音”这类兼容性问题需要一个工具做协议层面的比对。智能家居系统集成商现在不少智能灯泡、摄像头、窗帘电机走UPnP协议做局域网发现集成调试时经常要确认设备类型和服务能力。协议学习者把UPnP协议文档读十遍不如用分析器把一台真实设备“扒开”看一遍文本和XML字段对上号理解会非常快。搞清楚了“它是什么、给谁用”接下来就是剥洋葱看看它背后的协议原理和设计思路。2. 核心原理拆解UPnP协议栈与Coherence框架2.1 UPnP设备的三层协议栈你只需要理解这三层UPnP协议栈是理解整个工具的基础说白了就是三层结构。第一层是发现Discovery。设备接入网络后通过SSDPSimple Service Discovery Protocol协议向组播地址239.255.255.250的1900端口发送NOTIFY消息宣告“我在这里我是什么设备”。控制点Control Point也可以通过M-SEARCH消息主动问“局域网里有哪些UPnP设备”。这个过程全部走UDP无连接、轻量、不保证可靠所以设备掉线时是需要靠超时机制来判断的。第二层是描述Description。设备被找到之后控制点需要拉取设备描述XML。这个XML文件里有设备的UDN唯一设备名、设备类型如MediaServer、MediaRenderer、friendlyName友好名称、制造商、型号以及最重要的serviceList服务列表。每个服务还会有一个独立的SCPDService Control Protocol Description文档描述这个服务支持哪些Action和状态变量。第三层是控制Control。调用服务里的Action时控制点通过SOAP协议把请求发到设备指定的控制URL上参数格式完全由SCPD定义。整个UPnP的控制基本就是“读XML定义、按XML格式发SOAP、等XML响应”这样一个循环。很多人被UPnP搞晕就是因为这三层混在一起看。UPnP-Inspector做的事就是把三层结构里的第二层做深做透顺带打通第三层。2.2 为什么选Coherence框架在Python生态里做UPnP相关开发选项其实不多。Coherence是我个人认为最成熟的DLNA/UPnP框架它的几个特点对这个项目非常关键。第一它基于Twisted异步框架天生适合做设备扫描这种I/O密集任务。局域网里扫描几十台设备每台都要拉取描述XML和SCPD文档如果同步逐个请求体验非常差。Coherence把SSDP的监听、HTTP请求的发送都做成异步回调一套代码就能并发处理大量设备请求。第二它内置了一个完整的控制点Control Point实现。UPnP协议里控制点是“主动发现设备并调用服务”的角色整个UPnP-Inspector的分析逻辑都必须建立在控制点之上。Coherence的control_point模块提供了设备发现、服务订阅、Action调用等全套能力不用自己从零写SSDP和SOAP协议处理。第三它对DLNA规范的支持比较完整。Coherence不仅仅实现了UPnP基础协议还针对DLNA的媒体服务做了大量适配比如ContentDirectory服务CDS内容目录服务、AVTransport服务、ConnectionManager服务相关的建表和处理逻辑。这意味着基于它写分析工具时很多DLNA特有字段已经是被框架解析好的对象属性而不是原始XML里一串难懂的标签。2.3 UPnP-Inspector的整体设计思路基于Coherence框架UPnP-Inspector的设计可以归纳为四个步骤启动Coherence并创建控制点监听SSDP协议收集局域网内所有upnp设备的发现事件。对每台被发现的设备拉取设备描述XML解析出基本信息和服务列表。对每个服务拉取对应的SCPD文档解析出所有Action和状态变量。将解析结果统一展示出来并支持手动调用某个Action来测试设备的实际响应。这个设计与直接用wireshark抓包分析的区别在于它做的是协议层面的“结构化解读”而不是原始字节层面的“数据包分析”。调试DLNA设备时抓包只能告诉你“它发了一个XML”UPnP-Inspector能直接告诉你“它发的这个XML里服务内容目录查询的返回参数少了‘object.item.videoItem’这个类”。3. 实操用UPnP-Inspector分析局域网内的upnp设备3.1 环境准备与安装UPnP-Inspector基于Coherence框架而Coherence早期版本主要支持Python 2.x后来社区做了Python 3的移植分支。如果你在2024年之后动手建议直接找支持Python 3的版本否则在Python 2.7环境里编译依赖库会非常痛苦。安装方式推荐从源码安装。先拉取Coherence相关代码仓库再安装依赖git clone https://github.com/Coherence-upnp/Coherence.git cd Coherence pip install -r requirements.txt python setup.py install依赖里有Twisted、Pygments等库如果安装过程中Twisted编译报错通常需要先安装系统级的Python开发头文件和C编译器。在Debian/Ubuntu上可以用sudo apt-get install python3-dev build-essential libssl-devUPnP-Inspector如果作为独立脚本运行一般位于Coherence项目下的examples或inspector目录里。从我的经验看直接把它当成一个模块来调用比当作独立命令行工具更方便因为这样可以在自己的调试脚本里嵌入它的分析逻辑。3.2 快速开始扫描局域网内所有upnp设备启动一次完整的设备扫描代码量其实非常少这正是Coherence框架的功劳。以下是一段最简扫描程序的核心逻辑from twisted.internet import reactor from coherence.base import Coherence from coherence.upnp.core.utils import get_url def device_found(device, *args, **kwargs): print(发现设备:, device.friendly_name) print( 设备类型:, device.get_device_type()) print( UDN:, device.udn) print( 制造商:, device.get_manufacturer()) print( 服务列表:, [s.get_service_type() for s in device.get_services()]) def start_scan(): c Coherence({controlpoint: yes}) cp c.control_point cp.connect(device_found, Coherence.UPnP.Device.Detected) reactor.callLater(10, reactor.stop) reactor.callWhenRunning(start_scan) reactor.run()这里有几个绕不开的关键点。Coherence({controlpoint: yes})这行是启动框架并声明运行控制点模式如果漏掉这个配置框架不会主动发起SSDP搜索。cp.connect是Twisted风格的事件订阅第二个参数指定监听“新设备被发现”这一事件类型。扫描持续的10秒时间可以自己调整但注意SSDP协议里有T本文还有配套的精品资源点击获取 UPnP-Inspector：用Coherence框架解剖DLNA设备服务
简介面向DLNA/UPnP开发与调试的Python工具基于Coherence框架构建UPnP设备和服务分析器适合有一定Python基础、希望深入理解家庭网络协议的开发者。它能枚举网络中的UPnP设备、服务、操作与状态变量调用任意服务操作导出设备及服务描述XML还可作为简单控制点浏览DLNA媒体库并控制播放器对协议学习、设备排错和智能家居调试很有价值。压缩包仅152KB共58个文件以15个py源码和31个png图片为主py负责核心实现png用于界面展示另含说明文档、许可证及桌面启动配置等辅助文件。已有372人学习下载。通过阅读源码可深入理解UPnP协议解析、Coherence事件机制与DLNA媒体控制流程是进阶Python网络编程的实用参考。1. 项目概述UPnP设备分析器到底解决什么问题1.1 一个让我折腾了一周的DLNA电视问题上个月在调试一台支持DLNA的智能电视做手机投屏和媒体共享。电视端能看到媒体服务器目录缩略图也能正常加载但只要一点播放就报错错误码也不直观日志里只有一句“renderer error”。我先后怀疑过媒体服务器转码配置、网络带宽、视频编码格式折腾了整整一周最后用UPnP-Inspector把电视的UPnP服务结构完整拉出来才发现问题出在AVTransport服务的Action列表上——这台电视实现的Action数量比DLNA规范要求的少了好几个我调用的那条“SetAVTransportURI”参数格式也和规范有出入。那一刻我才真正意识到UPnP和DLNA设备虽然遍地都是但真正能把设备服务细节扒开看明白的工具太少了。UPnP-Inspector正是干这件事的。它是一个基于Python的Coherence DLNA/UPnP框架开发的UPnP设备和服务分析器核心能力是扫描局域网内的upnp设备解析每台设备暴露出来的设备描述、服务列表、Action动作和状态变量把通常只能“测到能不能用”的黑盒变成“看得见内部结构”的白盒。对调试DLNA设备的嵌入式工程师、做投屏协议的客户端开发者、智能家居集成商、以及正在学习UPnP协议栈的人来说这几乎是一个必备工具。1.2 从项目标题拆解UPnP-Inspector的本质项目标题信息量很大一块一块拆开看UPnPUniversal Plug and Play通用即插即用协议是DLNA设备之间互相发现、描述、控制的底层协议基础。Inspector检查器、分析器说明这个工具的核心职责不是“播放”也不是“控制”而是“扒开看”。CoherencePython语言实现的DLNA/UPnP框架提供完整的SSDP发现、SOAP控制、GENA事件等协议支持。串起来就是用Coherence框架把UPnP协议的底层细节全部处理掉让开发者把精力放在设备服务的分析与诊断上。换一句更直白的话——UPnP-Inspector解决的核心问题不是“这个设备能不能被发现”而是“设备被发现之后它内部到底提供了哪些服务每个服务能做什么动作这些动作符不符合DLNA规范”。1.3 哪些人需要它我按实际使用场景整理了四类典型用户DLNA媒体服务器开发者自己开发了DMSDigital Media Server需要验证它暴露的服务、Action是否符合DLNA规范能不能被各种品牌的电视、音响正常发现和调用。智能电视与投屏协议调试工程师这类工程师日常面对的就是“电视能看到但不能播”“音箱能连接但没声音”这类兼容性问题需要一个工具做协议层面的比对。智能家居系统集成商现在不少智能灯泡、摄像头、窗帘电机走UPnP协议做局域网发现集成调试时经常要确认设备类型和服务能力。协议学习者把UPnP协议文档读十遍不如用分析器把一台真实设备“扒开”看一遍文本和XML字段对上号理解会非常快。搞清楚了“它是什么、给谁用”接下来就是剥洋葱看看它背后的协议原理和设计思路。2. 核心原理拆解UPnP协议栈与Coherence框架2.1 UPnP设备的三层协议栈你只需要理解这三层UPnP协议栈是理解整个工具的基础说白了就是三层结构。第一层是发现Discovery。设备接入网络后通过SSDPSimple Service Discovery Protocol协议向组播地址239.255.255.250的1900端口发送NOTIFY消息宣告“我在这里我是什么设备”。控制点Control Point也可以通过M-SEARCH消息主动问“局域网里有哪些UPnP设备”。这个过程全部走UDP无连接、轻量、不保证可靠所以设备掉线时是需要靠超时机制来判断的。第二层是描述Description。设备被找到之后控制点需要拉取设备描述XML。这个XML文件里有设备的UDN唯一设备名、设备类型如MediaServer、MediaRenderer、friendlyName友好名称、制造商、型号以及最重要的serviceList服务列表。每个服务还会有一个独立的SCPDService Control Protocol Description文档描述这个服务支持哪些Action和状态变量。第三层是控制Control。调用服务里的Action时控制点通过SOAP协议把请求发到设备指定的控制URL上参数格式完全由SCPD定义。整个UPnP的控制基本就是“读XML定义、按XML格式发SOAP、等XML响应”这样一个循环。很多人被UPnP搞晕就是因为这三层混在一起看。UPnP-Inspector做的事就是把三层结构里的第二层做深做透顺带打通第三层。2.2 为什么选Coherence框架在Python生态里做UPnP相关开发选项其实不多。Coherence是我个人认为最成熟的DLNA/UPnP框架它的几个特点对这个项目非常关键。第一它基于Twisted异步框架天生适合做设备扫描这种I/O密集任务。局域网里扫描几十台设备每台都要拉取描述XML和SCPD文档如果同步逐个请求体验非常差。Coherence把SSDP的监听、HTTP请求的发送都做成异步回调一套代码就能并发处理大量设备请求。第二它内置了一个完整的控制点Control Point实现。UPnP协议里控制点是“主动发现设备并调用服务”的角色整个UPnP-Inspector的分析逻辑都必须建立在控制点之上。Coherence的control_point模块提供了设备发现、服务订阅、Action调用等全套能力不用自己从零写SSDP和SOAP协议处理。第三它对DLNA规范的支持比较完整。Coherence不仅仅实现了UPnP基础协议还针对DLNA的媒体服务做了大量适配比如ContentDirectory服务CDS内容目录服务、AVTransport服务、ConnectionManager服务相关的建表和处理逻辑。这意味着基于它写分析工具时很多DLNA特有字段已经是被框架解析好的对象属性而不是原始XML里一串难懂的标签。2.3 UPnP-Inspector的整体设计思路基于Coherence框架UPnP-Inspector的设计可以归纳为四个步骤启动Coherence并创建控制点监听SSDP协议收集局域网内所有upnp设备的发现事件。对每台被发现的设备拉取设备描述XML解析出基本信息和服务列表。对每个服务拉取对应的SCPD文档解析出所有Action和状态变量。将解析结果统一展示出来并支持手动调用某个Action来测试设备的实际响应。这个设计与直接用wireshark抓包分析的区别在于它做的是协议层面的“结构化解读”而不是原始字节层面的“数据包分析”。调试DLNA设备时抓包只能告诉你“它发了一个XML”UPnP-Inspector能直接告诉你“它发的这个XML里服务内容目录查询的返回参数少了‘object.item.videoItem’这个类”。3. 实操用UPnP-Inspector分析局域网内的upnp设备3.1 环境准备与安装UPnP-Inspector基于Coherence框架而Coherence早期版本主要支持Python 2.x后来社区做了Python 3的移植分支。如果你在2024年之后动手建议直接找支持Python 3的版本否则在Python 2.7环境里编译依赖库会非常痛苦。安装方式推荐从源码安装。先拉取Coherence相关代码仓库再安装依赖git clone https://github.com/Coherence-upnp/Coherence.git cd Coherence pip install -r requirements.txt python setup.py install依赖里有Twisted、Pygments等库如果安装过程中Twisted编译报错通常需要先安装系统级的Python开发头文件和C编译器。在Debian/Ubuntu上可以用sudo apt-get install python3-dev build-essential libssl-devUPnP-Inspector如果作为独立脚本运行一般位于Coherence项目下的examples或inspector目录里。从我的经验看直接把它当成一个模块来调用比当作独立命令行工具更方便因为这样可以在自己的调试脚本里嵌入它的分析逻辑。3.2 快速开始扫描局域网内所有upnp设备启动一次完整的设备扫描代码量其实非常少这正是Coherence框架的功劳。以下是一段最简扫描程序的核心逻辑from twisted.internet import reactor from coherence.base import Coherence from coherence.upnp.core.utils import get_url def device_found(device, *args, **kwargs): print(发现设备:, device.friendly_name) print( 设备类型:, device.get_device_type()) print( UDN:, device.udn) print( 制造商:, device.get_manufacturer()) print( 服务列表:, [s.get_service_type() for s in device.get_services()]) def start_scan(): c Coherence({controlpoint: yes}) cp c.control_point cp.connect(device_found, Coherence.UPnP.Device.Detected) reactor.callLater(10, reactor.stop) reactor.callWhenRunning(start_scan) reactor.run()这里有几个绕不开的关键点。Coherence({controlpoint: yes})这行是启动框架并声明运行控制点模式如果漏掉这个配置框架不会主动发起SSDP搜索。cp.connect是Twisted风格的事件订阅第二个参数指定监听“新设备被发现”这一事件类型。扫描持续的10秒时间可以自己调整但注意SSDP协议里有T本文还有配套的精品资源点击获取