AgileX·Weston Robot UGV SDK 빌드와 CAN 제어 안내

자료와 버전

UGV SDK는 이동 로봇에 명령을 보내고 최신 상태를 받는 C++ 인터페이스입니다. 중국 AgileX Robotics와 싱가포르 Weston Robot 개발팀의 공동 작업입니다. Copyright (c) 2020–2023 Weston Robot 및 AgileX Robotics 고지를 보존합니다. 아래는 2026년 8월 11일 커밋의 README 사용 안내를 한국어로 번역·정리한 자료이며 전체 SDK 소스·문서를 번역한 것은 아닙니다. 문제 보고 주소는 https://github.com/westonrobot/ugv_sdk/issues 입니다.

지원 환경

정기 시험 대상은 x86_64·arm64, Ubuntu 18.04·20.04·22.04와 ROS Melodic·Noetic·Foxy·Humble입니다. 유사 Linux에서도 동작할 수 있지만 원문은 위 환경만 정기적으로 시험한다고 설명합니다. 아래 모델별 표기는 해당 고정 버전 기준입니다.

지원 로봇·통신 표 읽기

원문 표의 Y는 지원, N은 미지원, -는 별도 지원 표시가 없는 항목입니다. 모든 나열 모델의 CAN 열은 Y입니다. Scout 1.0은 V1=Y, V2=-, UART=N이며 단종입니다. Scout 2.0은 V1/V2=Y, UART=N입니다. Scout Mini Skid·Omni와 Hunter 1.0은 V1/V2=Y, UART=-입니다. Hunter 2.0은 V1=-, V2=Y, UART=-입니다. Bunker는 V1/V2=Y, UART=-입니다. Tracer는 V1=-, V2=Y, UART=N입니다. Ranger Mini 1.0은 V1=-, V2=Y*, UART=-이며 단종입니다. Ranger Mini 2.0·3.0 및 Ranger는 V1=-, V2=Y, UART=-입니다. 단종으로 명시한 두 모델 외에는 원문에서 Active로 표시합니다.

프로토콜과 구형 모델 주의사항

main 브랜치는 나열한 로봇 모델 및 V1·V2 프로토콜을 지원합니다. v1.x·v2.x 브랜치는 각각 이전 V1·V2 SDK로, 적극적으로 유지보수되지 않는 참고용입니다. Ranger Mini 1.0은 일부 CAN 메시지와 기준 좌표계가 다른 수정 V2를 사용합니다. 원문은 2023년 5월 기준 단종으로 이 차이를 고치는 새 펌웨어가 나오지 않으므로 SDK에서 처리한다고 설명합니다. Ranger·Ranger Mini 2.0과 일관된 동작을 얻으려면 Ranger Mini 1.0에 RangerMiniV1Robot 클래스를 사용합니다.

의존성 설치와 빌드

터미널에서 sudo apt-get update 다음 sudo apt-get install build-essential git cmake libasio-dev를 실행합니다. catkin 작업공간의 src로 이동(cd <your-catkin-ws>/src)하여 git clone https://github.com/westonrobot/ugv_sdk.git으로 복제하고, cd .. 다음 catkin_make를 실행하는 예시입니다. 작업공간 이름은 실제 경로로 바꿉니다. 원문 명령은 공동 개발 상위 저장소를 복제하므로 이 첨부와 동일 버전이 필요하면 고정 커밋 출처를 함께 확인해야 합니다.

CAN–USB 어댑터 설정

sudo modprobe gs_usb로 커널 모듈을 활성화하고 sudo ip link set can0 up type can bitrate 500000으로 CAN 장치를 올립니다. 오류가 없다면 ifconfig -a로 확인합니다. sudo apt install can-utils로 시험 도구를 설치합니다. 수신 시험은 candump can0, 송신 예시는 cansend can0 001#1122334455667788입니다. scripts 폴더의 setup_can2usb.bash는 첫 설정, bringup_can2usb.bash는 어댑터를 뺐다 다시 꽂을 때 장치를 올리는 용도입니다.

CAN 기록과 로봇 예제

분석용 로그는 candump -l can0로 기록하고 canplayer -I <candump-log-file-name>.log로 재생합니다. 다른 인터페이스이면 can0를 실제 이름으로 바꿉니다. 모델별 예제는 sample 폴더에 있으며 Scout 실행 예시는 ./bin/demo_scout_robot can0입니다. 예제는 실제 로봇을 움직일 수 있으므로 원문은 조종기를 소지하고 이동 가능한 안전한 공간을 확보하거나 이동 명령을 비활성화하도록 안내합니다. 예상대로 움직이지 않으면 조종기의 수동 모드 여부와 비상정지 버튼 상태를 먼저 확인합니다.

통신 구조와 문제 찾기

첨부 interface_hierarchy.png는 로봇 베이스(CAN) ↔ ugv_sdk(C++) ↔ robot_ros(ROS) ↔ ROS 응용프로그램 구조입니다. 연결 구간은 각각 CAN 프레임, C++ 함수 호출, ROS 토픽·서비스입니다. SDK는 CAN 원시 프레임과 C++ 자료구조를 변환합니다. 먼저 candump에서 수신이 되는지 확인합니다. 메시지가 없으면 컨트롤러·어댑터·배선을 점검합니다. CAN이 정상이면 SDK로 상태 조회와 제어를 시험하고 SDK 문제가 있으면 보고합니다. SDK도 정상이면 ROS 네트워크 등 환경 설정을 살펴봅니다. ROS 래퍼 대신 C++ SDK를 직접 사용할 수도 있습니다.

세 가지 추상화 계층

interface(include/ugv_sdk/details/interface)는 각 로봇의 C++ API를 정의하며 RobotCommonInterface와 ScoutInterface 같은 모델별 인터페이스를 결합합니다. robot_base(include/ugv_sdk/details/robot_base)는 Scout·ScoutMiniOmni·ScoutMiniSkid 같은 계열별 API와 여러 CAN 프로토콜을 구현합니다. 대부분 기능이 이 계층에 있으며 특정 로봇·프로토콜과 이미 통신할 수 있습니다. mobile_robot(include/ugv_sdk/mobile_robot)는 실행 시 매개변수에 따라 같은 계열의 다른 모델을 생성하는 통합 인터페이스이며 내부에서 다형성을 처리합니다. 응용프로그램을 만들 때는 mobile_robot를 먼저 보고 더 세부 사항이 필요할 때 나머지 두 계층을 참고합니다.

참고·첨부·이용 조건

원문 Linux CAN 참고 주소는 https://notes.rdu.im/system/linux/canbus/ 입니다. 공식 README·구조도·Apache 2.0 LICENSE는 수정 없이 첨부하며 한국어 안내와 변경·출처 고지는 별도 파일로 제공합니다. 원문 README의 Cpp·ROS 상태 배지는 실시간 외부 상태이므로 번역 첨부에 복제하지 않았습니다. 본문의 모델 지원 정보는 원문 버전 기준이며 실제 연결 시험이나 장치 호환성 보증을 뜻하지 않습니다. 한국어 번역·정리는 로봇노드의 비공식 자료이며 Apache 2.0 조건을 따릅니다.

목록보기