4.11 C99 Jogging 점동 인터페이스

개요

C99 Jogging 은 티칭 동작 기능을 제공합니다. 객체 멤버를 노출하지 않으며, 모든 진입점은 Arm_Jogging_* 로 이름 붙은 평면 함수입니다.

인터페이스 시그니처

Arm_Jogging_StepMove

int Arm_Jogging_StepMove(ArmHandle* h, int ajNum, double stepLength, double stepAngle);

항목	설명
설명	단일 스텝 티칭 동작을 실행합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다. ajNum : int , 조그 축 또는 방향 번호. 부호는 동작 방향을 나타내며, 0 일 수 없고 절댓값은 9 를 초과할 수 없습니다. stepLength : double , 선형 축 또는 직교 방향의 스텝 거리 stepAngle : double , 관절 방향의 스텝 각도
반환값	STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.
비고	스텝 동작을 한 번만 트리거합니다. 실행 전에 로봇 주변의 안전 공간을 확인해야 합니다.

Arm_Jogging_ContinuousMove

int Arm_Jogging_ContinuousMove(ArmHandle* h, int ajNum);

항목	설명
설명	단일 축 연속 조그를 시작합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다. ajNum : int , 조그 축 또는 방향 번호. 부호는 동작 방향을 나타내며, 0 일 수 없고 절댓값은 9 를 초과할 수 없습니다.
반환값	STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.
비고	호출 후 로봇은 Arm_Jogging_Stop() 호출, 연결 해제 또는 핸들 해제 전까지 계속 움직입니다.

Arm_Jogging_MultiMove

int Arm_Jogging_MultiMove(ArmHandle* h, const int* ajNumList, size_t count);

항목	설명
설명	다축 연속 조그를 시작합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다. ajNumList : const int* , 조그 축 또는 방향 번호 배열. 각 요소의 규칙은 ajNum 과 같습니다. count : size_t , 배열 요소 수. 0 보다 커야 합니다.
반환값	STATUS_CODE 정수값. 0 은 성공을 의미하며, 그 외 값은 상태 코드로 처리합니다.
비고	여러 축을 동시에 조그하는 데 적합합니다. 호출자는 호출 중 배열이 유효하도록 보장해야 합니다.

Arm_Jogging_Stop

void Arm_Jogging_Stop(ArmHandle* h);

항목	설명
설명	연속 조그 작업을 정지합니다.
요청 파라미터	h : ArmHandle* , C99 세션 핸들. 일반적으로 Arm_Create() 에서 얻으며, 업무 인터페이스 호출 전 연결이 성공해야 합니다.
반환값	반환값 없음
비고	연속 조그를 시작하지 않았을 때도 호출할 수 있으며, 마무리 처리나 안전 정지에 사용할 수 있습니다.

파라미터 및 동작

항목	규칙
h	비어 있으면 안 됩니다.
ajNum	0 일 수 없고 절댓값은 9 를 초과할 수 없습니다.
stepLength	선형 축 또는 직교 방향의 스텝 거리
stepAngle	관절 방향의 스텝 각도
ajNumList	count > 0 일 때 비어 있으면 안 됩니다.
count	0 이면 INVALID_PARAMETER 를 반환합니다.
축 의미	1~9 는 컨트롤러의 현재 좌표계와 조그 모드에서의 축 또는 방향 번호에 대응합니다.
양/음 방향	양수는 정방향, 음수는 역방향을 나타냅니다.

동작 규칙:

• 연결되지 않은 경우 동작 계열 함수는 OTHER_ERR 를 반환합니다.
• Arm_Jogging_Stop() 은 시작된 연속 조그가 없어도 안전하게 호출할 수 있습니다.
• Arm_Jogging_StepMove() 는 단일 동기 조그입니다. stepAngle > 0 이면 각도 스텝을 사용하고, stepLength > 0 이면 직선 스텝을 사용합니다.
• 두 스텝 길이가 모두 0 이어도 스텝 동작은 한 번 시작되며, 실제 스텝은 컨트롤러의 현재 티칭 설정에 따라 결정됩니다.
• ContinuousMove() / MultiMove() 는 현재 세션의 전용 네트워크 스레드에 50ms 주기 작업을 등록합니다.
• 연속 조그를 반복해서 시작하면 기존 연속 조그 작업을 먼저 정지한 뒤 새 연속 조그 작업을 등록합니다.
• 연속 조그 중 어떤 요청이 0 이 아닌 값을 반환하면 SDK는 지속 전송을 취소합니다.
• Arm_Disconnect() / Arm_Destroy() 는 연속 조그 작업을 암묵적으로 정지합니다.

최소 호출 예제

#include "c_arm_api.h"  // C99 SDK 최상위 헤더
int main(void)  // 예제 프로그램 진입점
{  // 예제 main 함수 시작
    ArmHandle* h = Arm_Create();  // C99 세션 핸들 생성
    if (h == NULL) {  // 핸들 생성 실패 여부 확인
        return 1;  // 생성 실패 시 종료
    }  // 핸들 생성 확인 종료
    if (Arm_Connect(h, "10.27.1.254", NULL) != 0) {  // 컨트롤러 또는 라우팅 주소에 연결
        Arm_Destroy(h);  // 연결 실패 시 핸들 해제
        return 1;  // 오류 코드 반환
    }  // 연결 확인 종료
    int ret = Arm_Jogging_StepMove(h, 1, 0.0, 5.0);  // 1번 축을 5도씩 한 번 스텝 이동
    Arm_Jogging_Stop(h);  // 존재할 수 있는 연속 조그 작업 정지
    Arm_Disconnect(h);  // 로봇 연결 해제
    Arm_Destroy(h);  // 세션 핸들 해제
    return ret == 0 ? 0 : 1;  // 스텝 결과에 따라 예제 상태 반환
}  // 예제 main 함수 종료

시나리오 예제

아래 조각은 연결에 성공한 ArmHandle* h 가 이미 있다고 가정합니다. 연속 조그는 로봇을 계속 움직이게 하므로 실행 전에 현장 안전을 확인해야 합니다.

단일 축 스텝

int ret = Arm_Jogging_StepMove(h, 1, 0.0, 5.0);  // 1번 축을 각도 기준으로 한 번 스텝 이동
(void)ret;  // 예제에서 반환 코드를 보관하며, 실제 코드는 0인지 확인해야 함

단일 축 연속 조그

int ret = Arm_Jogging_ContinuousMove(h, 1);  // 1번 축 연속 조그 시작
Arm_Jogging_Stop(h);  // 연속 조그 정지
(void)ret;  // 예제에서 반환 코드를 보관하며, 실제 코드는 0인지 확인해야 함

다축 연속 조그

int axes[2] = {1, -2};  // 두 조그 방향 준비, 부호는 동작 방향을 의미
int ret = Arm_Jogging_MultiMove(h, axes, 2);  // 다축 연속 조그 시작
Arm_Jogging_Stop(h);  // 다축 연속 조그 정지
(void)ret;  // 예제에서 반환 코드를 보관하며, 실제 코드는 0인지 확인해야 함

예제 코드

c99/jogging_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_jogging] 创建句柄失败 / 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_jogging] 连接失败 / Connect failed, 状态码 / Status code: %d\n", ret);
        Arm_Destroy(handle);
        return 1;
    }
    printf("[c99_jogging] 机器人连接成功 / Robot connected successfully\n");

    // [ZH] 顺序执行全部点动接口。
    // [EN] Execute all jogging APIs in sequence.
    int ajNumList[2] = {1, -2};
    ret = Arm_Jogging_StepMove(handle, 1, 0.0, 5.0);
    printf("[c99_jogging] StepMove 状态码 / StepMove status code: %d\n", ret);
    ret = Arm_Jogging_ContinuousMove(handle, 1);
    printf("[c99_jogging] ContinuousMove 状态码 / ContinuousMove status code: %d\n", ret);
    Arm_Jogging_Stop(handle);
    printf("[c99_jogging] Stop 已调用 / Stop called\n");
    ret = Arm_Jogging_MultiMove(handle, ajNumList, 2U);
    printf("[c99_jogging] MultiMove 状态码 / MultiMove status code: %d\n", ret);
    Arm_Jogging_Stop(handle);
    printf("[c99_jogging] Stop 再次调用 / Stop called again\n");

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