muse-driver-framework 1.2.0__tar.gz → 1.3.0__tar.gz

{muse_driver_framework-1.2.0 → muse_driver_framework-1.3.0}/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 1.3.0 - 2026-11-01 (prepared for PyPI publication)
+
+- Promote the tested dev4 runtime to 1.3.0: manager-scoped automatic UDP port
+  sharing, optional WS/WSS and MQTT/MQTTS, and verified outbound raw TCP TLS.
+- Keep default plaintext and existing FIFO/latest, ACK, descriptor and feedback
+  semantics. No cross-driver broker and no mandatory third-party dependency.
+- Templates/recipes stay in their independent source repository; they are not
+  included in wheel/sdist. Existing business-driver requirements stay 1.2.0.
+- Source and local protocol/Dashboard validation are recorded separately from
+  public publication and MUSE runtime acceptance; no MUSE upgrade is implied.
+
+## 1.3.0.dev4 - 2026-10-31 (source candidate, unpublished)
+
+- Add opt-in verified TLS to outbound raw TCP and the TCP side of TCP+UDP, using
+  standard-library SSLContext and the existing queue/ACK/framing/lifecycle.
+- Share CA/client certificate helpers with WSS/MQTTS. Support a certificate DNS
+  name override for connections to an IP address; include TLS in connect timeout.
+- Keep plaintext default and reject unsupported TLS server mode; no implicit
+  downgrade, STARTTLS, new template, dependency or business-driver migration.
+- Document existing-template adoption and test actual TLS/mTLS sockets, binary
+  bytes, certificate errors, cancellation, FIFO/latest, reconnect and local Automator.
+
+## 1.3.0.dev3 - 2026-10-31 (source candidate, unpublished)
+
+- Add optional message-oriented WebSocket/WSS clients and managers, preserving
+  text/binary boundaries, verified TLS, headers/subprotocols and protocol-owned
+  authentication/subscription/state synchronization.
+- Add manager-scoped MQTT 3.1.1 broker sessions and topic routing, reference-counted
+  subscriptions, per-device FIFO reception, QoS/retain metadata and MQTTS. Physical
+  device online and application RPC ACK stay separate from broker/PUBACK state.
+- Reuse existing device FIFO/latest, ACK hooks, intervals, descriptors, streams
+  and thread/loop managers without changing TCP/UDP/HTTP lifecycle implementations.
+- Add complete candidate WS and MQTT templates plus documented OBS, Home Assistant
+  and Shelly recipes. Stable five templates and business driver pins stay 1.2.0.
+- Test documented product protocol subsets over real loopback sockets and a real
+  Aedes broker, including TLS failures, LWT, broker process restart, device recovery,
+  stale-write discard and subscription cleanup. No package publication or MUSE upload.
+
+## 1.3.0.dev2 - 2026-10-31 (source candidate, unpublished)
+
+- Unify all UDP channels under `UdpPortBroker`. Identical fixed local binds share
+  automatically; port zero allocates one independent ephemeral socket per channel.
+  Different fixed binds also remain separate. Remove the shared/exclusive switch
+  and the duplicate `SharedUdpChannel` implementation.
+- Pure UDP and TCP+UDP use `manager.udp_channel(...)`; standalone `AsyncUdpChannel`
+  owns a private broker or accepts an explicit broker. Keep per-peer queues, source
+  filtering, source-port-preserving sends and subscription-based socket release.
+- Extend acceptance for same-peer independent ephemeral/fixed sessions and
+  single-to-multiple subscriber transitions. No installed driver or stable pin changes.
+
+## 1.3.0.dev1 - 2026-10-31 (source candidate, unpublished)
+
+- Add manager-owned `UdpPortBroker` and opt-in `udp_shared_port` for pure UDP
+  and TCP+UDP clients. Share fixed binds and sending source ports, while keeping
+  each peer's existing receive queue, parsing, ACK and online lifecycle.
+- Replace blanket pure-UDP bind rejection with common shared/exclusive bind
+  validation, used by configuration loaders and direct manager construction.
+  Ambiguous source routes remain errors; no SO_REUSEPORT or cross-driver service.
+- Add loopback acceptance using documented subsets of QLab OSC and CasparCG
+  AMCP/OSC, including 100 UDP peers and manager restart. Protocol codecs and
+  device semantics live in test drivers, not the runtime broker.
+- Keep installed programs and stable template dependency pins unchanged.
+
 ## 1.2.0 - 2026-10-24 (prepared for PyPI publication)
 
 - Set package metadata, runtime `__version__` and all five copyable template

{muse_driver_framework-1.2.0 → muse_driver_framework-1.3.0}/MANIFEST.in

@@ -1,4 +1,7 @@
 include CHANGELOG.md
+include UDP_SHARED_ACCEPTANCE.md
+include P2_MESSAGE_ACCEPTANCE.md
+include TCP_TLS_ACCEPTANCE.md
 prune examples
 prune tests
 prune validation

muse_driver_framework-1.3.0/P2_MESSAGE_ACCEPTANCE.md

@@ -0,0 +1,78 @@
+# Roadmap P2：消息传输设计与验收
+
+2026-10-31，未发布候选 `1.3.0.dev3`。对应 [roadmap P2 / issue 3](https://github.com/WeiguoHu/muse-driver-framework/issues/3)。沿用 UDP 阶段的“调研→框架/模板→真实网络模拟→本机 Automator→记录”流程；按用户当前范围，不上传 MUSE、不发布、不更新业务驱动依赖。新候选包含前阶段 UDP broker，不覆盖其记录。
+
+## 设计与职责
+
+| 层 | 职责 |
+| --- | --- |
+| 原 _QueuedDeviceClient / _DeviceManagerRuntime | 原设备 FIFO/latest、ACK 钩子、间隔、descriptor、完整实时流、共享线程/loop |
+| message_device.py | WS/MQTT 消息会话的打开、握手、监听、初始查询、设备有效反馈在线、重连、关闭与协议状态清理 |
+| websocket_device.py | 完整 text/binary 消息、URL/path/headers/subprotocol、Ping/Pong、Close code、验证证书的 WSS |
+| mqtt_device.py | 单 manager 的 Broker Session、引用计数订阅、topic filter 路由、有界 FIFO、QoS/retain 元数据、验证证书的 MQTTS |
+| protocol.py / 可选配方 | 厂商 JSON/RPC、token/Challenge 认证、请求 ID、订阅内容、错误/ACK、设备 LWT、真实状态与 descriptor 映射 |
+
+没有为了新传输改写已经验证的 TCP/UDP/HTTP 生命周期；没有给公共框架加入 OBS、HA、Shelly 或 Tasmota 字段。普通框架导入不加载 websockets/aiomqtt/Paho。原有五套模板及四个业务驱动保持公共 1.2.0 精确依赖。
+
+WS 握手独占 read_message；完成后 listener 启动，再执行可等待 ACK 的初始查询。传输连接、认证/订阅、有效设备反馈是不同阶段；Ping/Pong、HTTP Upgrade、Broker CONNACK 不自动制造设备 online。断开清空待发写命令，重连通过协议只读查询恢复。
+
+MQTT 一条 Broker 会话可路由多个设备。客户端自己解析设备实际 online/LWT，`mark_device_offline()` 只关闭该设备接纳、清其待发命令，不断开其他设备；Online 提示通过 `request_state_sync()` 排入只读查询，实际返回后才上线。已进入网络的命令无法撤回。PUBACK/PUBCOMP 仅是传输确认，应用完成仍使用 prepare/wait ACK 钩子与协议关联。
+
+## 公共入口与配置
+
+WS：`AsyncWebSocketDeviceClient` / `AsyncWebSocketDeviceManager`，每 slot 一个 url（ws/wss）。`ws_headers`、`ws_subprotocols`、`ws_max_message_bytes` 默认 1 MiB、`ws_max_queue` 默认16、Ping/Pong 默认20秒。`self.channel.send(str|bytes)` 与 `await self.read_message()` 用于协议握手；正常控制交 descriptor 和现有队列。
+
+MQTT：`AsyncMqttDeviceClient` / `AsyncMqttDeviceManager`，manager 接收 `broker={host, port, ...}`；逻辑设备覆盖 subscription_topics。`MqttPublish(topic,payload,qos=0,retain=False)` 和 `MqttMessage(topic,payload,qos,retain)` 保留消息语义。`MqttBrokerSession` / `MqttTopicRouter` 是单 manager/loop 资源，不是跨进程服务。
+
+仅支持 MQTT 3.1.1、clean session；QoS 0/1/2 的协议交换交给库，fresh Client 不重放先前会话中的应用写入；不支持 MQTT 5 属性/会话过期或 MQTT over WebSocket。普通 topic filter +/# 支持按读订阅扇出，同一个客户端匹配多个 filter 时本地只分发一次；QoS 自身可能产生重复，协议层负责请求/事件序号和幂等性。
+
+broker 默认 keepalive_seconds=30、timeout_seconds=10、incoming_queue_size=1000；设备 mqtt_queue_size 默认100、mqtt_qos 默认1。全部接收 FIFO 有界，不能将 RPC/事件流自动替换成全局 latest。完整可丢弃的表计帧仍由协议解析后交 MeterStream/XYSeriesStream，不在 MQTT 入站丢 RPC。
+
+WSS/MQTTS 默认系统信任、证书和主机名验证，支持 tls_ca_file/tls_ca_data 与可选 tls_cert_file/tls_key_file。相对路径基于 config.json；不提供默认跳过验证。URL 不接受嵌入用户名密码；token/设备认证放私有配置，不打印原始认证报文。WSS/MQTTS 库处理加密，框架不自行实现 TLS。
+
+可选依赖锁定 `[websocket]`: websockets 15.0.1；`[mqtt]`: aiomqtt 2.4.0 + Paho 2.1.0。PyPI 元数据兼容目标 Python 3.9。aiomqtt/Paho 在初始化失败及 TLS 证书失败的 socket 所有权有已复现问题，本候选在局部会话内显式清理 Paho socket，并把该 SSLContext 的握手交 Python 持有，避免证书失败时遗留未归属 ssl socket；不修改全局 SSL/Paho 类。相关库内部接入（队列与 socket）针对精确版本测试，升级依赖必须重跑失败/关闭测试。
+
+## 官方参考
+
+- [IPComm 官方项目](https://github.com/amx-itg/muse-driver-amx-ipcomm)，[开发站 1.0.6 下载](https://developer.amx.com/assets/api/downloadMuseDriver.php?id=61)：实际 JAR 的 WS Endpoint/Adapter/Open/Message/Close/Error、path/headers/TLS 分离可借鉴；其文本/二进制转 byte[] 行为没有照搬。本包未发现 MQTT 实现。
+- [OBS 5.x 协议](https://github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md)：RPC1，Hello/Identify/Identified、SHA256/base64 认证、requestId、场景和音量、事件订阅。
+- [Home Assistant WebSocket](https://contributors.home-assistant.io/core/internals/websocket-api/)：auth_required/auth/auth_ok、递增 id、get_states、subscribe_events/state_changed、服务调用。
+- [Shelly Plus 1](https://shelly-api-docs.shelly.cloud/gen2/Devices/Gen2/ShellyPlus1/)、[RPC channels](https://shelly-api-docs.shelly.cloud/gen2/General/RPCChannels/)、[MQTT](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Mqtt/)：Gen2 relay0，WS/MQTT RPC、唯一 src、Switch.Set/GetStatus、NotifyStatus、online/LWT。
+- [Tasmota 14.6.0](https://github.com/arendst/Tasmota/releases/tag/v14.6.0)、[MQTT 文档](https://tasmota.github.io/docs/MQTT/)：POWER 读写、cmnd/stat/tele、RESULT、retained/LWT。
+- [MQTT 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html)、[websockets](https://websockets.readthedocs.io/en/15.0.1/reference/asyncio/client.html)、[aiomqtt](https://aiomqtt.bo3hm.com/developer-interface)、[Aedes](https://github.com/moscajs/aedes)。
+
+OBS 是桌面 AV/媒体场景，HA、Shelly/Tasmota 是楼宇/继电器场景，足够覆盖本阶段的消息语义差异。本轮没有为扩展品牌清单而加入缺少明确公开控制规范的商业设备。模拟器只实现文档子集，不运行厂商服务/固件；Home Assistant 按当前文档、Shelly 按 Gen2接口，不宣称固件全量兼容。Shelly 选用其文档化入站 WS，不把测试 WSS 能力宣传成 Shelly Plus 1 具有入站 WSS；Shelly 应用 Digest 未在默认配方实现。
+
+## 模板
+
+`examples/websocket-device`：完整 index/protocol/program/config/requirements/.uploadignore，默认 Shelly WS。可选 obs_example.py、home_assistant_example.py 在 factory 中采用；`接入说明.md` 和文件顶部给出类/方法、字段、改名、上传排除和固定/修改边界。
+
+`examples/mqtt-device`：完整同结构，默认 Tasmota，shelly_example.py 可替换客户端，manager/入口和 power descriptor 保持。Broker 配置独立，src 唯一，ACK 与反馈独立。
+
+两套候选 requirements 精确声明未发布 1.3.0.dev3 + extra，明确先用本地源码/wheel 测试，不能假装 PyPI 已存在。复制到独立目录后各自的最小协议/入口测试可执行，不依赖兄弟模板或全局 fake mojo 文件。正式部署需要另行发布并锁定真实版本。
+
+## 本机验收与边界
+
+真实 WS/WSS socket、Aedes 0.51.3 Broker + aiomqtt 模拟设备，不 mock 网络 send/recv。核心测试涵盖消息类型、路径/头/子协议、Close/重连、CA/认证失败、QoS0/1/2、retain、订阅拒绝、引用计数、慢设备 FIFO 溢出隔离。设备协议测试覆盖 OBS/HA/Shelly WS/MQTT/Tasmota，应用 ACK 等待独立于 PUBACK，单设备 LWT、Broker 服务真正重启、晚设备上线只读同步和待发写命令丢弃。
+
+MQTT 3.1.1 向已有订阅者实时投递 retained 发布时会清零 retain 位；因此“不把 retained 当作在线证据”针对订阅快照，不是防止外部客户端伪造实时状态的认证机制。正常重复/乱序是否可接受按设备关联字段处理，框架不凭空推断状态先后。
+
+原框架回归、四驱动回归、复制模板测试、可选依赖 import、wheel/sdist 文件和隔离 wheel 导入均单独记录。当前 Python 3.9.7/Conda 环境在部分 WSS 关闭与负向 TLS 服务器上仍输出 asyncio SSL transport ResourceWarning，测试断言未因此失败；本阶段如实保留日志，并以真实会话关闭、线程结束、server.wait_closed 和端口重新 bind 核实所测试资源。不能把本机结果解释成 MUSE 上的内核/SDK 资源验收。
+
+本机 Automator 48080 新增独立 P2 页：实际命令经 HTTP节点到协议 manager，反馈来自设备报文解析。HTTP 测试桥有秒级往返波动，不作为 UI 跟手性结论；协议事件与请求响应耗时在 Python 侧独立测量。CPU/RSS 覆盖组合 Python 模拟器及五个管理器线程，不包含 Automator、浏览器、Broker进程。
+
+源文件、研究、JAR 字节码、测试工具和逐次结果在上级项目 `local-validation/p2-message-transports-20261031/`。完整结果见下；短程运行分别保存，不与完整验收混淆。
+
+## 最终结果（2026-10-31）
+
+- CPython 3.9.7：框架运行 224 项，221 通过、3 项环境相关跳过；四个现有驱动合计 103 项全部通过（Precis 45、BLU 18、Meter 6、Alcorn 34）。复制模板的四组独立目录测试通过。
+- 构建 wheel 与 sdist；从独立目录导入 wheel，真实消息传输 9 项和厂商协议 7 项通过。普通 `python -S` 导入没有加载 websockets、aiomqtt 或 Paho。未安装到业务运行环境，未发布。
+- 本机 Automator 新增独立 13 节点；原 671 节点逐项一致，flow_cred.json 与 package.json 哈希保持。页面浏览器错误为零。测试进程及 Broker 已停止，页面保留最终缓存。
+- 十台设备 / 五个 manager：6 条 WS/WSS 会话，另 4 台 MQTT/MQTTS 逻辑设备共享 2 条 Broker 会话。8 项场景全部通过，包括实际 Broker 进程重启、单设备 LWT、WSS 订阅恢复、各 manager 三轮启停与关闭后 8 个服务器端口重新 bind。
+- 持续 180.042 秒、2,640 轮、26,400 次真实解析状态核对全部一致；意外重连 0、接收队列溢出 0。测量的是协议状态事件，不是厂商原生 Meter 流；原有 Meter/XY 完整帧回归保留，本轮不宣称新传输已完成厂商 Meter 实测。
+- 本机事件延迟 p50/p95/p99 = 1.322/3.301/5.616 ms，RPC ACK = 1.218/5.303/9.116 ms；Tasmota 查询 p95 = 7.300 ms。组合 Python 进程 CPU 32.489 秒、峰值 RSS 45,363,200 bytes。此为 loopback 模拟负载，不能推断 MUSE/局域网/界面性能。
+- HTTP 测试命令往返出现 1.088–7.672 秒波动；协议事件另行测量，不能拿事件分位数掩盖 HTTP 测试桥耗时，也不能把该桥耗时归为新消息客户端延迟。后续若验收 UI 跟手性，须独立排查 HTTP/Automator 链路。
+
+本地展示：[P2 验证页](http://127.0.0.1:48080/dashboard/p2-message-validation)。结果目录 `../local-validation/p2-message-transports-20261031/automator-2026-10-31T00-28-17-682Z/` 包含 result/deployment/browser JSON、完整截图、Python 日志及私有部署前备份；`验收汇总.json` 与 `test-logs/` 汇总源码/业务/独立 wheel 记录。运行前记录的所有框架、候选模板、协议模拟器源码哈希与验收后文件一致。
+
+本机阶段完成；真实 MUSE 的依赖安装、热重载、SDK 注册与真实厂商设备互通未执行，不据此关闭包含实机条款的远端 issue，也不提前进入 P3 Builder。

{muse_driver_framework-1.2.0 → muse_driver_framework-1.3.0}/PKG-INFO

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: muse-driver-framework
-Version: 1.2.0
+Version: 1.3.0
 Summary: Shared pure-Python framework for AMX MUSE Script-as-Device drivers
 Author: AMX MUSE driver project
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+Provides-Extra: websocket
+Requires-Dist: websockets==15.0.1; extra == "websocket"
+Provides-Extra: mqtt
+Requires-Dist: aiomqtt==2.4.0; extra == "mqtt"
+Requires-Dist: paho-mqtt==2.1.0; extra == "mqtt"
 Provides-Extra: http
 Requires-Dist: httpx<0.29,>=0.28.1; extra == "http"
 Provides-Extra: telnet
@@ -18,18 +23,98 @@ Requires-Dist: cryptography<49,>=48.0.1; extra == "ssh"
 
 Shared pure-Python runtime framework for AMX MUSE Script-as-Device programs.
 
-Version **1.2.0** packages the current protocol-adaptation work. Package metadata,
-runtime `__version__` and all five complete template requirements agree on
-1.2.0. The distributions are prepared locally; upload to PyPI before deploying
-templates that require this version. Existing device drivers keep their own
-exact requirements until explicitly upgraded.
+Version **1.3.0** is prepared for PyPI publication. It includes manager-scoped
+UDP port sharing, optional WebSocket/MQTT transports and verified outbound raw
+TCP TLS. This checkout has not uploaded the release or upgraded any MUSE program.
+The last verified public release remains **1.2.0** until publication is confirmed;
+existing business-driver and stable template pins are unchanged. After publishing,
+select the exact 1.3.0 requirement for programs adopting these new capabilities.
+Installing a package does not update existing programs.
+
+See [UDP shared-port design and acceptance](UDP_SHARED_ACCEPTANCE.md) for the
+configuration, architecture boundaries, protocol references and simulation scope.
+Pure UDP and TCP+UDP clients automatically share identical fixed local binds;
+there is no shared/exclusive configuration switch. Port `0` creates an independent
+OS-assigned socket per channel; different fixed binds also use separate sockets.
+Their existing `create_udp_channel()` / `receive()` / `send()` interface remains.
+A socket routes by resolved source IP+port, or by fixed IP when
+`udp_strict_peer_port` is false. Ambiguous overlapping source routes are rejected.
+Distinct managers and programs do not share listeners. Direct `AsyncUdpChannel`
+construction owns a private broker, unless explicitly given `broker=...`; driver
+overrides use `super().create_udp_channel()` or `manager.udp_channel(...)` to join
+their manager's broker. Per-device FIFO/latest buffers and lifecycle stay separate.
 
 PyPI distributes only the framework library and its build/documentation metadata.
-The five driver templates, protocol recipes and tests stay in the development
+The five stable and two candidate driver templates, protocol recipes and tests stay in the development
 checkout; they are not included in either the wheel or source distribution.
 Copy a template locally, then let its `requirements.txt` declare which framework
 version MUSE should install. Templates are not synchronized from PyPI.
 
+## Raw TCP TLS (1.3.0)
+
+Use the existing `AsyncTcpDeviceClient` / `AsyncTcpDeviceManager` with `tls: true`.
+Default `false` preserves plaintext TCP. This option supports outbound
+`tcp_mode: "client"` only; server mode with TLS is rejected explicitly.
+TLS uses Python's standard library, without a new extra or template.
+
+`tls_ca_file` / `tls_ca_data` configure private trust; `tls_cert_file` /
+`tls_key_file` optionally present a client certificate. Relative file paths resolve
+from `config.json`. `tls_server_hostname` defaults to `host`; set the certificate's
+DNS name when connecting to an IP endpoint whose certificate identifies that name.
+Certificate and hostname verification remain enabled. The connection deadline
+includes the TLS handshake; failures do not fall back to plaintext.
+
+Framing, application login, FIFO/latest, ACK, watchdog and reconnect still use the
+existing TCP protocol/lifecycle. Runtime statistics report `tcpTls` and the active
+`tlsVersion`; TLS itself does not prove application state or device execution.
+The TCP part of `AsyncTcpUdpDeviceClient` can use the same option; its UDP channel
+remains unchanged. Telnet/SSH, STARTTLS and a TLS server are separate protocols or
+modes and are outside this addition.
+
+See [TCP TLS design and acceptance](TCP_TLS_ACCEPTANCE.md) and the existing
+`examples/scoped-device/config.tls.example.json`. Stable template requirements
+remain 1.2.0; adopting TLS requires the exact 1.3.0 dependency after this release
+is published. No current business driver is upgraded.
+
+## P2 message transports (1.3.0)
+
+`AsyncWebSocketDeviceClient` / `AsyncWebSocketDeviceManager` preserve complete
+text/binary messages with optional `[websocket]` dependencies. Protocol handshake
+owns receive until authenticated; then the listener starts before initial RPC
+queries. Paths, headers, subprotocols and verified WSS CA/client certificates are
+configurable; Ping/Pong alone never marks a physical device online.
+
+`AsyncMqttDeviceClient` / `AsyncMqttDeviceManager` separate logical devices from
+one `MqttBrokerSession` per manager. A `MqttTopicRouter` shares subscriptions by
+reference count and routes to bounded per-device FIFOs. `[mqtt]` is optional.
+MQTT 3.1.1, QoS 0/1/2 and retained metadata are supported; MQTT 5 and cross-process
+sharing aren't included. Transport PUBACK/PUBCOMP never substitutes for a device
+action ACK. A new clean session and protocol-owned reads rebuild real state;
+pending writes aren't replayed after session loss.
+
+The seven local templates include the new candidate `websocket-device` (Shelly
+WS plus optional OBS/HA recipes) and `mqtt-device` (Tasmota plus Shelly RPC).
+These two require the 1.3.0 message transports and their named extra;
+the original five and installed drivers keep public `1.2.0` pins. Read each
+candidate template's Chinese integration guide before editing protocol hooks.
+The actual WS/TLS sockets and Aedes MQTT broker tests model documented product
+subsets, not vendor firmware certification. See [P2 acceptance](P2_MESSAGE_ACCEPTANCE.md).
+
+## Script-as-Device workflow
+
+Maintain one complete local `program.json` and upload the whole driver folder
+with the native VSCode MUSE Plugin. No descriptor-generation step or second
+`device-descriptor.json` is needed. Each driver entry point exports its registered
+descriptor to memory through `context.export.exporter.exportDescriptor()`;
+it does not read the controller-managed `program.json` at runtime. This SDK glue
+stays outside the transport library. The workflow was verified on MUSE 1.15.45.
+
+This entry-point change does not require a new framework or panel release.
+Existing drivers must receive updated entry-point source through a full driver
+upload; changing the installed framework alone cannot update their Python files.
+See the development checkout's `Script-as-Device开发与上传流程.md` for the current
+upload, testing and deployment checklist. Keep site configuration private.
+
 The package contains the transport-independent pieces shared by the Precis
 Driver and Meter Validation programs:
 
@@ -105,7 +190,7 @@ discard queued writes on failure. Session cleanup uses `session_ended()`.
 See `examples/http-device/` for a complete copyable driver and simulated-device
 tests. These APIs are included in 1.2.0, not the previously published 1.1.9
 package. Test source with `pip install -e '.[http]'`, or install
-`muse-driver-framework[http]==1.2.0` after publication.
+the published `muse-driver-framework[http]==1.2.0`.
 
 ## Runtime boundaries
 
@@ -136,7 +221,8 @@ port change without imposing that relationship on independent UDP notifications.
 The `udpOnline` runtime statistic means the UDP channel opened, not evidence
 that remote feedback is current; use `udpSocketOpen` for socket diagnostics.
 The device's public online state remains protocol-specific. This is not an
-Art-Net output scheduler or an SSE/WebSocket client.
+Art-Net output scheduler or an SSE client. WebSocket uses the separate optional
+message transport described above, not this TCP/UDP adapter.
 
 Each framework import belongs to one model-specific Script-as-Device runtime.
 The framework does not discover devices, verify model identity, or merge devices
@@ -283,7 +369,7 @@ described below; all are included in 1.2.0. Publication and target-runtime
 installation are separate steps. Older artifacts are unchanged.
 See [examples](examples/README.md) for TCP, pure UDP, TCP+UDP and HTTP templates.
 
-All five copyable directories include the MUSE entry point, descriptor,
+The original five copyable directories include the MUSE entry point, descriptor,
 configuration example, protocol module and minimal loopback tests. The TCP/UDP
 directories have optional ACK recipes; HTTP uses its request/response flow.
 The mixed template uses ordinary TCP controls plus a UDP readonly indicator;
@@ -432,8 +518,9 @@ Manager shutdown cancels device-owner tasks first and allows 250 ms for orderly
 cleanup before canceling residual tasks. The fallback also handles legacy
 receivers that swallow an initial cancellation during a receive timeout race.
 New BLU source requires `enqueue_recovery` and refuses to start with old framework
-code; its existing exact requirement remains 1.1.9. Adopting 1.2.0 is an explicit
-requirements change after publication. Previously published versions remain unchanged.
+code. Its exact requirement has now been explicitly upgraded to the published
+1.2.0. Previously published versions remain unchanged; this documentation update
+does not rebuild or replace the published 1.2.0 artifacts.
 
 The manager constructor accepts the normalized device list, not the config root:
 pass `config[entries_key]` and `config["connection_stagger_seconds"]`. Root

muse_driver_framework-1.2.0/muse_driver_framework.egg-info/PKG-INFO → muse_driver_framework-1.3.0/README.md

@@ -1,35 +1,99 @@
-Metadata-Version: 2.4
-Name: muse-driver-framework
-Version: 1.2.0
-Summary: Shared pure-Python framework for AMX MUSE Script-as-Device drivers
-Author: AMX MUSE driver project
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Provides-Extra: http
-Requires-Dist: httpx<0.29,>=0.28.1; extra == "http"
-Provides-Extra: telnet
-Requires-Dist: telnetlib3<5.1,>=5.0.1; extra == "telnet"
-Provides-Extra: ssh
-Requires-Dist: asyncssh<2.22,>=2.21.1; python_version < "3.10" and extra == "ssh"
-Requires-Dist: asyncssh<2.25,>=2.24.1; python_version >= "3.10" and extra == "ssh"
-Requires-Dist: cryptography<49,>=48.0.1; extra == "ssh"
-
 # muse-driver-framework
 
 Shared pure-Python runtime framework for AMX MUSE Script-as-Device programs.
 
-Version **1.2.0** packages the current protocol-adaptation work. Package metadata,
-runtime `__version__` and all five complete template requirements agree on
-1.2.0. The distributions are prepared locally; upload to PyPI before deploying
-templates that require this version. Existing device drivers keep their own
-exact requirements until explicitly upgraded.
+Version **1.3.0** is prepared for PyPI publication. It includes manager-scoped
+UDP port sharing, optional WebSocket/MQTT transports and verified outbound raw
+TCP TLS. This checkout has not uploaded the release or upgraded any MUSE program.
+The last verified public release remains **1.2.0** until publication is confirmed;
+existing business-driver and stable template pins are unchanged. After publishing,
+select the exact 1.3.0 requirement for programs adopting these new capabilities.
+Installing a package does not update existing programs.
+
+See [UDP shared-port design and acceptance](UDP_SHARED_ACCEPTANCE.md) for the
+configuration, architecture boundaries, protocol references and simulation scope.
+Pure UDP and TCP+UDP clients automatically share identical fixed local binds;
+there is no shared/exclusive configuration switch. Port `0` creates an independent
+OS-assigned socket per channel; different fixed binds also use separate sockets.
+Their existing `create_udp_channel()` / `receive()` / `send()` interface remains.
+A socket routes by resolved source IP+port, or by fixed IP when
+`udp_strict_peer_port` is false. Ambiguous overlapping source routes are rejected.
+Distinct managers and programs do not share listeners. Direct `AsyncUdpChannel`
+construction owns a private broker, unless explicitly given `broker=...`; driver
+overrides use `super().create_udp_channel()` or `manager.udp_channel(...)` to join
+their manager's broker. Per-device FIFO/latest buffers and lifecycle stay separate.
 
 PyPI distributes only the framework library and its build/documentation metadata.
-The five driver templates, protocol recipes and tests stay in the development
+The five stable and two candidate driver templates, protocol recipes and tests stay in the development
 checkout; they are not included in either the wheel or source distribution.
 Copy a template locally, then let its `requirements.txt` declare which framework
 version MUSE should install. Templates are not synchronized from PyPI.
 
+## Raw TCP TLS (1.3.0)
+
+Use the existing `AsyncTcpDeviceClient` / `AsyncTcpDeviceManager` with `tls: true`.
+Default `false` preserves plaintext TCP. This option supports outbound
+`tcp_mode: "client"` only; server mode with TLS is rejected explicitly.
+TLS uses Python's standard library, without a new extra or template.
+
+`tls_ca_file` / `tls_ca_data` configure private trust; `tls_cert_file` /
+`tls_key_file` optionally present a client certificate. Relative file paths resolve
+from `config.json`. `tls_server_hostname` defaults to `host`; set the certificate's
+DNS name when connecting to an IP endpoint whose certificate identifies that name.
+Certificate and hostname verification remain enabled. The connection deadline
+includes the TLS handshake; failures do not fall back to plaintext.
+
+Framing, application login, FIFO/latest, ACK, watchdog and reconnect still use the
+existing TCP protocol/lifecycle. Runtime statistics report `tcpTls` and the active
+`tlsVersion`; TLS itself does not prove application state or device execution.
+The TCP part of `AsyncTcpUdpDeviceClient` can use the same option; its UDP channel
+remains unchanged. Telnet/SSH, STARTTLS and a TLS server are separate protocols or
+modes and are outside this addition.
+
+See [TCP TLS design and acceptance](TCP_TLS_ACCEPTANCE.md) and the existing
+`examples/scoped-device/config.tls.example.json`. Stable template requirements
+remain 1.2.0; adopting TLS requires the exact 1.3.0 dependency after this release
+is published. No current business driver is upgraded.
+
+## P2 message transports (1.3.0)
+
+`AsyncWebSocketDeviceClient` / `AsyncWebSocketDeviceManager` preserve complete
+text/binary messages with optional `[websocket]` dependencies. Protocol handshake
+owns receive until authenticated; then the listener starts before initial RPC
+queries. Paths, headers, subprotocols and verified WSS CA/client certificates are
+configurable; Ping/Pong alone never marks a physical device online.
+
+`AsyncMqttDeviceClient` / `AsyncMqttDeviceManager` separate logical devices from
+one `MqttBrokerSession` per manager. A `MqttTopicRouter` shares subscriptions by
+reference count and routes to bounded per-device FIFOs. `[mqtt]` is optional.
+MQTT 3.1.1, QoS 0/1/2 and retained metadata are supported; MQTT 5 and cross-process
+sharing aren't included. Transport PUBACK/PUBCOMP never substitutes for a device
+action ACK. A new clean session and protocol-owned reads rebuild real state;
+pending writes aren't replayed after session loss.
+
+The seven local templates include the new candidate `websocket-device` (Shelly
+WS plus optional OBS/HA recipes) and `mqtt-device` (Tasmota plus Shelly RPC).
+These two require the 1.3.0 message transports and their named extra;
+the original five and installed drivers keep public `1.2.0` pins. Read each
+candidate template's Chinese integration guide before editing protocol hooks.
+The actual WS/TLS sockets and Aedes MQTT broker tests model documented product
+subsets, not vendor firmware certification. See [P2 acceptance](P2_MESSAGE_ACCEPTANCE.md).
+
+## Script-as-Device workflow
+
+Maintain one complete local `program.json` and upload the whole driver folder
+with the native VSCode MUSE Plugin. No descriptor-generation step or second
+`device-descriptor.json` is needed. Each driver entry point exports its registered
+descriptor to memory through `context.export.exporter.exportDescriptor()`;
+it does not read the controller-managed `program.json` at runtime. This SDK glue
+stays outside the transport library. The workflow was verified on MUSE 1.15.45.
+
+This entry-point change does not require a new framework or panel release.
+Existing drivers must receive updated entry-point source through a full driver
+upload; changing the installed framework alone cannot update their Python files.
+See the development checkout's `Script-as-Device开发与上传流程.md` for the current
+upload, testing and deployment checklist. Keep site configuration private.
+
 The package contains the transport-independent pieces shared by the Precis
 Driver and Meter Validation programs:
 
@@ -105,7 +169,7 @@ discard queued writes on failure. Session cleanup uses `session_ended()`.
 See `examples/http-device/` for a complete copyable driver and simulated-device
 tests. These APIs are included in 1.2.0, not the previously published 1.1.9
 package. Test source with `pip install -e '.[http]'`, or install
-`muse-driver-framework[http]==1.2.0` after publication.
+the published `muse-driver-framework[http]==1.2.0`.
 
 ## Runtime boundaries
 
@@ -136,7 +200,8 @@ port change without imposing that relationship on independent UDP notifications.
 The `udpOnline` runtime statistic means the UDP channel opened, not evidence
 that remote feedback is current; use `udpSocketOpen` for socket diagnostics.
 The device's public online state remains protocol-specific. This is not an
-Art-Net output scheduler or an SSE/WebSocket client.
+Art-Net output scheduler or an SSE client. WebSocket uses the separate optional
+message transport described above, not this TCP/UDP adapter.
 
 Each framework import belongs to one model-specific Script-as-Device runtime.
 The framework does not discover devices, verify model identity, or merge devices
@@ -283,7 +348,7 @@ described below; all are included in 1.2.0. Publication and target-runtime
 installation are separate steps. Older artifacts are unchanged.
 See [examples](examples/README.md) for TCP, pure UDP, TCP+UDP and HTTP templates.
 
-All five copyable directories include the MUSE entry point, descriptor,
+The original five copyable directories include the MUSE entry point, descriptor,
 configuration example, protocol module and minimal loopback tests. The TCP/UDP
 directories have optional ACK recipes; HTTP uses its request/response flow.
 The mixed template uses ordinary TCP controls plus a UDP readonly indicator;
@@ -432,8 +497,9 @@ Manager shutdown cancels device-owner tasks first and allows 250 ms for orderly
 cleanup before canceling residual tasks. The fallback also handles legacy
 receivers that swallow an initial cancellation during a receive timeout race.
 New BLU source requires `enqueue_recovery` and refuses to start with old framework
-code; its existing exact requirement remains 1.1.9. Adopting 1.2.0 is an explicit
-requirements change after publication. Previously published versions remain unchanged.
+code. Its exact requirement has now been explicitly upgraded to the published
+1.2.0. Previously published versions remain unchanged; this documentation update
+does not rebuild or replace the published 1.2.0 artifacts.
 
 The manager constructor accepts the normalized device list, not the config root:
 pass `config[entries_key]` and `config["connection_stagger_seconds"]`. Root

muse_driver_framework-1.3.0/TCP_TLS_ACCEPTANCE.md

@@ -0,0 +1,45 @@
+# 原始 TCP＋TLS 设计与验收
+
+2026-10-31，候选 **1.3.0.dev4**，未发布/未上传 MUSE。用户授权在现有 TCP 模板中补充 TLS，参考官方 IPComm 1.0.6；完整模板仍为七套。
+
+## 实现
+
+`AsyncTcpDeviceClient` / `AsyncTcpDeviceManager` 在主动连接上接受 `tls=true`；默认 false 保持普通 TCP。使用标准库，不新增 extra。TLS 连接成功后继续复用同一套协议分帧、登录、FIFO/latest、ACK、watchdog 与重连。
+
+支持系统/私有 CA、证书及主机名验证、`tls_server_hostname`（连接 IP 与证书 DNS 名分离）、可选客户端证书/密钥。TLS 握手计入 connect_timeout，失败不会改连明文。相对证书文件基于 config.json 解析。当前只实现 client，不实现 TLS server、STARTTLS 或 Telnet-over-TLS；SSH 继续采用原独立适配。
+
+共享 TLS 工具从 message_device 提取到 tls.py，WSS/MQTTS 使用相同函数；现有消息传输专项纳入全量回归。TCP+UDP / 网关模板的主动 TCP 部分可采用该配置；UDP 部分不变。
+
+## IPComm 1.0.6 对照
+
+来源：[官方项目](https://github.com/amx-itg/muse-driver-amx-ipcomm)、[官方二进制下载](https://developer.amx.com/assets/api/downloadMuseDriver.php?id=61)。本次读取已保存 1.0.6 JAR 的 class，而非凭类名推断：TLSClientPersistentDriverAdapter 只设置 TLS 标志，共用 TCP adapter；后者加载 SSLContext 并向 NioEngine.enableTLS 注入连接层配置。
+
+其 SSLContextProvider 在 certificate 为空时使用 TrustAll。本框架继续采用证书/主机名验证，不把其 Java trust store 或 TrustAll 直接移入 Python。原始字节码、JAR 哈希和说明保存在 `../local-validation/tcp-tls-20261031/`。
+
+Python 官方依据：[SSLContext](https://docs.python.org/3.9/library/ssl.html)、[asyncio 连接](https://docs.python.org/3.9/library/asyncio-eventloop.html#asyncio.loop.create_connection)。TLS 协商版本由目标 Python/OpenSSL 与设备共同决定，不承诺所有 MUSE 固件具有同一版本/信任库。
+
+## 模板采用
+
+使用原 `examples/scoped-device`，读取 [TLS 接入说明](examples/scoped-device/TLS接入说明.md)，参考 config.tls.example.json。无需新客户端类或修改 create_client；设备正文、认证、参数范围/反馈仍在 protocol.py。原五套 requirements 保留 1.2.0，启用 TLS 前必须使用匹配的新框架；未发布候选不能直接假定 PyPI 可安装。两套消息模板继续跟随当前候选版本，四个业务驱动依赖不变。
+
+## 源码结果
+
+- CPython 3.9.7：TCP TLS 专项 7 项全部通过。
+- 全框架运行 231 项，228 通过、3 项未安装 Telnet/SSH extra 而跳过；WS/WSS/MQTT/MQTTS、TCP/UDP/HTTP、复制模板测试包含在通过部分。
+- 四现有业务驱动共 103 项通过：Precis 45、BLU 18、Meter 6、Alcorn 34；它们的 requirements 仍锁公共 1.2.0，测试使用候选源码，并未替换安装版本。
+- 实际 TLS/mTLS 验证服务器身份、主机名与客户端身份；错误证书在应用报文发送前失败。二进制测试保持包括非 UTF-8/NUL/换行在内的完整 bytes。
+- 使用当前 Conda Python 3.9 的负向 TLS 服务器可能输出预期证书拒绝/ConnectionReset 和已有 asyncio SSL transport ResourceWarning；日志完整保留，不把这些日志当业务连接失败，也不据本机端口重绑断言 MUSE 内核资源行为。
+
+本机 Automator 结果见下。研究、脚本、私有备份与日志都在上级 `local-validation/tcp-tls-20261031/`；不发布、Push 或上传，不宣称已对接真实厂商加密协议。
+
+## 本机 Automator 最终结果
+
+- 独立 Tab `TCP TLS · 本机验证`；状态结果：[本地 JSON](http://127.0.0.1:48080/tcp-tls-validation/status)。新增 10 个验证节点，原 684 节点逐项保持，凭据和 package 哈希保持。未修改业务绑定，也未重启控制器。
+- 4 台同协议模拟设备：3 条 TLS（含 1 条 mTLS）、1 条明文，同 manager/loop；3 条加密连接实际协商 TLSv1.3。
+- 6 项场景全部通过：混合连接、Automator 控制与真实反馈、latest/FIFO/ACK、单设备重连隔离、3 轮管理器启停、持续事件。
+- 持续 60.062 秒，931 轮、3,724 次状态核对一致；意外重连 0，结束时待发 latest 为 0。100 次连续目标在该次突发中合并成 1 次设置，最终目标 99；离散静音顺序保留。
+- manager 线程和所有测试会话停止，4 个服务器端口实际重新 bind。测试 HTTP 适配服务退出，Automator 只保留最后状态缓存。
+- 本机检测等待分位数 p50/p95/p99=12.395/15.028/17.134 ms。这里使用 10 ms 间隔等待状态条件，包含测试轮询发现耗时，不能当作 TLS 本身开销或 UI 延迟。组合 Python 模拟器与管理器进程 CPU 2.498 秒、峰值 RSS 31,551,488 bytes，不含 Automator。
+- 测试 HTTP 命令往返：mute 3.145 秒、volume 0.152 秒，保留实测波动，不以协议事件检测值掩盖测试桥耗时。
+
+完整结果 `../local-validation/tcp-tls-20261031/automator-2026-10-31T01-07-26-899Z/` 包含 result.json、deployment.json、python.log、部署前私有备份与验证 Flow。源码哈希在运行前后核对一致。首次 HTTP 节点注册时序失败单独保留，修正测试工具等待路由就绪后本轮通过。新功能尚未发布、未上传 MUSE；MUSE 的 Python/OpenSSL、证书部署与真实设备协议需要独立验收。