Troubleshooting
Installation
Q: SDK installation fails?
- Confirm Python version ≥ 3.10
- Update pip with
pip install --upgrade pip - If you encounter compilation errors, try installing the pre-built wheel package
Runtime Errors
Q: SDK script throws exception during execution?
| Exception Message | Cause | Resolution |
|---|---|---|
DeviceNotFound | Device not discovered | Check physical connection and network |
Disconnected | Connection interrupted | Check cables, reconnect |
ConnectionTimeout | Connection timed out | Check network connection or increase timeout_ms parameter |
OperationTimeout | Operation timed out | Increase timeout_ms parameter or check device status |
StreamClosed | Subscription stream closed | Device may have disconnected, reconnect |
SessionAlreadyExists | A session for the same device already exists | Keep using the existing handle, or disconnect() and reconnect |
| Connecting to a Wuji Hand fails and names unresponsive joints | The hand isn't ready and some joints didn't answer | Check power and cabling, then reconnect once the joints are powered. The Python SDK and C SDK behave the same |
ValueError | Wuji Hand 2 write to hand.mit_params() (kp / kd both required non-negative), hand.effort_limit() (non-negative), or joint_command realtime publisher receives NaN / infinity / negative values | Filter invalid values before writing |
ValueError | Wuji Hand 2 write to hand.effort_limit() exceeds the ceiling the device currently allows, so the device rejects the write | Lower the value. Firmware sets the ceiling — read effort_limit back to confirm what's in effect |
Q: SDK data subscription has latency or frame drops?
- Check network bandwidth and latency (wired connection preferred over WiFi)
- Reduce the number of simultaneously subscribed data streams
- Ensure callback functions don't contain blocking operations
- On Wuji Hand 2, subscribe to
hand.joint_diagnostics()and read the frame-levelcommsummary to locate where frames go missing:e2e_lostis network loss, whilesdk_droppedmeans your consumer is falling behind. For field definitions, see Wuji Hand 2 Types — Hand2CommSummary
Compatibility
Q: SDK version incompatible with firmware?
- Check the SDK release notes for version compatibility
- Keep SDK and firmware on the same minor version (e.g., both 0.6.x)
Q: After upgrading the SDK, tactile_binary or tactile_residual suddenly stops producing data?
The Wuji Glove tactile data layout now uses 24×31 (was 24×32). The SDK validates incoming frame size and the loaded contact calibration model against the new layout — if either still targets 24×32, the affected streams stop publishing to prevent misaligned output. To recover, upgrade the Wuji Glove firmware to a version that supports 24×31 and re-run tactile contact calibration under the new layout. See the Wuji Glove tactile data reference for details.
Support
Q: How do I get technical support?
Contact support@wuji.tech with the following information:
- Device serial number (SN)
- Firmware version
- SDK/Studio version
- Operating system and version
- Steps to reproduce the issue