# Art-Net 舞台灯光DMX工具箱

**Repository Path**: lover520f_admin/ArtNet_toolbox

## Basic Information

- **Project Name**: Art-Net 舞台灯光DMX工具箱
- **Description**: Art-Net DMX 监视器: 监听 UDP 6454 的 ArtDmx 数据, 实时显示 universe/channel 数值波动 (PySide6 GUI)
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-03
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Art-Net Tools (v0.2)

Art-Net DMX 调试工具集 —— 一个**控制台**（模拟数据源 + 推子控台）+ 一个**通道监视器**（监听显示），均基于 UDP 6454 端口的 ArtDmx 协议，各自独立打包为 exe（单实例）。

```
Art-Net 控制台.exe       控制台 v0.2 —— 标签: 全局测试(4 种模拟模式) + 推子控台1~15(各 10 推子)
Art-Net 通道监视器.exe   通道监视器 v0.2 —— 监听 ArtDmx，表格 + 波形图实时显示
```

## 项目截图

![套件启动标志页](项目截图/0.png)

![双工具主界面（监视器 + 控制台全局测试）](项目截图/1.png)

![推子控台界面（含推子设置弹窗）](项目截图/2.png)

![多标签推子控台（推子控台 1~15）](项目截图/3.png)

![推子扩展布局示意（最多 15 标签 150 推子，可浮窗）](项目截图/4.png)

## 工具一：控制台 Art-Net 控制台

主界面顶部两个标签页：**全局测试**（v0.1 原功能）与 **推子控台**（v0.2 新增）。

### 标签一：全局测试

向指定目标持续发送 ArtDmx 数据包，用于测试监视器 / 灯具，无需真实控台。

- **4 种数据模式**：正弦波 / 移动光带 / 随机闪烁 / 静态填充

- **Universe**（0-32767）、**动画速度**、**刷新率**（1-60 FPS）实时可调，改动立即生效

- **发送目标**：默认广播 `255.255.255.255`（同一局域网所有监听者都能收到），也可指定单播 IP

- **波形预览**：实时显示正在发送的 512 通道数据

- 状态栏显示已发包数 / 包速率

### 标签二：推子控台 1..15（v0.2 新增）

10 个竖向音量条推子（fade 蓝色填充、刻度 0-255），每个推子独立配置输出并实时发送。**可创建最多 15 个推子控台**（推子控台1 默认存在，标签右侧 `+` 按钮逐个新增），每个控台完全独立：自己的 10 个推子、发送目标/端口/FPS、发送开关与推子值。

- **推子外观**：自绘竖推子——在组内居中，轨道细槽，值 0 时无色；向上推时蓝色渐变填充从底部生长到手柄；右侧刻度 `255 / 128 / 0`（层级在推子之后，被遮挡无妨）；**60×30 手柄**整块可点按/拖动，支持点按轨道跳值与滚轮微调（Ctrl+滚轮步进 5）

- **推子分组**：每组推子以圆角深色**方框**分隔，边界清晰

- **推子布局**：每控台 10 个竖推子，推子下方各带「设置」与「启用/禁用」状态按钮（文字"启用"= 绿色、文字"禁用"= 红色，点击切换）；地址行 S/U/CH 文字为绿色

- **默认参数跨控台连续**：推子控台 N 的推子默认名称 = `推子{(N-1)×10+1} … 推子{N×10}`（控台1: 推子1-10 / 控台2: 推子11-20 / …），Channel 同号对齐

- **归零 / 全推**：控台顶部「全推」（天蓝）一键全部推子到 255、「归零」（淡紫）一键全部归 0（启用/禁用状态不变）

- **恢复默认设置**：控台顶部「恢复默认设置」按钮（浮窗左侧）——弹窗询问"确定恢复当前页到默认出厂设置吗？"，确认后只恢复本控台全部参数（发送设置 + 推子名/通道/值）

- **浮窗**：每个推子控台顶部有「浮窗」（金色）按钮——当前推子控台 N 的 UI 以独立子窗口打开；关闭子窗口后自动回到原标签页（编号位置不变）；**主窗口关闭时所有浮窗一起关闭**

- **开始发送 / 停止 状态色**：空闲时「开始发送」默认色、「停止」禁用并**红色常显**；发送中「开始发送」禁用变绿、「停止」可用恢复默认色；停止后回到空闲样式（推子控台与全局测试均适用；三态 padding 一致不跳动）

- **关闭标签**：标签页右侧 `-` 按钮关闭当前选中的推子控台标签（该控台线程停止、配置移除）；「全局测试」与「推子控台1」不可关闭；新增时自动补 1~15 中最小空缺编号

- **设置小窗**：点击「设置」弹出，可配置：

  - **Subnet**（0-15）、**Universe**（0-15）：组合成端口地址（Net=0），允许 10 个推子分散到不同 universe

  - **Channel**（1-512）：每个推子输出**单个 DMX 通道**（8bit，0-255）

  - **自定义名称**（默认"推子 N"，显示在推子顶部）

- **启用/禁用**：禁用推子不输出（该通道按 0 处理），滑块置灰

- **共享输出总线（多控台同端口不打架）**：所有推子控台把各自推子写入全局输出总线（按端口地址分组），发送的是**合并整帧**——控台1 控制 S0U0 CH1-10、控台2 控制 S0U0 CH11-20 同时发送时，接收端每一帧都同时包含两边的值，**互不清零**；推子禁用或控台被关闭时只把自己负责的通道归 0

- 每推子显示：名称 / 当前值（0-255）/ 地址行（S·U · CH 范围）

- **发送目标 / 端口 / 刷新率**：全局测试与推子控台**各有独立**的广播 / 指定 IP 目标、UDP 端口（1-65535，默认 6454）、刷新率（1-60 FPS），各自开始 / 停止互不干扰

- 状态行显示发送目标:端口、FPS、启用推子数、实时包速率

- **自动保存**：所有可变更项目（窗口几何、两个标签页全部设置、10 个推子的名称/启用/地址/值）自动保存到主程序同目录 **`table.yml`**（YAML 兼容格式）：启动时读取恢复，无文件自动创建；变更后防抖 500ms 写入，关闭时立即写入；若创建/写入失败（如目录无写权限）弹窗提示"以管理员身份运行"

## 工具二：通道监视器 Art-Net 通道监视器

解析 ArtDmx（OpCode 0x5000），自动忽略其他 Art-Net 包。

- **监听设置**（左侧面板，**改动后自动生效，无需「应用监听」按钮**）：

  - **IP**：`0.0.0.0 (全部内网)` 监听所有网卡，或选择本机网卡 IP / 手动输入指定 IP（改动或输入完成即自动重启监听）

  - **端口**：`全部端口`（默认，raw 模式捕获所有 UDP 端口；无管理员权限时自动回退 6454）或 `指定端口`（默认 6454）——切换即生效

  - 重启监听会清空已收数据（界面同步重置）

- **左右分栏可拖拽**：左侧面板与右侧内容区之间的分隔条可用鼠标拖动调整宽度（位置自动保存）

- **监视全部 universe**（0-32767）：左侧列表实时列出有数据的 universe，也可手动指定任意 universe

- **表格 + 波形图**展示 512 通道数值；表格为 **104 行 × 10 列网格**，每通道占两行（上行通道号、下行数值），每个通道带绿色线框；**通道号文字黄色（11pt 加粗）**；已关闭默认网格线——通道号行与数值行之间无淡横线，上下两格拼成一个完整格子

- **数值格 = 天蓝色能量条**：数值行不再按 0-255 色阶变色——统一深灰底，格内**天蓝色横向能量条**（整格高、从左到右按 值/255 比例延伸，0 值无条），白色数值文字叠在条上

- 超过 2 秒未收到数据判定为 "无信号"，通道按 0 显示

- **来源显示 IP:端口**：信息栏中数据来源以 `ip:port` 形式展示

- **暂停 / 开始**：冻结当前画面便于查看，后台接收继续运行

- **清空按钮**：一键清除全部已收 Universe 数据（列表、表格、波形、统计全部归零）

- **Subnet 显示**：按 Art-Net 规范把端口地址分解为 Net / Subnet / Universe

- **自动保存 view.yml**：窗口几何、左右/上下分栏宽度、监听设置（IP/端口模式/端口）、监视 Universe 输入值自动保存到主程序同目录（无累计包数统计；界面只显示实时包速率）

## 通用特性

- **单实例**：两个工具各自只允许启动一个实例，重复启动会提示"已在运行"

- **应用图标**：`ui/logo.ico` 同时用于 exe 文件图标与运行时窗口/任务栏图标

- **右下角品牌**：状态栏右下角 `Ahsinsoft` 可点击跳转 Gitee

## 快速体验

同时打开两个程序即可看到效果：

```
"Art-Net 控制台.exe"       # 选好模式点「开始发送」
"Art-Net 通道监视器.exe"   # 左侧列表出现数据，点选对应 universe 查看
```

## 技术栈

- Python 3.11+ + PySide6 (Qt6)

- PyInstaller 打包为单文件 exe（各约 45MB，PySide6 体积较大属正常）

## 目录结构

```
Art-Net 控制台.py        控制台源码（单文件）
Art-Net 通道监视器.py    通道监视器源码（单文件）
Art-Net 控制台.spec      PyInstaller 构建配置
Art-Net 通道监视器.spec  PyInstaller 构建配置
ui/logo.ico              应用图标（exe / 窗口）
ui/logo.png              图标源图（PNG）
项目截图/                界面截图（README 展示用）
README.md                本文档（含交接说明）
dist/                    exe 打包产物（发布时同步到 Release）
```

## 源码运行

```
pip install PySide6
python "Art-Net 控制台.py"        # 控制台
python "Art-Net 通道监视器.py"    # 通道监视器
```

## 重新打包 exe

```
pip install pyinstaller
pyinstaller --noconfirm "Art-Net 控制台.spec"
pyinstaller --noconfirm "Art-Net 通道监视器.spec"
```

产物在 `dist\Art-Net 控制台.exe` 与 `dist\Art-Net 通道监视器.exe`。

## 网络 / 协议要点（维护必读）

- 协议默认端口：UDP 6454；控制台发送 / 监视器普通模式监听均用 6454

- 监视器普通模式：绑定 `0.0.0.0:port`，设置 `SO_REUSEADDR`

- 监视器全部端口模式：raw socket（`SIO_RCVALL`，**需要管理员权限**），接收所有 IP 包后由 `parse_ip_packet` 自行解析 IPv4/UDP 头提取 ArtDmx；非管理员时静默回退默认监听

- Windows 下 `SO_REUSEADDR` 允许多个程序同时绑定 6454；**广播 / 组播数据所有监听者都能收到，单播数据只投递给其中一个 socket**

- 控制台发送整帧 512 通道数据；监视器对长度不足的包，长度之外通道按 0 处理

- 信号超时 2 秒（`STALE_AFTER`）判定为无信号

- 端口地址分解：`decode_port(port) -> (net, subnet, universe4)`，即 Net(7bit) + Subnet(4bit) + Universe(4bit)

- 监视器性能优化要点：颜色 / 字体预计算成查表（`_COLOR_TABLE` / `_FONT`）、数值未变化跳过刷新、`dataChanged` 只通知显示角色避免整表重排、列表文字 2Hz 低频更新

- 控制台参数实时读取（线程每次发包前从 UI 读配置），改参数无需重启

- 单实例：基于 `QSharedMemory` 命名锁，进程退出后锁自动释放

## 交接说明（换电脑继续开发）

### 新电脑需要做的事

1. 安装 **Python 3.11+**（python.org 或 `winget install Python.Python.3.11`）

2. 安装 **Git**（`winget install Git.Git`）

3. 克隆本仓库：

   ```
   git clone https://gitee.com/ahsin/ArtNet_toolbox.git
   ```

4. 安装依赖：

   ```
   pip install PySide6 pyinstaller
   ```

5. 运行 / 打包：见上文「使用」章节

### 当前开发状态（换电脑续接点）

- **已完成**：两个工具 v0.1 全部功能 + 打包（详见「版本历史」），产物在 `dist\` 下

- **遗留问题**：任务栏图标空白（详见「已知问题」排查记录，含已确认的事实与下一步方向）

- **代码同步状态**：本地有大量未提交改动（拆分、更名、图标、单实例、监听设置、网格表格等），**尚未推送 Gitee**（仓库 `ahsin/ArtNet_toolbox`，公开，MIT）。换电脑后克隆仓库后需把本地改动合并/提交；或确认后再统一同步

- **图标文件**：`ui/logo.ico` / `ui/logo.png` 为应用图标源；换电脑排查图标问题时从这两份文件入手

### 本机环境记录（旧开发机）

- Python 3.12.10：`C:\Users\Ahsin\AppData\Local\Programs\Python\Python312`

- MinGit（免安装版）：`%LOCALAPPDATA%\Programs\MinGit`

- Gitee 账号：ahsin（`https://gitee.com/ahsin`）

### 已知问题 / 注意事项

- **任务栏图标空白（未解决，换电脑续查重点）**：

  - 现象：两个 exe 运行后，任务栏按钮图标显示空白

  - 已排查结论：

    1. exe 文件图标正常（`ExtractAssociatedIcon` 可提取 32x32）
    2. 运行时窗口图标句柄有效（Win32 `WM_GETICON` / `GCLP_HICONSM` 均非空）
    3. 打包后 `QIcon` 加载 `ui/logo.ico` 成功（availableSizes = 16/32/48/64/72/80/96/128/256）
    4. `qico.dll` 图像插件已打入 exe；图标文件已随 datas 打包
    5. 代码已同时设置 app 级与窗口级 `setWindowIcon`

  - 可疑点：`ui/logo.ico` 整体为**不透明中灰**（平均 RGB≈119），任务栏小尺寸 / 深色背景下可能极不明显，视觉上像"空白"

  - 下一步排查（换电脑后）：

    1. 用识图工具确认任务栏图标是"纯空白方块"还是"浅灰图案看不清"
    2. 替换高对比图标（深色主体 + 亮色背景或描边），重新打包验证
    3. 检查 ico 编码兼容性（重新导出含 16/32/48/256 尺寸、BMP 编码的 ico）
    4. 排除 Windows 任务栏设置（合并按钮 / 图标大小）与系统图标缓存影响

- 若同时运行多个 Art-Net 监听程序，单播数据可能被其他 socket 接收，监视器只保证收到广播数据

- 全部端口模式需管理员权限（无权限时自动回退 6454）

- 控制台选择广播目标时，若本机防火墙拦截 UDP 6454 出站，需要放行

- 依赖仅 PySide6（运行时）+ pyinstaller（仅打包时需要）

### 后续可扩展方向

- 接收器：波形缩放 / 暂停后曲线保持、数据记录到文件 / 日志、刷新率可调

- 控制台：多 universe 同时发送、通道数可选（<512）、参数预设保存 / 加载

## 版本历史

### v0.2 (2026-09-03)

- **控制台新增「推子控台」标签页**：主界面顶部改为标签页（全局测试 / 推子控台1，可 + 新增至 15 个）

- 推子控台：10 个竖向音量条推子（自绘 fade 蓝色渐变填充，值 0 无色、刻度 255/128/0 在推子层级之后，支持滚轮微调）

- 每个推子独立设置：**Subnet / Universe**（0-15，组合端口地址 Net=0）、**Channel**（1-512，单通道 8bit 输出）、**自定义名称**；启用/禁用状态按钮（"启用"绿 / "禁用"红）

- 全局测试与推子控台**均新增 UDP 端口设置**（1-65535，默认 6454），发送目标显示带端口

- 推子手柄 **60×30**，每组推子以**圆角方框**分隔；名称默认"推子N"跨控台连续（控台N: 推子(N-1)×10+1 起）

- **配置自动保存 table.yml**：全部可变更项目（窗口几何 / 全局测试 / 各推子控台 1..15 独立分 key / 每控台 10 推子）防抖自动保存到主程序同目录（YAML 兼容格式，无第三方依赖），启动读取、无文件自动创建、写失败弹窗提示以管理员运行；旧版配置结构自动迁移

- **单实例**：控制台只允许运行一个实例（避免多进程争写 table.yml）；需要多组推子时使用程序内多推子控台标签

- 推子控台支持**多标签页（1..15）**（`+` 新增 / `-` 关闭，编号自动补缺）、**浮窗**独立显示（主窗口关闭时一起关闭）；「归零」「全推」；「恢复默认设置」；S/U/CH 地址绿色；任一推子控台开跑自动停止全局测试（全局测试也拒绝在推子运行时启动）

- **多控台同端口不打架**：推子发送走全局共享输出总线，同端口各控台只更新自己的通道，发送合并整帧

- **监视器 v0.2**：去除总包数统计（只显示实时包速率）；新增「清空」按钮；左右分栏可拖拽；监听设置改动自动生效（去掉"应用监听"按钮）；表格通道号黄色、去掉默认网格线（上下两格拼完整格子）；新增 view.yml 自动保存（窗口/分栏/监听设置/监视值）

### v0.1 (2026-09-02)

- 拆分为两个独立工具：**Art-Net 控制台**（原 ArtNetTransmitter）+ **Art-Net 通道监视器**（原 ArtNetMonitor）

- 原 `artnet_monitor.py` 的 `--demo` 演示功能升级为独立控制台工具

- 两个程序主窗口标题均带版本号 `v0.1`（格式：`名字 版本`）；文件名 / exe 名 / 窗口标题统一使用中文名

- 右下角品牌文字 Ahsinsoft（点击跳转 Gitee）；应用图标（exe + 窗口）；单实例限制

- 通道监视器增强：

  - 监听设置：指定 IP / 全部内网、指定端口 / 全部端口（raw，默认全部端口）

  - 来源显示 `IP:端口`；表格改为 104 行 × 10 列网格（每通道两行，绿色线框，通道号字体加大）