vgnhub — VGN/VXE weisheng 键盘 Linux 控制

在 Linux 上直接控制 VGN/VXE 键盘(有线 + 2.4G 无线),不依赖官方 Hub。 协议逆向自 VGN Hub Web 版前端源码,详见 PROTOCOL.md。

免责声明 (Disclaimer)

本项目全部代码由 AI "vibe coding" 生成,未经人工代码审查、未经专业测试,不保证正确性。 代码可能包含缺陷、边界情况处理不当或潜在风险,仅供个人学习与互操作使用。 使用本项目(改灯、改键、改配置、恢复出厂等)所造成的一切后果由使用者自行承担, 包括但不限于设备异常、配置丢失或硬件损坏。作者不承担任何责任。 本项目与 VGN/VXE 及其官方软件无任何关联。

支持机型 (weisheng 协议族, 自动识别)

机型	键位矩阵	自定义灯效格式
VXE V87 / V87 RGB	lO_vxe_v87.json	16色调色板+半字节压缩
VGN S99	sO_s99.json	RGB 三元组
VGN V98pro / V2	rO_v98pro.json / aO_v98pro_v2.json	RGB
VGN N75 PRO	fO_n75pro.json	RGB
VGN VXE75 / V2	uO_vxe75.json / dO_vxe75_v2.json	RGB (V2 带布局重映射)
VGN S87	cO_s87.json	RGB

安装

sudo ./scripts/install_udev.sh     # 免 root 访问 hidraw, 装完重插拔设备
# 可选: pip install .              # 安装后可用 `vgnctl` 命令

使用

./vgnctl.py info                      # 机型/连接/电量/版本/灯效
./vgnctl.py battery
./vgnctl.py light set steady FF0000   # 红色常亮
./vgnctl.py light set breath 00FF00   # 绿色呼吸
./vgnctl.py light custom-set 255 0 0 64    # Enter 红色 (V87 自动用调色板格式)
./vgnctl.py light color FF0000
./vgnctl.py keys dump
./vgnctl.py keys set 0 32 0 41        # 重映射 index 0 为默认 ESC
./vgnctl.py factory-reset

项目结构

vgn-hub/
├── pyproject.toml          # 打包配置 (console_script: vgnctl)
├── opencode.json           # opencode 配置 (注册根目录 SKILL.md)
├── SKILL.md                # AI agent skill: 键盘操作指引
├── LICENSE                 # MIT
├── vgnctl.py               # CLI 兼容入口 (未安装时直接运行)
├── vgnhub/                 # Python 包
│   ├── constants.py        # 协议常量 (命令字/字段偏移)
│   ├── transport.py        # hidraw 发现与底层传输 (非阻塞+超时)
│   ├── models.py           # 机型检测/矩阵加载/VXE75V2 重映射
│   ├── v87light.py         # V87 调色板+半字节灯效布局
│   ├── device.py           # VGNKeyboard 高层 API
│   ├── cli.py              # argparse 命令行
│   └── data/               # 各机型键位/Fn 矩阵 (逆向导出)
├── tests/                  # unittest 测试 (零依赖)
│   ├── mock_dongle.py      # 仿真 dongle (无硬件可测)
│   ├── test_models.py
│   ├── test_v87light.py
│   ├── test_device.py      # 协议/设备逻辑 (仿真)
│   └── test_hardware.py    # 真机测试 (无设备自动跳过)
├── scripts/install_udev.sh
└── 99-vgn-hub.rules

测试

python3 -m unittest discover -s tests -t .      # 全部 (含真机, 无设备则跳过硬件项)
python3 -m unittest tests.test_device -v        # 仅仿真测试 (不碰硬件)
python3 -m unittest tests.test_hardware -v      # 仅真机

自定义脚本

from vgnhub import VGNKeyboard

with VGNKeyboard() as k:
    print(k.model, k.dongle)          # 自动识别机型
    print(k.get_battery())            # (电量, 是否充电)
    k.set_key_color(64, (255, 0, 0))  # Enter 红 (自动按机型格式)

注意

• 写回报率/OS模式可能触发设备短暂 USB 重连,库已做非阻塞超时与重连。
• 键值格式 [b0,b1,b2]: 普通键 [32,0,HID码], 修饰键 [32,掩码,0], Fn [160,1,0]。
• HID 键码表: https://usb.org/sites/default/files/hut1_22.pdf
• 灯效模式: off(20) 时即使开关开着灯也不亮。