架构说明

Python SDK 通过 SWIG 从 C++ libnrc_host 自动生成，nrc_interface.py 包含全部接口。

SDK 组成

SDK 包/
├── nrc_interface.py      ← SWIG 生成的 Python 接口（全量）
├── _nrc_host.so          ← Linux 原生动态库
└── nrc_host.pyd          ← Windows 原生动态库

调用链

Python 代码 → nrc_interface.py → _nrc_host.so → TCP Socket → 控制器

所有 Python 函数名与 C++ 完全一致，参数对应关系参见 类型映射。

类型映射

C++	Python	说明
SOCKETFD (int)	int	socket 文件描述符
Result (int)	int	返回状态码
std::string	str	字符串
std::vector<double>	VectorDouble	先创建再 append
std::vector<vector<double>>	VectorVectorDouble	二维数组
结构体 (MoveCmd等)	同名 Python 类	字段名一致

C++ 对照

所有参数含义参见 C++ API 文档。

通信模型

Python SDK 与 C++ 一致，采用 JSON 文本协议进行请求/响应交互，支持两种通信模式：

模式	说明	典型场景
同步请求/响应	上位机发送指令，阻塞等待控制器回复	参数设置、状态查询、标定计算
异步回调	控制器主动推送数据，通过注册的回调函数接收	7000 端口伺服跟踪、状态变化通知

请求流程： Python 构造 JSON 指令 → nrc_interface.py → _nrc_host.so → TCP 发送 → 控制器解析执行 → 返回 JSON 响应 → SDK 解析为返回值/输出参数。

回调机制： 调用 send_message / recv_message / set_receive_error_or_warnning_message_callback 等注册回调函数后，控制器事件到达时 SDK 在内部线程触发回调，开发者无需主动轮询。

多机器人支持

控制器支持 1~4 台机器人协同工作，Python 接口与 C++ 一致，提供两种调用方式：

方式	接口	说明
单机器人	robot_xxx(...)（如 robot_movej）	默认操作 1 号机器人
多机器人	robot_xxx_robot(fd, robotNum, ...)	通过 robotNum 参数指定机器人编号（1-4）

多机器人并行需先调用 set_robots_parallel 开启并行模式；外部轴跟随主机器人编号管理。

工艺扩展架构

工艺类功能以独立头文件形式提供，Python 中对应同名接口，通过工艺号（1-9）管理多套参数：

工艺	Python 模块	典型接口
焊接	nrc_craft_weld	焊接参数配置、送丝/退丝/送气、摆焊
码垛	nrc_craft_pallet	码垛参数设置、状态查询
视觉	nrc_craft_vision	视觉参数、标定、目标点计算
激光切割	nrc_craft_laser_cutting	全局/工艺/模拟量/IO 参数
传送带跟踪	nrc_craft_conveyor_belt_track	传送参数、编码器、PID 同步

工艺参数采用"设置/查询"成对接口，设置前需先指定工艺号，与示教器工艺配置保持数据一致。

数据流说明

端口	数据方向	内容	典型接口
6001	双向	命令流：控制指令与响应（JSON）	robot_movel、set_servo_state
7000	双向	伺服数据流：点位跟踪、状态回调	servo_move、servo_point_position_motion_control
5000	双向	文件流：作业文件上传/下载/备份	文件传输接口

6001 为 SDK 主命令端口；涉及伺服跟踪（如外部点移动、点位运动控制）需同时连接 7000 端口。