wujihandpy 1.4.0

Python bindings for WujiHandCpp

WujihandPy: Unified Wuji Hand SDK: C++ Core with Python Bindings

English | 简体中文

WujihandPy is the Python binding of WujihandCpp. It provides an easy-to-use Python API for Wujihand dexterous-hand devices (powered by the underlying C++ SDK).

Documentation

Quick Start

Installation

WujihandPy supports one-line installation via pip:

pip install wujihandpy

For Linux users, you need to configure udev rules to allow non-root users to access USB devices. Run the following in a terminal:

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

Common Errors

If you see Could not find a version that satisfies the requirement during installation, upgrade pip first:

python3 -m pip install --upgrade pip

Then retry with the upgraded pip:

python3 -m pip install wujihandpy

Supported CPU Architectures

• x86_64
• ARM64

Minimum System Requirements (Linux)

glibc 2.28+

Linux distributions with glibc 2.28 or later:

• Debian 10+
• Ubuntu 18.10+
• Fedora 29+
• CentOS/RHEL 8+

Python 3.8+

Supported Python versions:

• Python 3.8-3.14

Minimum System Requirements (Windows)

WujihandPy does not support Windows yet; we will work to add support as soon as possible.

Quick Start

Import Modules

import wujihandpy
import numpy as np

Connect to the Hand

hand = wujihandpy.Hand()

Read Data

def read_<dataname>(self) -> datatype
def read_<dataname>(self) -> np.ndarray[datatype] # For bulk-read

All available data can be found in the API Reference.

For example, read the hand’s powered-on running time (us):

time = hand.read_system_time()

Besides hand-level data, each joint also has its own data; joint-level data names all use joint as the prefix.

For example, read the current position of joint 0 on finger 1 (index finger):

position = hand.finger(1).joint(0).read_joint_actual_position()

Joint angles are of type np.float64 in radians. The zero point and positive direction follow the definitions in the URDF files.

Reading multiple data items with a single command is called Bulk-Read.

For example, the following reads the current position of all (20) joints on the hand:

positions = hand.read_joint_actual_position()

For bulk reads, the function returns an np.ndarray[np.float64] containing all values:

>>> print(positions)
[[ 0.975  0.523  0.271 -0.45 ]
 [ 0.382  0.241 -0.003 -0.275]
 [-0.299  0.329  0.067 -0.286]
 [-0.122  0.228  0.315 -0.178]
 [ 0.205  0.087  0.288 -0.149]]

read blocks until the operation completes. When the function returns, the read is guaranteed to have succeeded.

Write Data

The write API is similar, but takes an extra parameter for the target value:

def write_<dataname>(self, datatype)
def write_<dataname>(self, np.ndarray[datatype]) # For bulk-write

For example, write a target position to a single joint:

hand.finger(1).joint(0).write_joint_target_position(0.8)

Valid angle limits for each joint can be obtained via:

upper = < Hand / Finger / Joint >.read_joint_upper_limit()
lower = < Hand / Finger / Joint >.read_joint_lower_limit()

If the written angle is outside the valid range, it will be automatically clamped to the upper/lower limit.

Bulk-Write is also supported. For example, write the same target position to all joints of finger 1 (index finger):

hand.finger(1).write_joint_target_position(0.8)

If each joint has a different target, pass an np.ndarray containing the target values for each joint:

hand.finger(1).write_joint_target_position(
    np.array(
        #   J1    J2    J3    J4
        [0.8,  0.0,  0.8,  0.8],
        dtype=np.float64,
    )
)

write blocks until the operation completes. When the function returns, the write is guaranteed to have succeeded.

Realtime Control

By default, both reads and writes use a buffer pool: data is accumulated for a while before being transmitted, so the maximum read/write frequency cannot exceed 100 Hz.

For scenarios that require smooth joint position control, use Realtime Control.

Asynchronous Read/Write

All read/write functions have asynchronous versions, with an _async suffix.

async def read_<dataname>_async(self) -> datatype
async def read_<dataname>_async(self) -> np.ndarray[datatype] # For bulk-read
async def write_<dataname>_async(self, datatype)
async def write_<dataname>_async(self, np.ndarray[datatype])  # For bulk-write

Asynchronous APIs must be awaited. The thread/event loop is not blocked while waiting, and when the call returns the read/write is guaranteed to have succeeded.

Unchecked Read/Write

If you do not care whether a read/write succeeds, you can use the Unchecked versions, with an _unchecked suffix.

def read_<dataname>_unchecked(self) -> None
def write_<dataname>_unchecked(self, datatype)
def write_<dataname>_unchecked(self, np.ndarray[datatype])  # For bulk-write

Unchecked functions always return immediately without blocking, and are typically used in latency-sensitive scenarios.

Get Cached Values (Get)

If you want to retrieve results from previous reads/writes, use the get family of functions:

def get_<dataname>(self) -> datatype
def get_<dataname>(self) -> np.ndarray[datatype] # For bulk-read

get functions also never block. They always return the most recently read value, regardless of whether it came from read, async-read, or read-unchecked.

If the data has never been requested, or the request has not succeeded yet, the return value of get is undefined (usually 0).

Examples

All example code is located in the example directory.

Performance and Optimization

While ensuring usability, WujihandPy has been optimized for performance and efficiency as much as possible.

We recommend prioritizing bulk read/write to maximize performance.

For scenarios that require smooth joint position control, be sure to use realtime_controller.

License

This project is licensed under the MIT License. See LICENSE for details.