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

# Getting Started

> Learn about Wuji Hand SDK (wujihandpy) installation, quick start examples, and core concepts including device model and data model.

## Compatibility and Requirements

* CPU: x86\_64 (AMD64) / arm64 (aarch64)
* Python: 3.8–3.14
* OS: Ubuntu 22.04 LTS / Ubuntu 24.04 LTS

## Installation Guide

This section covers the installation of wujihandpy, system requirements, and common troubleshooting.

### Installation

wujihandpy supports one-step installation via `pip`:

```bash theme={null}
python3 -m pip install wujihandpy
```

> [!WARNING]
>
> Note: Unless you're developing wujihandpy itself, don't clone its Git repository locally—this may cause your IDE to misidentify .pyi file locations, resulting in abnormal code completion.

On Linux, configure udev to allow non-root USB access:

```bash theme={null}
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
```

> [!NOTE]
>
> Note: For common installation errors and fixes, see [Troubleshooting - Installation Issues](#installation-issues) at the end of this page.

## Quick Start

This section provides a minimal working example to quickly test the dexterous hand with the wujihandpy library.

```python theme={null}
# quickstart.py
import time
import wujihandpy

hand = wujihandpy.Hand()
try:
    # Enable all joints (blocking, ensures success)
    hand.write_joint_enabled(True)

    # Move index finger joint 0 to 1.57 rad (approximately 90° downward)
    hand.finger(1).joint(0).write_joint_target_position(1.57)

    # Wait for motion to complete
    time.sleep(0.5)
finally:
    # Always disable all joints when finished
    hand.write_joint_enabled(False)
```

Run the above code with the following command to see the dexterous hand's index finger first joint move to the specified position:

```bash theme={null}
python3 quickstart.py
```

> [!NOTE]
>
> Note: For common connection and permission issues during quick start, see [Troubleshooting - Quick Start Issues](#quick-start-issues) at the end of this page.

## Core Concepts

This section introduces wujihandpy's device model and data model to help you understand the library's overall architecture and usage patterns.

### Device Model

wujihandpy has a three-layer device model: Hand, Finger, and Joint. The hierarchy is: `Hand.finger(i) -> Finger`, `Finger.joint(j) -> Joint`. Specifically:

* **Hand** represents the complete dexterous hand device and can be created via wujihandpy.Hand().
* **Finger** is a lightweight reference to Hand, does not hold independent state, and can be constructed and destroyed multiple times. Finger objects can be constructed via `hand.finger(i)` (0 ≤ i \< 5), where i corresponds to actual fingers as follows:
  * 0: Thumb
  * 1: Index finger
  * 2: Middle finger
  * 3: Ring finger
  * 4: Pinky finger
* **Joint** is also a lightweight reference to Hand, does not hold independent state, and can be constructed and destroyed multiple times. Joint objects can be constructed via `finger.joint(j)` (0 ≤ j \< 4), where j roughly corresponds to actual joints as follows:
  * 0: Proximal joint
  * ...
  * 3: Distal joint

### Data Model

Data consists of readable/writable objects. Similar to devices, data also has a hierarchical relationship:

> [!NOTE]
>
> Note: Only some data fields are listed here as examples. For the complete API Reference, see [Field List](https://docs.wuji.tech/docs/en/wujihandpy/latest/api-reference.md#field-list).

* **Hand** layer: Data unique to the entire hand resides at this layer, for example:
  * `handedness`: Handedness (left/right hand)
  * `firmware_version`: Firmware version
  * `system_time`: Uptime

* **Finger** layer: Data where each finger holds an independent copy resides at this layer. Currently, this layer has no data.

* **Joint** layer: Data where each joint holds an independent copy resides at this layer, for example:
  * `joint_enabled`: Whether the joint is enabled
  * `joint_actual_position`: Current joint position
  * `joint_target_position`: Target joint position
  * `joint_temperature`: Current joint temperature
  * `joint_error_code`: Joint error code

> [!NOTE]
>
> Note: All data belonging to the Joint layer is prefixed with `joint`.

## Troubleshooting

### Installation Issues

#### Upgrade pip

If you encounter `Could not find a version that satisfies the requirement`, for example in an older Python or pip environment:

```text theme={null}
ERROR: Could not find a version that satisfies the requirement wujihandpy (from versions: none)
ERROR: No matching distribution found for wujihandpy
```

Consider upgrading pip and using the upgraded pip to install:

```bash theme={null}
python3 -m pip install --upgrade pip && python3 -m pip install wujihandpy
```

If the issue remains unresolved, please verify that your system version and Python version meet the [Compatibility and Requirements](#compatibility-and-requirements).

#### Using Virtual Environments

If you encounter `This environment is externally managed`, for example in Ubuntu environments where the system Python is managed by the OS:

```text theme={null}
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
```

This indicates that pip is managed by the system package manager and requires using a virtual environment (venv) for installation.

### Quick Start Issues

#### Dexterous Hand Not Connected

```text theme={null}
[ERROR] No device found with specified vendor id (0x0483)
Traceback (most recent call last):
  File "/workspaces/quickstart.py", line 5, in <module>
    hand = wujihandpy.Hand()
           ^^^^^^^^^^^^^^^^^
RuntimeError: Failed to init.
```

If you encounter the above error, please confirm that the dexterous hand is connected to the computer via USB.
You can use `lsusb` to verify the device is properly recognized. If the device is correctly connected, `lsusb` will produce output similar to:

```text theme={null}
Bus 001 Device 032: ID 0483:2000 WUJITECH WUJIHAND
```

When using a USB-C to USB-C cable to connect the dexterous hand, some computers may not properly recognize the device. Please try replacing it with a USB-A to USB-C cable.

#### Insufficient Permissions

```text theme={null}
[ERROR] No device found with specified vendor id (0x0483)
[ERROR]   Device 1 (0483:2000): Ignored because device could not be opened: -3 (ERROR_ACCESS)
[ERROR] Consider relaxing some filters
Traceback (most recent call last):
  File "/workspaces/quickstart.py", line 5, in <module>
    hand = wujihandpy.Hand()
           ^^^^^^^^^^^^^^^^^
RuntimeError: Failed to init.
```

If you encounter the above error (ERROR\_ACCESS), it indicates that the current user does not have read/write permissions for the USB device.
Please check the Linux udev configuration section in [Installation](#installation), complete the permission configuration, and try again.

> [!WARNING]
>
> Note: If developing in a Docker container (DevContainer), the udev configuration commands must still be executed on the host machine.

### Get Logs

SDK runtime logs are stored in `~/.wuji/log/` by default. File names follow `{timestamp}_{pid}.log`, with each file rolling at 10 MB and up to 5 historical files retained. Send the latest log to technical support when reporting an issue.

#### Custom Path and Level

**Configure through environment variables (recommended, zero code)**

The SDK reads them once at logger initialization (in the common `Hand` flow that means when the first `Hand` is constructed) and won't pick up later changes:

```bash theme={null}
export WUJI_LOG_PATH=~/logs/wujihand
export WUJI_LOG_LEVEL=debug
python3 your_script.py
```

| Variable | Values | Default | Description |
| :- | :- | :- | :- |
| `WUJI_LOG_PATH` | Any directory path | `~/.wuji/log/` | Log file directory |
| `WUJI_LOG_LEVEL` | `trace` / `debug` / `info` / `warn` / `err` / `critical` / `off` | `info` | Log level |
| `WUJI_LOG_TO_FILE` | `true` / `false` | `true` | Write to file |
| `WUJI_LOG_TO_CONSOLE` | `true` / `false` | `true` | Write to terminal (stdout / stderr) |

Value matching is case-insensitive. `WUJI_LOG_LEVEL` also accepts the aliases `error` (=`err`), `warning` (=`warn`), `information` (=`info`), and `crit` (=`critical`). Both boolean variables also accept `1`/`0`, `on`/`off`, and `yes`/`no`.

**Configure from code**

Call the `wujihandpy.logging` submodule before creating `Hand`:

```python theme={null}
import os
import wujihandpy
from wujihandpy import logging as wuji_logging

wuji_logging.set_log_path(os.path.expanduser("~/logs/wujihand"))
wuji_logging.set_log_level(wuji_logging.Level.Debug)

hand = wujihandpy.Hand()
```

For the full API reference and call-timing constraints, see [API Reference - logging Module](https://docs.wuji.tech/docs/en/wujihandpy/latest/api-reference.md#logging-module).

#### Collect Detailed Logs

The default `info` level captures only key events. When you need detailed command flow analysis (for example, a command was sent but the actual state didn't follow), switch to `debug` for SDO/PDO traffic, or `trace` for the raw TX/RX bytes as well:

```bash theme={null}
export WUJI_LOG_LEVEL=debug
python3 your_script.py
```

Send the log file covering the problem time window to technical support to speed up diagnosis.


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