安装与环境配置

环境要求

• 操作系统：Windows / Linux / macOS（需对应编译好的原生 SDK 库）
• Python：3.8 及以上版本
• 依赖：
  • 已编译好的 _dexcelbot_sdk 动态库（.so / .dll / .dylib / .pyd）
  • dexcelbot_apexhand_sdk.py 与原生库处于同一 SDK 发行包中

SDK 底层通过 ctypes 和 pybind11 加载 C++ 扩展，因此 正确放置原生库和配置搜索路径非常重要。

目录结构建议

典型的 SDK 目录结构如下（仅示例）：

your_project/
  ├─ python/
  │   ├─ dexcelbot_apexhand_sdk.py
  │   ├─ _dexcelbot_sdk.cp311-win_amd64.pyd  # 或对应平台的 .so / .dylib
  │   └─ lib/
  │       ├─ libdexcelbot_xxx.dll
  │       └─ ...
  └─ examples/
      └─ basic_control.py

dexcelbot_apexhand_sdk.py 会自动：

• 将 python/lib/ 目录加入 sys.path
• 预加载 libdexcelbot*.so / libdexcelbot*.dylib / libdexcelbot*.dll
• 按多种策略尝试导入 _dexcelbot_sdk

安装方式

方式一：作为本地包开发使用（推荐）

如果 SDK 以 Python 包形式提供，你可以在 SDK 根目录执行：

pip install -e .

然后在任意项目中直接：

from dexcelbot_apexhand_sdk import DexcelBot

方式二：直接拷贝到项目

1. 将 dexcelbot_apexhand_sdk.py 拷贝到你的项目（例如 your_project/python/）。
2. 将 _dexcelbot_sdk.* 与 lib/ 整个目录保持原有相对位置一并拷贝。
3. 在脚本中添加路径或通过包导入，例如：

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

原生库加载失败时的排查

当无法导入 _dexcelbot_sdk 时，SDK 会抛出 ImportError，并给出详细的尝试路径和错误信息。常见原因与解决方案包括：

1. 包未安装或路径不在 sys.path 中
   • 请确保在 SDK 根目录执行过：
   Terminal

   pip install -e .
   

   • 或在运行脚本前手动将包含 _dexcelbot_sdk 的目录加入 sys.path。
2. 缺少共享库 / 动态链接库
   • 请确认 python/lib/ 目录下存在 libdexcelbot*.so / .dll / .dylib。
   • 如果你从源码构建 SDK，请确认已成功执行构建命令（例如 cmake --build ...），并把生成的库文件复制到 python/lib/。
3. Linux 环境下动态库搜索路径问题
   • 可以通过设置 LD_LIBRARY_PATH 让系统找到 SDK 依赖库，例如：
   Terminal

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

4. Windows 环境下 DLL 依赖缺失
   • 确保所有 SDK 依赖的 DLL 已经放在同一目录，或已加入系统 PATH。
   • 使用 Dependency Walker 等工具可以帮助排查缺失的依赖 DLL。

验证安装是否成功

安装完成后，建议运行一个最小脚本验证：

from dexcelbot_apexhand_sdk import DexcelBot, ErrorCode

bot = DexcelBot()
print("SDK 实例创建成功")

# 如果当前环境还未连接真实硬件，此处仅调用而不校验返回值
result = bot.disconnect()
print("调用 disconnect() 返回:", result)

能正常导入并创建 DexcelBot 实例，则说明 Python 层 SDK 安装已经正确，接下来可以继续配置网络与实际机械手连接。