antbot/README_ko.md at main · Terry-9067/antbot

🌐 English · 한국어

모든 길 위의 자율주행 배송 로봇
by ROBOTIS AI

시작하기 » · 패키지 » · 아키텍처 »

📌 목차

소개
패키지
아키텍처
디렉토리 구조
시작하기
- 사전 요구사항
- 설치
사용법
하드웨어 사양
ROS 2 토픽 & 인터페이스
라이선스
연락처
Contributors

🤖 소개

AntBot은 ROBOTIS AI에서 개발한 자율주행 배송 로봇용 오픈소스 소프트웨어입니다. 4바퀴가 각각 독립적으로 조향하는 스워브 드라이브 방식으로, 실제 배송 현장에서 바로 사용할 수 있는 수준의 코드를 제공합니다.

좋은 로봇은 어디든 갈 수 있어야 합니다. 좋은 기술은 누구나 쓸 수 있어야 합니다. — 자세히 보기 →

이 저장소 하나로 로봇 구동에 필요한 모든 것을 갖출 수 있습니다:

Swerve-drive controller — 역기구학 기반 4륜 독립 조향 제어, 오도메트리 출력
Hardware interface — Dynamixel Protocol 2.0으로 ANT-RCU 보드와 통신
Multi-camera driver — V4L2, USB, RGB-D 카메라 동시 지원
Sensor integration — 2D/3D LiDAR, IMU, GNSS 센서 통합 관리
Complete URDF model — 센서 프레임, 메시까지 포함된 전체 로봇 모델
One-command bringup — 명령어 하나로 전체 시스템 한 번에 실행

(상단으로)

📦 패키지

Package	설명
`antbot`	메타 패키지
`antbot_bringup`	전체 시스템 launch 파일 모음
`antbot_description`	URDF / Xacro 로봇 모델 (센서 프레임, 메시 포함)
`antbot_swerve_controller`	ros2_control 기반 스워브 드라이브 컨트롤러 (IK, 오도메트리)
`antbot_hw_interface`	RCU 보드용 ros2_control `SystemInterface` 플러그인
`antbot_libs`	Dynamixel Protocol 2.0 통신 라이브러리 (C++)
`antbot_interfaces`	커스텀 ROS 2 메시지 및 서비스 정의
`antbot_camera`	멀티 카메라 드라이버 (V4L2 / USB / Orbbec RGB-D)
`antbot_imu`	IMU 드라이버 (상보 필터, 자동 캘리브레이션)
`antbot_teleop`	키보드 원격 조종 (전방향 이동 지원)

외부 센서 드라이버 포함: vanjee_lidar_sdk (3D LiDAR), vanjee_lidar_msg (LiDAR 메시지 정의)

(상단으로)

🏛️ 아키텍처

System Block Diagram (클릭하여 펼치기)

  antbot_bringup                    antbot_description
  (launch files)                    (URDF / Xacro, meshes)
       │                                   │
       │  launches                         │  robot_description
       ▼                                   ▼
┌──────────────────────────────────────────────────────┐
│               ros2_control Framework                 │
│             (Controller Manager)                     │
│                                                      │
│   antbot_swerve_controller  ◄──── /cmd_vel           │
│   (IK, motion profiling, odometry)                   │
│             ├── /odom                                │
│             └── /tf                                  │
└───────────────────────┬──────────────────────────────┘
                 read() │ write()
                        ▼
          ┌───────────────────────────────┐
          │   antbot_hw_interface         │
          │   (BoardInterface plugin)     │
          │                               │
          │   Wheel ─ Steering            │
          │   Encoder ─ Motor             │
          │   Battery                     │
          └──────────────┬────────────────┘
                         │
          ┌──────────────▼────────────────┐
          │   antbot_libs                 │      ┌─────────────────────┐
          │   Communicator                │      │   antbot_imu        │
          │   ControlTableParser          │      │   (ImuNode)         │
          └──────────────┬────────────────┘      └──────────┬──────────┘
                         │                                  │
          ┌──────────────▼──────────────────────────────────▼───┐
          │            Serial (Dynamixel Protocol 2.0)          │
          └──────────────┬──────────────────────────────────┬───┘
                         │                                  │
                  ┌──────▼──────┐                    ┌──────▼──────┐
                  │  ANT-RCU    │                    │  IMU Board  │
                  │  Motors x4  │                    │  Accel/Gyro │
                  │  Steering x4│                    └─────────────┘
                  │  Encoders   │
                  │  Battery    │
                  └─────────────┘

          ┌───────────────────────────────┐
          │   antbot_camera               │
          │   V4L2 / USB / RGB-D          │──── /sensor/camera/*/image_raw
          └───────────────────────────────┘

          ┌───────────────────────────────┐
          │   vanjee_lidar_sdk            │
          │   3D LiDAR                    │──── /sensor/lidar_3d/point_cloud
          │   2D LiDAR × 2                │──── /sensor/lidar_2d_{front,back}/scan
          └───────────────────────────────┘

Launch Dependency Graph

bringup.launch.py
 ├── robot_state_publisher.launch.py    →  URDF → /tf, /tf_static
 ├── controller.launch.py              →  ros2_control + swerve controller
 ├── imu.launch.py                     →  6-axis IMU
 ├── lidar_2d.launch.py                →  2× 2D LiDAR (USB serial)
 ├── lidar_3d.launch.py                →  3D LiDAR (Ethernet)
 ├── ublox_gps_node-launch.py          →  u-blox GNSS
 ├── camera.launch.py                  →  V4L2 + USB + RGB-D cameras
 └── teleop_joy.launch.py             →  DualSense joystick teleop

(상단으로)

📂 디렉토리 구조

antbot/
├── antbot/                        # 메타 패키지
├── antbot_bringup/                # Launch 파일 (bringup, view, controller, sensors)
├── antbot_description/            # URDF / Xacro 모델, 메시, RViz 설정
├── antbot_swerve_controller/      # Swerve-drive 컨트롤러 (IK, 오도메트리, 프로파일링)
├── antbot_hw_interface/           # ANT-RCU용 ros2_control 하드웨어 플러그인
├── antbot_libs/                   # 공유 C++ 라이브러리 (Dynamixel 통신, XML 파싱)
├── antbot_interfaces/             # 커스텀 ROS 2 메시지 및 서비스 정의
├── antbot_camera/                 # 멀티 드라이버 카메라 노드 (V4L2, USB, RGB-D)
├── antbot_imu/                    # 상보 필터 포함 IMU 드라이버
├── antbot_teleop/                 # 키보드 텔레오퍼레이션 (Python)
├── vanjee_lidar_sdk/              # Vanjee 3D LiDAR 드라이버
├── vanjee_lidar_msg/              # Vanjee LiDAR 메시지 정의
├── docs/                          # 문서 및 이미지
├── scripts/                       # 유틸리티 스크립트
│   └── setting.sh                 # 의존성 설치 스크립트
└── additional_repos.repos         # vcs import용 외부 저장소 목록

(상단으로)

🚀 시작하기

Quick Start — ROS 2 Humble이 이미 설치되어 있다면?

mkdir -p ~/antbot_ws/src && cd ~/antbot_ws/src
git clone https://github.com/ROBOTIS-move/antbot.git
cd ~/antbot_ws/src/antbot && bash scripts/setting.sh
cd ~/antbot_ws && colcon build --symlink-install && source install/setup.bash
ros2 launch antbot_bringup bringup.launch.py

사전 요구사항

설치

1. 워크스페이스를 생성하고 저장소를 클론합니다:

mkdir -p ~/antbot_ws/src && cd ~/antbot_ws/src
git clone https://github.com/ROBOTIS-move/antbot.git

2. 설정 스크립트를 실행하여 의존성을 설치합니다 (시스템 도구, 외부 저장소, rosdep 기반 ROS 의존성):

cd ~/antbot_ws/src/antbot
bash scripts/setting.sh

3. 워크스페이스를 빌드합니다:

cd ~/antbot_ws
colcon build --symlink-install

4. 워크스페이스를 소싱합니다:

source ~/antbot_ws/install/setup.bash

💡 Tip: ~/.bashrc에 source ~/antbot_ws/install/setup.bash를 추가하면 새 터미널마다 자동으로 소싱됩니다.

(상단으로)

🎮 사용법

전체 로봇 Bringup

ros2_control, swerve controller, IMU, LiDAR, GPS, 카메라를 포함한 전체 시스템을 실행합니다:

ros2 launch antbot_bringup bringup.launch.py

시각화

RViz로 모든 센서 모니터링 (별도 PC에서 실행):

ros2 launch antbot_bringup view.launch.py

URDF 모델 미리보기 (하드웨어 불필요):

ros2 launch antbot_description description.launch.py

원격 조종

키보드로 직접 조종:

# 키보드 텔레오퍼레이션 (터미널에서 실행)
ros2 run antbot_teleop teleop_keyboard

# 조이스틱 텔레오퍼레이션 (DualSense, USB)
ros2 launch antbot_teleop teleop_joy.launch.py

키 바인딩:

Key	Action
`W` / `X`	전진 / 후진
`A` / `D`	좌측 / 우측 이동
`Q` / `E`	반시계 / 시계 회전
`1` ~ `9`	속도 레벨
`ESC`	종료

조이스틱 버튼 바인딩 (DualSense):

수동 속도 명령

# 0.5 m/s로 전진
ros2 topic pub /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.5, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"

# 0.3 m/s로 우측 이동
ros2 topic pub /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.0, y: -0.3, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}"

# 1.0 rad/s로 제자리 회전
ros2 topic pub /cmd_vel geometry_msgs/msg/Twist \
  "{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 1.0}}"

(상단으로)

🔧 하드웨어 사양

구성 요소	사양
Drive Type	4륜 독립 조향 스워브 드라이브
Control Board	ANT-RCU (Dynamixel Protocol 2.0, ID 200)
Communication	USB Serial @ 4 Mbps
Wheel Motors	4× (M1–M4), 범위: −185 ~ 185 RPM
Steering Motors	4× (S1–S4), 범위: −56.2° ~ 56.2°
Cameras	1× 스테레오 RGB-D + 4× 모노 (V4L2)
3D LiDAR	3D LiDAR (Ethernet)
2D LiDAR	2× 2D LiDAR (USB Serial)
IMU	6축 (3축 가속도계 + 3축 자이로스코프)
GNSS	u-blox GPS 수신기
Battery	BMS 모니터링 (전압, 전류, SoC, 온도)

(상단으로)

📡 ROS 2 토픽 & 인터페이스

Published Topics

Topic	Type	설명
`/odom`		Swerve controller 오도메트리
`/tf`		Transform tree
`/imu/accel_gyro`		IMU 데이터 (쿼터니언, 각속도, 선가속도)
`/sensor/camera/*/image_raw`		카메라 이미지 스트림
`/sensor/camera/*/camera_info`		카메라 캘리브레이션 데이터
`/sensor/lidar_3d/point_cloud`		3D 포인트 클라우드
`/sensor/lidar_2d_front/scan`		전방 2D 레이저 스캔
`/sensor/lidar_2d_back/scan`		후방 2D 레이저 스캔

Subscribed Topics

Topic	Type	설명
`/cmd_vel`		속도 명령 (linear x/y + angular z)

Services

Service	Type	설명
`/cargo/command`		화물함 잠금 / 해제
`/headlight/operation`		전조등 켜기 / 끄기
`/wiper/operation`		와이퍼 모드 설정 (OFF / ONCE / REPEAT)

Key Dependencies

Package	용도
	Dynamixel Protocol 2.0 통신
	Controller manager 프레임워크
	파라미터 자동 생성
	ROS ↔ OpenCV 이미지 변환
	Control table XML 파싱
	RViz IMU 시각화