tarpediem/zenvision-linux

来源：https://github.com/tarpediem/zenvision-linux

zenvision-linux

🟢 首个 ASUS ZenVision 盖板 OLED 开源 Linux 驱动 —— 协议通过对 MyASUS 进行逆向工程（使用 Ghidra）从零解析而来。想要在此基础上添加实时小部件和音频可视化效果？请参阅配套应用 zenvision-studio (https://github.com/tarpediem/zenvision-studio)。

适用于 ASUS ZenVision 盖板 OLED 的用户空间 Linux 驱动 —— 该屏幕为嵌入在 ASUS Zenbook 14X OLED Space Edition（UX5401ZAS） 盖板中的 3.5 英寸、256×64 单色显示屏。

ASUS 仅在 Windows 平台（通过 MyASUS）提供该屏幕的驱动软件。本项目对 USB 协议进行逆向工程，让您能够在 Linux 下驱动该面板：显示图片、播放动画，或展示任何您想要的内容。

状态：可正常使用（已在 UX5401ZAS 上验证）。其他 ASUS 盖板 OLED 机型可能使用类似的协议 —— 欢迎反馈问题或提交 PR。

demo

工作原理

盖板屏幕是一个 Nuvoton M480 USB 设备（0b05:8835）。它不是 DRM 显示设备 —— 您不会获得 /dev/fb；而是在完成一小段命令握手之后，通过 bulk 端点推送 256×64、4 位灰度帧缓冲区。完整细节请参阅 PROTOCOL.md。

环境要求

• Python 3.9+
• pyusb (https://pypi.org/project/pyusb/) 和 Pillow (https://pypi.org/project/Pillow/)
• libusb-1.0
• 原始 USB 访问权限（root 权限，或使用提供的 udev 规则）

bash python -m venv .venv && . .venv/bin/activate pip install pyusb pillow

Arch Linux（AUR）

bash yay -S zenvision-linux-git # 安装 `zenvision` CLI 及 udev 规则

使用方法

``bash

静态图片（自动缩放至 256x64，转换为灰度图）

sudo ./zenvision.py image picture.png

白色测试图案 / 清屏

sudo ./zenvision.py image –white sudo ./zenvision.py off

将一个文件夹中的帧作为流畅动画播放

sudo ./zenvision.py anim frames/ –fps 20 ``

亮度调节：--bright 0xff（刻度为近似值，建议根据视觉效果调整）。

生成演示动画

examples/spark_demo.py 会渲染一个通用的旋转星爆动画，输出到 frames/ 文件夹，然后可传入 anim 命令播放：

bash pip install pillow python examples/spark_demo.py --out frames --w 256 --h 64 sudo ./zenvision.py anim frames/ --fps 20

想显示 Logo？将任意单色 256×64 帧渲染到一个文件夹，然后用 anim 指向该文件夹即可。（小技巧：用 rsvg-convert 转换 SVG，或用 ffmpeg -i clip.gif frames/%03d.png 提取 GIF 帧。）

免 root 运行（udev）

复制规则文件，使您的用户能够访问该设备：

bash sudo cp udev/70-zenvision.rules /etc/udev/rules.d/ sudo udevadm control --reload-rules && sudo udevadm trigger

70- 前缀很重要：该规则必须排在 73-seat-late.rules 之前，以确保 uaccess 标签被正确应用 —— 否则 ACL 权限将永远无法生效。uaccess 会向已登录用户授予访问权限（这是 systemd 下的正确机制，无需添加 plugdev 组）。之后即可不使用 sudo 直接运行。

注意事项与安全说明

• 面板由固件驱动，重新插拔后仍可正常工作；实验过程中如出现问题，重启即可恢复。在 HID 接口上发送格式错误的控制报告可能导致 MCU 软复位（它会重新枚举并恢复正常）—— 本驱动仅使用 vendor 接口。
• 本项目是独立的非官方项目，与 ASUS 无任何关联，亦未获得其授权。
• 本项目不包含、也不需要任何 ASUS 固件、二进制文件或反编译代码。

贡献指南

如果您拥有其他带盖板 OLED 的 ASUS 机型，欢迎提交 issue，并附上：lsusb 输出、您的机型编号，以及此处的协议帧格式是否适用。协议文档的编写旨在使移植工作尽量简便。

许可证

MIT。