4.2 C99 Info APIs

Overview

The C99 Info APIs cover controller version and robot model queries, controller and robot status, servo status, soft mode, operation mode, LED control, emergency stop, servo power control, and control-access keepalive.

Header file:

include/c_arm_info.h

API Signatures

`Arm_Info_GetControllerVersion`

int Arm_Info_GetControllerVersion(ArmHandle* h, char* outVersion, size_t bufSize);

Item	Description
Description	Reads the controller version string.
Request parameters	`h` : `ArmHandle` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `outVersion` : `char` , output buffer for the controller version `bufSize` : `size_t` , size of the output buffer, including space for the trailing `\0`
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_GetArmModelInfo`

int Arm_Info_GetArmModelInfo(ArmHandle* h, char* outModel, size_t bufSize);

Item	Description
Description	Reads the robot model string.
Request parameters	`h` : `ArmHandle` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `outModel` : `char` , output buffer for the robot model `bufSize` : `size_t` , size of the output buffer, including space for the trailing `\0`
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_AcquireAccess`

void Arm_Info_AcquireAccess(ArmHandle* h);

Item	Description
Description	Starts acquiring or keeping control access.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first
Return value	No return value

`Arm_Info_ReleaseAccess`

void Arm_Info_ReleaseAccess(ArmHandle* h);

Item	Description
Description	Releases the control-access keepalive task.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first
Return value	No return value

`Arm_Info_SwitchLedLight`

int Arm_Info_SwitchLedLight(ArmHandle* h, int mode);

Item	Description
Description	Switches the robot LED indicator state.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `mode` : `int` , LED switch value; non-zero means on, and `0` means off
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_Estop`

int Arm_Info_Estop(ArmHandle* h);

Item	Description
Description	Triggers an emergency stop on the robot.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_ServoReset`

int Arm_Info_ServoReset(ArmHandle* h);

Item	Description
Description	Resets the servo state.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_GetOpMode`

int Arm_Info_GetOpMode(ArmHandle* h, int* outMode);

Item	Description
Description	Reads the current operation mode.
Request parameters	`h` : `ArmHandle` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `outMode` : `int` , mode output pointer
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_GetCtrlStatus`

int Arm_Info_GetCtrlStatus(ArmHandle* h, int* outStatus);

Item	Description
Description	Reads the controller running state.
Request parameters	`h` : `ArmHandle` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `outStatus` : `int` , status output pointer
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_GetRobotStatus`

int Arm_Info_GetRobotStatus(ArmHandle* h, int* outStatus);

Item	Description
Description	Reads the robot running state.
Request parameters	`h` : `ArmHandle` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `outStatus` : `int` , status output pointer
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_GetServoStatus`

int Arm_Info_GetServoStatus(ArmHandle* h, int* outStatus);

Item	Description
Description	Reads the servo state.
Request parameters	`h` : `ArmHandle` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `outStatus` : `int` , status output pointer
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_ServoOn`

int Arm_Info_ServoOn(ArmHandle* h);

Item	Description
Description	Powers on the servo system.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_ServoOff`

int Arm_Info_ServoOff(ArmHandle* h);

Item	Description
Description	Powers off the servo system.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_GetSoftMode`

int Arm_Info_GetSoftMode(ArmHandle* h, int* outMode);

Item	Description
Description	Reads the current soft mode.
Request parameters	`h` : `ArmHandle` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `outMode` : `int` , mode output pointer
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_SetSoftMode`

int Arm_Info_SetSoftMode(ArmHandle* h, int mode);

Item	Description
Description	Sets the current soft mode.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `mode` : `int` , target soft-mode value, using the same value set returned by `Arm_Info_GetSoftMode()`
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

`Arm_Info_SetOpMode`

int Arm_Info_SetOpMode(ArmHandle* h, int mode);

Item	Description
Description	Sets the current operation mode.
Request parameters	`h` : `ArmHandle*` , C99 session handle, usually created by `Arm_Create()` ; service APIs require a successful connection first `mode` : `int` , target operation mode: `1=AUTO` , `2=MANUAL_LIMIT` , `3=MANUAL`
Return value	Integer `STATUS_CODE` ; `0` means success, and other values should be handled according to the status-code definitions

Function Groups

Group	Functions	Description
Basic information	`Arm_Info_GetControllerVersion` / `Arm_Info_GetArmModelInfo`	Reads version and model strings
Status queries	`Arm_Info_GetCtrlStatus` / `Arm_Info_GetRobotStatus` / `Arm_Info_GetServoStatus`	Reads running states
Mode read/write	`Arm_Info_GetSoftMode` / `Arm_Info_SetSoftMode` / `Arm_Info_GetOpMode` / `Arm_Info_SetOpMode`	Reads or switches modes
Control actions	`Arm_Info_SwitchLedLight` / `Arm_Info_Estop` / `Arm_Info_ServoReset` / `Arm_Info_ServoOn` / `Arm_Info_ServoOff`	Changes controller or robot state
Access keepalive	`Arm_Info_AcquireAccess` / `Arm_Info_ReleaseAccess`	Keeps PC control access alive in industrial scenarios

Parameters and Return Values

Item	Rule
String outputs	`outVersion` / `outModel` must not be null, and `bufSize` must be greater than `0`
Buffer too small	Returns `BUFFER_TOO_SMALL`
Status outputs	`outStatus` / `outMode` must not be null
Mode values	`1=AUTO` , `2=MANUAL_LIMIT` , `3=MANUAL` ; passing `0=UNKNOWN` to `Arm_Info_SetOpMode()` returns `UNSUPPORTED_PARAMETER`
Action APIs	LED, emergency stop, servo, and mode-write APIs change the on-site robot or controller state
`AcquireAccess` / `ReleaseAccess`	No return value; normally used as the start and end of a keepalive task

Prerequisites and Control Access

Scenario	Description
Query API called before connection	Returns an error code; string outputs are cleared, and status or mode outputs remain under caller control
Control API called before connection	Returns an error code and does not issue a control command
`Arm_Info_AcquireAccess()`	Starts the control-access keepalive task; repeated calls release the existing keepalive task first; the keepalive period is `2000ms`
`Arm_Info_ReleaseAccess()`	Stops the control-access keepalive task; it can be called even if keepalive has not been started
Disconnecting or destroying the handle	Ends the control-access keepalive task for the current session

After connecting, read the controller version, robot model, and current modes before calling mode-write, servo, LED, or emergency-stop APIs. Arm_Info_AcquireAccess() is usually used to keep PC control access alive for industrial robots; collaborative robots normally do not need it.

Minimal Example

#include <stdio.h>  // Provides printf for printing the version and status.
#include "c_arm_api.h"  // Includes the aggregate C99 SDK header.
int main(void)  // Example program entry point.
{  // Enters the example main function.
    ArmHandle* h = Arm_Create();  // Creates a C99 session handle.
    char version[128] = {0};  // Prepares the controller-version buffer.
    int servoStatus = 0;  // Prepares the servo-status output variable.
    if (h == NULL) {  // Checks whether handle creation failed.
        return 1;  // Exits when creation fails.
    }  // Ends the handle check.
    if (Arm_Connect(h, "10.27.1.2", "10.27.1.102") != 0) {  // Connects to the controller.
        Arm_Destroy(h);  // Releases the handle after connection failure.
        return 1;  // Returns an error.
    }  // Ends the connection check.
    int versionRet = Arm_Info_GetControllerVersion(h, version, sizeof(version));  // Reads the controller version.
    int statusRet = Arm_Info_GetServoStatus(h, &servoStatus);  // Reads the servo status.
    printf("version=%s servo=%d\n", version, servoStatus);  // Prints the read result.
    Arm_Disconnect(h);  // Disconnects from the controller.
    Arm_Destroy(h);  // Destroys the handle.
    return versionRet == 0 && statusRet == 0 ? 0 : 1;  // Returns according to the query result.
}  // Ends the example main function.

Scenario Examples

Read Version, Model, and Status

char version[128] = {0};  // Prepares the version output buffer.
char model[128] = {0};  // Prepares the model output buffer.
int ctrlStatus = 0;  // Prepares the controller-status output variable.
int robotStatus = 0;  // Prepares the robot-status output variable.
int servoStatus = 0;  // Prepares the servo-status output variable.
int versionRet = Arm_Info_GetControllerVersion(h, version, sizeof(version));  // Reads the controller version.
int modelRet = Arm_Info_GetArmModelInfo(h, model, sizeof(model));  // Reads the robot model.
int ctrlRet = Arm_Info_GetCtrlStatus(h, &ctrlStatus);  // Reads the controller status.
int robotRet = Arm_Info_GetRobotStatus(h, &robotStatus);  // Reads the robot status.
int servoRet = Arm_Info_GetServoStatus(h, &servoStatus);  // Reads the servo status.
(void)versionRet;  // Keeps the version-query status code in this example.
(void)modelRet;  // Keeps the model-query status code in this example.
(void)ctrlRet;  // Keeps the controller-status code in this example.
(void)robotRet;  // Keeps the robot-status code in this example.
(void)servoRet;  // Keeps the servo-status code in this example.

Read and Write Modes

int softMode = 0;  // Prepares the soft-mode output variable.
int opMode = 0;  // Prepares the operation-mode output variable.
int getSoftRet = Arm_Info_GetSoftMode(h, &softMode);  // Reads the soft mode.
int getOpRet = Arm_Info_GetOpMode(h, &opMode);  // Reads the operation mode.
/* int setSoftRet = Arm_Info_SetSoftMode(h, softMode); */  // Writing the soft mode changes the control state; execute only after confirmation.
/* int setOpRet = Arm_Info_SetOpMode(h, opMode); */  // Writing the operation mode changes the control state; execute only after confirmation.
(void)getSoftRet;  // Keeps the soft-mode query status code in this example.
(void)getOpRet;  // Keeps the operation-mode query status code in this example.

Control Actions

Arm_Info_AcquireAccess(h);  // Acquires or keeps SDK control access.
/* int ledRet = Arm_Info_SwitchLedLight(h, 1); */  // Switching the LED changes on-site indication; execute only after confirmation.
/* int resetRet = Arm_Info_ServoReset(h); */  // Servo reset changes device state; execute only after confirmation.
/* int servoOnRet = Arm_Info_ServoOn(h); */  // Servo power-on changes device state; execute only after confirmation.
/* int servoOffRet = Arm_Info_ServoOff(h); */  // Servo power-off changes device state; execute only after confirmation.
/* int estopRet = Arm_Info_Estop(h); */  // Emergency stop is an action API; execute only after confirmation.
Arm_Info_ReleaseAccess(h);  // Releases SDK control access.

Sample code

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

#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;
}

1 Overview and Setup

2 Data Structures

3 Methods

4 C99 API

6 Other Language Integration

4.2 C99 Info APIs

Overview

API Signatures

`Arm_Info_GetControllerVersion`

`Arm_Info_GetArmModelInfo`

`Arm_Info_AcquireAccess`

`Arm_Info_ReleaseAccess`

`Arm_Info_SwitchLedLight`

`Arm_Info_Estop`

`Arm_Info_ServoReset`

`Arm_Info_GetOpMode`

`Arm_Info_GetCtrlStatus`

`Arm_Info_GetRobotStatus`

`Arm_Info_GetServoStatus`

`Arm_Info_ServoOn`

`Arm_Info_ServoOff`

`Arm_Info_GetSoftMode`

`Arm_Info_SetSoftMode`

`Arm_Info_SetOpMode`

Function Groups

Parameters and Return Values

Prerequisites and Control Access

Minimal Example

Scenario Examples

Read Version, Model, and Status

Read and Write Modes

Control Actions

4.2 C99 Info APIs ​

Overview ​

API Signatures ​

Arm_Info_GetControllerVersion ​

Arm_Info_GetArmModelInfo ​

Arm_Info_AcquireAccess ​

Arm_Info_ReleaseAccess ​

Arm_Info_SwitchLedLight ​

Arm_Info_Estop ​

Arm_Info_ServoReset ​

Arm_Info_GetOpMode ​

Arm_Info_GetCtrlStatus ​

Arm_Info_GetRobotStatus ​

Arm_Info_GetServoStatus ​

Arm_Info_ServoOn ​

Arm_Info_ServoOff ​

Arm_Info_GetSoftMode ​

Arm_Info_SetSoftMode ​

Arm_Info_SetOpMode ​

Function Groups ​

Parameters and Return Values ​

Prerequisites and Control Access ​

Minimal Example ​

Scenario Examples ​

Read Version, Model, and Status ​

Read and Write Modes ​

Control Actions ​

4.2 C99 Info APIs

Overview

API Signatures

`Arm_Info_GetControllerVersion`

`Arm_Info_GetArmModelInfo`

`Arm_Info_AcquireAccess`

`Arm_Info_ReleaseAccess`

`Arm_Info_SwitchLedLight`

`Arm_Info_Estop`

`Arm_Info_ServoReset`

`Arm_Info_GetOpMode`

`Arm_Info_GetCtrlStatus`

`Arm_Info_GetRobotStatus`

`Arm_Info_GetServoStatus`

`Arm_Info_ServoOn`

`Arm_Info_ServoOff`

`Arm_Info_GetSoftMode`

`Arm_Info_SetSoftMode`

`Arm_Info_SetOpMode`

Function Groups

Parameters and Return Values

Prerequisites and Control Access

Minimal Example

Scenario Examples

Read Version, Model, and Status

Read and Write Modes

Control Actions