배포 안내
이번 3.0.0 업데이트는 자율 주행(Graph Nav)의 맵 관리 고도화, Arm을 활용한 물리적 조작(Constrained Manipulation) 기능 추가, 그리고 네트워크 단절에 대비한 자동 복귀(Auto Return) 서비스 등 산업 현장에서의 안정성과 제어력을 대폭 강화하는 데 초점을 맞추었습니다.
1. 신규 기능 (New Features)
자율 주행 및 맵 관리 (Graph Nav)
- 맵 프로세싱(Map Processing): Graph Nav 맵 데이터를 처리하는 두 가지 신규 방식이 추가되었습니다. 맵 내 루프 클로징(Close loops) 및 연결을 추가하기 위해 새로운 웨이포인트(Waypoints)와 에지(Edges)를 맵에 병합할 수 있습니다. 맵의 앵커링(Anchorings)을 최적화하여 뷰어 표시 및 네비게이션을 위한 웨이포인트의 전역 좌표계를 고도화할 수 있습니다.
- 앵커 기반 네비게이션(NavigateToAnchor): 로봇이 특정 앵커 위치로 자율 주행하도록 명령하는 RPC가 추가되었습니다. 로봇의 현재 위치에서 경로가 가장 짧으면서도 목표에 근접한 웨이포인트를 자동으로 탐색하여 이동합니다.
오토 리턴 (Auto Return)
- 자동 복귀 서비스 추가: 무선 통신이 단절(Communication loss)될 경우, 로봇이 자체적으로 제어권을 확보하여 최근 이동했던 경로를 되짚어 돌아오도록 구성하는 시스템이 도입되었습니다. 이를 통해 운영자와의 통신 복구 가능성을 높일 수 있습니다.
안무 및 모션 제어 (Choreography)
- Choreography Logging: 지정된 시간 또는 댄스 지속 시간 동안 로봇의 포즈 및 관절 상태 데이터를 타임스탬프와 함께 로깅하는 기능이 추가되었습니다.
- 키프레임 애니메이션 지원: Autodesk Maya 등 범용 애니메이션 소프트웨어, 수기 작성, 혹은 로그 데이터를 바탕으로 타임스탬프가 지정된 커스텀 키프레임 모션을 생성할 수 있습니다. 생성된 애니메이션 모션은 로봇에 업로드하여 기본 모션처럼 활용할 수 있습니다.
매니퓰레이션 및 암 제어 (Constrained Manipulation)
- 제한적 조작 API: Spot의 암(Arm)을 이용해 크랭크, 레버, 캐비닛 등 특정 궤적을 가지는 사물을 조작할 수 있는 API가 추가되었습니다. 원하는 작업 유형과 속도를 지정하여 하드웨어를 조작할 수 있습니다.
- 푸시바 도어 개방(Pushbar Door Opening): AutoPush API를 통해 지정된 좌표의 문을 감지하고 푸시바 형태의 문을 밀어서 열 수 있는 기능이 API 및 태블릿 컨트롤러에 추가되었습니다.
Spot CAM 및 페이로드 연동 (Spot CAM & Payloads)
- PTZ 포커스 제어: Spot CAM의 PTZ 카메라 포커스를 제어하는 SetPtzFocus, GetPtzFocus RPC가 추가되었습니다.
- Arm 마운트 지원: 페이로드를 암(Arm)의 손목(Wrist)이나 그리퍼(Gripper)에 마운트할 수 있도록 MountFrameName 열거형에 새로운 마운트 위치가 추가되었습니다.
- 런타임 페이로드 갱신: 로봇이 작동 중인 상태에서도 페이로드를 탈부착할 수 있는 UpdatePayloadAttached RPC가 추가되었습니다.
자율 주행 미션 (Missions)
- 미션 강제 종료 상태 추가: 미션을 완전히 중단하는 StopMission RPC가 추가되었으며, 이로 인해 호출되는 STATUS_STOPPED 상태가 도입되었습니다. (일시 정지와 달리 해당 미션은 재개할 수 없습니다.)
- 신규 미션 노드(Nodes) 추가: BosdynNavigateRoute(Graph Nav 특정 경로 주행), BosdynRecordEvent(API 이벤트 기록), SpotCamLed(LED 밝기 제어), SpotCamResetAutofocus(오토포커스 초기화), StoreMetadata(메타데이터 첨부), RetainLease(제어 권한 유지), RestartWhenPaused(일시 정지 후 재개 시 처음부터 시작).
IR(적외선) 방출기 제어
- IREnableDisable 서비스 추가: 커스텀 페이로드와의 간섭이 발생하는 특수 상황을 위해 로봇 바디 및 핸드 센서의 적외선 조명(IR Emitters)을 활성화/비활성화할 수 있습니다. (주의: 비활성화 시 로봇의 인지 시스템이 저하되어 이동성에 악영향을 미치며, SystemFault가 발생합니다.)
2. 버그 수정 및 개선 사항 (Bug Fixes and Improvements)
- Graph Nav 개선: 로봇 상태 이상으로 RPC 실패 시 응답에 RobotImpairedState가 포함되어 원인을 파악할 수 있으며, 네비게이션 완료 후 정지 상태 확인을 위한 body_movement_status가 추가되었습니다. 우회 경로 탐색 기능을 비활성화할 수 있는 필드와 신규 상태 코드도 대거 추가되었습니다.
- 대용량 미션 전송 최적화: 초거대 미션 맵 구동 시 단일 메시지 전송 대신 청크(Chunk) 단위로 분할하여 스트리밍하는 신규 RPC가 추가되었습니다.
- Arm 및 그리퍼 피드백 강화: ArmJointMoveCommand 요청 시 계산된 궤적을 반환하며, ApiGraspOverride를 통해 파지한 물체의 캐리 상태를 재정의할 수 있어 대처 방식을 세밀히 제어할 수 있습니다.
- 제어 권한(Leases) 분할 제어: Lease 시스템이 업데이트되어 1대의 로봇을 부분적으로 소유하고 제어할 수 있습니다.
- 에러 계층 고도화 (RpcError): PersistentRpcError와 RetryableRpcError 서브클래스가 추가되어 재시도 성공 가능성 판단이 간소화되었습니다.
3. 주요 호환성 변경 (Breaking Changes)
⚠️ 개발자 주의 사항: 3.0.0 버전 환경으로 마이그레이션 시 기존 애플리케이션의 아래 사항을 반드시 점검하십시오.
- RobotCommand 예외 코드 변경: 잘못된 명령 전송 시 RobotCommandResponse 자체에 STATUS_INVALID_REQUEST를 반환하지 않고, 공통 헤더의 CODE_INVALID_REQUEST 에러 코드를 직접 사용하도록 통일되었습니다.
- E-Stop 등록 해제 조건 강화: 로봇 모터의 전원이 켜진 상태에서는 E-Stop 서비스 등록을 해제할 수 없도록 차단되었습니다. 등록 해제를 위해서는 안전하게 전원을 차단(Safe power off)해야 합니다.
- API 호출 속도 제한 (Rate-limiting): AuthService는 초당 5회, PayloadRegistration 서비스는 초당 10회로 RPC 호출 빈도가 제한됩니다. 초과 시 HTTP 429 에러가 발생합니다.
- 로컬 그리드 장애물 데이터 변경: "obstacle_distance" 로컬 그리드에서 시스템이 자체 생성하던 가상 장애물 영역 데이터가 더 이상 포함되지 않습니다.
4. 지원 중단 (Deprecations)
- 바닥 표면 감지 파라미터 변경: enable_grated_floor 필드 사용이 중단되었으며, 격자형 바닥을 자동 감지하는 grated_surfaces_mode로 대체되었습니다.
- 헬퍼 함수명 명확화: 모터 전원을 차단하는 safe_power_off() 함수가 safe_power_off_motors()로 교체되었습니다.
- 도킹 미션 노드 구조 변경: 도킹 노드 하위에 자식 노드를 구성하는 방식이 중단되었습니다. 도킹 결과에 따른 분기 처리는 블랙보드 데이터를 참조하여 설계해야 합니다.
- 페이로드 인증 필드 대체: 페이로드 등록 시 사용되던 guid 및 secret 파라미터가 단일 PayloadCredentials 메시지로 통일되었습니다.
5. 알려진 문제 (Known Issues) 및 임시 해결 방법(Workaround)
- Spot CAM LED 조명 레벨 미적용: 설정 사항이 Autowalk 미션에 레코딩되거나 재생되지 않는 현상이 있습니다.
- 커스텀 데이터 수집 플러그인 갱신 지연: 플러그인/이미지 서비스 실행 중 설정을 동적으로 변경하지 마십시오. 해제 후 캐시가 지워지기를 기다려 재등록해야 합니다.
- 플러그인 GetStatus() 타임아웃: 직접 개발한 플러그인에서 GetStatus() 지연 시 데이터 수집 서비스 전체 타임아웃을 유발할 수 있습니다.
- SE2VelocityLimits 누락 오류: 제한을 두지 않을 방향 필드를 비우면 0으로 처리되어 이동하지 않습니다. 제한하지 않을 방향에는 명시적으로 큰 값(예: 1e6)을 입력하십시오.
6. 샘플 코드 업데이트 (Sample Code)
신규 추가 예제:
- Animation Recorder: 태블릿으로 생성한 모션을 레코딩하고 Choreographer 서비스로 재생하는 예제입니다.
- Arm Constrained Manipulation: 암을 활용하여 크랭크/레버 등을 조작하는 예제입니다.
- Auto Return: 통신 단절 시 작동하는 자동 복귀 서비스를 구성하고 트리거하는 예제입니다.
- Graph Nav Extract Point Cloud: Graph Nav 맵에서 일관된 글로벌 포인트 클라우드 데이터를 추출하는 예제입니다.
주요 업데이트 예제:
- Graph Nav Command Line: 앵커 위치 직접 네비게이션, 루프 닫기, 앵커링 최적화 레코딩 옵션이 제공됩니다.
- Mission Recorder: 로봇 맵에서 미션을 직접 빌드하는 옵션이 추가되었습니다.
- Replay Mission: 우회 경로 및 목적 지향 탐색을 비활성화하는 추가 제어 옵션이 포함되었습니다.