3.1 Arm 주 진입점

개요

Arm 은 C++17 SDK의 통합 진입점입니다. 호출자 관점에서는 주로 세 가지를 담당합니다.

1. 세션 수명 주기 관리: Connect() / Disconnect()
2. 연결 성공 후 장치 식별 정보 채우기: version , model , robotType
3. 업무 인터페이스 모듈 노출: controllerInfo , motionControl , programManager , ioSignals , topicPubSub 등

공개 필드 및 하위 인터페이스 모듈

장치 식별 필드

필드	타입	설명
version	std::string	컨트롤러 버전. 연결 성공 후 채워집니다.
model	std::string	로봇 암 모델. 연결 성공 후 채워집니다.
robotType	RobotType	로봇 타입. 연결 성공 후 채워집니다.

업무 인터페이스 모듈

멤버	역할	대응 문서
controllerInfo	기본 상태 및 제어	3.2-info
alarmClient	알람 조회 및 리셋	3.3-alarm
programManager	프로그램 실행 및 포즈	3.5-program
motionControl	모션 및 페이로드	3.4-motion
ioSignals	IO 읽기/쓰기	3.7-signals
registerBank	레지스터	3.8-registers
trajectoryManager	궤적 및 경로 테이블	3.9-trajectory
realTimeTrajectoryControl	실시간 궤적	3.9-trajectory
controllerFileManager	파일 관리	3.10-file-manager
topicPubSub	WebSocket 구독/발행	3.13-sub-pub
joggingControl	티칭 모션	3.11-jogging
extensionClient	확장 서비스	3.12-extension
coordinateSystemManager	좌표계 관리	3.15-coordinate-system
modbusClient	ModbusClient	3.14-modbus

---

3.1.1 생성자

Arm()

항목	설명
설명	로봇 세션 객체를 생성합니다. 구성을 수동으로 로드할 필요가 없으며, 연결 시 SDK 버전 확인과 컨트롤러 타입 식별을 완료합니다.
요청 파라미터	없음
반환값	생성된 객체
호환 로봇 소프트웨어 버전	협동(Copper): v7.5.0.0+ 산업용(Bronze): v7.5.0.0+

3.1.2 로봇 연결

Connect(const std::string& controllerIp, const std::string& teachPanelIp = "") -> STATUS_CODE

항목	설명
설명	Agilebot 로봇에 연결합니다. 이 메서드는 Arm 의 전용 네트워크 스레드를 시작하고 각 업무 인터페이스 모듈을 바인딩하며, 연결 후 version , model , robotType 을 채웁니다.
요청 파라미터	controllerIp : std::string , 컨트롤러 IP 주소. teachPanelIp : std::string , 티치 펜던트 IP 주소(선택 사항, 산업용 로봇은 전달 권장).
반환값	STATUS_CODE: 함수 실행 결과
비고	- controllerIp 또는 teachPanelIp 가 유효한 IP가 아니면 INVALID_IP_ADDRESS 를 반환합니다. - 컨트롤러에 연결할 수 없으면 OTHER_ERR 를 반환하고 오류 정보를 함께 제공합니다.
호환 로봇 소프트웨어 버전	협동(Copper): v7.5.0.0+ 산업용(Bronze): v7.5.0.0+

연결 성공 후 바로 사용할 수 있는 내용

연결 성공 후:

1. version , model , robotType 이 채워집니다.
2. controllerInfo , alarmClient , programManager , motionControl , ioSignals , registerBank , trajectoryManager , controllerFileManager , joggingControl , extensionClient , coordinateSystemManager , modbusClient 를 바로 호출할 수 있습니다.
3. topicPubSub 은 기본 대상 주소를 기록하며, 이후 arm.topicPubSub.Connect() 를 바로 호출할 수 있습니다.

3.1.3 로봇 연결 유효 여부 확인

IsConnected() const -> bool

항목	설명
설명	로봇과의 연결이 유효한지 확인합니다.
요청 파라미터	파라미터 없음
반환값	bool: 연결 상태. True는 연결 유효, False는 연결 무효를 의미합니다.
호환 로봇 소프트웨어 버전	협동(Copper): v7.5.0.0+ 산업용(Bronze): v7.5.0.0+

3.1.4 SDK 초기화 완료 여부 확인

IsInitialized() const -> bool

항목	설명
설명	로컬 네트워크 스레드 객체가 생성되었는지 확인합니다. 정상적으로 생성된 Arm 에서는 일반적으로 항상 true 입니다.
요청 파라미터	파라미터 없음
반환값	bool: True는 초기화 완료로 Connect() 를 시도할 수 있음을 의미하고, False는 초기화 실패를 의미합니다.
호환 로봇 소프트웨어 버전	협동(Copper): v7.5.0.0+ 산업용(Bronze): v7.5.0.0+

3.1.5 로봇 연결 해제

Disconnect()

항목	설명
설명	Agilebot 로봇과의 연결을 해제하고 모든 인터페이스 모듈 바인딩 상태를 정리하며 전용 네트워크 스레드를 중지합니다.
요청 파라미터	파라미터 없음
반환값	반환 없음
동작	- topicPubSub 을 능동적으로 연결 해제 - joggingControl , extensionClient 정리 - controllerIp , teachPanelIp , version , model 비우기 - robotType 을 UNKNOWN 으로 리셋
호환 로봇 소프트웨어 버전	협동(Copper): v7.5.0.0+ 산업용(Bronze): v7.5.0.0+

수동 호출이 필요한 경우

• 정상 업무 종료 시 능동적으로 호출해야 합니다.
• 오류가 발생해 장치를 전환하려는 경우 능동적으로 호출해야 합니다.
• 정상 종료와 장치 전환 시에는 Disconnect() 를 명시적으로 호출하는 방식을 권장합니다.

---

3.1.6 주소 정규화 동작

Connect() 는 일부 알려진 기본 토폴로지에 대해 호환성 보완 규칙을 유지합니다. 업무 측에서 양쪽 주소를 이미 알고 있다면 암시적 보완에 의존하지 말고 명시적으로 전달하는 것을 권장합니다.

입력	결과
controllerIp = "192.168.110.2" , teachPanelIp = ""	teachPanelIp 를 자동으로 192.168.110.102 로 보완
controllerIp = "192.168.110.102" , teachPanelIp = ""	controllerIp 를 자동으로 192.168.110.2 로 수정하고, teachPanelIp 를 192.168.110.102 로 설정
controllerIp 에 값이 있고 teachPanelIp = ""	협동 로봇의 경우 SDK가 빈 teachPanelIp 를 controllerIp 로 정규화
controllerIp 와 teachPanelIp 를 모두 명시적으로 전달	사용자가 명시적으로 입력한 값을 사용

---

3.1.7 연결 제한 및 동작

• Connect() 는 모든 업무 인터페이스 모듈의 선행 조건입니다.
• 현재 같은 controllerIp + teachPanelIp 조합에 이미 연결되어 있으면 바로 OK 를 반환합니다.
• 현재 다른 장치에 연결되어 있으면 Connect() 는 먼저 자동으로 Disconnect() 를 호출한 뒤 새 장치로 전환합니다.
• 연결 단계에서 버전 조회가 실패하면 연결 상태를 자동으로 롤백합니다.

---

3.1.8 스레드 모델(호출자 관점)

• 여기서 "동기"란 호출자가 요청을 시작한 뒤 결과 반환을 기다린다는 뜻이며, SDK가 업무 스레드를 대신해 별도의 동기 스레드를 추가로 여는 것은 아닙니다.
• 하나의 Arm 세션은 하나의 전용 네트워크 스레드에 대응합니다. 같은 Arm 의 대부분 네트워크 요청은 직렬로 실행됩니다.
• ControllerInfo::AcquireAccess() 와 JoggingControl::ContinuousMove() / MultiMove() 의 주기 작업은 이 네트워크 스레드를 재사용합니다.
• TopicPubSub::StartReceiving() 의 콜백은 독립적인 WebSocket 수신 스레드에서 실행되며, 콜백 안에서는 가벼운 로직만 수행해야 합니다.
• 더 완전한 동시성 제약은 1.3-thread-model을 참고하십시오.

---

최소 호출 예제

예제 코드

cpp17/arm_connect_disconnect/src/main.cpp

#include "connect_disconnect/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunArmConnectDisconnectLifecycle();
}

cpp17/arm_reconnect/src/main.cpp

#include "reconnect_once/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunArmReconnectOnce();
}

cpp17/sub_pub_basic/src/main.cpp

#include "multi_instance_isolation/run.h"
#include "subscribe_topics/run.h"
#include "send_receive_text/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunSubPubBasicSubscribeTopics();
    // return RunSubPubBasicSendReceiveText();
    // return RunSubPubBasicMultiInstanceIsolation();
}

cpp17/info_state_modes/src/main.cpp

#include "query_state_modes/run.h"
#include "write_back_modes/run.h"
#include "access_control/run.h"
#include "action_apis/run.h"

int main(void)
{
    // [ZH] 默认只调用一个门面方法；如需体验其他接口，请把下一行替换成下面任意一行。
    // [EN] The main function calls only one facade by default. Replace the next line with any line below to try other APIs.
    return RunInfoStateModesQueryStateModes();
    // return RunInfoStateModesWriteBackModes();
    // return RunInfoStateModesAccessControl();
    // return RunInfoStateModesActionApis();
}