核心概念
Python SDK 与 C++ SDK 接口完全一致，核心概念参见 C++ 核心概念。以下仅列出 Python 特有差异。
返回值差异（重要）
C++ 通过引用参数输出数据，Python 通过元组同时返回结果码和输出值：
python
status = 0
result, status = nrc.get_servo_state(fd, status)
# result = 0（成功），status = 3（运行中）每次调用 getter 前必须重新初始化变量，因为 Python 端通过引用修改原始对象的值。
容器类
python
# 一维数组
pos = nrc.VectorDouble()
pos.append(1.0)
pos.append(2.0)
# 二维数组
pos_list = nrc.VectorVectorDouble()
pos_list.append(pos)结构体
python
cmd = nrc.MoveCmd()
cmd.coord = 0 # 关节坐标
cmd.velocity = 80
cmd.targetPosType = nrc.PosType_data枚举
python
nrc.PosType_data # == C++ PosType::data
nrc.SUCCESS # == 0异步回调
回调在 SDK 内部线程触发，Python 中需注意线程上下文：
python
def on_message(messageID, msg):
print(f"收到消息 ID={messageID}: {msg}")
nrc.recv_message(fd, on_message)回调线程中不应执行阻塞或耗时操作；如需更新 UI，应通过队列或信号量转发到主线程（与 C++ 一致）。
错误处理
- 返回值语义与 C++ 一致：
SUCCESS(0)表示成功，负数表示通信/执行错误 - 异步接口返回值仅表示"指令已接收"，实际结果通过回调或状态查询获取
- 伺服报警后需调用
clear_error清错，清错后重新下电再上电
线程安全
- 不同 socketFd 之间线程安全
- 同一 socketFd 的并发调用需自行加锁（Python 可使用
threading.Lock） - 受 GIL 限制，Python 多线程无法利用多核并行，高实时场景建议使用多进程或 C++ 端处理
- 回调函数内不应执行阻塞或耗时操作