> ## 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. # Product Introduction ## Product Overview Wuji Hand is a bionic dexterous hand with 20 active degrees of freedom developed by WUJI TECH, designed for various application scenarios such as scientific research, robot integration, and human-computer interaction. ## Product Parameters The Wuji Hand core technical parameters table covers structural design, drive control, load performance, dynamic response, and electrical characteristics for product selection, simulation modeling, and application integration.

Parameter Category	Parameter Item	Typical Value or Description
Structure and Degrees of Freedom	Active Degrees of Freedom	20, 4 per finger
	Number of Joints	20, 4 per finger
	Finger Configuration	Full opposable, supports lateral swing
	Kinematic Configuration	Serial direct drive rotary joints, no nonlinear kinematics
	Maximum Grasping Diameter	100 mm
Dimensions and Weight	Self-weight (excluding cables)	580 ± 10 g
Dimensions and Weight	Dimensions	201 mm × 75 mm × 50 mm
Drive Mode	Drive Mode	Self-locking rotary direct drive joints
Drive Mode	Control Algorithm	FOC vector control drive
Control and Communication	Control Frequency	1000 Hz × 20 axes
	Communication Interface	USB 2.0
	Control Mode	Position control
	Communication Protocol	Self-developed protocol
	Communication Rate	480 Mbps (theoretical value)
Load Performance	Fingertip Force	15 N
	Single Finger Maximum Load (Hook Grip)	3 kg
	Maximum Static Load for Whole-hand Grasping	10 kg
	Maximum Static Load of Whole-hand Hook Grip	10 kg
	Maximum Static Load for Whole-hand Vertical Grasping	5 kg
	Max Hanging Weight	5 kg
Dynamic Performance	Minimum Opening and Closing Time	≈ 0.3 s
	Repeat Opening and Closing Speed	≥ 2 times/s
	Thumb Flexion/Lateral Swing Speed	≥ 100 rpm
	Four-finger Bending Speed	≈ 0.25 s
Precision and Lifespan	Positioning Repeatability	± 1 mm
	Idle Grip Life	≥ 300,000 times
	Backlash	≤ ± 7 mm
Electrical Performance	Operating Voltage	12V - 20V DC
	Static Power	12 W
	Included Adapter Specifications	Rated Output: 12V 20A Peak Power: 420 W (10 ms transient) Cable: 14 AWG
Materials and Protection	Shell Material	Aluminum alloy
Materials and Protection	Protection Class	IP40

## Product Structural Features This section introduces the overall structural design of Wuji Hand, communication and power interface layout, as well as the naming conventions and motion parameters of each degree of freedom, helping users understand the mechanical structure and usage specifications of the product. ### Structural Schematic Wuji Hand adopts a five-finger bionic structural design, with each finger containing multiple joints for flexible motion. The figure below shows the overall structure and main components:

* A to E in the figure correspond to: * A: Thumb * B: Index * C: Middle * D: Ring * E: Little * Numbers 1 to 5 correspond to commonly used anatomical region identifications: * 1: Distal phalanges * 2: Intermediate phalanges * 3: Proximal phalanges * 4: Metacarpals * 5: Carpals ### Wuji Hand DOF Configuration The figure below shows the anatomical naming and corresponding positional relationships of each joint of Wuji Hand, helping users understand the functional positioning of each degree of freedom.

Numbers 1 to 6 in the figure correspond to: * 1: CMC1 * 2: CMC2 * 3: MCP1 * 4: MCP2 * 5: PIP * 6: DIP ### DOF Motion Direction and Range The four-finger structure is consistent, with a single finger full length of approximately 157 mm. The thumb module structure is slightly different, with a single finger full length of approximately 130 mm. The figure below uses the thumb and little finger as examples to illustrate the motion direction and angle range of each degree of freedom:

* Thumb * 1: Carpometacarpal abduction/adduction, motion range approximately 100° * 2: Carpometacarpal lateral swing, motion range approximately 80° * 3: Flexion/extension, motion range approximately 130° * 4: Flexion/extension, motion range approximately 130° * Little Finger * 1: Flexion/extension, motion range approximately 125° * 2: Lateral swing, motion range approximately 60° * 3: Flexion/extension, motion range approximately 130° * 4: Flexion/extension, motion range approximately 130° ### Communication and Power Interface Schematic Wuji Hand achieves data communication with the host computer through a USB-C interface while supporting external power supply. The figure below shows the communication and power interface positions and connection methods of Wuji Hand:

* Numbers 1 to 3 in the figure are: * 1: USB data cable connection end (plugged into the dexterous hand device) * 2: USB data cable other end (connected to host computer or robot controller) * 3: XT30 power interface for external power supply Note: Use the original cables to maintain stable communication and safe power delivery ## Product Electrical Characteristics ### Pin Definition

### Indicator Light Reference Table An RGB status indicator sits on the lower back of the hand. It provides real-time feedback on power supply and system operation.

The meanings corresponding to each status are shown in the table below:

	Status Symbol	System Phase Description	Description
No Light	OFF	Powered off/unpowered state	Power supply not connected or main power failure
Blue Solid	Bootloader	Firmware update or bootloader	Device is in bootloader. If device is performing firmware upgrade, strictly prohibit power disconnection or cable reconnection to avoid system damage
Green Flashing	Standby	Normal standby	Power supply normal, system normal, not connected to host computer or SDK
Green Solid	Running	Normal operation	Power supply normal, system started, connected to host computer or SDK
Yellow Solid	Warning	Device warning	System detected warnings such as high temperature, power fluctuation, and other non-fatal faults. Pause debugging and investigate the warning cause
Red Flashing	Pre-fault	Fault warning	Warning of impending fault, such as temperature approaching overtemperature threshold
Red Solid	Fault	Critical fault	Serious hardware/software fault (such as main MCU abnormality, communication out of sync, etc.). Disable immediately and troubleshoot via host computer (observe indicator light, terminal log, reset/factory restore)

## Product Accessories Introduction ### Product Accessories Table

Image	Name	Description
	12V 20A Power Adapter	Power supply
	Power Adapter AC Cable	Power supply
	Impact-resistant Adapter	[See Impact-resistant Adapter](#impact-resistant-adapter)
	Direct-mount Adapter	Connects Wuji Hand to user equipment (such as robot arm flange)
	Toolkit	Hex wrench Pry bar: for separating the latched impact-resistant adapter
	Accessory Kit	Socket head cap screws: M4x6, M5x10, M6x10 XT30 female connector
	USB A to USB C Cable	For communication between host device and Wuji Hand
	Tactile Sensing Glove (Optional)	[See Tactile Sensing Glove](#tactile-sensing-glove) Whether it ships with Wuji Hand, and the left- or right-hand fit, depend on your order

### Tactile Sensing Glove The Tactile Sensing Glove is an optional tactile perception accessory for Wuji Hand. It targets research and engineering scenarios — sensing, data collection, human-machine interaction — and provides a unified hardware foundation for algorithm adaptation, simulation modeling, and multi-modal fusion. * **High sensing density**: Full-palm uniformly distributed sensor array, more than 400 sensors, each independently capturing contact states, with super-resolution further enhancing perception * **High compliance**: Fully flexible Nerve skin (flexible sensing skin) accommodates bending and stretching, forming a dynamic sensing array that conforms closely to objects #### System Requirements

Category	Item	Requirement
Hardware setup	USB-C port	At least one free USB-C port on the host (USB 2.0 or higher)
Hardware setup	Cables	Bundled USB-C cable and short interconnect cable (see Connection)
Recommended computer	CPU	x86\_64 or ARM64
	Memory	≥ 16 GB, to support parallel data streams and visualization
	Storage	≥ 1 GB free space for SDK and dependencies
Operating system	SDK platform	Currently Linux only
	Recommended distribution	Ubuntu 22.04 / 24.04
	Windows support	Not yet supported, planned for a future release
Wuji Hand SDK (wujihandpy)	Python version	3.8 – 3.14
	Dependency	numpy
	Install	`pip install wujihandpy`
Wuji Hand SDK (wujihandcpp)	Packages	Deb / RPM, install directly
Wuji Hand SDK (wujihandcpp)	Build instructions	See wujihandcpp
USB device permissions (Linux)	udev rule	Add the rule so the device can be accessed without sudo: {`echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0483", MODE="0666"' \| \\ sudo tee /etc/udev/rules.d/95-wujihand.rules && \\ sudo udevadm control --reload-rules && sudo udevadm trigger`}

Tactile Sensing Glove connection diagram

1. Connect the **circle marker** end of the bundled short data cable to the Brain Watch bridge port (**circle marker**). Route the other end around the inner wrist of Wuji Hand and connect it to the Wuji Hand [communication port](#communication-and-power-interface-schematic). 2. Use a USB-C (USB 2.0 or higher) data cable to connect to the PC — connect either USB-C end to the Brain Watch output port (triangle marker), and the other end to the PC. #### Communication Interface The product currently exposes a single communication interface, simplifying host integration.

Category	Item	Description
Physical interface	Port type	USB-C (USB 2.0 or higher)
Transport protocol	Mode	USB CDC (virtual serial port). The host recognizes a standard serial device
	Linux node	`/dev/ttyACM\*`
	USB identifiers	VID = `0x0483` PID = `0x5700`
Data stream	Push rate	Up to 120 FPS, 24 × 32 float pressure frames
Data stream	Frame structure	Sequence number, timestamp, and CRC. The SDK handles frame sync, drop counting, and reconnect
Data access	Recommended	Official SDK (C++ / Python) for structured frame data
Data access	Debug	Generic serial tool to read the raw byte stream

#### Software Support The official SDK provides full data access and device control, covering everything from algorithm validation to production deployment. See the [SDK User Guide — Tactile Sensing Glove](/en/docs/wujihandpy/api-reference/#tactile-sensing-glove) for the full API reference. **SDK interfaces** Two interfaces share a single backend and behave identically: | SDK | Source | Installation | Use cases | | - | - | - | - | | Wuji Hand SDK (wujihandpy) | [wuji-technology/wujihandpy](https://github.com/wuji-technology/wujihandpy) | `pip install wujihandpy` | Algorithm validation, data collection, rapid integration | | Wuji Hand SDK (wujihandcpp) | [wujihandcpp directory in the wujihandpy repo](https://github.com/wuji-technology/wujihandpy/tree/main/wujihandcpp) | Deb / RPM / build from source | Production deployment, low-latency real-time control | **Core API capabilities** * Connection: `connect()` / `disconnect()` / `is_connected()`, with multi-device addressing by USB serial number * Frame reading: blocking `read_frame(timeout_ms)` or callback-based `start_streaming(callback)` / `stop_streaming()` * Device info: `get_device_info()` (serial / hardware / firmware version), `get_fw_build()`, `get_handedness()` * Diagnostics: `get_diagnostics()` (uptime, frame count, CRC errors, drops, USB resets), `reset_counters()` * Runtime config: `get_sample_rate_hz()` / `set_sample_rate_hz()` (1–120 Hz), `set_streaming(enable)` * Time sync: `get_device_time()`, `sync_host_epoch(host_unix_ns)` for multi-device alignment * Lifecycle: `reset_device()` for soft reset * Error handling: USB disconnection triggers DisconnectCallback. C++ raises `ConnectionLostError`, and Python raises the corresponding exception **Joint operation** The tactile glove and Wuji Hand use independent USB transports and threads, so they can run in parallel within the same process (see `example/joint_with_tactile.py`) — enabling closed-loop scenarios such as tactile-driven motion control. ### Impact-resistant Adapter The impact-resistant adapter uses a twist-lock and slot locking structure to maintain a rigid connection under normal conditions. When subjected to external impact forces exceeding the safety threshold (such as robot arm loss of control or severe end-effector collision), Wuji Hand and the robot arm will trigger active separation to protect critical components (joints, motors, reducers, etc.) from damage. This design ensures improved reliability while minimizing maintenance and repair risks. * **Normal state:** Twist-lock and set screws are tightened to ensure structural stability and prevent loosening due to daily vibration or minor impacts. * **Abnormal state:** Automatically releases when exceeding the safety threshold, with Wuji Hand suspended by the safety chain to avoid secondary impact or falling hazards. This trigger mechanism has been engineered to ensure it will not be falsely triggered during normal minor vibrations or routine operations, and is only effective for severe impacts exceeding the safety threshold. Note that this mechanism mainly covers most common impact and vulnerable scenarios, but cannot completely avoid potential damage in all extreme situations.

Impact-resistant Adapter Component Names

| No. | Component Name | | :-: | :- | | 1 | Four-claw Latch | | 2 | Grooved Flange | | 3 | Twist-lock | | 4 | Safety Chain | | 5 | Set Screw | ## Installation and Removal **Safety Warning**: * Installation and removal must be performed with power off. Live operation is prohibited * After installation, confirm that the twist-lock is fully tightened and the set screw is locked before starting the robot arm ### Installation Steps **Step 1:** Remove the impact-resistant adapter from the packaging (left image), pull apart the four-claw latch and grooved flange (right image), remove the set screw and rotate the twist-lock counterclockwise to separate the upper and lower components.

**Step 2:** Use screws to connect the grooved flange to the user equipment (such as robot arm). The grooved flange provides two hole sizes, with matching screw sizes of M5×10 and M6×10. Use M4×6 screws to connect Wuji Hand to the four-claw latch.

Grooved Flange and Four-claw Latch Connection

**Step 3:** Insert the twist-lock into the four-claw latch and rotate clockwise until tight (gently pull the safety chain to verify the twist-lock will not slip out). Install the set screw. Align the four-claw latch with the positioning slot on the grooved flange, press down to latch, and the impact-resistant adapter installation is complete.

Twist-lock Tightening and Installation Complete

### Precautions #### Fastening Check * Use recommended specification screws. Screws of insufficient length or incorrect specifications are strictly prohibited * It is recommended to tighten screws in a diagonal sequence to ensure even flange surface contact * If possible, configure a recommended torque wrench according to screw specifications to ensure tightening torque meets standards #### Maintenance and Inspection * After each installation or removal, check whether the **safety chain and twist-lock** are flexible, unworn, and whether the attachment points are loose * If impact-resistant release is triggered during operation, check whether installation screws are loose and whether the twist-lock locking mechanism is intact before reinstallation ## Wuji SDK Data Types ### HandJointStates Real-time 20-joint state (the `hand.joint_states().subscribe()` frame). Joint order is finger-major: `{left,right}_finger{1..5}_joint{1..4}`. | Field | Type | Description | | - | - | - | | `header` | `FrameHeader` | Frame header | | `position` | `list[float]` | 20 joint positions in radians, always length 20 | | `velocity` | `list[float]` | Angular velocity, length 0 when not provided | | `effort` | `list[float]` | Joint effort, length 0 when not provided | ```json theme={null} { "header": { "seq": 42, "timestamp_us": 1709876543210, "frame_id": "" }, "position": [0.001, -0.012, 0.087, 0.045, ...], "velocity": [], "effort": [] } ``` ### HandJointCommand 20-joint command frame. `seq` is client-incrementing so receivers can detect dropped frames. | Field | Type | Description | | - | - | - | | `seq` | `int` | Client-incremented sequence number | | `position` | `list[float]` | Target positions, length 20 | | `velocity` | `list[float]` | Target velocity, optional | | `effort` | `list[float]` | Target effort, optional | ### TactileGloveFrame A single pressure frame from the paired tactile glove, on a 24×32 grid. | Field | Type | Description | | - | - | - | | `handedness` | `int` | Handedness (0 = Left, 1 = Right — note this is the opposite of the `WujiHand` SDO encoding) | | `sequence` | `int` | Frame sequence number | | `timestamp_ms` | `int` | Device timestamp in milliseconds | | `pressure` | `list[float]` | 768 f32 pressure values, row-major 24×32 | ## Wuji Hand SDK Subscription ### Wuji Hand Data Subscription Wuji Hand product docs are archived. The subscription APIs are maintained on this page. The device connects over USB, exposed as `wuji_sdk.WujiHand` in Python and as the `wuji_hand_*` functions in C. | Operation | Python | C | | - | - | - | | Subscribe to joint state | `hand.joint_states().subscribe()` | `wuji_hand_subscribe_joint_states()` | | Read a joint position snapshot | No equivalent — read it from a subscribed frame | `wuji_hand_read_joint_state()` | | Open a realtime control session | `hand.realtime_controller(LowPass(cutoff_hz=...))` | `wuji_hand_realtime_controller_open()`, `wuji_hand_realtime_controller_close()` | | Publish 20-joint commands | `hand.joint_command().publish()`, `publisher.send(joints)` | `wuji_hand_joint_command_publish()`, `wuji_hand_joint_command_publisher_send()` | | Write filtered target positions | No equivalent — send them through the publisher | `wuji_hand_realtime_controller_set_target_position()` | | Read back actual position and effort | `ctrl.get_actual_position()`, `ctrl.get_actual_effort()` | `wuji_hand_realtime_controller_get_actual_position()`, `wuji_hand_realtime_controller_get_actual_effort()` | | Read and write effort limits | `hand.set_all_effort_limit(amps)`, `hand.get_all_effort_limit()` | `wuji_hand_set_all_effort_limit()`, `wuji_hand_get_all_effort_limit()` | | Check whether a tactile glove is attached | `hand.is_tactile_attached()` | `wuji_hand_is_tactile_attached()` | | Subscribe to tactile pressure frames | `hand.tactile.subscribe_pressure_frame()` | `wuji_hand_subscribe_tactile_pressure_frame()` | | Subscribe to tactile status | `hand.tactile_status().subscribe()` | `wuji_hand_subscribe_tactile_status()` | | Read tactile glove info, diagnostics, and handedness | No equivalent | `wuji_hand_get_tactile_device_info()`, `wuji_hand_get_tactile_diagnostics()`, `wuji_hand_get_tactile_handedness()` | #### Subscribing to joint state Receive real-time 20-joint position, with optional velocity and effort: ```python theme={null} sub = hand.joint_states().subscribe() for _ in range(100): state = await sub.recv_async() print(f"seq={state.header.seq}, joint0={state.position[0]:+.3f}") sub.close() ``` ```c theme={null} void on_state(WujiFrameKind kind, const WujiHandJointStates *frame, void *user) { if (kind != WUJI_FRAME_KIND_OK) return; printf("seq=%u, joint0=%+.3f\n", frame->header.seq, frame->position[0]); } WujiSub *sub = NULL; wuji_hand_subscribe_joint_states(hand, on_state, NULL, &sub); // ... after receiving in the background for a while wuji_sub_close(sub); ``` In Python, `hand.joint_states().subscribe()` returns `Subscription[HandJointStates]`. In C the same data arrives as `WujiHandJointStates`, where `position`, `velocity`, and `effort` each carry their own length field. #### Publishing joint commands (realtime control) A realtime control session applies a lowpass filter to suppress high-frequency jitter. Inside the session, get a PUB handle and push exactly 20 joint commands (`position` / `velocity` / `effort` each). The command shape matches Wuji Hand 2, so control code is portable between Wuji Hand 2 and Wuji Hand: ```python theme={null} from wuji_sdk import JointCommand, LowPass with hand.realtime_controller(LowPass(cutoff_hz=5.0)) as ctrl: publisher = hand.joint_command().publish() joints = [JointCommand(0.0, 0.0, 0.0)] * 20 joints[0] = JointCommand(0.3, 0.0, 0.0) publisher.send(joints) print(ctrl.get_actual_position()[0], ctrl.get_actual_effort()[0]) publisher.close() ``` ```c theme={null} WujiRealtimeController *ctrl = NULL; WujiLowPass filter = { .cutoff_hz = 5.0 }; wuji_hand_realtime_controller_open(hand, filter, &ctrl); WujiHandJointCommandPublisher *pub = NULL; wuji_hand_joint_command_publish(hand, &pub); WujiJointCommand joints[20] = {0}; joints[0].position = 0.3f; wuji_hand_joint_command_publisher_send(pub, joints); float actual_pos[20], actual_eff[20]; wuji_hand_realtime_controller_get_actual_position(ctrl, actual_pos); wuji_hand_realtime_controller_get_actual_effort(ctrl, actual_eff); printf("%.3f %.3f\n", actual_pos[0], actual_eff[0]); wuji_hand_joint_command_publisher_close(pub); wuji_hand_realtime_controller_close(ctrl); ``` For continuous control, send commands at a fixed rate (typically 100 Hz). The session handle reads back actual state at any time: actual position is 20 joint values in radians and actual effort is 20 joint values in amps, both read from a non-blocking cache, so control frequency is unaffected. You can share the session handle across threads without locking — for example, one thread streaming targets at a fixed rate while another polls actual positions. In C, release both the publisher and the controller explicitly. `wuji_hand_joint_command_publisher_close()` and `wuji_hand_realtime_controller_close()` are NULL-safe, but skipping them leaks resources. #### Effort limits Set the torque limit on all 20 joints to the same amperage and read back a length-20 array: ```python theme={null} hand.set_all_effort_limit(1.5) limits = hand.get_all_effort_limit() ``` ```c theme={null} wuji_hand_set_all_effort_limit(hand, 1.5f); float limits[20]; // finger-major order wuji_hand_get_all_effort_limit(hand, limits); ``` * Default is 1.5 A, suitable for most applications * Valid range is 0.0 to 3.5 A — values above 3.5 are clamped to 3.5 Modifying the effort limit changes the maximum output capability of each joint. The firmware also reduces the effective limit based on joint temperature. For the full reference and risk notes, see [Wuji Hand SDK Guide — joint\_effort\_limit](/en/docs/wujihandpy/api-reference/#joint_effort_limit). #### Tactile sensing glove companion data When a tactile sensing glove shares the USB bus and matches the hand's handedness, the SDK auto-pairs it while connecting. Check the pairing status and subscribe to pressure frames: ```python theme={null} if hand.is_tactile_attached(): tactile_sub = hand.tactile.subscribe_pressure_frame() frame = await tactile_sub.recv_async() print(f"max pressure: {max(frame.pressure):.2f}") tactile_sub.close() ``` ```c theme={null} void on_pressure(WujiFrameKind kind, const WujiTactileGloveFrame *frame, void *user) { if (kind != WUJI_FRAME_KIND_OK) return; float max = 0.0f; for (size_t i = 0; i < frame->pressure_len; i++) { if (frame->pressure[i] > max) max = frame->pressure[i]; } printf("max pressure: %.2f\n", max); } bool attached = false; wuji_hand_is_tactile_attached(hand, &attached); if (attached) { WujiSub *tactile_sub = NULL; wuji_hand_subscribe_tactile_pressure_frame(hand, on_pressure, NULL, &tactile_sub); // ... after receiving in the background for a while wuji_sub_close(tactile_sub); } ``` C adds three tactile info readers: `wuji_hand_get_tactile_device_info` (fills `WujiTactileGloveDeviceInfo`), `wuji_hand_get_tactile_diagnostics` (fills `WujiTactileGloveDiagnostics`), and `wuji_hand_get_tactile_handedness` (fills a `uint8_t`). On `WUJI_STATUS_OK`, the first two leave heap-owned fields in `out`. Release them with `wuji_tactile_glove_device_info_free` and `wuji_tactile_glove_diagnostics_free` respectively, and don't free on a non-OK status. When the glove is missing or faulty, these calls return an error status — read the details with `wuji_last_error()`. `wuji_hand_get_handedness` and `wuji_hand_get_tactile_handedness` both return a raw `uint8_t`, but their encodings are opposites—don't mix them. `wuji_hand_get_handedness` returns `0` for right and `1` for left, the reverse of the `WujiHandedness` enum, so reading it through the enum swaps left and right. `wuji_hand_get_tactile_handedness` returns `0` for left and `1` for right, which matches the enum. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.