Agilebot Robot SDK
Search K

한국어

中文
English

한국어

中文
English

外观

1.4 C99 인터페이스 개요 ​

개요 ​

C99 인터페이스는 C++17 SDK의 평면 C ABI 진입점입니다. 호출자는 ArmHandle* 만 보유하며, 모든 업무 기능은 Arm_* 함수를 통해 접근합니다.

일반적인 호출 순서는 다음과 같습니다.

  1. Arm_Create() 로 세션 핸들을 생성합니다.
  2. Arm_Connect() 로 컨트롤러 연결을 설정합니다.
  3. Arm_Info_* , Arm_Motion_* , Arm_Program_* 등의 모듈 함수를 호출합니다.
  4. Arm_Disconnect() 로 연결을 해제합니다.
  5. Arm_Destroy() 로 핸들을 해제합니다.

세션 모델 ​

c
ArmHandle* Arm_Create(void);
void Arm_Destroy(ArmHandle* h);
int Arm_Connect(ArmHandle* h, const char* controllerIp, const char* teachPanelIp);
void Arm_Disconnect(ArmHandle* h);
int Arm_IsConnected(ArmHandle* h);
항목설명
세션 객체ArmHandle*
생성 / 파괴Arm_Create / Arm_Destroy
연결 / 연결 해제Arm_Connect / Arm_Disconnect
연결 상태Arm_IsConnected 가 0 이 아닌 값을 반환하면 연결됨을 의미합니다.
다중 인스턴스여러 handle의 공존을 지원합니다. 각 handle은 독립 세션입니다.

C99 호출 규칙 ​

규칙설명
반환 코드대부분의 함수는 int 를 반환하며, 0 은 STATUS_CODE::OK 를 의미합니다.
데이터 출력C99는 double* outValue , ArmMotionPose* outPose 처럼 out 파라미터로 데이터를 반환합니다.
문자열 출력char* outBuf + size_t bufSize 를 사용하며, 버퍼는 호출자가 할당합니다.
배열 출력outArray + maxCount + outCount 를 사용하며, 배열 메모리는 호출자가 할당합니다.
count-only일부 배열 인터페이스는 outArray == NULL 일 때 개수만 조회할 수 있습니다.
리소스 해제ArmHandle* , ArmModbusSlaveHandle* , ArmBasScriptHandle* 등의 핸들은 대응하는 Destroy 가 필요합니다.

모듈 그룹 ​

그룹 페이지포함 헤더주요 내용
4.1-arminclude/c_arm_core.h , include/c_arm_api.h세션 수명 주기, 루트 진입점
4.2-infoinclude/c_arm_info.h기본 상태, 모드, 권한 및 제어 동작
4.3-alarminclude/c_arm_alarm.h알람 조회 및 리셋
4.4-motioninclude/c_arm_motion.h모션, 포즈, 페이로드
4.5-programinclude/c_arm_program.h프로그램 실행 및 프로그램 포즈
4.6-bas-scriptinclude/c_arm_bas_script.hBasScript 빌더
4.7-signalsinclude/c_arm_signals.hIO 읽기/쓰기 및 펄스
4.8-registersinclude/c_arm_registers.hR/PR/SR/MR/MH/MI
4.9-trajectoryinclude/c_arm_trajectory.h궤적, 경로, 실시간 궤적
4.10-file-managerinclude/c_arm_file_manager.h업로드, 다운로드, 검색, 존재 여부
4.11-jogginginclude/c_arm_jogging.h스텝 티칭, 연속 조그, 정지
4.12-extensioninclude/c_arm_extension.h확장 조회, 전환, 서비스 호출
4.13-sub-pubinclude/c_arm_sub_pub.hWebSocket 구독 및 발행
4.14-modbusinclude/c_arm_modbus.hModbus 파라미터, 슬레이브 핸들, 읽기/쓰기 및 시리얼 포트 패스스루
4.15-coordinate-systeminclude/c_arm_coordinate.h사용자 / 도구 좌표계 관리

자주 쓰는 타입 ​

타입설명
ArmHandleC99 SDK 세션 핸들 타입이며, 호출자는 포인터만 보유합니다.
ArmMotionPose모션 포즈이며, ArmPoseType 에 따라 관절 또는 직교 좌표로 해석됩니다.
ArmSoftLimit사용자 소프트 리밋
ArmPayloadInfo페이로드 상세 정보
ArmPoseRegisterPR 포즈 레지스터
ArmRunningProgramInfo실행 중인 프로그램 정보
ArmAlarmInfo알람 정보
ArmProgramPose프로그램 포즈
ArmTrajectorySegmentC실시간 궤적 세그먼트
ArmFileInfo파일 검색 결과
ArmCoordinate / ArmCoordinateInfo좌표계 상세 정보 및 목록 항목
ArmModbusSlaveHandleModbus 슬레이브 핸들
ArmBasScriptHandleBasScript 빌더 핸들
ArmBasExtraParamHandleBasScript 추가 파라미터 빌더 핸들

최소 연동 예제 ​

예제 코드

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

C++17과의 외부 차이 ​

기능C++17C99
세션 모델Arm 객체ArmHandle*
모듈 진입점arm.controllerInfo.GetServoStatus()Arm_Info_GetServoStatus(h, &status)
반환값STATUS_CODE 또는 std::pair<T, STATUS_CODE>int 상태 코드 + out 파라미터
문자열 반환std::stringchar* + bufSize
컨테이너 반환std::vector<T>호출자가 배열 버퍼를 직접 준비
콜백 파라미터Json::ValueUTF-8 JSON 텍스트
수명 주기C++ 객체 소멸자가 보완호출자가 명시적으로 Destroy 해야 함

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