> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

<Info>
  可视化显示异常（热力图全黑、错位）请参阅 [Wuji CLI 可视化的故障处理](/docs/wuji-cli/visualization/#处理故障)。SDK 调用相关问题请参阅 [Wuji SDK 故障排查](/docs/wuji-sdk/troubleshooting)。
</Info>

## 无法连接手套

1. 检查物理连接
   * USB-C 线缆是否插紧，正反面标识是否一致
   * 网线连接是否牢固，适配器指示灯是否亮起
   * 电源是否正常供电（手套 LED 是否亮起，并正常转变至呼吸灯状态。必须使用 USB-A to USB-C 线缆，USB-C to USB-C 线缆无法为手套供电）

2. 确认手套 IP
   * 出厂默认 IP：左手 `192.168.1.100`，右手 `192.168.1.101`
   * 若曾通过 Wuji CLI 或 SDK 修改过手套 IP，下文出现的 `192.168.1.100/101` 请替换为实际配置的 IP

3. 检查网络配置
   * 电脑 IP 是否与手套同网段（默认 `192.168.1.x`，已修改 IP 时为实际 IP 所在网段）
   * 子网掩码是否为 255.255.255.0
   * 电脑 IP 是否与手套冲突（避开手套实际占用的 IP）
   * 尝试 `ping <手套 IP>` 验证可达性（出厂默认即 `ping 192.168.1.100` 或 `ping 192.168.1.101`）

## ping 有响应但无法连接手套

ping 有响应不代表客户端（Wuji CLI 或 SDK 脚本）能连接手套。先排除[网络层](#network-layer)干扰，再排查[软件层](#software-layer)。

<a id="network-layer" />

### 网络层：ping 实际未到达手套

多网卡环境下，ping 流量可能被错误路由到其他设备：

* **冒名设备**：另一张网卡所在网段下挂有其他设备，恰好占用了手套 IP 并响应 ping。
* **IP 冲突**：电脑上有两张网卡都被分配到与手套相同的网段。操作系统通常会报冲突，即便不报错，ping 流量也会在两张网卡间随机走，表现为响应时有时无。

而连接手套的网卡若不在手套所在网段，客户端依然无法连接手套。

处理步骤（下文以出厂默认 IP `192.168.1.100` 为例，已修改 IP 请替换为实际手套 IP）：

1. **拔下手套后，重新 ping 手套 IP**：
   * 仍能收到 ping 响应 → 网段下有冒名设备。从这台电脑的网络中断开它（拔线、关闭对端，或从路由表中剔除），使对应网卡不再能访问到它。
   * ping 响应时有时无，或系统提示 IP 冲突 → 多网卡 IP 冲突。仅保留连接手套的那张网卡处于手套所在网段，将其他同网段网卡移出该网段或临时禁用。
2. **重新插上手套再 ping**。若仍无响应，检查手套所连网卡的 IP 是否与手套同网段。不在则将其改为同网段（如手套为默认 `192.168.1.100`，可将网卡设为 `192.168.1.50/24`）。

辅助排查命令（命令中的 `192.168.1.100` 同样以默认 IP 为例，已修改请替换为实际手套 IP）：

```bash theme={null}
ip addr show                # 查看每张网卡的 IP
ip route get 192.168.1.100  # 查看 ping 流量走的是哪张网卡
ip neigh show 192.168.1.100 # 查看响应方的 MAC，与手套实际 MAC 对比
```

<a id="software-layer" />

### 软件层：ping 已到达手套但客户端无法连接

* 确认无其他客户端（Wuji CLI 或 SDK 脚本）同时占用设备连接

* 若 Ubuntu 已启用 ufw，请确认已放行设备所需的 UDP 端口（`50000` 用于设备发现，`50001` 用于数据通信，可在设备配置中修改）：

  ```bash theme={null}
  sudo ufw status
  sudo ufw allow 50000/udp
  sudo ufw allow 50001/udp
  ```

* 尝试重启手套（断电后重新上电）

## 两只同手性手套无法同时连接

同网段接入两只同手性手套时，出厂默认 IP 相同会冲突：

1. 先只接入一只手套
2. 按[设备运维](/docs/wuji-glove/sdk-data-reference/device-operations#参数持久化)修改其中一只的 IP，改址后重启设备
3. 再将两只手套同时组网，连接时用序列号（`sn`）区分，见[设备连接](/docs/wuji-sdk/device-connection/#指定-sn-连接)

## 触觉数据全为 0 或 -1

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

1. 确认已订阅 `tactile` 数据流
2. 运行 `wuji calib tactile` 执行[触觉标定](/docs/wuji-cli/tactile-calibration/)
3. 标定后仍无变化，检查传感器区域是否有物理损坏

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

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

## 触觉数据闪烁或跳变

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

## EMF 定位不准或漂移

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

## EMF 置信度始终很低

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

## IMU 朝向数据漂移

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

## 获取技术支持

请联系 [support@wuji.tech](mailto:support@wuji.tech)，并附上以下信息：

* 手套序列号（SN）
* 固件版本
* SDK 与 CLI 版本
* 操作系统和版本
* 问题复现步骤


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.