Spot SDK 5.0.1 릴리즈 노트

배포 안내

이번 5.0.1 버전은 A/V(시청각) 경고 시스템 제어 지원, 장기 구동(Long-running) 클라이언트의 인증 에러 핸들링 개선, GraphNav 맵 델타(부분) 업로드 기능 등을 포함하는 마이너 업데이트입니다. Orbit API 및 파라미터 구조에 대한 주요 호환성 변경(Breaking Changes)이 포함되어 있으므로 실무 담당자는 아래 사항을 반드시 점검해 주시기 바랍니다.

1. 주요 호환성 변경 (Breaking Changes)

⚠️ 개발자 주의 사항: Orbit API 활용 시 아래 엔드포인트 파라미터 변경 사항을 코드에 반영해야 합니다.

• Orbit API 파라미터 구조 변경: /runs/facets/actions 엔드포인트에서 사용되던 missionName이 경로 파라미터(Path parameter)에서 쿼리 파라미터(Query parameter) 방식으로 변경되었습니다.
  • 기존: /runs/facets/actions/{missionName}
  • 변경: /runs/facets/actions?missionName={yourMissionName}
• Orbit API 파라미터명 변경: 기존 includeLaunchFailures 쿼리 파라미터가 디스패치(Dispatch) 실패에 대한 의미를 명확히 하기 위해 includeDispatchFailures로 이름이 변경되었습니다.

2. 향후 변경 예고 (Upcoming Breaking Changes)

• 페이로드 GUID 소문자 정규화 (5.1 버전 이후): 다가오는 5.1 버전에서는 페이로드 GUID가 RFC 4122의 UUID 표준 규격을 준수하도록 정규화될 예정입니다. 5.1 업데이트 이후에는 GUID의 모든 알파벳이 소문자(Lowercase)로 처리됩니다.
  • 시스템 내부적으로 자동 변환을 지원하여 운영 중단을 최소화할 예정이나, 극히 일부 페이로드의 경우 재등록(Re-registration)이 필요할 수 있습니다.

3. 신규 기능 (New Features)

4. 버그 수정 및 개선 사항 (Bug Fixes and Improvements)

• 장기 구동 클라이언트 인증 에러 핸들링 강화: 장기간 실행되는 API 클라이언트가 네트워크 문제 등으로 인해 인증 토큰(Authentication token)을 갱신하지 못할 경우, 알림 없이 조용히 오작동(Silent failures)하던 문제가 개선되었습니다.
  • 토큰 만료 및 디렉터리 등록 실패 시 클라이언트에 즉각 알림을 전달하는 에러 핸들링 콜백(Callback) 프로퍼티가 추가되었습니다.
  • 적용 속성: Robot 클래스의 token_refresh_error_callback, DirectoryRegistrationKeepalive.reregistration_error_callback, PayloadRegistrationKeepAlive.reregistration_error_callback, PolicyKeepalive.keepalive_error_callback
• GraphNav 맵 업로드 효율성 개선: 전체 맵 데이터를 매번 덮어쓰지 않고, 변경된 부분만 선별적으로 업로드하여 통신 오버헤드를 줄이는 기능이 기본적으로 허용됩니다.
  • 참고: 현재 SDK 자체에는 델타(Delta) 추출 로직이 포함되어 있지 않으므로, 변경된 맵 데이터를 필터링하는 로직은 클라이언트 단에서 구현해야 합니다.
  • 로봇이 클라이언트의 부분 업로드 요청을 인지했는지 확인하려면 UploadGraphResponse의 replaced_graph 플래그를 체크하십시오.
  • 기존처럼 전체 맵 데이터를 강제로 덮어쓰려면 UploadGraphRequest에서 replace_graph 필드를 true로 설정하십시오.
• Math Helpers 개선: math_helpers.py의 SE3Pose 클래스에 해당 포즈의 유클리드 노름(Euclidean norm)을 계산하는 헬퍼 함수가 추가되었습니다.
• Missions 파이썬 버전 호환성 패치: util.py 내의 python_var_to_value 및 python_type_to_pb_type 헬퍼 함수에서 사용되던 match: case: 구문(Python 3.10 전용)이 제거되어, 권장 환경인 Python 3.7~3.10 버전대에서 정상적으로 호환되도록 개선되었습니다.
• 서비스 커스터마이징 검증 로직 패치: 런타임 중에 CustomParams 메시지 검증 시 발생하던 예외(Exception) 버그가 수정되었습니다. (사용자가 editable이 활성화된 StringParam에 옵션 목록에 없는 문자열을 입력할 때 재생 과정에서 크래시가 발생하던 현상이 해결되었습니다.)

5. 지원 중단 (Deprecations)

• 오타 메서드 교체: gripper_camera_param.py에 존재하던 오타 메서드인 get_camera_calib_asnyc가 지원 중단되고, 올바른 표기인 get_camera_calib_async로 대체되었습니다.
• Orbit 미션 파라미터 교체: Orbit Client의 post_dispatch_mission_to_robot 메서드에서 사용되던 mission_uuid 파라미터가 향후 제거될 예정이며, walk 파라미터 사용으로 대체됩니다.

6. 알려진 문제 (Known Issues)

• Arm 매니퓰레이터 토크(Torque) 데이터 미지원 정정: 이전 5.0.0 릴리즈 노트에서 ManipulatorState의 estimated_end_effector_wrench_in_end_effector 필드를 통해 엔드이펙터 토크 값을 조회할 수 있다고 안내되었으나, 현재 렌치(Wrench) 메시지 구조만 지원할 뿐 실제 토크 데이터는 렌더링(Set)되지 않는 상태입니다.
• 데이터 버퍼 로깅 예제 버그: 현재 제공되는 'Log Spot Data' 예제 코드로는 Signal 데이터를 Spot 실험 로그에 안정적으로 기록하지 못하는 문제가 발견되었습니다. 당분간 DataBufferClient의 다른 메서드를 활용하시기 바랍니다.

7. 샘플 코드 업데이트 (Sample Code)

현장 구축을 지원하기 위해 다음 예제 코드가 추가 및 갱신되었습니다.