Upgrader 使用说明

1. 软件安装

1. 确认系统满足以下要求：

   项目	要求
   架构	x86_64 (AMD64)
   操作系统	Ubuntu 22.04 LTS / Ubuntu 24.04 LTS
   内存	至少 4GB RAM
   存储空间	至少 2GB 可用空间
   权限	需要串口访问权限
   网络	良好的网络连接

2. 进入 GitHub Releases 下载安装包

3. 进入安装包所在目录，安装软件包

   # 将 <package-name> 替换为实际下载的软件包名称
   sudo apt install ./<package-name>.deb

   安装完成后，系统自动完成以下配置，无需手动设置：

   • 配置串口访问权限
   • 将当前用户加入所需用户组
   • 配置硬件访问权限

2. 连接设备

2.1 启动软件

启动软件前，请先确认灵巧手处于断电状态。

方式一：在应用程序菜单中搜索 wujihand-upgrader，点击图标启动

方式二：在终端运行命令

wujihand-upgrader

启动后主界面如下：

2.2 硬件连接

保持灵巧手断电，使用包装中的 USB A to USB C 线束将灵巧手连接到计算机，然后给灵巧手上电。

2.3 自动连接

灵巧手上电后，软件会自动开始扫描设备，并连接到 Bootloader，等待连接建立。

2.4 设备信息显示

连接成功后，界面显示以下设备信息：

• 串口：设备连接的串口路径（如 /dev/ttyUSB*）
• 系统版本：当前设备的系统版本
• 节点状态：在线节点数/总节点数（悬停在信息图标上可查看详细的节点版本信息）
• 状态：设备当前状态（如就绪）

确认设备信息显示正常后，即可继续执行固件升级。

3. 固件升级

3.1 一键升级（推荐）

1. 在设备信息页面，点击一键升级，进入升级确认界面。

2. 确认设备信息和目标版本无误后，点击开始升级。

3. 软件自动执行以下操作，等待升级完成：

   • 下载最新固件
   • 验证固件完整性
   • 执行烧录操作

4. 升级完成后，界面跳转到升级完成页面。参考 3.3 升级完成 完成收尾操作。

3.2 手动选择固件

需要特定版本或本地固件时，使用手动选择模式。在连接设备页面的一键升级下方，点击或手动选择版本，进入固件选择界面。

• 左侧显示固件详情和发布说明
• 右侧上方显示可用固件版本卡片
• 右侧下方显示上传本地固件

3.2.1 选择在线固件

1. 在可用固件版本区域选择需要的固件版本。
2. 点击版本卡片选中。
3. 点击安装固件开始升级。

3.2.2 选择本地固件

1. 点击上传本地固件。
2. 选择本地固件压缩包文件（.zip 格式）。
3. 等待文件解压和验证完成。
4. 点击安装固件开始升级。

点击安装固件后，等待烧录完成，参考 3.3 升级完成 完成收尾操作。

3.3 升级完成

升级流程结束后，软件跳转到更新完成页面，提示固件版本验证通过。

页面显示：

• 后续步骤：关闭本程序、将设备重新上电
• 版本对比：当前版本 与 目标版本，并标识版本一致

按以下步骤完成升级收尾：

1. 点击关闭程序退出 Upgrader，或点击返回首页继续升级其他设备。
2. 给灵巧手断电后重新上电，使设备退出 Bootloader 模式，恢复正常工作状态。

4. 故障排除

4.1 安装依赖问题

安装 deb 包时出现依赖问题，执行以下命令修复：

sudo apt-get install -f

4.2 串口权限问题

启动时提示串口权限不足，使用以下方式解决：

sudo wujihand-upgrader

或将当前用户加入 dialout 组（推荐，无需每次 sudo）：

sudo usermod -a -G dialout $USER
newgrp dialout
wujihand-upgrader

4.3 升级工具窗口不显示

如果安装完成后点击桌面图标，任务栏中出现了升级工具图标，但主窗口始终没有显示，可先在终端中启动程序进行排查。

若终端中出现 Failed to create GBM buffer of size 1280x720: Permission denied（GBM 缓冲区错误），通常说明 NVIDIA 驱动未启用 DRM 内核模式设置（Kernel Mode Setting）。相关背景可参考 dioxus#1909。

可按以下步骤处理：

1. 检查是否已启用 modesetting：

   cat /sys/module/nvidia_drm/parameters/modeset

2. 如果输出为 N，执行以下命令启用：

   echo options nvidia_drm modeset=1 | sudo tee /etc/modprobe.d/nvidia_drm.conf

3. 重启计算机后，再次启动升级工具。

5. 卸载软件

如需卸载 Wuji Hand Upgrader，执行以下命令：

sudo apt remove wujihand-upgrader