Installation & Environment Setup

Requirements

• OS: Windows / Linux / macOS (with matching native SDK build)
• Python: 3.8+
• Native dependencies:
  • Compiled _dexcelbot_sdk extension (.so / .dll / .dylib / .pyd)
  • dexcelbot_apexhand_sdk.py shipped together with the native libraries

The SDK uses ctypes and pybind11 to load the C++ backend, so correctly placing the shared libraries and exposing them to the loader is critical.

Recommended directory layout

your_project/
  ├─ python/
  │   ├─ dexcelbot_apexhand_sdk.py
  │   ├─ _dexcelbot_sdk.cp311-win_amd64.pyd   # or platform‑specific .so / .dylib
  │   └─ lib/
  │       ├─ libdexcelbot_xxx.dll
  │       └─ ...
  └─ examples/
      └─ basic_control.py

dexcelbot_apexhand_sdk.py will:

• Insert python/lib/ into sys.path.
• Preload libdexcelbot*.so / .dylib / .dll.
• Try several strategies to import _dexcelbot_sdk.

Option 1 — Install as a local editable package (recommended)

If the SDK is distributed as a Python package, from the SDK root run:

pip install -e .

Then in your project:

from dexcelbot_apexhand_sdk import DexcelBot

Option 2 — Directly vendor into your project

1. Copy dexcelbot_apexhand_sdk.py into your project (for example your_project/python/).
2. Copy _dexcelbot_sdk.* and the lib/ folder preserving the original relative layout.
3. Add the SDK folder to sys.path in your script:

import sys
from pathlib import Path

SDK_ROOT = Path(__file__).parent / "python"
sys.path.insert(0, str(SDK_ROOT))

from dexcelbot_apexhand_sdk import DexcelBot

Troubleshooting native import errors

If _dexcelbot_sdk cannot be imported, the SDK raises an ImportError with details. Common causes and fixes:

1. Package not installed / path not on sys.path
   • Ensure you have run:
   Terminal

   pip install -e .
   

   • Or manually add the directory containing _dexcelbot_sdk to sys.path.
2. Missing shared libraries
   • Check that python/lib/ contains libdexcelbot*.so / .dll / .dylib.
   • If you built from source, verify that cmake --build ... succeeded and copy the produced libraries into python/lib/.
3. Linux: dynamic linker cannot find dependencies
   • Add the SDK library folder to LD_LIBRARY_PATH:
   Terminal

   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/dexcelbot_sdk/python/lib
   

4. Windows: missing dependent DLLs
   • Make sure all DLLs required by the SDK are either in the same directory or on the system PATH.
   • Tools like Dependency Walker can help identify missing DLLs.

Quick sanity check

After installation, run a minimal script:

from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode

bot = DexcelBot()
print("SDK instance created successfully")

# If no real hardware is connected yet, just call disconnect to verify linkage
result = bot.disconnect()
print("disconnect() returned:", result)

If the script imports and instantiates DexcelBot without errors, your Python‑side SDK setup is correct and you can proceed to network and hardware configuration.