示例与 TestApi.cpp（RobotDriver）

main.cpp为简单的读取版本信息使用案例，examples文件夹含各个接口使用案例、老化案例等；
本文档说明工程 examples/TestApi.cpp 的编写意图与各段代码对应的 RobotArm 用法，适用于 MyCobotPro450、Linux 下 TCP 联调。环境搭建与编译见 6.4.1、6.4.2；接口释义见 6.4.7 API。

重要提示（请先阅读）

• TestApi.cpp 是联调演示脚本，按块依次调用大量接口，不等于生产环境可直接运行的安全程序。
• 请勿在不理解含义的情况下整文件编译执行：可能触发大幅度运动、长时间 JOG、拖动示教录制等；务必在净空、急停可达、已理解每段作用后再试。
• 建议做法：按业务需要复制其中若干段到自有 main，删掉无关测试；参数（IP、端口、角度、坐标、速度）按现场修改。
• 编译注意：当前根目录 CMakeLists.txt 中 examples/TestApi.cpp 默认被注释，未编入 RobotDriver 可执行文件。若要以该文件为入口，需在 CMakeLists.txt 的 SRC_SOURCES 中取消注释并视情况注释其它示例源，或单独为 TestApi.cpp 增加 add_executable，避免多个 main 冲突。

源码中 RobotArm robot(1, params) 的 1 即 TCP_COMM（与 include/Protocol.hpp 一致）。

文档约定以下各节与 TestApi.cpp 内 // ========== N. 注释块一一对应。每节给出 作用、主要涉及接口、使用注意，便于按需借鉴。

1. 系统配置、版本信息

• 作用：上电前读取主控/机型/末端/库版本，确认通信与固件信息。
• 主要涉及接口：getSystemVersion、getModifyVersion、getRobotType、getAtomVersion、getToolModifyVersion、getLibVersion。
• 使用注意：无运动风险；版本字符串格式以固件为准。

2. 上电与状态查询

• 作用：上电，并查询上电状态、刷新模式、自由移动模式、零位校准首项等。
• 主要涉及接口：powerOn、isPowerOn、getFreshMode、setFreeMoveMode、getFreeMoveMode、isInitCalibration。
• 使用注意：powerOff()、切换 setFreshMode 等在源码中注释掉——下电约耗时数秒；切换刷新模式后固件侧可能有较长内部延时（源码注释示例为约 6 s），慎用。

3. 运动控制模式

• 作用：读取当前为位置模式还是力矩模式。
• 主要涉及接口：getControlMode；（可选）setControlMode。
• 使用注意：切换模式前确认机械臂状态与安全空间。

4. 关节角度控制

• 作用：读取单关节/全关节角；演示开环（setWaitArrival(false) +发指令 + usleep 手动等待）与闭环（setWaitArrival(true)，sendAngles 侧等待到位）的差异。
• 主要涉及接口：getAngle、getAngles、setFreeMoveMode、setWaitArrival、getWaitArrival、sendAngle、sendAngles。
• 使用注意：
  • 发位置指令前通常需 关闭自由移动模式（示例中 setFreeMoveMode(0)），否则固件可能不执行位置指令。
  • 目标角与速度须符合 关节控制 中的 MyCobotPro450 范围。

5. 坐标控制

• 作用：读取当前 getCoords；单轴 sendCoord 开环示例；stop 打断。
• 主要涉及接口：getCoords、sendCoord、stop。
• 使用注意：
  • 源码注释指出：SendCoords({0,0,0,0,0,0}) 一类无效位姿可能导致固件异常刷 POS_ARRIVED，演示中已禁用，请勿盲目套用全零坐标。
  • 坐标与速度范围见 坐标控制。

6. 运动状态控制

• 作用：查询是否运动中；pause / isPaused / resume / stop；isInPosition 角度模式示例。
• 主要涉及接口：isMoving、pause、isPaused、resume、stop、isInPosition。
• 使用注意：isInPosition 第二参数为 false 表示按角度比较；示例中目标为全零，实际使用请改为真实目标且注意限位。

7. 软件关节限位

• 作用：循环打印各关节软件最小/最大角。
• 主要涉及接口：getJointMinAngle、getJointMaxAngle。
• 使用注意：只读，无运动。

8. 速度 / 加速度参数

• 作用：读取并示例性写入角度/坐标最大速度、最大加速度。
• 主要涉及接口：getMaxSpeed、setMaxSpeed、getMaxAcc、setMaxAcc。
• 使用注意：mode 0 为关节角相关，1 为坐标相关；数值有效范围见 6.4.7。不当设置可能影响运动平滑度与安全。

9. 编码器

• 作用：读取六路伺服编码器整数。
• 主要涉及接口：getServoEncoders。
• 使用注意：解析与单位以下位机为准。

10. JOG 模式

• 作用：关节 jogAngle 与坐标 jogCoord 各运行一段时间后用 stop 结束。
• 主要涉及接口：jogAngle、jogCoord、stop。
• 使用注意：JOG 为持续运动，必须预留 stop 或限位保护；方向 0/1、速度 1~100。

11. 拖动示教

• 作用：stop 停稳 → 开自由移动 → dragTeachSave 录制 → dragTeachPause → 关自由移动 → dragTeachExecute 回放 → dragTeachClean 清除。
• 主要涉及接口：stop、setFreeMoveMode、dragTeachSave、dragTeachPause、dragTeachExecute、dragTeachClean。
• 使用注意：录制时长建议 ≤ 120 s；需在安全环境下人工拖动；若无需示教功能，整段可删除，勿照搬执行。

12. 异常信息（源码注释为13）

• 作用：读取运动报错、clearErrorInfomation；打印 getRobotStatusDetail 中碰撞、运动、限位、关节状态、通信状态等字段。
• 主要涉及接口：getErrorInformation、clearErrorInfomation、getRobotStatusDetail。
• 使用注意：clearErrorInfomation 拼写与头文件一致；错误码含义见 6.4.7。源码中 getMotorsRunErr 保留为注释，需要时可自行打开。

小结

再次强调：按块裁剪使用，修改 IP/端口与运动参数，并在安全环境下验证。

← 上一章 | 返回 C++ 引导