> ## 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.

# 设备参数与操作

## handedness（GET）

获取**左右手识别**结果（left / right）。

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    side = hand.handedness().get()   # → "left" 或 "right"
    ```
  </Tab>

  <Tab title="C">
    ```c theme={null}
    WujiHandedness side;
    wuji_hand_2_get_handedness(dev, &side);
    ```
  </Tab>
</Tabs>

## ip（SET/GET）

**读写设备静态 IP 地址**。`set` 把新 IP 写入设备 flash，固件不会热切换正在运行的以太网栈，新 IP 下次重启才生效。`set` 之后、重启之前，`get` 仍返回当前生效的 IP。

```python theme={null}
hand.ip().get()                    # 读当前 IP，如 "192.168.1.110"
hand.ip().set("192.168.1.201")     # 写入 flash，重启后生效
```

IP 在同网段内必须唯一，避开其他设备与电脑网卡。

修改 IP 分四步：`set` 写入新地址、`reboot` 重启设备、按新 IP 重连、`get` 确认。

```python theme={null}
hand.ip().set("192.168.1.201")
hand.reboot()
manager.disconnect_all()
# 等设备重启且以太网就绪，约 8 秒
hand = manager.connect(address="192.168.1.201:50001", device_name="wuji_hand_2")
hand.ip().get()                    # → "192.168.1.201"
```

<Warning>
  新 IP 重启后才生效。`set` 只写入 flash，不改变正在运行的连接。重启前 `get` 返回的仍是当前 IP。
</Warning>

## port（SET/GET）

**读写设备数据端口**，即灵巧手接受 SDK 连接的 UDP 端口，出厂默认 `50001`。修改端口需要较新的固件与 Wuji SDK，先将两者升级到最新版本。固件 v2.10.0 之前的版本只能读取，写入会报错。

`set` 保存新端口，设备重启后改用新端口，断电后仍保留。与 `ip` 不同，`set` 成功后 `get` 立即返回新端口，即设备下次重启后使用的端口。

```python theme={null}
hand.port().get()                  # 读端口，如 50001
hand.port().set(50002)             # 保存新端口，重启后生效
```

可设范围为 10000–65535，发现端口 `50000` 除外。超出范围或设为 `50000` 时，`set` 抛 `WujiException`（消息含 `Invalid argument`），端口保持原值。设备正在升级固件时写入同样失败，升级结束后重试即可。

修改端口的步骤：

1. 调用 `hand.port().set()` 写入新端口。
2. 调用 `hand.reboot()` 重启设备。
3. 按新端口重新连接设备。
4. 调用 `hand.port().get()` 确认端口。

通过 `auto_connect`、`sn` 或 `handedness` 连接时，SDK 从设备发现结果中获取新端口，连接代码无需改动。按地址连接时，将地址中的端口改为新端口，示例：

```python theme={null}
hand.port().set(50002)
hand.reboot()
manager.disconnect_all()
# 等设备重启且以太网就绪，约 8 秒
hand = manager.connect(address="192.168.1.111:50002", device_name="wuji_hand_2")
hand.port().get()                  # → 50002
```

<Warning>
  新端口重启后才生效，重启前设备仍在原端口上通信。电脑启用防火墙时，重启前先放行新端口的 UDP 流量。
</Warning>

## reboot（EXEC）

**重启设备**。设备会断连，重启后需重新连接。常与 `ip().set()`、`port().set()` 搭配，让新保存的 IP 或端口生效。

```python theme={null}
hand.reboot()
```

## 使能 / 失能 / 急停

```python theme={null}
hand.enable()               # 使能全部关节
hand.disable()              # 失能全部关节
hand.enable(joints=mask)    # 可选：长度 20 的 0/1 掩码，作用于掩码位为 1 的关节
hand.emergency_stop()       # 急停：整手动作，不接受掩码
```

## clear\_fault（EXEC）

**清除故障**：直接动作，无参数时作用于整手。

```python theme={null}
hand.clear_fault()                  # 清除全部关节故障
hand.clear_fault(joints=mask)       # 可选：长度 20 的 0/1 掩码，只清除掩码位为 1 的关节
```

C 侧接口与本页 Python 接口语义一致，函数前缀 `wuji_hand_2_`。初始化约定、内存管理、错误码与工程构建见 [C 接口参考](/docs/wuji-sdk/data-reference/)。

## 控制动作（含 20 关节掩码）

`enable / disable / clear_fault / set_origin / clear_origin` 接受可选掩码 `const uint8_t mask[20]`，传 `NULL` 表示对全部关节触发。`emergency_stop` 仅作用于整手、不接受掩码：

```c theme={null}
// 整手使能
wuji_hand_2_enable(dev, NULL);
// 整手清错
wuji_hand_2_clear_fault(dev, NULL);

// 仅食指 4 关节（flat 索引 4..7）
uint8_t mask[20] = {0};
for (int i = 4; i < 8; i++) mask[i] = 1;
wuji_hand_2_enable(dev, mask);            // 仅使能食指 4 关节
wuji_hand_2_clear_fault(dev, mask);       // 仅清食指 4 关节的故障

// 整手紧急停止
wuji_hand_2_emergency_stop(dev);

// 用户零点
wuji_hand_2_set_origin(dev, NULL);
wuji_hand_2_clear_origin(dev, NULL);
```

## 数据端口

`wuji_hand_2_get_port` 读取数据端口（设备接受 SDK 连接的 UDP 端口，出厂默认 `50001`），`wuji_hand_2_set_port` 保存新端口。修改端口需要较新的 Wuji Hand 2 固件与 Wuji SDK，先将两者升级到最新版本。

```c theme={null}
uint16_t port = 0;
wuji_hand_2_get_port(dev, &port);          // 如 50001

if (wuji_hand_2_set_port(dev, 50002) != WUJI_STATUS_OK) {
    fprintf(stderr, "set port failed: %s\n", wuji_last_error());
} else {
    wuji_hand_2_reboot(dev);               // 重启后改用新端口
}
```

新端口在设备重启后生效，断电后仍保留。`wuji_hand_2_set_port` 成功后，`wuji_hand_2_get_port` 立即返回新端口。可设范围为 10000–65535，发现端口 `50000` 除外。超出范围时 `wuji_hand_2_set_port` 返回非 `WUJI_STATUS_OK` 状态，`wuji_last_error()` 含 `Invalid argument`，端口保持原值。固件 v2.10.0 之前的版本不接受写入，同样返回错误状态。重启后按地址连接时改用新端口，通过设备发现连接则无需改动。

## 身份与诊断

```c theme={null}
WujiHandedness side;
wuji_hand_2_get_handedness(dev, &side);   // WUJI_HANDEDNESS_LEFT / _RIGHT

uint8_t n_online;
wuji_hand_2_online_joints_count(dev, &n_online);  // 0..20

// 字符串两步查询：先用 buf=NULL,buf_len=0 探出所需长度
size_t needed = 0;
wuji_hand_2_get_ip(dev, NULL, 0, &needed);
char* ip = malloc(needed);
wuji_hand_2_get_ip(dev, ip, needed, NULL);
printf("ip=%s\n", ip);
free(ip);
```

写入 IP 用 `wuji_hand_2_set_ip(dev, "192.168.1.201")`，重启设备用 `wuji_hand_2_reboot(dev)`，生效时机与 Python 一致。

`get_hw_version` / `get_comm_diag` 返回的 `out` 持有堆字段，使用后需调对应 `_free` 释放（仅在返回 `WUJI_STATUS_OK` 时）。


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