4.1 C99 Arm 루트 진입점

개요

C99의 루트 진입점은 ArmHandle* 입니다. 호출자는 Arm_Create() 로 세션 핸들을 만들고, 연결이 성공한 뒤 같은 핸들을 Arm_Info_* , Arm_Motion_* , Arm_Program_* 등의 모듈 함수에 전달합니다.

해당 헤더 파일:

• include/c_arm_core.h
• include/c_arm_api.h

인터페이스 시그니처

Arm_Create

ArmHandle* Arm_Create(void);

항목	설명
설명	C99 세션 핸들을 생성합니다.
요청 파라미터	파라미터 없음
반환값	ArmHandle* ; 성공 시 비어 있지 않은 세션 핸들을 반환하고, 실패 시 NULL 을 반환합니다.

Arm_Destroy

void Arm_Destroy(ArmHandle* h);

항목	설명
설명	C99 세션 핸들을 해제하고 로컬 리소스를 반환합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻습니다.
반환값	반환값 없음

Arm_Connect

int Arm_Connect(ArmHandle* h, const char* controllerIp, const char* teachPanelIp);

항목	설명
설명	컨트롤러에 연결하고 현재 세션의 업무 기능을 초기화합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다. controllerIp : const char* , 컨트롤러, 라우터 또는 현장에서 지정한 진입 주소 teachPanelIp : const char* , 티치 펜던트 주소. NULL 또는 빈 문자열을 전달하면 기본 연결 규칙을 사용합니다.
반환값	STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.

Arm_Disconnect

void Arm_Disconnect(ArmHandle* h);

항목	설명
설명	현재 로봇 연결을 해제합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻습니다.
반환값	반환값 없음

Arm_IsConnected

int Arm_IsConnected(ArmHandle* h);

항목	설명
설명	현재 세션이 아직 연결되어 있는지 조회합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻습니다.
반환값	1 은 연결됨을 의미하고, 0 은 미연결 또는 유효하지 않은 핸들을 의미합니다.

호출 규칙

항목	규칙
controllerIp	컨트롤러, 라우터 또는 현장에서 지정한 진입 주소입니다. NULL 일 수 없습니다.
teachPanelIp	NULL 또는 빈 문자열을 전달할 수 있으며, SDK가 주소 정규화 규칙에 따라 기본 주소를 보완합니다.
수명 주기	Arm_Create() 와 Arm_Destroy() 는 쌍으로 사용합니다.
업무 선행 조건	대부분의 Arm_* 업무 함수는 먼저 Arm_Connect() 가 성공해야 합니다.
오류 코드	Arm_Connect() 는 성공 시 0 을 반환하며, 다른 값은 STATUS_CODE로 판단합니다.

주소 정규화

Arm_Connect() 는 일부 기본 토폴로지에 대해 호환성 주소 보완을 수행합니다. 컨트롤러와 티치 펜던트 주소가 명확하면 두 파라미터를 모두 명시적으로 전달하는 것을 권장합니다.

입력	결과
controllerIp = "192.168.110.2" , teachPanelIp = NULL 또는 빈 문자열	teachPanelIp 를 자동으로 192.168.110.102 로 보완합니다.
controllerIp = "192.168.110.102" , teachPanelIp = NULL 또는 빈 문자열	controllerIp 를 자동으로 192.168.110.2 로 보정하고, teachPanelIp 를 192.168.110.102 로 설정합니다.
controllerIp 에 값이 있고 teachPanelIp = NULL 또는 빈 문자열	협동 로봇은 빈 teachPanelIp 를 controllerIp 로 정규화합니다.
controllerIp 와 teachPanelIp 를 모두 명시적으로 전달	호출자가 전달한 주소를 사용합니다.

연결 및 스레드 의미

시나리오	설명
연결 성공 후	같은 ArmHandle* 를 Info , Motion , Program , Registers , SubPub 등의 모듈 함수에 계속 전달할 수 있습니다.
반복 연결	같은 주소 조합에 이미 연결된 상태에서 Arm_Connect() 를 다시 호출하면 성공을 반환합니다. 다른 주소에 연결되어 있으면 먼저 연결을 끊고 전환합니다.
연결 해제	Arm_Disconnect() 는 현재 연결에 의존하는 업무 인터페이스를 무효화합니다. 업무 인터페이스를 다시 호출하기 전에 재연결해야 합니다.
핸들 해제	Arm_Destroy() 는 이미 연결 해제되었거나 연결 실패 후의 핸들을 받을 수 있습니다. 호출 후 해당 포인터를 계속 사용하면 안 됩니다.
스레드 모델	같은 ArmHandle* 는 하나의 세션 컨텍스트를 재사용합니다. 네트워크 요청이 포함된 업무 호출은 세션 단위로 직렬 실행됩니다.

연결 단계에서는 컨트롤러 버전, 로봇 모델, 로봇 타입을 읽습니다. 버전 조회에 실패하면 연결 상태는 미연결로 롤백됩니다. controllerIp 는 컨트롤러 주소, 라우터 주소 또는 현장에서 지정한 진입 주소일 수 있습니다.

최소 호출 예제

#include <stdio.h>  // 연결 상태를 출력하기 위한 표준 출력
#include "c_arm_api.h"  // C99 SDK 최상위 헤더
int main(void)  // 예제 프로그램 진입점
{  // 예제 main 함수 시작
    ArmHandle* h = Arm_Create();  // C99 세션 핸들 생성
    if (h == NULL) {  // 핸들 생성 실패 여부 확인
        return 1;  // 생성 실패 시 종료
    }  // 핸들 확인 종료
    int ret = Arm_Connect(h, "10.27.1.2", "10.27.1.102");  // 컨트롤러와 티치 펜던트 연결
    if (ret != 0) {  // 연결 실패 여부 확인
        Arm_Destroy(h);  // 생성된 핸들 해제
        return 1;  // 오류 반환
    }  // 연결 확인 종료
    printf("connected=%d\n", Arm_IsConnected(h));  // 연결 상태 출력
    Arm_Disconnect(h);  // 명시적으로 연결 해제
    Arm_Destroy(h);  // 세션 핸들 해제
    return 0;  // 예제 정상 종료
}  // 예제 main 함수 종료

시나리오 예제

티치 펜던트 주소를 비워 두기

ArmHandle* h = Arm_Create();  // C99 세션 핸들 생성
int ret = Arm_Connect(h, "10.27.1.2", NULL);  // 컨트롤러 주소만 전달하고 티치 펜던트 주소는 SDK 기본 규칙에 맡김
(void)ret;  // 예제에서 연결 결과 보관
Arm_Disconnect(h);  // 연결 해제
Arm_Destroy(h);  // 핸들 해제

실패 시 해제 보장

ArmHandle* h = Arm_Create();  // 세션 핸들 생성
if (h == NULL) {  // 생성 실패 여부 확인
    return 1;  // 바로 반환
}  // 생성 확인 종료
int ret = Arm_Connect(h, "10.27.1.2", "10.27.1.102");  // 연결 시도
if (ret != 0) {  // 연결 실패 여부 확인
    Arm_Destroy(h);  // 실패 경로에서 핸들 해제
    return ret;  // 연결 상태 코드 반환
}  // 실패 확인 종료
Arm_Disconnect(h);  // 정상 경로에서 연결 해제
Arm_Destroy(h);  // 정상 경로에서 핸들 해제

예제 코드

c99/arm_connect_disconnect/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.
    ArmHandle* handle = Arm_Create();
    if (handle == NULL) {
        printf("[c99_arm] 创建句柄失败 / Failed to create the handle\n");
        return 1;
    }

    // [ZH] 连接机器人。
    // [EN] Connect to the robot.
    int ret = Arm_Connect(handle, "10.27.1.2", "10.27.1.102");
    if (ret != 0) {
        printf("[c99_arm] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_arm] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 查询当前连接状态。
    // [EN] Query the current connection state.
    ret = Arm_IsConnected(handle);
    printf("[c99_arm] 当前连接状态 / Current connection state: %d\n", ret);

    // [ZH] 断开机器人连接。
    // [EN] Disconnect from the robot.
    Arm_Disconnect(handle);
    printf("[c99_arm] 已断开连接 / Disconnected from the robot\n");

    // [ZH] 再次查询连接状态，确认已经断开。
    // [EN] Query the connection state again to confirm it is disconnected.
    ret = Arm_IsConnected(handle);
    printf("[c99_arm] 断开后的连接状态 / Connection state after disconnect: %d\n", ret);

    // [ZH] 销毁句柄并结束示例。
    // [EN] Destroy the handle and finish the example.
    Arm_Destroy(handle);
    printf("[c99_arm] 句柄销毁成功 / Handle destroyed successfully\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;
}