1.2 快速接入

推荐路径

推荐接入路径：

1. 先实例化 Arm
2. 调用 Connect(controllerIp, teachPanelIp) 建立主 RPC 连接
3. 通过 arm.controllerInfo / arm.motionControl / arm.programManager / ... 调用业务能力
4. 若使用订阅发布，再单独调用 arm.topicPubSub.Connect()
5. 结束时调用 Disconnect()

C++17 最小接入

示例代码

cpp17/info_get_controller_version/src/main.cpp

#include "query_version_and_model/run.h"
#include "query_statuses/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 RunInfoGetControllerVersionQueryVersionAndModel();
    // return RunInfoGetControllerVersionQueryStatuses();
}

cpp17/info_get_controller_version/src/query_version_and_model/run.cpp

#include <iostream>
#include "arm_api.h"
#include "status_code.h"

#include "query_version_and_model/run.h"

/**
 * 查询版本与型号门面。
 * @return 0 表示成功，否则返回 1。
 */
int RunInfoGetControllerVersionQueryVersionAndModel(void)
{
    // [ZH] 连接机器人，请直接修改下面的魔鬼字符串。
    // [EN] Connect to the robot and edit the hard-coded magic strings below directly.
    Arm arm;
    STATUS_CODE connectRet = arm.Connect("10.27.1.2", "10.27.1.102");
    if (connectRet != STATUS_CODE::OK) {
        std::cerr << "[cpp17_info_basic] 连接机器人失败 / Connect to the robot failed, 状态码 / Status code: "
                  << static_cast<int>(connectRet) << "\n";
        return 1;
    }
    std::cout << "[cpp17_info_basic] 机器人连接成功 / Robot connected successfully\n";
    // [ZH] 获取控制器版本和机械臂型号。
    // [EN] Get the controller version and robot model.
    std::pair<std::string, STATUS_CODE> versionPair = arm.controllerInfo.GetControllerVersion();
    std::pair<std::string, STATUS_CODE> modelPair = arm.controllerInfo.GetArmModelInfo();
    std::cout << "[cpp17_info_basic] GetControllerVersion 状态码 / GetControllerVersion status code: "
              << static_cast<int>(versionPair.second)
              << ", 版本 / Version: " << versionPair.first << "\n";
    std::cout << "[cpp17_info_basic] GetArmModelInfo 状态码 / GetArmModelInfo status code: "
              << static_cast<int>(modelPair.second)
              << ", 型号 / Model: " << modelPair.first << "\n";

    // [ZH] 断开连接，结束示例。
    // [EN] Disconnect and finish the example.
    arm.Disconnect();
    std::cout << "[cpp17_info_basic] 示例结束 / Example finished\n";
    return 0;
}

C99 最小接入

示例代码

c99/info_basic/src/main.cpp

#include <stdio.h>

extern "C" {
#include "c_arm_api.h"
}

int main(void)
{
    // [ZH] 本示例直接在源码中写死连接地址，不解析命令行参数。
    // [EN] This example hard-codes the connection addresses in the source code and does not parse command-line arguments.
    // [ZH] 创建并连接 SDK 句柄。
    // [EN] Create the SDK handle and connect to the robot.
    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[c99_info] 创建句柄失败 / Failed to create the handle\n");
        return 1;
    }
    int ret = Arm_Connect(handle, "10.27.1.2", "10.27.1.102");
    if (ret != 0) {
        printf("[c99_info] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_info] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 读取控制器版本与机械臂型号。
    // [EN] Read the controller version and robot model.
    char version[128] = {0};
    char model[128] = {0};
    ret = Arm_Info_GetControllerVersion(handle, version, sizeof(version));
    printf("[c99_info] GetControllerVersion 状态码 / GetControllerVersion status code: %d, 版本 / Version: %s\n", ret, version);
    ret = Arm_Info_GetArmModelInfo(handle, model, sizeof(model));
    printf("[c99_info] GetArmModelInfo 状态码 / GetArmModelInfo status code: %d, 型号 / Model: %s\n", ret, model);

    // [ZH] 获取并归还 SDK 控制权限。
    // [EN] Acquire and release the SDK control access.
    Arm_Info_AcquireAccess(handle);
    printf("[c99_info] 已获取控制权 / SDK access acquired\n");
    Arm_Info_ReleaseAccess(handle);
    printf("[c99_info] 已归还控制权 / SDK access released\n");

    // [ZH] 顺序读取全部状态类接口。
    // [EN] Read all status-oriented APIs in sequence.
    int opMode = 0;
    int ctrlStatus = 0;
    int robotStatus = 0;
    int servoStatus = 0;
    int softMode = 0;
    ret = Arm_Info_GetOpMode(handle, &opMode);
    printf("[c99_info] GetOpMode 状态码 / GetOpMode status code: %d, 操作模式 / Operation mode: %d\n", ret, opMode);
    ret = Arm_Info_GetCtrlStatus(handle, &ctrlStatus);
    printf("[c99_info] GetCtrlStatus 状态码 / GetCtrlStatus status code: %d, 控制器状态 / Controller status: %d\n", ret, ctrlStatus);
    ret = Arm_Info_GetRobotStatus(handle, &robotStatus);
    printf("[c99_info] GetRobotStatus 状态码 / GetRobotStatus status code: %d, 机器人状态 / Robot status: %d\n", ret, robotStatus);
    ret = Arm_Info_GetServoStatus(handle, &servoStatus);
    printf("[c99_info] GetServoStatus 状态码 / GetServoStatus status code: %d, 伺服状态 / Servo status: %d\n", ret, servoStatus);
    ret = Arm_Info_GetSoftMode(handle, &softMode);
    printf("[c99_info] GetSoftMode 状态码 / GetSoftMode status code: %d, 软模式 / Soft mode: %d\n", ret, softMode);

    // [ZH] 顺序执行全部写接口与动作接口。
    // [EN] Execute all setter APIs and action APIs in sequence.
    ret = Arm_Info_SetSoftMode(handle, softMode);
    printf("[c99_info] SetSoftMode 状态码 / SetSoftMode status code: %d\n", ret);
    ret = Arm_Info_SetOpMode(handle, opMode);
    printf("[c99_info] SetOpMode 状态码 / SetOpMode status code: %d\n", ret);
    ret = Arm_Info_SwitchLedLight(handle, 1);
    printf("[c99_info] SwitchLedLight 状态码 / SwitchLedLight status code: %d\n", ret);
    ret = Arm_Info_ServoOn(handle);
    printf("[c99_info] ServoOn 状态码 / ServoOn status code: %d\n", ret);
    ret = Arm_Info_ServoOff(handle);
    printf("[c99_info] ServoOff 状态码 / ServoOff status code: %d\n", ret);
    ret = Arm_Info_ServoReset(handle);
    printf("[c99_info] ServoReset 状态码 / ServoReset status code: %d\n", ret);
    ret = Arm_Info_Estop(handle);
    printf("[c99_info] Estop 状态码 / Estop status code: %d\n", ret);

    // [ZH] 断开连接并销毁句柄。
    // [EN] Disconnect and destroy the handle.
    Arm_Disconnect(handle);
    Arm_Destroy(handle);
    printf("[c99_info] 示例结束 / Example finished\n");
    return 0;
}

Connect 语义

项	说明
controllerIp	控制器 IP
teachPanelIp	可为空；为空时 SDK 会按默认连接规则推导，建议业务侧显式传入以避免歧义
地址补全	工业机器人地址组合和协作机器人地址组合会按 SDK 默认连接规则处理
成功后回填	version 、 model 、 robotType
同步绑定	controllerInfo 、 motionControl 、 programManager 、 ioSignals 、 registerBank 、 trajectoryManager 、 coordinateSystemManager 、 modbusClient 、 topicPubSub 等接口模块会在连接阶段可直接使用

连接后的公共成员

成员	作用	对应文档
version / model / robotType	连接时回填的设备识别信息	Arm
controllerInfo	控制器状态与基础控制	ControllerInfo
alarmClient	报警查询与复位	AlarmClient
motionControl	运动与负载	MotionControl
programManager	程序执行与点位	ProgramManager
ioSignals	IO 读写	IoSignals
registerBank	R/PR/SR/MR/MH/MI 寄存器	RegisterBank
trajectoryManager	离线轨迹、路径表	TrajectoryManager
realTimeTrajectoryControl	实时轨迹	RealTimeTrajectoryControl
controllerFileManager	文件上传下载与搜索	ControllerFileManager
joggingControl	示教运动	JoggingControl
extensionClient	插件服务	ExtensionClient
topicPubSub	WebSocket 订阅发布	TopicPubSub
coordinateSystemManager	坐标系管理	CoordinateSystemManager
modbusClient	Modbus 能力	ModbusClient

返回值约定

语言	返回形式
C++17	STATUS_CODE 或 std::pair<T, STATUS_CODE>
C99	int 状态码 + out 参数

C++17

• 纯动作接口返回 STATUS_CODE
• 查询接口返回 std::pair<T, STATUS_CODE>
• 连接未完成或接口模块未初始化时，失败数据位通常返回空字符串、 UNKNOWN 、零值结构或空容器

C99

• 返回值是 int 状态码
• 业务结果通过 out 参数返回
• 对字符串 / 数组输出，需额外关注缓冲区大小和 BUFFER_TOO_SMALL

单独连接 topicPubSub

Arm::Connect() 只负责把 topicPubSub 绑定到当前控制器 / 示教器地址； 真正建立 WebSocket 连接仍需调用：

STATUS_CODE ret = arm.topicPubSub.Connect();  // 使用 Arm::Connect() 绑定的地址建立 TopicPubSub WebSocket 连接

如果你直接单独使用 TopicPubSub 对象，而不是从 Arm 进入，则要显式传入地址：

TopicPubSub topicPubSub;  // 创建独立的 TopicPubSub 对象
STATUS_CODE ret = topicPubSub.Connect("192.168.110.102");  // 显式传入示教器或代理侧 WebSocket 地址