核心概念
使用 C++ SDK 前需要了解以下关键概念。
连接生命周期
text
connect_robot() → 等待连接就绪 → 操作（伺服/运动/查询）
↓
disconnect_robot()- 连接：
connect_robot(ip, port)返回 socket 文件描述符（SOCKETFD），失败返回 ≤0 - 等待就绪： 连接成功后需轮询
get_connection_status()直到返回SUCCESS(0) - 操作： 通过 socketFd 调用所有接口
- 断开：
disconnect_robot(fd)主动断开
坐标系
| 坐标系 | coord 参数 | 说明 |
|---|---|---|
| 关节坐标 | 0 | 各关节电机的角度位置 |
| 直角坐标 | 1 | 末端相对于机器人底座的世界位置 |
| 工具坐标 | 2 | 末端安装工具后的工具端点位置 |
| 用户坐标 | 3 | 在工作台上自定义的局部坐标系 |
伺服状态机
text
停止(0) → 就绪(1) → 运行(3)
↑ ↓ ↓
←←←←← 报警(2) ←←←←←←| 状态码 | 说明 |
|---|---|
| 0 | 停止 — 未使能，可进行清错操作 |
| 1 | 就绪 — 已清错，等待上电 |
| 3 | 运行 — 已上电，可执行运动指令 |
上电前必须先设为就绪状态：
set_servo_state(fd, 1)→set_servo_poweron(fd)
运动模式
| 模式 | 函数 | 特点 |
|---|---|---|
| MoveJ | robot_movej | 关节空间点到点，快速但路径不定 |
| MoveL | robot_movel | 笛卡尔空间直线运动 |
| Jog | robot_start_jogging / robot_stop_jogging | 手动点动 |
| Queue | queue_motion_push_back_* + queue_motion_send_to_controller | 无作业文件队列运动 |
| Servo | servo_move | 7000 端口伺服跟踪 |
返回值
| 返回值 | 含义 |
|---|---|
SUCCESS (0) | 调用成功 |
| 其他值 | 错误码，具体含义参见错误码表 |
异步接口返回值仅表示"指令已接收"，不代表执行完毕。实际执行结果通过回调或状态查询获取。
线程安全
- 所有接口以 socketFd 区分连接，不同 socketFd 之间线程安全
- 同一 socketFd 的并发调用需自行加锁
- 回调函数内不应执行阻塞或耗时操作
坐标系深化
工具坐标系
工具坐标系定义末端工具的中心点（TCP）位置与姿态，默认工具坐标系原点为法兰盘中心，+Z 方向垂直法兰向外。
工具手参数：
| 参数 | 含义 | 单位 |
|---|---|---|
| X/Y/Z | 工具 TCP 相对法兰中心的偏移量 | mm |
| A/B/C | 工具相对法兰坐标系绕 X/Y/Z 轴的旋转角 | °/rad |
标定方式选择：
| 方式 | 适用场景 | 说明 |
|---|---|---|
| 6点标定 | 已激光标定+焊枪 | 校准工具手尺寸+姿态，C轴精度较好 |
| 7点标定 | 6点标定 A/B 轴误差大 | 校准尺寸+姿态，A/B 轴精度较好 |
| 12点标定 | 未激光标定 | 校准零点+工具手尺寸 |
| 15点标定 | 高精度要求 | 校准零点+尺寸+姿态 |
| 20点标定 | 零点丢失 | 校准零点+工具手尺寸 |
用户坐标系
用户坐标系是工作台上自定义的局部坐标系，默认 User0 与直角坐标系重合，新用户坐标系基于 User0 变换得到。
用户坐标参数：
| 参数 | 含义 | 单位 |
|---|---|---|
| X/Y/Z | 用户坐标原点相对机器人基座原点的偏移 | mm |
| A/B/C | 用户坐标相对直角坐标系绕 X/Y/Z 轴的旋转角 | °/rad |
标定步骤：
- 末梢移到期望的用户坐标原点位置，标定原点
- 向期望 X 轴正方向移动任意距离，标定 X 轴
- 向期望 Y 轴正方向移动任意距离，标定 Y 轴
- 计算并保存，提示成功后标定完成
标定体系
| 标定类型 | 用途 | 相关接口 |
|---|---|---|
| 工具手标定（6/7/12/15/20点） | 确定 TCP 偏移与姿态 | tool_hand_7_point_calibrate 等 |
| 用户坐标标定 | 建立工作台局部坐标系 | calibration_oxy、set_user_coordinate_data、calculate_user_coordinate |
| 零点标定 | 设置/偏移电机单圈零点 | set_axis_zero_position、set_zero_pos_deviation |
| 4点标定（SCARA） | 计算杆长和轴零点偏移，填入 DH 参数 | set_four_point_mark、four_point_calculation、set_result_for_DH |
| 20点标定 | 高精度校准（支持 2/12/15/20/21 点法） | tool_hand_2_or_20_point_calibrate 等 |
标定前将法兰盘平行于水平面，标定过程中保持参考点固定；计算结果大于 1 需重新标定。
工艺系统
工艺号（craftID，1-9）用于管理同一工艺的多套参数，示教器与 SDK 共享同一套工艺数据。
| 工艺 | 工艺号 | 参数读写方式 |
|---|---|---|
| 焊接 | 1-9 | weld_set_config / weld_get_config + 摆焊参数 |
| 码垛 | 1-9 | pallet_set_running_state / 状态查询 |
| 视觉 | 0-98 | vision_set_basic_parameter / 标定/触发 |
| 激光切割 | 1-9 | 全局/工艺/模拟量/IO 四类参数 |
| 传送带跟踪 | 1-9 | 传送参数 + 编码器 + PID |
使用前先设置当前工艺号，再读写参数，与示教器配置保持一致。
点位与变量
全局点位（GP/GE）
| 类型 | 说明 | posInfo 长度 |
|---|---|---|
| GP | 全局点位（机器人） | 14 |
| GE | 全局点位（含外部轴） | 21 |
posInfo 格式（14 长度）：
| 索引 | 含义 |
|---|---|
| [0] | 坐标系：0=关节，1=直角，2=工具，3=用户 |
| [1] | 角度单位：0=角度制，1=弧度制 |
| [2] | 形态（SCARA：1=左手，2=右手） |
| [3] | 工具手坐标序号 |
| [4] | 用户坐标序号 |
| [5]-[6] | 备用 |
| [7]-[13] | 点位信息（关节角或 XYZ+姿态） |
全局变量
| 系列 | 类型 | 说明 |
|---|---|---|
| GI | int | 全局整数变量 |
| GD | double | 全局浮点变量 |
| GB | bool | 全局布尔变量 |
错误处理机制
返回值语义
| 返回值 | 含义 |
|---|---|
SUCCESS (0) | 调用成功 |
| 负数 | 通信/执行错误（-1 接收失败、-2 断开连接、-6 超时等） |
| 其他值 | 业务错误码，参见错误码表 |
异步接口
异步接口返回值仅表示"指令已接收"，实际执行结果通过：
- 回调函数：
recv_message、set_receive_error_or_warnning_message_callback等注册 - 状态查询：
get_robot_running_state、get_servo_state等轮询
报警与清错
- 伺服报警后进入报警状态（状态码 2）
- 清错操作：
clear_error，清错后需重新下电再上电 - 实时错误信息通过
set_receive_error_or_warnning_message_callback回调接收