3.1 Arm 主入口

概述

Arm 是 C++17 SDK 的统一入口。对调用方来说，它主要负责三件事：

1. 管理会话生命周期： Connect() / Disconnect()
2. 在连接成功后回填设备识别信息： version 、 model 、 robotType
3. 暴露业务接口模块： controllerInfo 、 motionControl 、 programManager 、 ioSignals 、 topicPubSub 等

公开字段与子接口模块

设备识别字段

字段	类型	说明
version	std::string	控制器版本，连接成功后回填
model	std::string	机械臂型号，连接成功后回填
robotType	RobotType	机器人类型，连接成功后回填

业务接口模块

成员	作用	对应文档
controllerInfo	基础状态与控制	3.2-info
alarmClient	报警查询与复位	3.3-alarm
programManager	程序执行与点位	3.5-program
motionControl	运动与负载	3.4-motion
ioSignals	IO 读写	3.7-signals
registerBank	寄存器	3.8-registers
trajectoryManager	轨迹与路径表	3.9-trajectory
realTimeTrajectoryControl	实时轨迹	3.9-trajectory
controllerFileManager	文件管理	3.10-file-manager
topicPubSub	WebSocket 订阅发布	3.13-sub-pub
joggingControl	示教运动	3.11-jogging
extensionClient	插件服务	3.12-extension
coordinateSystemManager	坐标系管理	3.15-coordinate-system
modbusClient	ModbusClient	3.14-modbus

---

3.1.1 构造函数

Arm()

项	说明
描述	创建机器人会话对象，无需手动加载配置，类会在连接时完成 SDK 版本检查、控制器类型识别。
请求参数	无
返回值	构造对象
兼容的机器人软件版本	协作 (Copper): v7.5.0.0+ 工业 (Bronze): v7.5.0.0+

3.1.2 连接机器人

Connect(const std::string& controllerIp, const std::string& teachPanelIp = "") -> STATUS_CODE

项	说明
描述	连接捷勃特机器人。该方法会启动 Arm 的专用网络线程，绑定各业务接口模块，并在连上后回填 version 、 model 、 robotType 。
请求参数	controllerIp ： std::string ，控制器 IP 地址。 teachPanelIp ： std::string ，示教器 IP 地址（可选，工业机器人建议传入）。
返回值	STATUS_CODE: 函数执行结果
备注	- 当 controllerIp 或 teachPanelIp 不是合法 IP 时，返回 INVALID_IP_ADDRESS 。 - 若无法连接控制器，会返回 OTHER_ERR 并附带错误信息。
兼容的机器人软件版本	协作 (Copper): v7.5.0.0+ 工业 (Bronze): v7.5.0.0+

连接成功后可以直接使用的内容

连接成功后：

1. version 、 model 、 robotType 会被回填
2. controllerInfo 、 alarmClient 、 programManager 、 motionControl 、 ioSignals 、 registerBank 、 trajectoryManager 、 controllerFileManager 、 joggingControl 、 extensionClient 、 coordinateSystemManager 、 modbusClient 可直接调用
3. topicPubSub 会记录默认目标地址，后续可以直接 arm.topicPubSub.Connect()

3.1.3 判断与机器人的连接是否有效

IsConnected() const -> bool

项	说明
描述	判断与机器人的连接是否有效
请求参数	无参数
返回值	bool: 连接状态，True: 连接有效，False: 连接失效
兼容的机器人软件版本	协作 (Copper): v7.5.0.0+ 工业 (Bronze): v7.5.0.0+

3.1.4 判断 SDK 是否完成初始化

IsInitialized() const -> bool

项	说明
描述	判断本地网络线程对象是否已创建。对正常构造的 Arm 来说，它通常始终为 true 。
请求参数	无参数
返回值	bool: True 表示初始化完成，可以尝试 Connect() ；False 表示初始化失败
兼容的机器人软件版本	协作 (Copper): v7.5.0.0+ 工业 (Bronze): v7.5.0.0+

3.1.5 与机器人断开连接

Disconnect()

项	说明
描述	断开与捷勃特机器人的连接，清理所有接口模块绑定状态，并停止专用网络线程。
请求参数	无参数
返回值	无返回
行为	- 主动断开 topicPubSub - 清理 joggingControl 、 extensionClient - 清空 controllerIp 、 teachPanelIp 、 version 、 model - 把 robotType 重置为 UNKNOWN
兼容的机器人软件版本	协作 (Copper): v7.5.0.0+ 工业 (Bronze): v7.5.0.0+

什么时候需要手动调用

• 正常业务结束时应主动调用
• 发生错误准备切换设备时应主动调用
• 即使析构会兜底调用，也不建议完全依赖析构清理

---

3.1.6 地址归一化行为

Connect() 对少量已知默认拓扑保留了兼容补全规则。业务侧如果已经知道两端地址，还是建议显式传入，不要依赖隐式补全。

输入	结果
controllerIp = "192.168.110.2" ， teachPanelIp = ""	自动把 teachPanelIp 补成 192.168.110.102
controllerIp = "192.168.110.102" ， teachPanelIp = ""	自动把 controllerIp 纠正为 192.168.110.2 ，同时把 teachPanelIp 设为 192.168.110.102
controllerIp 有值， teachPanelIp = ""	对协作机器人，SDK 会把空的 teachPanelIp 归一化为 controllerIp
controllerIp 和 teachPanelIp 都显式传入	使用用户显式输入值

---

3.1.7 连接限制与行为

• Connect() 是所有业务接口模块的前置条件。
• 如果当前已经连接到相同的 controllerIp + teachPanelIp 组合，会直接返回 OK 。
• 如果当前已连接到其他设备， Connect() 会先自动 Disconnect() ，再切换到新设备。
• 连接阶段如果版本查询失败，会自动回滚连接状态。

---

3.1.8 线程模型（调用方视角）

• 这里说的 “同步”，指的是调用方发起请求后等待结果返回，不是 SDK 再替业务线程额外开一条同步线程。
• 一个 Arm 会话对应一条专用网络线程；同一个 Arm 上的大多数网络请求会串行执行。
• ControllerInfo::AcquireAccess() 和 JoggingControl::ContinuousMove() / MultiMove() 的周期任务复用这条网络线程，不额外暴露独立业务线程。
• TopicPubSub::StartReceiving() 的回调运行在独立的 WebSocket 接收线程，回调里应只做轻量逻辑。
• 更完整的并发约束见 1.3-thread-model。

---

最小调用示例

示例代码

cpp17/arm_connect_disconnect/src/main.cpp

#include "connect_disconnect/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunArmConnectDisconnectLifecycle();
}

cpp17/arm_reconnect/src/main.cpp

#include "reconnect_once/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunArmReconnectOnce();
}

cpp17/sub_pub_basic/src/main.cpp

#include "multi_instance_isolation/run.h"
#include "subscribe_topics/run.h"
#include "send_receive_text/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunSubPubBasicSubscribeTopics();
    // return RunSubPubBasicSendReceiveText();
    // return RunSubPubBasicMultiInstanceIsolation();
}

cpp17/info_state_modes/src/main.cpp

#include "query_state_modes/run.h"
#include "write_back_modes/run.h"
#include "access_control/run.h"
#include "action_apis/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunInfoStateModesQueryStateModes();
    // return RunInfoStateModesWriteBackModes();
    // return RunInfoStateModesAccessControl();
    // return RunInfoStateModesActionApis();
}