故障排查

无法启动 / 白屏或崩溃

1. 确认操作系统版本满足要求（Ubuntu 22+）
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）

触觉数据全为 0 或 -1

数值为 -1 表示无效点，属于正常现象。若按压传感器表面后数值仍全为 0：

1. 确认已订阅 tactile 数据流
2. 尝试执行校准
3. 校准后仍无变化，检查传感器区域是否有物理损坏

触觉数据不准确或数值异常

• 穿戴前确保手套传感器区域平整，无折叠
• 保持手指微弯，在自然放松状态下连接设备
• 检查是否已执行校准流程
• 数据中出现 -1 表示无效点，属于正常现象

触觉数据闪烁或跳变

• 检查手套是否穿戴过松，传感器与皮肤接触不稳定
• 避免在传感器区域施加过大压力导致饱和
• 确认手套布线未受损

触觉矩阵热力图显示全黑

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

EMF 定位不准或漂移

1. 查看 confidence 值，低于 0.8 说明环境干扰严重
2. 远离金属物体和电子设备
3. 减小手与发射线圈的距离（建议 30 cm 以内）
4. 确保发射线圈与手之间无大面积金属遮挡
5. 执行 EMF 校准流程

EMF 置信度始终很低

• 检查手与发射线圈的距离是否过远（建议 30 cm 以内）
• 确认发射线圈电源正常
• 检查接收线圈是否有物理损坏

IMU 朝向数据漂移

• IMU 需要短暂的初始化稳定时间（约 2-3 秒）
• 避免在强磁场环境下使用（如大型电机附近）
• 确保手套穿戴稳固，避免松动导致的相对运动

固件升级失败

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

升级过程中遇到错误提示

使用本地固件升级

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

获取技术支持

请联系 support@wuji.tech，并附上以下信息：

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