Reading Device Info

SDK Practice

Overview

After connecting, print the device’s static information and current diagnostic state in one pass: handedness, IP, online-joint bitmap, labels and effort limits for all 20 joints, plus each joint’s status word, current, bus voltage, temperature, and error code.

This is the first step in diagnosing a device. Offline joints, abnormal temperatures, and non-zero fault codes are all visible at a glance.

Matching example: examples/c/wuji_hand_2/2_hand_info.c.

For API and field definitions, see Identity and Diagnostics and Joint Diagnostic Data Types.

Python has no standalone example, though every capability is available: hand.handedness(), hand.ip(), hand.online_joints_count(), hand.joints, hand.effort_limit(), and a joint_diagnostics subscription for the diagnostic snapshot.

This example only reads. It doesn’t enable the motors, and the fingers don’t move.

Prerequisites

Hardware

Item	Requirement
Wuji Hand 2	1
Connection	Ethernet

Software

Item	Requirement
Operating system	Linux or a Mac with Apple silicon, meeting the system requirements
Wuji SDK	v2026.8.31 or later
C toolchain	CMake 3.16 or later, plus the extracted SDK package

Data Flow

The online bitmap is a 32-bit integer where bit N corresponds to the joint at index N. With all 20 joints online it reads 0x000FFFFF.

Two Joint Numbering Schemes

This is the key to reading both this example’s output and joint_states.

Numbering	Values	Used by
Array index	Contiguous 0 through 19	Subscripts for array APIs such as `effort_limit`, `mit_params`, and `joint_command`
`nid`	1–4, 6–9, 11–14, 16–19, 21–24	Firmware bus node IDs, appearing in `joint_states` and `joint_diagnostics`

Each finger occupies a block of 5 nids but uses only the first 4, so 5, 10, 15, and 20 are skipped. The conversion holds across all 20 joints:

nid = (index // 4) * 5 + (index % 4) + 1

Index	Label	nid
0	`thumb_S1`	1
3	`thumb_S4`	4
4	`index_S1`	6
7	`index_S4`	9
8	`middle_S1`	11
19	`pinky_S4`	24

Using an nid from joint_states directly as an array subscript shifts everything.

Integration Steps

1. Discover and Connect to the Device

This page follows the C example. Initialize with wuji_init(), find a Wuji Hand 2 with wuji_scan(), then pass the target serial number to wuji_connect(). Free the discovery results after the connection call returns. Continue reading information only after a successful connection.

WujiConnectTarget tgt = {
    .kind = WUJI_CONNECT_TARGET_KIND_SN,
    .value = list[idx].serial_number,
};
struct WujiDevice *dev = NULL;
WujiStatus st = wuji_connect(&tgt, "hand2", NULL, &dev);
wuji_discovered_free(list, n);

idx is the index of a confirmed Wuji Hand 2 in the discovery results. If no device matches or the connection fails, enter cleanup directly.

2. Read Device Information and Joint Limits

Read handedness with wuji_hand_2_get_handedness() and the online count with wuji_hand_2_online_joints_count(). Call wuji_hand_2_get_ip() twice: first to query the buffer size, then to allocate and read the string.

WujiHandedness side;
uint8_t count = 0;
wuji_hand_2_get_handedness(dev, &side);
wuji_hand_2_online_joints_count(dev, &count);

wuji_hand_2_get_all_effort_limit() returns the limit array and online bitmap. Read only entries marked online in the bitmap.

float limits[WUJI_HAND_2_JOINT_COUNT];
uint32_t online = 0;
if (wuji_hand_2_get_all_effort_limit(dev, limits, &online) == WUJI_STATUS_OK) {
    for (int i = 0; i < WUJI_HAND_2_JOINT_COUNT; i++) {
        if (WUJI_JOINT_ONLINE(online, i))
            printf("joint %d: %.3f A\n", i, limits[i]);
    }
}

3. Capture One Diagnostic Frame

Register a joint_diagnostics callback, copy entries into an application-owned snapshot, and notify the main thread with an atomic flag. The example waits up to about one second, closes the subscription, then reads the copied data.

diag_snapshot_t snap = {0};
struct WujiSub *sub = NULL;
if (wuji_hand_2_subscribe_joint_diagnostics(dev, on_diag, &snap, &sub)
        == WUJI_STATUS_OK) {
    for (int i = 0; i < 100 && !atomic_load_explicit(&snap.got, memory_order_acquire); i++)
        usleep(10000);
    wuji_sub_close(sub);
}

diag_snapshot_t and on_diag are the example’s snapshot structure and callback. C example includes field copying and cross-thread synchronization. Don’t read snapshot entries if no frame arrives before the timeout.

4. Release the Device and SDK

After reading information, disconnect, release the device handle, and shut down the SDK. Use the same cleanup order on error paths.

wuji_dev_disconnect(dev);
wuji_dev_release(dev);
wuji_shutdown();

Running It

./build/hand2/2_hand_info

Measured Output

On a right-hand Wuji Hand 2 with all 20 joints online:

Connecting to WH2KA00XXXXXXXXX (192.168.1.100:7447)
handedness: right
ip: 192.168.1.100
online joints (count): 20

online bitmap = 0x000FFFFF  (20 joints online)
  i   label     state      effort_lim
  0   thumb_S1  online        1.500A
  1   thumb_S2  online        1.500A
  2   thumb_S3  online        1.500A
  3   thumb_S4  online        1.500A
  4   index_S1  online        1.500A
  ...
  19  pinky_S4  online        1.500A

joint_diagnostics snapshot (20 joints):
  nid  status_word   current    vbus   temp err_code
  1    0x24620001    0.00A   12.3V  54.8C   0x0000
  2    0x24620001   -0.01A   12.4V  55.4C   0x0000
  ...
  24   0x24620001    0.01A   12.3V  55.8C   0x0000

Metric	Measured
Online bitmap	`0x000FFFFF`, all 20 bits set
Joint labels	`thumb_S1` through `pinky_S4`, 4 per finger
Effort limit	1.500 A across the board
Status word	`0x24620001` across the board
Bus voltage	12.3 to 12.4 V
Temperature	49.1 to 58.6 degrees Celsius
Error code	`0x0000` across the board
Current at rest	−0.02 to +0.01 A

At rest and unenabled, current fluctuates slightly around zero and temperature holds near 50 degrees Celsius. That’s a normal state.

Notes

Branch point	Behavior	What to do
Joint offline	Its bitmap bit is 0 and the joint is marked `offline`	Check bus wiring and power
Non-zero error code	The `err_code` column isn’t `0x0000`	Look up the fault code and call `clear_fault()` if needed
Elevated temperature	The `temp` column reads high	At rest, measurements ranged from 49 to 59 degrees Celsius
Several devices	The example connects to the first it finds	On a shared network, name a serial number

Adapting It

Testing Whether a Joint Is Online

The bitmap beats querying one at a time. (bitmap >> i) & 1 equal to 1 means the joint at index i is online. Note that this uses the array index, not the nid.

Reference Ranges for Temperature and Voltage

At rest, temperature measured 49 to 59 degrees Celsius and bus voltage 12.3 to 12.4 V. Temperature rises after sustained large motions, and a persistently high reading calls for checking cooling and load.

Investigating Fault Codes

When err_code is non-zero, look it up in the fault code table. Clear faults with clear_fault(), and a fault that won’t clear means the condition is still present.

Locating a Specific Joint

To go from a label to an nid, use the formula above. To go from an nid back to a label, compute i = (nid - 1) // 5 * 4 + (nid - 1) % 5, noting that nids 5, 10, 15, and 20 correspond to no joint.

Subscribing With Callbacks: how nid behaves in joint_states
Publishing Control Commands: how array index and nid are used in control APIs
Troubleshooting: fault codes and how to handle them