배포 안내
이번 2.0.0 메이저 업데이트는 로봇의 자율 주행 및 제어 권한을 대폭 확대하고 환경 인지 API를 새롭게 제공합니다. 특히 좌표계(Frame) 및 서비스 등록 체계에 주요 호환성 변경(Breaking Changes)이 포함되어 있으므로 실무 담당자는 마이그레이션 가이드를 반드시 확인하시기 바랍니다.
1. 신규 기능 (New Features)
자율 주행(Autonomous Navigation) API 개방
개발자가 Autowalk 기반의 API에 직접 접근하여 자율 주행 시스템을 구성할 수 있도록 개방되었습니다.
- GraphNavService: 주변 환경의 맵(Map) 데이터를 업로드/다운로드하고 로봇의 로컬라이제이션(위치 인식)을 업데이트하며, 맵 내 특정 목적지로 자율 주행하도록 명령을 전송할 수 있습니다.
- GraphNavRecordingService: 로봇이 수동으로 이동하는 동안 백그라운드에서 주변 맵을 레코딩할 수 있습니다.
- MissionService: 저장된 자율 주행 미션(Mission) 파일을 로드하고 실행합니다.
- RemoteMissionService: RPC를 통해 미션 수행 도중 사용자 정의 코드를 트리거할 수 있는 새로운 미션 콜백(Callback) 시스템이 도입되었습니다.
Spot CAM API 통합
Spot CAM의 하드웨어 및 미디어 제어 권한이 추가되었습니다.
- CompositorService & StreamQualityService: WebRTC 스트림의 레이아웃 및 영상 품질을 조정합니다.
- PtzService: PTZ 카메라의 지향 위치(Pose)를 직접 제어합니다.
- LightingService: 조명(Illuminator) LED의 개별 밝기를 제어합니다.
- MediaLogService: 고해상도 이미지를 내부 USB 드라이브에 저장하거나, 후처리를 위해 다운로드합니다.
- AudioService: 오디오 파일을 업로드하고 Spot CAM 스피커를 통해 재생합니다.
- NetworkService: 네트워크 관련 설정을 조정합니다.
- HealthService, VersionService, PowerService: 하드웨어/소프트웨어 상태를 조회하고 컴포넌트의 전원을 제어합니다.
페이로드(Payload) API 연동
컴퓨팅 성능을 갖춘 페이로드가 로봇의 시스템에 자체 등록(Self-register)할 수 있도록 인터페이스가 확장되었습니다.
- DirectoryRegistrationService: 페이로드 내부에서 구동되는 신규 gRPC 서비스를 로봇의 서비스 디렉터리에 등록할 수 있습니다. 이를 통해 오프보드(Off-robot) 환경에서도 로봇의 프록시를 경유하여 통신할 수 있으며, Autowalk 연동용 미션 콜백을 등록할 수 있습니다.
- PayloadRegistrationService: 페이로드가 고유 속성을 담아 로봇에 스스로를 등록하고, 시스템 관리자(Administrator)의 권한 승인을 대기할 수 있는 기능이 추가되었습니다.
주변 환경 인지(Environmental) API
Spot이 주변 환경을 인식하고 상호작용하는 방식을 고도화할 수 있는 API가 추가되었습니다.
- WorldObjectService: 주변 환경에서 인식된 객체의 세부 데이터를 요청하거나, 사용자가 자체적으로 감지한 커스텀 객체를 시스템 맵에 추가할 수 있습니다.
- LocalGridService: 지형의 높이 및 장애물 분류 정보를 포함하여, 로봇 주변 영역에 대한 로컬 그리드 맵(Local grid map) 데이터를 요청할 수 있습니다.
- depth_in_visual_frame 지원: 기존 흑백(Grayscale) 이미지와 동일한 해상도 및 카메라 파라미터(Extrinsics/Intrinsics)를 갖는 깊이 맵(Depth map) 이미지 소스가 제공되어, 픽셀-깊이 매칭(Pixel-depth correspondence) 처리가 용이해졌습니다.
2. 버그 수정 및 개선 사항 (Bug Fixes and Improvements)
- 공식 문서(Documentation) 개선: SDK 초기 세팅을 위한 Python QuickStart 가이드가 전면 개편되었으며, 핵심 개념(Conceptual) 문서, 페이로드 개발자 가이드, API 프로토콜 생성 문서가 새롭게 추가되었습니다.
- 불안정한 네트워크 환경 성능 최적화: API 요청(Request)당 오버헤드가 수백 바이트(Bytes) 감소하여 통신 효율이 증가했습니다. TimeSync 추정기가 일시적인 네트워크 단절 및 극단적인 지연(Outlier latencies) 환경에서도 안정적으로 동작하도록 개선되었습니다.
- 추가적인 로봇 상태(Robot State) 제공: PowerState: 전체 배터리 충전 잔량(%) 및 예상 잔여 구동 시간이 제공됩니다. KinematicState: 로봇 본체의 속도(Body velocities) 데이터가 추가되었습니다. RobotState: 로봇 발의 지면 접촉 상태(Contact vs Not in contact)를 확인할 수 있습니다.
- 고급 이동 제어(Locomotion) 옵션 지원: 특수 상황이나 험지 지형에서 로우레벨(Low-level) 이동 기본값(계단 추적, 피치 제한, 절벽 회피 등)을 비활성화할 수 있으며, 본체 회전 시 수평면(Horizontal)이나 기본 기준점(Nominal) 대비 오프셋(Offset)을 지정할 수 있습니다.
- CLI 툴(bosdyn.client) 개선: 깊이 이미지(Depth images) 다운로드가 지원되며 PGM 파일 포맷으로 저장됩니다. 디렉터리 목록 출력 포맷도 가독성이 개선되었습니다.
3. 주요 호환성 변경 (Breaking Changes)
⚠️ 개발자 주의 사항: 2.0.0 버전은 이전 1.x 버전과 호환되지 않는 주요 변경 사항을 다수 포함하고 있습니다. 기존 애플리케이션의 안정적인 구동을 위해 다음 항목에 대한 코드 마이그레이션이 필수적입니다.
좌표계(Frame) 처리 방식 변경
기존 geometry.proto의 Frame 메시지 및 FrameType 열거형(Enum)이 지원 중단(Deprecated)되었습니다. 이제 API 전반에서 모든 좌표계는 문자열(String)로 취급됩니다.
- 로봇 상태, 이미지, 그리드 맵 등의 데이터를 수신할 때, 해당 데이터의 기준 좌표계를 나타내는 문자열과 함께 다른 좌표계로의 변환 방법을 정의한 FrameTreeSnapshot 메시지가 동반됩니다.
- 좌표계 변환 시 frame_helpers.py에 내장된 함수(get_a_tform_b 등)를 활용해야 합니다.
- 1.x 코드는 아래의 새로운 표기법에 맞게 업데이트해야 합니다:
| 버전 1.x 좌표계 (Enum) | 버전 2.0 좌표계 (String) | frame_helpers.py 상수 |
|---|---|---|
| FRAME_KO | "odom" | ODOM_FRAME_NAME |
| FRAME_VO | "vision" | VISION_FRAME_NAME |
| FRAME_BODY | "body" | BODY_FRAME_NAME |
신규 예외 처리(Exceptions) 도입
- 신규 RpcError 발생: PermissionDeniedError, ResponseTooLargeError, NotFoundError, TransientFailureError
- RPC 호출 전 검증 예외(bosdyn.client.Error 상속): TimeSyncRequired, NoSuchLease, LeaseNotOwnedByWallet
- 신규 로봇 통신 예외(RobotError 상속): UnregisteredServiceError, UnregisteredServiceNameError, UnregisteredServiceTypeError (기존의 NonexistentAuthorityError는 더 이상 발생하지 않습니다.)
- 신규 좌표계 에러: 인식 불가능한 좌표계 지정 시 UnknownFrameError가 발생합니다.
이동 및 이름 변경 (Moved or Renamed)
- Trajectory 지정 방식: Trajectory 자체가 아닌 부모 메시지 레벨에서 좌표계(Frame)의 이름을 명시하도록 변경되었습니다.
- Body 좌표계 지정 제한: 제어 동작의 모호성을 방지하기 위해 body frame을 기준으로 하는 Trajectory 명령 지원이 제거되었습니다.
- 프로토콜 분리: 로봇 명령 메시지가 용도에 따라 분할되었습니다 (basic_command, full_body_command). 기존의 import/include 경로 수정이 필요합니다.
- 필드명 변경: SE3TrajectoryPoint의 vel 필드가 velocity로 변경되었습니다. Payload.proto에서 LabelPrefix가 'String'에서 'Repeated String' 타입으로 변경되었습니다. 페이로드 마운트 필드명이 body_tform_payload, mount_tform_payload로 각각 변경되었습니다.
지원 종료 및 제거 (Removed)
- 가능한 모든 Frame 메시지가 'Frame string(좌표계 문자열)' 체계로 완전히 대체되었습니다.
- AddLogAnnotationResponse의 status 필드가 제거되었으며, 오류 정보는 메시지 헤더에 인코딩되어 반환됩니다.
- KinematicState의 ko_tform_body, vo_tform_body, ground_plane_rt_ko 데이터가 transforms_snapshot으로 통합 및 대체되었습니다.
- 이미지 캡처용 SampleCommon 메시지가 수집 시간(Acquisition time)과 FrameTreeSnapshot의 조합으로 대체되었습니다.
기타 호환성 변경 (Miscellaneous)
- bosdyn-client 패키지에 numpy 의존성이 새롭게 추가되었습니다.
- 버전 1.1 환경에서 레코딩된 Autowalk 미션 및 맵(Map) 데이터는 2.0 버전 시스템과 호환되지 않습니다. 다시 매핑 작업을 수행해야 합니다.
4. 알려진 문제 (Known Issues) 및 임시 해결 방법(Workaround)
- 월드 객체 삭제 후 잔상 현상: WorldObjectService에서 객체를 삭제한 직후 ListWorldObjects를 호출하면 삭제된 객체가 여전히 조회되는 경우가 있습니다.
→ 해결 방법: 객체 삭제 후 목록 조회를 요청하기 전, 시스템 동기화를 위한 짧은 대기 시간(Delay)을 부여하십시오. - 신규 서비스 클라이언트 생성 오류: 새 서비스를 등록한 직후 robot.ensure_client를 호출해 해당 클라이언트를 생성하려 할 때 UnregisteredServiceNameError가 발생할 수 있습니다.
→ 해결 방법: 클라이언트 생성(ensure_client) 전에 반드시robot.sync_with_directory()를 호출하여 디렉터리를 강제로 동기화하십시오. - SE2VelocityLimits 값 지정 누락 버그: 속도 제한(Min/Max) 지정 시 제한을 걸지 않을 방향의 필드를 비워둘 경우, 해당 값이 기본값 0으로 처리되어 로봇이 아예 회전하지 않거나 지정되지 않은 방향으로 이동하지 못하는 버그가 있습니다.
→ 해결 방법: SE2VelocityLimit 메시지 구성 시 제한하지 않을 방향 필드에도 명시적으로 매우 큰 값(예: 1e6)을 채워 넣어 메시지의 모든 필드가 누락 없이 전송되도록 하십시오. - LogAnnotationClient 비동기 미지원: 현재 해당 클라이언트에는 비동기(Async) 버전의 RPC가 포함되어 있지 않습니다.
→ 해결 방법: 비동기식 호출이 필요한 경우, 별도의 스레드(Thread)를 생성하여 동기식으로 호출하십시오.
5. 샘플 코드 주요 변경 사항 (Sample Code)
자율 주행, 페이로드 등록 및 Spot CAM 제어 등 2.0.0 버전의 신규 기능을 실무에 쉽게 적용할 수 있도록 다수의 예제 코드가 추가/업데이트 되었습니다.
- directory: 서비스 등록, 업데이트 및 등록 해제 예제.
- payloads: (기존 get_payload에서 이름 변경) 페이로드 버전 처리 방법 추가.
- self_registration: 페이로드 자체 등록 프로세스 및 서비스 호스팅 구현 예제.
- estop: 기존 GUI 버전에 추가로 CLI 환경에서 구동 가능한 EstopNoGui 예제 추가.
- get_mission_state / replay_mission / mission_recorder: 자율 주행 미션(Mission)의 레코딩, 상태 조회 및 API를 통한 재생 예제.
- graph_nav_command_line / graph_nav_view_map: GraphNav 맵 다운로드/업로드, 네비게이션 제어 및 맵 시각화 예제.
- remote_mission_service: 원격 미션 콜백용 gRPC 서버 구축 및 통신 예제.
- frame_trajectory_command: Visual 및 Odometry 좌표계를 파악하여 기준 위치에서 x축으로 +1.0 이동하는 좌표계 기반 Trajectory 명령 예제.
- spot_cam: Spot CAM 하드웨어 기능 제어 데모 예제.
- visualizer: 일관된 좌표계 위에서 Spot의 주변 환경 인지(Perception) 씬을 렌더링하는 시각화 예제.
- world_object_mutations / get_world_objects: 월드 객체의 추가, 변경, 삭제 및 특정 객체 대상 필터링 예제.
- xbox_controller: Windows 환경 Xbox 드라이버 지원 업데이트.