RobotDirver C++ API 说明
本文档描述 RobotArm 类（include/RobotArm.hpp）对外接口。签名与类型以头文件为准；Angles、Coords 为 std::array<float, 6>，Param 含 ip_serial、port_baud（见 include/config.hpp）。
说明：RobotArm 未封装夹爪、末端/底部 IO 等扩展能力。
下文每条接口均按 功能、返回值、参数说明、取值范围 列出；其中 取值范围 适用于 MyCobotPro450。
连接与类型速查
#include "RobotArm.hpp"
#include "config.hpp"
Param p;
p.ip_serial = "192.168.0.232";
p.port_baud = 4500;
RobotArm arm(TCP_COMM, p);
| 符号 | 取值范围 / 含义 |
|---|---|
TCP_COMM |
1，Socket（TCP） |
通用约定：多数 int 接口在通信正常时返回 1 表示指令侧成功或已收到有效应答，-1 表示通信失败或未收到有效数据；具体以下位机与联调为准。
构造与析构
RobotArm(uint8_t mode, Param params)
- 功能：构造实例，内部创建
Protocol并建立通信（begin()）。 - 返回值：无。
- 参数说明：
mode为通信方式；params为地址与端口或串口参数。 - 取值范围：
mode∈ {TCP_COMM（1）,SERIAL_COMM（2）}；TCP 时port_baud为端口号（如 4500），ip_serial为可达 IP，暂不支持串口通信。
~RobotArm()
- 功能：析构，释放协议与通信资源。
- 返回值：无。
- 参数说明：无。
- 取值范围：无。
系统配置、上电与版本信息
int powerOn()
- 功能：机械臂上电。
- 返回值：
1上电成功；0失败；-1无通信（与控制器实际约定为准）。 - 参数说明：无。
- 取值范围：无。
int powerOff()
- 功能：机械臂下电。
- 返回值：
1成功接收指令；-1无通信。 - 参数说明：无。
- 取值范围：无。
int isPowerOn()
- 功能：查询是否已上电。
- 返回值：
1已上电；0未上电；2上电失败等状态；-1无通信。 - 参数说明：无。
- 取值范围：无。
vector<int> isInitCalibration()
- 功能：查询零位/校准相关状态。
- 返回值：整型向量，长度与语义以下位机为准。
- 参数说明：无。
- 取值范围：无。
string getLibVersion()
- 功能：读取本驱动库版本字符串。
- 返回值：版本号字符串（如与
LIB_VERSION一致）。 - 参数说明：无。
- 取值范围：无。
string getSystemVersion()
- 功能：读取主控/系统版本。
- 返回值：版本字符串。
- 参数说明：无。
- 取值范围：无。
int getModifyVersion()
- 功能：读取主控更正版本号。
- 返回值：整数更正版本。
- 参数说明：无。
- 取值范围：无。
string getRobotType()
- 功能：读取机型字符串。
- 返回值：如 4503 等，以控制器返回为准。
- 参数说明：无。
- 取值范围：无。
string getAtomVersion()
- 功能：读取末端版本。
- 返回值：版本字符串。
- 参数说明：无。
- 取值范围：无。
int getToolModifyVersion()
- 功能：读取末端更正版本号。
- 返回值：整数。
- 参数说明：无。
- 取值范围：无。
控制模式与数据刷新
int getFreshMode()
- 功能：查询刷新/队列运动模式。
- 返回值：
0插补/按队列顺序执行；1刷新模式（优先执行最新指令）；失败时可能为-1。 - 参数说明：无。
- 取值范围：无。
int setFreshMode(bool mode)
- 功能：设置位置运动模式。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
mode，false→0（插补），true→1（刷新）。 - 取值范围：逻辑值对应 0 / 1。
int getControlMode()
- 功能：查询控制模式（位置/力矩）。
- 返回值：
0位置模式；1力矩模式；失败-1。 - 参数说明：无。
- 取值范围：无。
int setControlMode(bool mode)
- 功能：设置控制模式。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
mode，false→位置（0），true→力矩（1）。 - 取值范围：逻辑值对应 0 / 1。
关节控制
int sendAngle(uint8_t joint, float angle, uint8_t sp)
- 功能：下发单关节目标角度。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
joint关节序号；angle目标角（°）；sp速度档。 - 取值范围：
joint：1 ~ 6；angle（°）：J1 -162~162，J2 -125~125，J3 -154~154，J4 -162~162，J5 -162~162，J6 -165~165；sp：1 ~ 100。
int sendAngles(Angles angles, uint8_t sp)
- 功能：一次性下发六关节目标角度。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
angles长度 6；sp速度档。 - 取值范围：各元素角度范围 同
sendAngle按关节序号；sp：1 ~ 100。
float getAngle(uint8_t joint)
- 功能：读取单关节当前角度。
- 返回值：浮点角度（°）；无效或失败时可能为错误哨兵值（以联调为准）。
- 参数说明：
joint关节序号。 - 取值范围：
joint：1 ~ 6。
Angles getAngles()
- 功能：读取六关节当前角度。
- 返回值：
Angles，六个浮点数。 - 参数说明：无。
- 取值范围：无。
float getJointMinAngle(uint8_t joint)
- 功能：读取软件关节最小角。
- 返回值：浮点（°）。
- 参数说明：
joint。 - 取值范围：
joint：1 ~ 6。
float getJointMaxAngle(uint8_t joint)
- 功能：读取软件关节最大角。
- 返回值：浮点（°）。
- 参数说明：
joint。 - 取值范围：
joint：1 ~ 6。
int jogAngle(uint8_t joint, uint8_t direction, uint8_t speed)
- 功能：关节连续 JOG，至限位或
stop()等停止。 - 返回值：
int，成功常为1，失败-1。 - 参数说明：
joint；direction方向；speed速度档。 - 取值范围：
joint：1 ~ 6；direction：0 负向、1 正向；speed：1 ~ 100。
int setFreeMoveMode(bool state)
- 功能：设置自由移动模式（便于手动拖动等）。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
state，false关闭，true打开。 - 取值范围：对应 0 / 1。
int getFreeMoveMode()
- 功能：查询自由移动模式。
- 返回值：
0关闭；1打开；-1无通信。 - 参数说明：无。
- 取值范围：无。
int setMotorEnabled(uint8_t joint, bool state)
- 功能：单关节电机使能/掉使能。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
joint；state，false掉使能，true使能。 - 取值范围：
joint：1 ~ 6 或 254（全部关节）。
int servoRestore(uint8_t joint)
- 功能：清除关节异常/恢复相关指令。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
joint。 - 取值范围：
joint：1 ~ 6 或 254（全部关节）。
void setWaitArrival(bool enable)
- 功能：设置运动指令是否等待到位再返回（闭环/开环），默认未闭环。
- 返回值：无。
- 参数说明：
enable，true闭环等待，false开环立即返回。 - 取值范围：布尔。
bool getWaitArrival() const
- 功能：查询是否启用等待到位。
- 返回值：
true/false。 - 参数说明：无。
- 取值范围：无。
bool waitPosArrived(int timeout_ms = 30000)
- 功能：阻塞等待
POS_ARRIVED类到位反馈。 - 返回值：等到为
true，超时等为false。 - 参数说明：
timeout_ms超时时间。 - 取值范围：
timeout_ms：> 0（毫秒），默认 30000。
拖动示教
int dragTeachSave()
- 功能：开始录制拖动示教轨迹。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：无。
- 取值范围：单次录制 ≤ 120 s。
int dragTeachPause()
- 功能：暂停拖动示教录制。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：无。
- 取值范围：无。
int dragTeachExecute()
- 功能：执行已录制轨迹（单次）。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：无。
- 取值范围：无。
int dragTeachClean()
- 功能：清除已录制的示教采样点。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：无。
- 取值范围：无。
坐标控制
int sendCoord(uint8_t axis, float coord, uint8_t sp)
- 功能：下发单轴坐标/位姿分量。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
axis1~6 对应 x,y,z,rx,ry,rz；coord数值；sp速度档。 - 取值范围：
axis：1 ~ 6；分量范围：x、y（mm）-474 ~ 474；z（mm）-180 ~ 677；rx、ry、rz（°）-180 ~ 180；sp：1 ~ 100。
int SendCoords(Coords coords, uint8_t sp)
- 功能：一次性下发六位姿
[x,y,z,rx,ry,rz]。 - 返回值：
int，成功常为1，失败-1。 - 参数说明：
coords长度 6；sp速度档。 - 取值范围：各分量 同
sendCoord对应轴；sp：1 ~ 100。
Coords getCoords()
- 功能：读取当前坐标/位姿。
- 返回值：
Coords，六个浮点数。 - 参数说明：无。
- 取值范围：无。
int jogCoord(uint8_t axis, uint8_t direction, uint8_t speed)
- 功能：坐标轴连续 JOG。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
axis；direction；speed。 - 取值范围：
axis：1 ~ 6；direction：0 负向、1 正向；speed：1 ~ 100。
运动控制（关节与坐标共用）
int stop()
- 功能：停止当前运动。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：无。
- 取值范围：无。
int pause()
- 功能：暂停运动指令。
- 返回值：
int，如1已暂停，0未停止，-1错误（以控制器为准）。 - 参数说明：无。
- 取值范围：无。
int resume()
- 功能：恢复运动。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：无。
- 取值范围：无。
int isPaused()
- 功能：是否处于暂停状态。
- 返回值：
1已暂停；0未暂停；-1错误。 - 参数说明：无。
- 取值范围：无。
int isMoving()
- 功能：是否在运动中。
- 返回值：
1运动中；0静止；-1错误。 - 参数说明：无。
- 取值范围：无。
int isInPosition(Angles angle_coords, bool mode)
- 功能：判断当前是否到达给定目标（角度或坐标）。
- 返回值：
1已到位；0未到位；-1异常或无有效应答。 - 参数说明：
angle_coords六个目标量；mode数据类型标志。 - 取值范围：
mode：false表示angle_coords为六轴角度（°）；true表示为六轴坐标（mm/°，与sendCoord轴定义一致）。各分量范围分别 同关节角表 / 坐标表。
机器人异常处理与状态
int getErrorInformation()
- 功能：读取运动/系统错误码。
- 返回值：
0无错误；1~6对应关节超限位；32坐标无解（臂展临近限位）；33直线运动无相邻解；34速度融合报错；35零空间运动无相邻解；36奇异位置无解；81~86J1~J6 碰撞相关（需按流程resume等）；其它以固件为准。 - 参数说明：无。
- 取值范围：无。
int clearErrorInfomation()
- 功能：清除可清除的错误信息（方法名拼写与头文件一致）。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：无。
- 取值范围：无。
vector<int> getRobotStatus()
- 功能：读取机器人状态。
- 返回值：长度多为 20 时依次为：① 关节是否碰撞；② 是否运动；③～⑧ J1～J6 是否超限位；第 9～14 项 J1～J6 是否电机硬件报错；第 15～20 项 J1～J6 是否软件通信报错（0 一般正常，非 0 异常）。长度随固件可能变化，以联调为准。
- 参数说明：无。
- 取值范围：无。
RobotStatus getRobotStatusDetail()
- 功能：读取结构化状态（碰撞、运动、限位、关节状态字、通信状态字等）。
- 返回值：
RobotStatus结构体（见RobotArm.hpp）。 - 参数说明：无。
- 取值范围：各字段 0/1 或状态字，以协议为准。
vector<int> getMotorsRunErr()
- 功能：读取运动过程中电机错误信息。
- 返回值：长度 6 的列表，全 0 一般表示正常。
- 参数说明：无。
- 取值范围：无。
速度 / 加速度参数
int getMaxSpeed(uint8_t mode)
- 功能：读取最大速度参数。
- 返回值：当前最大速度设定值；失败
-1。 - 参数说明：
mode，0 关节角速度，1 坐标线速度。 - 取值范围：
mode∈ {0, 1}；物理量范围：角速度 1 ~ 150（°/s），坐标速度 1 ~ 200（mm/s）。
int setMaxSpeed(uint8_t mode, uint16_t max_speed)
- 功能：设置最大速度。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
mode同getMaxSpeed；max_speed目标值。 - 取值范围：
mode：0 / 1；max_speed：角速度 1~150（°/s），坐标 1~200（mm/s）。
int getMaxAcc(uint8_t mode)
- 功能：读取最大加速度参数。
- 返回值：当前最大加速度；失败
-1。 - 参数说明：
mode，0 关节角加速度，1 坐标加速度。 - 取值范围：
mode∈ {0, 1}；角加速度 1 ~ 150（°/s²），坐标 1 ~ 400（mm/s²）。
int setMaxAcc(uint8_t mode, uint16_t max_acc)
- 功能：设置最大加速度。
- 返回值：
int，成功常为1，失败-1。 - 参数说明：
mode同getMaxAcc；max_acc目标值。 - 取值范围：
mode：0 / 1；max_acc：角 1~150（°/s²），坐标 1~400（mm/s²）。
编码器
vector<int> getServoEncoders()
- 功能：读取六关节伺服编码器值。
- 返回值：长度 6 的整型向量（以控制器解析为准）。
- 参数说明：无。
- 取值范围：无。
调试
编译时定义 ROBOT_ARM_DEBUG 可打开 RobotArm 内调试日志（见头文件注释）。