배포 안내
이번 4.1.0 업데이트는 자율 주행(Graph Nav)의 대용량 맵 스트리밍, 장거리 경로 탐색(Long Range Planner) 기능 추가, 통신 단절에 대비한 Keepalive 서비스의 정식 지원을 포함하고 있습니다. 페이로드 연동과 미션 제어 시스템의 대규모 호환성 변경(Breaking Changes)이 포함되어 있으므로 실무 담당자는 아래 사항을 반드시 확인하시기 바랍니다.
1. 주요 호환성 변경 (Breaking Changes)
⚠️ 개발자 주의 사항: 4.1.0 버전으로 마이그레이션할 때 기존 애플리케이션의 아래 코드를 점검하십시오.
- Area Callback 요청 데이터 구조 변경: BeginCallbackRequest 메시지에서 더 이상 recorded_data 필드가 채워지지 않습니다. Area Callback 서비스는 중복된 recorded_data 대신 기존에 제공되던 custom_params를 사용하도록 코드를 수정해야 합니다.
- 비동기 안무 상태 조회(Choreography Client) 변경: get_choreography_status_async 비동기 호출 시, 더 이상 Future 객체와 validity time을 튜플 형태로 동시에 반환하지 않습니다. 이제 Future 객체만 반환하며, 해당 객체에 result()를 호출해야 상태 응답(GetChoreographyStatus)과 유효 시간을 튜플로 얻을 수 있습니다. (단, 동기 호출인 get_choreography_status는 기존과 동일합니다.)
- 평지(Flat Ground) 어노테이션 변경: Edge 메시지 내 Annotations의 flat_ground 필드는 더 이상 기능하지 않을 수 있습니다. 대신 ground_clutter_mode 필드를 사용하십시오.
2. 신규 기능 (New Features)
Autowalk 및 자율 주행 미션 (Missions)
- 인간-로봇 상호작용(HRI) 동작 지원: 사전 정의된 HRI 동작이 Autowalk에 추가되었습니다. GlobalParameters 메시지에 신규 필드 hri_behaviors가 도입되었습니다.
- play_alert_behaviors: 활성화 시 검사 중 이상(Anomaly)이 발견되면 Spot이 앞-왼쪽 발을 두 번 구르는 동작을 수행합니다.
- play_undock_behaviors: 활성화 시 도킹을 해제하기 전 다리를 두 번 들었다 놓는 동작을 수행합니다.
- 다중 도크(Multiple docks) 지원: Dock 메시지에 disable_recharge와 disable_end 필드가 추가되었습니다.
- disable_recharge: 로봇이 해당 도크를 충전용으로 사용할지, 아니면 실패 후 재시도를 위한 복귀용으로만 사용할지 제어합니다.
- disable_end: 미션 완료 시 로봇이 해당 도크에서 미션을 종료할 수 있는지 여부를 지정합니다.
- 미션 텍스트 노드(CreateMissionText) 추가: 사용자 응답을 요구하지 않는 단방향 프롬프트 기능이 추가되었습니다. 미션 진행 상태를 사용자에게 단순 전달할 때 유용하며, GetState RPC의 active_mission_text 필드를 통해 현재 실행 중인 텍스트를 조회할 수 있습니다.
- 데이터 수집 저장소 쿼리 노드(BosdynQueryStoredCaptures): Data Acquisition Store를 쿼리하고 응답을 블랙보드(Blackboard)에 기록하는 기능이 추가되었습니다. 선행 검사 결과(예: 이상 감지 여부)에 따라 후속 행동을 결정하는 분기형(Contingent) 미션 시나리오 구성에 활용할 수 있습니다.
클라이언트 및 데이터 처리 (Clients / Data Acquisition)
- 비동기 스트리밍(Async streaming) 지원: Python SDK에서 스트리밍 RPC의 비동기 호출이 지원됩니다. DataAcquisitionClient의 store_file_async, store_data_as_chunks_async, query_stored_captures_async 메서드를 참조하십시오.
- 초대용량 파일 저장소 기능: 레이저 스캐너 등 초대용량 페이로드 장비를 위해, StoreDataStream RPC를 통해 100MB 초과 파일을 단일 RPC로 저장할 수 있습니다.
- 주의: Data Acquisition Store의 총 용량은 50GB이며, 여유 공간 부족 시 오래된 데이터가 덮어쓰여집니다.
- QueryParameters 메시지의 include_large 필드를 통해 100MB 초과 캡처 데이터를 쿼리 결과에 포함할지 제어할 수 있습니다.
자율 주행 및 맵 관리 (Graph Nav)
- 대용량 맵 스트리밍: UploadGraphStreaming 및 DownloadGraphStreaming RPC가 추가되어 4MB를 초과하는 대규모 Graph Nav 맵 데이터의 전송을 지원합니다.
- Area Callback 진입 상태 인지: 로봇이 콜백을 시작할 때, 단순히 영역 경계선에 있는지 이미 영역 내부에 있는지 여부를 콜백 구현체에 전달합니다. 로봇이 영역 내부에 갇혀서 네비게이션을 재시작하는 경우 등에 유연하게 대응할 수 있습니다.
로봇 네비게이션 및 통신 제어 (Navigation / Keepalive)
- 장거리 경로 플래너(Long Range Planner): TravelParams에 planner_mode 필드가 추가되었습니다. PLANNER_MODE_LONG_RANGE 설정 시, 기록 당시 없었던 거대한 장애물을 우회하기 위해 기존 경로에서 최대 6m까지 벗어날 수 있습니다. (기본 플래너는 1.5m, 엄격한 경로 추종 시 0.25m 제한)
- 주의: 경로를 크게 이탈하여 위험 구역으로 진입할 수 있으므로 극히 주의하여 사용해야 합니다.
- 위험 구역 감지 및 회피: MobilityParams의 hazard_detection_mode 필드를 통해 기존에 무시되던 잠재적 장애물이나 위험 구역을 감지하고 회피 엄격도를 조절할 수 있습니다.
- 계단 통행 차단: MobilityParams의 StairsMode 열거형에 STAIRS_MODE_PROHIBITED가 추가되어 로봇의 계단 오르내림을 강제로 제한할 수 있습니다.
- 출입 금지 구역(No-go regions) 원형 지원: NoGoRegionProperties 메시지에 circle 필드가 추가되어 원형 형태의 접근 금지 구역을 설정할 수 있습니다.
- Keepalive Service 정식 도입 (Beta 종료): 클라이언트가 주기적으로 CheckInRequest를 보내지 않을 경우(통신 단절 시), 사전에 정의된 정책(Policies)과 액션에 따라 로봇이 자체적으로 대처하도록 지원합니다.
3. 버그 수정 및 개선 사항 (Bug Fixes and Improvements)
- 안무(Choreography) 제어 개선:
- 모션 시작점 또는 댄스 프레임을 기준으로 하는 상대적 이동 제어 필드(relative_position, relative_yaw, relative)가 추가되었습니다.
- 로봇의 A/V 조명, A/V 부저음, 상태 표시등을 제어할 수 있는 신규 모션 타입이 추가되었습니다.
- 애니메이션 입력을 활용해 커스텀 보행(Custom gait)의 바디 모션이나 스윙 궤적(x-y)을 제어하는 고급 옵션이 도입되었습니다.
- 클라이언트 및 응답 처리(Clients): ResponseContext에서 응답 헤더에 타임스탬프가 누락된 경우 이를 자동으로 설정하도록 패치되었습니다.
- 익스텐션(Extensions) 개발 지원:
- manifest.json에 extension_name 속성이 공식적으로 추가되었습니다.
- docker-compose.yml에서 journald 로깅 드라이버가 지원되어, 전원을 껐다 켜거나 컨테이너가 종료된 후에도 로그를 안전하게 보관 및 열람할 수 있습니다.
- 좌표계 프레임(Frames) 확장:
- 중력에 정렬된 로봇 발자국의 기하학적 중심을 뜻하는 신규 기준 프레임인 feet_center가 추가되었습니다.
- 글로벌 맵 기준용 seed 프레임과 waypoint 프레임 처리를 돕는 헬퍼 기능이 frame_helpers.py에 편입되어 레이저 정밀 스캐닝 연동이 용이해졌습니다.
- Graph Nav 안정성 고도화:
- 로컬라이제이션 요청 시 로드된 맵이 없다면 명시적인 에러 코드(STATUS_NO_MAP_LOADED)를 반환합니다.
- 목표 도달 범위를 기존의 원형 반경에서 box_region 필드를 활용한 방향성 사각형(OrientedBox2)으로 정밀하게 설정할 수 있습니다.
- 주변 환경이 지속적으로 변하는 지역에서 로봇이 자주 길을 잃는 문제를 해결하기 위해, 길 잃음 감지기(Lost detector)의 엄격도를 제어하는 LostDetectorStrictness 옵션이 추가되었습니다.
- 미션 블랙보드 변수 확대: 실행 중인 미션 노드의 Duration, NavigateRouteRequest, SetLocalizationRequest, Dock ID 등의 데이터를 런타임에 블랙보드에서 읽어올 수 있도록 개선되었습니다.
- 로봇 상태(RobotState) 가시성 향상: 걷기, 서기, 앉은 상태 전환 중 등 로봇의 직관적인 현재 행동 상태를 반환하는 behavior_state 필드가 추가되었습니다.
4. 지원 중단 예고 (Deprecations)
- AreaCallbackData 메시지의 custom_params 필드가 param_collection 필드로 대체됩니다. 당분간은 런타임에 기존 필드가 채워지나 시스템 마이그레이션을 권장합니다.
- PlaybackMode 메시지의 skip_docking_after_completion 필드가 Dock 메시지의 disable_end 필드로 교체되었습니다.
- 미션 서비스 내 블랙보드(Blackboard) 변수 키(Key) 값으로 사용하는 ., [], () 등의 특수 문자는 향후 릴리즈에서 지원이 중단될 예정입니다. (알파벳, 숫자, 언더바 사용 강력 권장)
5. 알려진 문제 (Known Issues)
- TimeSync 클라이언트 오차 누적: 4.1.0 이전부터 존재했던 이슈로, TimeSync 클라이언트가 로봇과의 시간 동기화를 잃을 경우 런타임 동안 시간 오차(Drift)가 누적되어 최종적으로 로봇이 클라이언트의 제어 메시지를 시간 초과 사유로 거부하는 문제가 발생할 수 있습니다.
6. 샘플 코드 업데이트 (Sample Code)
산업 현장 구현을 돕기 위해 다수의 예제 코드가 추가 및 갱신되었습니다.
Spot SDK 업데이트
- GPS: GPS 기기가 로봇 시스템의 페이로드로 자동 자체 등록되도록 gps_listener.py가 업데이트되었습니다. 또한 TimeSync 클라이언트 통신 거부 문제를 회피하기 위해 NTP를 활용해 코어 시간을 직접 동기화하는 임시 워크어라운드 옵션(--disable-time-sync)이 docker-compose.yml에 추가되었습니다.
- GraphNav: 맵 렌더링 부하를 줄이기 위해 상대 시간에 따라 GPS 데이터를 필터링하는 옵션이 추가되었습니다.
- 기타 Area Callback 예제, GCode(로봇 팔을 이용한 분필 드로잉 툴 길이 보정), 비동기 Data Acquisition 예제 등이 4.1.0 사양에 맞춰 업데이트되었습니다.
Orbit SDK 업데이트
- Orbit Client가 PATCH 엔드포인트를 지원하도록 patch_resource 기반의 5가지 신규 메서드(얼럿/이상 수정, 백업 작업 지시, 아카이브 다운로드 등)가 추가되었습니다.
- 기존 Webhook 예제를 확장하여 데이터를 외부 EAM(Enterprise Asset Management) 시스템에 연동하는 웹훅 통합(Webhook Integration) 예제가 추가되었습니다. (단, 구형 Scout Client 예제는 업데이트되지 않았습니다.)