捷勃特机器人 SDK
搜索 K

中文

English
한국어

中文

English
한국어

外观

4.2 C99 Info 信息接口 ​

概述 ​

C99 Info 负责控制器版本、机器人型号、控制器状态、机器人状态、伺服状态、软模式、操作模式、LED、急停、伺服上下电和控制权保活。

对应头文件：

  • include/c_arm_info.h

接口签名 ​

Arm_Info_GetControllerVersion ​

c
int Arm_Info_GetControllerVersion(ArmHandle* h, char* outVersion, size_t bufSize);
项说明
描述读取控制器版本字符串。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
outVersion : char* ，控制器版本输出缓冲区
bufSize : size_t ，输出缓冲区大小，包含结尾 \0 的空间
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_GetArmModelInfo ​

c
int Arm_Info_GetArmModelInfo(ArmHandle* h, char* outModel, size_t bufSize);
项说明
描述读取机器人型号字符串。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
outModel : char* ，机器人型号输出缓冲区
bufSize : size_t ，输出缓冲区大小，包含结尾 \0 的空间
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_AcquireAccess ​

c
void Arm_Info_AcquireAccess(ArmHandle* h);
项说明
描述开始获取或保持控制权。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值无返回值

Arm_Info_ReleaseAccess ​

c
void Arm_Info_ReleaseAccess(ArmHandle* h);
项说明
描述释放控制权保活。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值无返回值

Arm_Info_SwitchLedLight ​

c
int Arm_Info_SwitchLedLight(ArmHandle* h, int mode);
项说明
描述切换机器人 LED 指示灯状态。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
mode : int ，LED 开关值，非 0 表示开启， 0 表示关闭
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_Estop ​

c
int Arm_Info_Estop(ArmHandle* h);
项说明
描述触发机器人急停。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_ServoReset ​

c
int Arm_Info_ServoReset(ArmHandle* h);
项说明
描述复位伺服状态。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_GetOpMode ​

c
int Arm_Info_GetOpMode(ArmHandle* h, int* outMode);
项说明
描述读取当前操作模式。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
outMode : int* ，模式输出指针
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_GetCtrlStatus ​

c
int Arm_Info_GetCtrlStatus(ArmHandle* h, int* outStatus);
项说明
描述读取控制器运行状态。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
outStatus : int* ，状态输出指针
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_GetRobotStatus ​

c
int Arm_Info_GetRobotStatus(ArmHandle* h, int* outStatus);
项说明
描述读取机器人运行状态。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
outStatus : int* ，状态输出指针
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_GetServoStatus ​

c
int Arm_Info_GetServoStatus(ArmHandle* h, int* outStatus);
项说明
描述读取伺服状态。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
outStatus : int* ，状态输出指针
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_ServoOn ​

c
int Arm_Info_ServoOn(ArmHandle* h);
项说明
描述执行伺服上电。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_ServoOff ​

c
int Arm_Info_ServoOff(ArmHandle* h);
项说明
描述执行伺服下电。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_GetSoftMode ​

c
int Arm_Info_GetSoftMode(ArmHandle* h, int* outMode);
项说明
描述读取当前软模式。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
outMode : int* ，模式输出指针
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_SetSoftMode ​

c
int Arm_Info_SetSoftMode(ArmHandle* h, int mode);
项说明
描述设置当前软模式。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
mode : int ，目标软模式值，取值同 Arm_Info_GetSoftMode() 返回值
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

Arm_Info_SetOpMode ​

c
int Arm_Info_SetOpMode(ArmHandle* h, int mode);
项说明
描述设置当前操作模式。
请求参数h : ArmHandle* ，C99 会话句柄，通常来自 Arm_Create() ，业务接口需要先连接成功
mode : int ，目标操作模式， 1=AUTO 、 2=MANUAL_LIMIT 、 3=MANUAL
返回值STATUS_CODE 整数值； 0 表示成功，其他值按状态码处理

函数分组 ​

分组函数说明
基础信息Arm_Info_GetControllerVersion / Arm_Info_GetArmModelInfo读取版本和型号字符串
状态查询Arm_Info_GetCtrlStatus / Arm_Info_GetRobotStatus / Arm_Info_GetServoStatus读取运行状态
模式读写Arm_Info_GetSoftMode / Arm_Info_SetSoftMode / Arm_Info_GetOpMode / Arm_Info_SetOpMode读取或切换模式
控制动作Arm_Info_SwitchLedLight / Arm_Info_Estop / Arm_Info_ServoReset / Arm_Info_ServoOn / Arm_Info_ServoOff改变控制器或机器人状态
权限保活Arm_Info_AcquireAccess / Arm_Info_ReleaseAccess工业场景下的 PC 控制权保活

参数与返回 ​

项规则
字符串输出outVersion / outModel 不能为空， bufSize 必须大于 0
缓冲区不足返回 BUFFER_TOO_SMALL
状态输出outStatus / outMode 不能为空
模式值1=AUTO 、 2=MANUAL_LIMIT 、 3=MANUAL ； Arm_Info_SetOpMode() 传 0=UNKNOWN 时返回 UNSUPPORTED_PARAMETER
动作型接口LED、急停、伺服和模式写入会改变现场状态
AcquireAccess / ReleaseAccess无返回值，通常作为保活任务的开始和结束

使用前提与控制权 ​

场景说明
查询接口未连接返回错误码，字符串输出为空，状态或模式输出保持调用方可控值
控制接口未连接返回错误码，不下发控制动作
Arm_Info_AcquireAccess()启动控制权保活；重复调用会先释放已有保活任务；保活周期为 2000ms
Arm_Info_ReleaseAccess()停止控制权保活；未启动保活时可直接调用
断开或销毁句柄会结束当前会话上的控制权保活

连接后建议先读取控制器版本、机器人型号和当前模式，再执行模式写入、伺服、LED 或急停等动作型接口。 Arm_Info_AcquireAccess() 常用于工业机器人 PC 模式保活，协作机器人通常不需要调用。

最小调用示例 ​

c
#include <stdio.h>  // 引入 printf，用于打印版本和状态
#include "c_arm_api.h"  // 引入 C99 SDK 总头文件
int main(void)  // 示例程序入口
{  // 进入示例主函数
    ArmHandle* h = Arm_Create();  // 创建 C99 会话句柄
    char version[128] = {0};  // 准备控制器版本缓冲区
    int servoStatus = 0;  // 准备伺服状态输出变量
    if (h == NULL) {  // 判断句柄是否创建失败
        return 1;  // 创建失败时退出
    }  // 结束句柄判断
    if (Arm_Connect(h, "10.27.1.2", "10.27.1.102") != 0) {  // 连接控制器
        Arm_Destroy(h);  // 连接失败时释放句柄
        return 1;  // 返回错误
    }  // 结束连接判断
    int versionRet = Arm_Info_GetControllerVersion(h, version, sizeof(version));  // 读取控制器版本
    int statusRet = Arm_Info_GetServoStatus(h, &servoStatus);  // 读取伺服状态
    printf("version=%s servo=%d\n", version, servoStatus);  // 打印读取结果
    Arm_Disconnect(h);  // 断开连接
    Arm_Destroy(h);  // 销毁句柄
    return versionRet == 0 && statusRet == 0 ? 0 : 1;  // 根据查询结果返回
}  // 结束示例主函数

场景化示例 ​

读取版本、型号和状态 ​

c
char version[128] = {0};  // 准备版本输出缓冲区
char model[128] = {0};  // 准备型号输出缓冲区
int ctrlStatus = 0;  // 准备控制器状态输出变量
int robotStatus = 0;  // 准备机器人状态输出变量
int servoStatus = 0;  // 准备伺服状态输出变量
int versionRet = Arm_Info_GetControllerVersion(h, version, sizeof(version));  // 读取控制器版本
int modelRet = Arm_Info_GetArmModelInfo(h, model, sizeof(model));  // 读取机器人型号
int ctrlRet = Arm_Info_GetCtrlStatus(h, &ctrlStatus);  // 读取控制器状态
int robotRet = Arm_Info_GetRobotStatus(h, &robotStatus);  // 读取机器人状态
int servoRet = Arm_Info_GetServoStatus(h, &servoStatus);  // 读取伺服状态
(void)versionRet;  // 示例中保留版本查询状态码
(void)modelRet;  // 示例中保留型号查询状态码
(void)ctrlRet;  // 示例中保留控制器状态码
(void)robotRet;  // 示例中保留机器人状态码
(void)servoRet;  // 示例中保留伺服状态码

模式读写 ​

c
int softMode = 0;  // 准备软模式输出变量
int opMode = 0;  // 准备操作模式输出变量
int getSoftRet = Arm_Info_GetSoftMode(h, &softMode);  // 读取软模式
int getOpRet = Arm_Info_GetOpMode(h, &opMode);  // 读取操作模式
/* int setSoftRet = Arm_Info_SetSoftMode(h, softMode); */  // 写回软模式会改变控制状态，确认后再执行
/* int setOpRet = Arm_Info_SetOpMode(h, opMode); */  // 写回操作模式会改变控制状态，确认后再执行
(void)getSoftRet;  // 示例中保留软模式查询状态码
(void)getOpRet;  // 示例中保留操作模式查询状态码

控制动作 ​

c
Arm_Info_AcquireAccess(h);  // 获取或保持 SDK 控制权限
/* int ledRet = Arm_Info_SwitchLedLight(h, 1); */  // 切换 LED 会改变现场显示，确认后再执行
/* int resetRet = Arm_Info_ServoReset(h); */  // 伺服复位会改变设备状态，确认后再执行
/* int servoOnRet = Arm_Info_ServoOn(h); */  // 伺服上电会改变设备状态，确认后再执行
/* int servoOffRet = Arm_Info_ServoOff(h); */  // 伺服下电会改变设备状态，确认后再执行
/* int estopRet = Arm_Info_Estop(h); */  // 急停是动作型接口，确认后再执行
Arm_Info_ReleaseAccess(h);  // 释放 SDK 控制权限

示例代码

c99/info_basic/src/main.cpp
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;
}
mingw_c99/gcc_capi_info_read/src/main.c
c
#include <stdio.h>

#include "c_arm_api.h"

int main(void)
{
    // [ZH] 本示例使用 MinGW/GCC 直接调用 C99 接口，并通过 libAgilebotCppSdk.dll.a 链接 DLL。
    // [EN] This example uses MinGW/GCC to call the C99 API directly and links the DLL through libAgilebotCppSdk.dll.a.
    const char* controller_ip = "10.27.1.2";
    const char* teach_panel_ip = "10.27.1.102";
    int ret = 0;

    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[gcc_capi_info_read] 创建句柄失败 / Failed to create handle\n");
        return 1;
    }

    // [ZH] 连接前先查询一次状态，便于确认 import library、DLL 与基础句柄函数都可用。
    // [EN] Query once before connecting to validate the import library, DLL, and basic handle APIs.
    printf("[gcc_capi_info_read] 连接前状态 / State before connect: %d\n", Arm_IsConnected(handle));

    ret = Arm_Connect(handle, controller_ip, teach_panel_ip);
    if (ret != 0) {
        printf("[gcc_capi_info_read] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[gcc_capi_info_read] 连接后状态 / State after connect: %d\n", Arm_IsConnected(handle));

    // [ZH] 只调用读接口，适合作为客户 MinGW 环境的低风险联调模板。
    // [EN] Only read APIs are used, making this a low-risk integration template for customer MinGW environments.
    char version[128] = {0};
    ret = Arm_Info_GetControllerVersion(handle, version, sizeof(version));
    printf("[gcc_capi_info_read] GetControllerVersion 状态码 / Status code: %d, 版本 / Version: %s\n", ret, version);

    char model[128] = {0};
    ret = Arm_Info_GetArmModelInfo(handle, model, sizeof(model));
    printf("[gcc_capi_info_read] GetArmModelInfo 状态码 / Status code: %d, 型号 / Model: %s\n", ret, model);

    int op_mode = 0;
    ret = Arm_Info_GetOpMode(handle, &op_mode);
    printf("[gcc_capi_info_read] GetOpMode 状态码 / Status code: %d, 操作模式 / Operation mode: %d\n", ret, op_mode);

    int ctrl_status = 0;
    ret = Arm_Info_GetCtrlStatus(handle, &ctrl_status);
    printf("[gcc_capi_info_read] GetCtrlStatus 状态码 / Status code: %d, 控制器状态 / Controller status: %d\n", ret, ctrl_status);

    int robot_status = 0;
    ret = Arm_Info_GetRobotStatus(handle, &robot_status);
    printf("[gcc_capi_info_read] GetRobotStatus 状态码 / Status code: %d, 机器人状态 / Robot status: %d\n", ret, robot_status);

    int servo_status = 0;
    ret = Arm_Info_GetServoStatus(handle, &servo_status);
    printf("[gcc_capi_info_read] GetServoStatus 状态码 / Status code: %d, 伺服状态 / Servo status: %d\n", ret, servo_status);

    int soft_mode = 0;
    ret = Arm_Info_GetSoftMode(handle, &soft_mode);
    printf("[gcc_capi_info_read] GetSoftMode 状态码 / Status code: %d, 软模式 / Soft mode: %d\n", ret, soft_mode);

    // [ZH] 清理连接与句柄。
    // [EN] Clean up connection and handle.
    Arm_Disconnect(handle);
    printf("[gcc_capi_info_read] 断开后状态 / State after disconnect: %d\n", Arm_IsConnected(handle));
    Arm_Destroy(handle);
    printf("[gcc_capi_info_read] 示例结束 / Example finished\n");
    return 0;
}

Copyright © 2026-present Agilebot Robotics Co., Ltd.