Device Parameters and Operations

SDK Reference

Device Information

In Python, connect() and auto_connect() return a WujiHand2 instance when connecting to a Wuji Hand 2.

Hardware Version

version = hand.hw_version().get()
print(f"{version.major}.{version.minor}.{version.patch}")

Returns HwVersion(major, minor, patch) for the device’s factory hardware version. 0.0.0 means no factory hardware version is recorded.

handedness (GET)

Get the handedness result (left / right).

• Python

• C

side = hand.handedness().get() # → "left" or "right"

WujiHandedness side;
wuji_hand_2_get_handedness(dev, &side);

ip (SET/GET)

Read and write the device’s static IP address. set writes the new IP to the device’s flash. The firmware doesn’t hot-swap the running Ethernet stack, so the new IP takes effect only after the next reboot. Between set and reboot, get still returns the current IP.

hand.ip().get() # read the current IP, e.g. "192.168.1.110"
hand.ip().set("192.168.1.201") # write to flash, takes effect after reboot

The IP must be unique on the subnet. Avoid addresses already used by other devices or the host network adapter.

Changing the IP takes four steps: set the new address, reboot the device, reconnect at the new IP, and get to confirm.

hand.ip().set("192.168.1.201")
hand.reboot()
manager.disconnect_all()
# wait for the device to reboot and Ethernet to come up, about 8 seconds
hand = manager.connect(address="192.168.1.201:50001", device_name="wuji_hand_2")
hand.ip().get() # → "192.168.1.201"

port (SET/GET)

Read and write the device’s data port, the UDP port the hand accepts SDK connections on. The factory default is 50001. Changing the port requires recent firmware and Wuji SDK. Upgrade both to the latest version first. Firmware earlier than v2.10.0 allows reads only and rejects writes with an error.

set saves the new port, and the device switches to that port after the next reboot. The saved port persists across power loss. Unlike ip, get returns the new port as soon as set succeeds, which is the port the device uses after its next reboot.

hand.port().get() # read the port, e.g. 50001
hand.port().set(50002) # save the new port, takes effect after reboot

Valid ports are 10000–65535, except the discovery port 50000. A port outside that range, or 50000, makes set raise WujiException (the message contains Invalid argument), and the port keeps its current value. Writes also fail while the device is upgrading firmware. Retry after the upgrade finishes.

To change the port:

1. Call hand.port().set() to write the new port.
2. Call hand.reboot() to restart the device.
3. Reconnect to the device on the new port.
4. Call hand.port().get() to confirm the port.

Connections made through auto_connect, sn, or handedness pick up the new port from device discovery, so the connection code stays the same. For connections by address, change the port in the address. Example:

hand.port().set(50002)
hand.reboot()
manager.disconnect_all()
# wait for the device to reboot and Ethernet to come up, about 8 seconds
hand = manager.connect(address="192.168.1.111:50002", device_name="wuji_hand_2")
hand.port().get() # → 50002

reboot (EXEC)

Reboot the device. The device disconnects and needs a fresh connection. Pair it with ip().set() or port().set() to apply a newly saved IP or port.

hand.reboot()

Enable / Disable / Emergency Stop

hand.enable() # enable all joints
hand.disable() # disable all joints
hand.enable(joints=mask) # optional: 0/1 mask of length 20 — acts on joints with a 1
hand.emergency_stop() # emergency stop: whole-hand action, no mask

clear_fault (EXEC)

Clear faults: a direct action. Without arguments it acts on the whole hand.

hand.clear_fault() # clear faults on all joints
hand.clear_fault(joints=mask) # optional: 0/1 mask of length 20 — only joints with a 1 are cleared

The C API matches the Python API on this page and uses the wuji_hand_2_ prefix. For initialization conventions, memory management, error codes, and build setup, see the C API Reference.

Control Actions (With 20-Joint Mask)

enable / disable / clear_fault / set_origin / clear_origin accept an optional const uint8_t mask[20]. Pass NULL to act on every joint. emergency_stop only acts on the whole hand and accepts no mask:

// Whole-hand enable
wuji_hand_2_enable(dev, NULL);
// Whole-hand clear faults
wuji_hand_2_clear_fault(dev, NULL);

// Index finger only (flat indices 4..7)
uint8_t mask[20] = {0};
for (int i = 4; i < 8; i++) mask[i] = 1;
wuji_hand_2_enable(dev, mask);            // enable only the 4 index-finger joints
wuji_hand_2_clear_fault(dev, mask);       // clear faults only on the 4 index-finger joints

// Whole-hand emergency stop
wuji_hand_2_emergency_stop(dev);

// User origin
wuji_hand_2_set_origin(dev, NULL);
wuji_hand_2_clear_origin(dev, NULL);

Data Port

wuji_hand_2_get_port reads the data port (the UDP port the device accepts SDK connections on, 50001 by factory default), and wuji_hand_2_set_port saves a new port. Changing the port requires recent Wuji Hand 2 firmware and Wuji SDK. Upgrade both to the latest version first.

uint16_t port = 0;
wuji_hand_2_get_port(dev, &port);          // e.g. 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);               // switch to the new port after reboot
}

The new port takes effect after the device reboots and persists across power loss. Once wuji_hand_2_set_port succeeds, wuji_hand_2_get_port returns the new port right away. Valid ports are 10000–65535, except the discovery port 50000. An out-of-range port makes wuji_hand_2_set_port return a status other than WUJI_STATUS_OK, with Invalid argument in wuji_last_error(), and the port keeps its current value. Firmware earlier than v2.10.0 doesn’t accept the write and also returns an error status. After the reboot, connections by address need the new port. Connections through device discovery need no change.

Identity and Diagnostics

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

// Two-call string getter: first probe with buf=NULL, buf_len=0 to learn the required size
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);

Write the IP with wuji_hand_2_set_ip(dev, "192.168.1.201") and restart the device with wuji_hand_2_reboot(dev). Both take effect exactly as the Python calls do.

get_hw_version / get_comm_diag return an out struct with heap-owned fields. Release with the matching _free function after use (only when the call returned WUJI_STATUS_OK).