纳博特科技开放平台

中文

English
한국어

中文

English
한국어

Appearance

常见问题 ​

本文档收录了 SDK 开发和协议集成中最常见的问题。每个问题包含 症状、原因、检查步骤 和 解决方法。

1. 连接失败 / IP 不通 ​

症状： connect_robot 返回 <= 0，或连接超时无响应。

可能原因：

  • 控制器 IP 地址配置错误
  • PC 与控制器不在同一网段
  • 防火墙或安全软件拦截
  • 控制器未上电或系统未启动完毕
  • 网线物理断开

检查步骤：

  1. 在 PC 上 ping 控制器 IP，确认网络可达：

    bash
    ping 192.168.1.16

    如果不通，检查网线、IP 地址和子网掩码

  2. 在示教器上查看「系统信息」确认控制器 IP

  3. 确认端口未被防火墙拦截（临时关闭防火墙测试）

  4. 如果使用 WiFi，改为有线直连排查

解决方法： 保证网络连通后重试。若 IP 正确但始终不通，请联系技术支持。

2. 端口区别：5000 / 6000 / 6001 / 7000 ​

端口用途协议格式一般使用者
5000文件传输（上传/下载/备份）TCP工具、HTTP 客户端
6000JSON 文本命令通信JSON 文本示教器
6001JSON 文本命令通信JSON 文本上位机、C++/C#/Python SDK
7000上位机服务功能端口TCP上位机、工具

关键区别： 四个端口两个版本通用。SDK 用户统一使用 6001 即可；JSON 协议用户根据场景选择 6000（示教器）或 6001（上位机）。

3. SDK 与控制器版本不兼容 ​

症状： 连接成功但 API 调用返回错误，或部分功能异常。

可能原因：

  • SDK 版本太新，控制器固件版本过旧
  • 不同 RTL 版本的 SDK 混用

检查步骤：

  1. 确认 SDK 版本号（查看下载包的文件名或 README）
  2. 在示教器上查看控制器固件和 RTL 版本
  3. 对照下载页的兼容矩阵确认匹配关系

解决方法： 下载与控制器固件版本匹配的 SDK。版本信息不明确时，联系技术支持并提供控制器型号和固件版本。

4. _nrc_host.so 或 DLL 无法加载 ​

症状： C++ 报 无法定位程序输入点；C# 报 DllNotFoundException；Python 报 ImportError: No module named _nrc_host。

可能原因：

  • 本地库文件未放在正确目录
  • 库文件架构不匹配（x86 vs x64）
  • 库文件与 SDK 包版本不一致
  • 缺少运行时依赖（Linux 缺少 libstdc++ 等；Windows 缺少 VC++ Redistributable）

检查步骤：

  1. Python： 确认 _nrc_host.so（Linux）或对应的本地库文件与 nrc_interface.py 在同一目录
  2. C++： 确认 nrc_host.dll 在可执行文件目录或系统 PATH 中
  3. C#： 确认 nrc_host.dll 的"复制到输出目录"属性已设置
  4. 用 ldd（Linux）或 Dependency Walker（Windows）检查缺失的依赖库

解决方法： 将对应平台和架构的本地库放在正确目录。Windows 还需安装 Visual C++ Redistributable。

5. Python 版本不匹配 ​

症状： ImportError: bad magic number 或 undefined symbol 错误。

可能原因： Python SDK 是为特定 Python 小版本编译的，不同版本（如 3.6 vs 3.10）的 C 扩展二进制不兼容。

检查步骤：

bash
python3 --version    # 查看 Python 版本
file _nrc_host.so    # 查看编译架构（Linux）

解决方法： 下载与你的 Python 版本严格匹配的 SDK 包。32 位 Python 需要 32 位 SDK，64 位 Python 需要 64 位 SDK。

6. MinGW 与 MSVC 库混用 ​

症状： 链接时报 undefined reference 或 unresolved external symbol，即使库路径正确。

可能原因： MinGW 编译的库与 MSVC 编译的库 ABI 不兼容，无法交叉链接。

检查步骤：

  1. 确认你使用的编译器：Qt Creator 中查看编译套件（MinGW 64-bit / MSVC）
  2. 确认 SDK 包名称：win_mingw64 → MinGW；win_msvc2017_x64 → MSVC

解决方法：

  • MinGW 用户：使用 win_mingw64 包，链接时用 -lnrc_host（自动找 libnrc_host.dll.a）
  • MSVC 用户：使用 win_msvc2017_x64 包，链接 nrc_host.lib

7. x86/x64、Debug/Release 不匹配 ​

症状： 加载 DLL 时报 0xC000007B 错误（Windows），或链接时报架构不匹配。

可能原因：

  • 32 位程序加载 64 位 DLL
  • Debug 配置链接 Release 库（或反过来）

检查步骤：

  1. Windows：确认项目平台目标为 x64（非 x86/Any CPU）
  2. 确认库的 Debug/Release 版本与项目的构建配置一致
  3. Visual Studio：生成 → 配置管理器 中查看活动解决方案平台

解决方法： 统一使用 x64 + Release 组合。如须调试，使用对应版本的 Debug 库。

8. 连接成功但机器人不能运动 ​

症状： connect_robot 成功，但运动指令发送后机器人无反应。

可能原因（按可能性排序）：

  1. 伺服未使能（最常见）
  2. 急停按钮被按下
  3. 运动队列未启动（未调用 queue_motion_set_status(socketFd, True)）
  4. 机器人处于错误状态（查看示教器错误信息）
  5. 速度参数为 0
  6. 目标位置超出工作空间

检查步骤：

  1. 在示教器上查看伺服状态（是否已使能）
  2. 检查急停按钮是否释放
  3. 确认代码中调用了 queue_motion_set_status(socketFd, True)
  4. 读取机器人状态查看是否有错误码

解决方法： 先通过示教器手动使能伺服，确认急停已释放，再执行运动指令。

9. 如何读取错误码和注册错误回调 ​

Python：注册错误/警告消息回调 ​

使用 set_receive_error_or_warnning_message_callback 注册回调函数，控制器发生错误或警告时会自动调用：

python
import nrc_interface
import time

def my_callback(message_type: int, message: str, message_code: int):
    print(f"[回调] 类型={message_type}, 信息={message}, 代码={message_code}")

socketFd = nrc_interface.connect_robot("192.168.1.13", "6001")
result = nrc_interface.get_connection_status(socketFd)
print(result)
nrc_interface.set_receive_error_or_warnning_message_callback(socketFd, my_callback)
time.sleep(1000)  # 保持连接以接收回调

C#：注册消息接收回调 ​

csharp
using System;
using System.Runtime.InteropServices;

public delegate void RecvMsgCallbackDelegate(int cmd, IntPtr message);
private RecvMsgCallbackDelegate recvMsgbackDelegate;

public void RecvMsgCallback(int messageType, IntPtr messagePtr)
{
    string msg = Marshal.PtrToStringAnsi(messagePtr);
    Console.WriteLine($"[回调] 类型={messageType}, 信息={msg}");
}

// 注册回调
recvMsgbackDelegate = new RecvMsgCallbackDelegate(RecvMsgCallback);
IntPtr recvCallbackPtr = Marshal.GetFunctionPointerForDelegate(recvMsgbackDelegate);
var recvMsgCallback = new SWIGTYPE_p_f_int_p_q_const__char__void(recvCallbackPtr, true);
nrc_interface.recv_message(fd, recvMsgCallback);

C++ 错误回调 API 以实际 SDK 接口文档为准。更多回调示例请参考 C# 连接示例 和 Python 接口示例。

10. 多机器人报错 5410（外部轴超限） ​

症状： 添加第二个机器人后，第一个机器人或第二个机器人报错误码 5410，提示"外部轴超限"。之前单个机器人运行时正常。

可能原因： 误启用了双机同步模式，该模式会将第二个机器人视为第一个机器人的外部轴。当第二个机器人未配置参数或超出限位时，即报外部轴超限。

检查步骤：

  1. 确认是否配置为双机同步：检查系统设置中是否启用了"双机同步"或"协同模式"
  2. 检查各机器人是否独立配置：确认每个机器人的 DH 参数、关节限位等均已单独配置
  3. 确认上电顺序：运行模式下应先切换到多机模式再依次上电

解决方法：

  • 如果不需要双机同步：关闭双机同步模式，为每个机器人独立配置
  • 如果需要双机同步：确认第二个机器人的所有参数（DH、限位、减速比等）已正确设置

提示： 示教模式下只能为当前选中的单个机器人上电；需要在运行模式下切换到多机模式才能同时控制多台机器人。

11. 如何提交有效的技术支持信息 ​

当需要联系技术支持时，建议同时提供以下信息以便快速定位问题：

  1. 控制器信息： 型号、固件版本、RTL 版本（在示教器"系统信息"中查看）
  2. SDK 信息： 使用的 SDK 语言、版本号、下载来源
  3. 开发环境： 操作系统和版本、编译器版本（如 Visual Studio 2022 / GCC 9.3）、Python 版本
  4. 错误描述： 完整的错误信息或错误码、复现步骤、是否必现
  5. 代码片段： 出问题的关键代码（简化后仍能复现问题的最小代码）
  6. 网络拓扑： PC 与控制器的连接方式（直连/交换机）、IP 地址

联系方式： sales@inexbot.com