故障排查

​

无法启动 / 白屏或崩溃

1. 确认操作系统版本满足要求（Ubuntu 22.04 LTS 及以上版本）
2. 更新 GPU 驱动到最新版本
3. 安装 WebKitGTK：
   sudo apt install libwebkit2gtk-4.1-0
   
4. 删除应用数据目录后重试：
   # 先备份
   cp -r ~/.wuji/studio/data ~/.wuji/studio/data.backup.$(date +%Y%m%d%H%M%S)
   rm -rf ~/.wuji/studio/data
   
5. 仍无法启动时，检查系统代理。代理拦截 WebView 本地资源加载会导致白屏，临时清除代理环境变量后启动：
   env -u http_proxy -u https_proxy -u all_proxy -u ftp_proxy -u no_proxy \
       -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY -u FTP_PROXY -u NO_PROXY \
       GSETTINGS_BACKEND=memory \
       wuji-studio
   

​

面板显示空白

• 确认已连接设备并进入可视化视图
• 检查面板是否订阅了正确的 Topic
• 尝试重置面板布局（右键点击预设标签 → Reset to Default）

​

恢复默认布局

当布局调整后，右键点击顶部预设栏的当前预设标签（下图中的 Tactile Monitor），选择 Reset to Default 即可恢复默认布局。更多预设操作见布局预设。

​

触觉矩阵热力图显示全黑

• 确认已订阅正确的 Topic（tactile 或 tactile_zones）
• 检查 Matrix 面板的数据范围设置是否正确（默认 0.0~1.0）
• 轻按手套表面，观察是否有数据变化

​

触觉矩阵热力图错位或呈斜切状

• 检查 Matrix 面板设置中的 Columns 是否为 31：触觉矩阵为 24×31，列数与布局不一致时每行错开一格，热力图整体呈斜切状
• 在 Sidebar 的 Panel 设置中把 Columns 改回 31，或右键预设标签选择 Reset to Default 恢复默认布局

​

固件升级失败

1. 确认电源稳定，升级期间不要断电
2. 确认网络连接稳定，使用有线连接
3. 手套内置回退机制，升级失败会自动恢复上一版本
4. 等待手套 LED 指示完成回退后重试

​

升级过程中遇到错误提示

​

使用本地固件升级

在第 2 步选择固件时，点击 Upload local file 按钮选择固件文件（.zip 格式）。上传后会自动解析并显示固件的版本号、发布日期和发布说明。

​

获取技术支持

请联系 [email protected]，并附上以下信息：

• 设备序列号（SN）
• 固件版本
• Wuji SDK / Wuji Studio 版本
• 操作系统和版本
• 问题复现步骤