ROS 2 토픽 레퍼런스

로봇 소프트웨어가 CycloneDDS로 노출하는 ROS 2 토픽의 전체 레퍼런스입니다.

ROS 2 호환 DDS로 직접 통신하므로 ros2 topic, rviz2, rqt가 로봇과 그대로 연동됩니다.

Pub — 로봇이 발행, 사용자 노드가 구독
Sub — 사용자 노드가 발행, 로봇이 구독

커스텀 메시지 타입(rbq_msgs/*, api/*)은 빌드된 워크스페이스 소싱 후 사용 가능합니다:

bash

source rbq_sdk/ros2/install/setup.bash

발행 주기 — Network/DdsBridge가 모든 Pub 상태 토픽을 하나의 ~500 Hz 루프로 재발행하므로, 아래 Hz는 그 발행 주기(ros2 topic hz로 측정)이며 센서/값의 실제 갱신 주기가 아닙니다.

모션 명령 토픽

`/rbq/cmd/auto_start`

항목	내용
타입	`std_msgs/Bool`
방향	Sub
설명	전체 초기화 시퀀스 실행: CAN 확인 → 홈 탐색 → 제어 시작. 올바른 초기 자세 필요. 진행 상황은 `/rbq/robot_status`의 `can_check`, `find_home`, `con_start` 플래그로 확인.

`/rbq/cmd/switch_gait`

항목	내용
타입	`std_msgs/Int8`
방향	Sub
설명	`gait_id` 값으로 목표 보행 모드로 전환. 아래 보행 상태 레퍼런스 참조.

`/rbq/cmd/switch_control_mode`

항목	내용
타입	`std_msgs/Bool`
방향	Sub
설명	`true` → 하이레벨 명령 모드 (`/rbq/cmd/high_level` 수신). `false` → 조이스틱 모드 (기본값).

`/rbq/cmd/emergency`

항목	내용
타입	`std_msgs/Bool`
방향	Sub
설명	즉시 전체 관절을 고감쇠 모드로 설정합니다. 로봇이 즉시 쓰러집니다. 테스트 시 먼저 앉히고 사용하세요.

`/rbq/cmd/dock`

항목	내용
타입	`std_msgs/Int8MultiArray`
방향	Sub
설명	자동 도킹 시퀀스를 시작합니다. `data[0]`: 보행 모드 — `0` = wave(기본값), `1` = trot. `data[1]`: 비전 모드 — `0` = blind(기본값), `1` = 비전 높이 피드백(trot 전용). 로봇이 서 있는(Standing) 상태여야 하며 후방 카메라가 ArUco 마커(≤ 5 m)를 봐야 합니다. `robot_status.docking_state`로 확인.

`/rbq/ref/payload_params`

항목	내용
타입	`std_msgs/Float64MultiArray`
방향	Sub
설명	CoM 보상을 위한 외부 페이로드 파라미터 설정. `data: [mass_kg, com_x, com_y, com_z]` (미터). 추가 하중을 실을 때 사용.

보행 상태 레퍼런스

명령과 상태 모두 하나의 gait enum을 사용합니다. HighLevelCommand.gait_state(switch_gait도 사용)로 보내고, robot_status.gait_id로 같은 값을 읽습니다.

`gait_id`	이름	설명
`-2`	Fall Mode	예기치 않은 균형 상실로 트리거
`-1`	Control Off	모든 제어 비활성
`0`	Sitting	낮은 자세, 지면에 착지
`1`	Standing	중립 자세, 보행 준비
`2`	Aim Mode	타게팅용 조준 자세
`3`	Walk (Trot)	트롯 보행
`4`	Stairs	계단 보행 (카메라 사용)
`5`	Wave	웨이브 보행
`6`	Run	고속 보행
`30`	RL Trot	강화학습 트롯
`31`	RL Front Walk	RL 전진 보행
`33`	RL Left Walk	RL 좌측 보행
`34`	RL Right Walk	RL 우측 보행
`35`	RL Bound	RL 바운드 보행
`36`	RL Pace	RL 페이스 보행
`37`	RL Pronk	RL 프롱크 보행
`38`–`41`	RL 3-Leg	RL 3족 보행 (HR, HL, FR, FL)
`42`	RL Trot Vision	비전 연동 RL 트롯
`45`	RL Trot Run	RL 고속 트롯
`46`	RL Silent	RL 저소음 보행
`47`	RL Stairs	RL 계단 보행

하이레벨 제어

`/rbq/cmd/high_level`

항목	내용
타입	`rbq_msgs/HighLevelCommand`
방향	Sub
설명	속도 및 자세 명령. 동작과 유효 범위는 현재 보행 모드에 따라 다릅니다. 하이레벨 모드 필요 (`switch_control_mode: true`).

필드:

필드	타입	단위	설명
`header`	`std_msgs/Header`	—	타임스탬프 포함 ROS 헤더
`identifier`	`string`	—	로깅/추적용 선택 라벨
`roll`	`float32`	deg	몸체 롤. Standing `[-25, +25]`
`pitch`	`float32`	deg	몸체 피치. Standing `[-20, +20]`, Walk (몸체 기울임 각), RL Walk `[-25, +25]`
`yaw`	`float32`	deg	몸체 요 트위스트. Standing `[-25, +25]`
`vel_x`	`float32`	m/s	전진 속도. Walk `[-1.0, +1.2]` / Run `[-1.0, +1.8]` / RL Trot `[-1.5, +2.0]` / RL Walk `[-1.5, +2.5]` / Stairs `[-1.0, +1.0]`
`vel_y`	`float32`	m/s	측면 속도. Walk `[-0.4, +0.4]` / Run `[-0.6, +0.6]` / RL Trot `[-1.0, +1.0]` / RL Walk `[-1.0, +1.0]` / Stairs `[-0.4, +0.4]`
`omega_z`	`float32`	deg/s	요 각속도. Walk `[-75, +75]` / Stairs `[-17, +17]` / Wave `[-20, +20]` / RL Walk `[-86, +86]`
`delta_body_h`	`float32`	m	기본 대비 몸체 높이 오프셋. Standing/Walk `[-0.15, +0.05]` / RL Walk `[-0.25, +0.10]`
`delta_foot_h`	`float32`	m	스윙 발 들림 오프셋. `[-0.06, +0.04]`
`gait_state`	`int8`	—	목표 보행 ID (보행 상태 레퍼런스 참조)
`gait_transition`	`bool`	—	`true` = `gait_state`로 먼저 전환 후 명령 적용

예제 명령:

bash

# 0.5 m/s로 전진 (gait_state: 3 = Walk/Trot)
ros2 topic pub --once /rbq/cmd/high_level rbq_msgs/msg/HighLevelCommand \
'{header: {stamp: {sec: 0, nanosec: 0}, frame_id: "base"},
  identifier: "walk_fwd", roll: 0.0, pitch: 0.0, yaw: 0.0,
  vel_x: 0.5, vel_y: 0.0, omega_z: 0.0,
  delta_body_h: 0.0, delta_foot_h: 0.0,
  gait_state: 3, gait_transition: false}'

# 제자리 회전 30°/s
ros2 topic pub --once /rbq/cmd/high_level rbq_msgs/msg/HighLevelCommand \
'{header: {stamp: {sec: 0, nanosec: 0}, frame_id: "base"},
  identifier: "turn", roll: 0.0, pitch: 0.0, yaw: 0.0,
  vel_x: 0.0, vel_y: 0.0, omega_z: 30.0,
  delta_body_h: 0.0, delta_foot_h: 0.0,
  gait_state: 3, gait_transition: false}'

# 정지 (속도 0)
ros2 topic pub --once /rbq/cmd/high_level rbq_msgs/msg/HighLevelCommand \
'{header: {stamp: {sec: 0, nanosec: 0}, frame_id: "base"},
  identifier: "stop", roll: 0.0, pitch: 0.0, yaw: 0.0,
  vel_x: 0.0, vel_y: 0.0, omega_z: 0.0,
  delta_body_h: 0.0, delta_foot_h: 0.0,
  gait_state: 3, gait_transition: false}'

# 커스텀 서 있는 자세 (roll: 15°, pitch: 30°, yaw: 20°)
ros2 topic pub --once /rbq/cmd/high_level rbq_msgs/msg/HighLevelCommand \
'{header: {stamp: {sec: 0, nanosec: 0}, frame_id: "base"},
  identifier: "standing_pose", roll: 15.0, pitch: 30.0, yaw: 20.0,
  vel_x: 0.0, vel_y: 0.0, omega_z: 0.0,
  delta_body_h: 0.0, delta_foot_h: 0.0,
  gait_state: 1, gait_transition: true}'

`/rbq/cmd/navigate_to`

항목	내용
타입	`geometry_msgs/Pose2D`
방향	Sub
설명	절대 월드 좌표 자세로 이동. `x`, `y`는 목표 위치(미터), `theta`는 목표 요(라디안). Standing과 Wave 모드에서 사용 가능.

`/rbq/cmd/target_go`

항목	내용
타입	`rbq_msgs/TargetGo`
방향	Sub
설명	상대 "목표 지점 이동" 내비게이션 명령(gait, mode, `x`/`y`/`theta`, 오프셋, `slow`/`wide`/`vision` 플래그). Target-Go 예제 참조.

로봇 상태

`/rbq/robot_status`

항목	내용
타입	`rbq_msgs/RobotStatus`
방향	Pub
Hz	500
설명	전반적인 로봇 상태 플래그, 보행 상태, 도킹 진행 상황.

필드:

필드	타입	설명
`header`	`std_msgs/Header`	ROS 헤더
`con_start`	`bool`	모터 제어 활성
`ready_pos`	`bool`	준비 자세 도달
`ground_pos`	`bool`	지면/착지 자세
`force_con`	`bool`	힘 제어 모드 활성
`ext_joy`	`bool`	외부 조이스틱 연결
`is_standing`	`bool`	로봇이 실제로 서 있음
`can_check`	`bool`	CAN 통신 확인됨
`find_home`	`bool`	엔코더 홈 탐색 완료
`gait_id`	`int8`	현재 보행. 보행 상태 레퍼런스 참조.
`is_fall`	`bool`	낙상 감지
`docking_state`	`int8`	도킹 진행 상황 (아래 표 참조)
`imu_success`	`bool`	IMU 연결·정상 동작

도킹 상태 값:

값	상수	설명
`-6`	`DOCKING_MAX_FAIL_CNT_REACHED`	최대 재시도(10회) 도달 — 중단
`-5`	`DOCKING_MARKER_POS_INVALID_ROTATION`	마커 회전 > ±40° — 중단
`-4`	`DOCKING_MARKER_POS_INVALID_TOO_FAR`	마커 > 5 m — 중단
`-3`	`DOCKING_MARKER_POS_INVALID_WRONG_DIR`	마커가 전면에서 감지됨 — 중단
`-2`	`DOCKING_MARKER_NOT_FOUND`	마커 미발견 — 중단
`-1`	`DOCKING_FAILED`	도킹 실패 — 자동 재시도
`0`	`DOCKING_OPERATION_MODE`	정상 동작 (도킹 아님)
`1`	`DOCKING_APPROACH_OFFSET`	1단계: 오프셋 접근
`2`	`DOCKING_APPROACH`	2단계: 직접 접근
`3`	`DOCKING_APPROACH_WIDE`	3단계: 넓은 스탠스 접근
`4`	`DOCKING_SIT_DOWN`	연결을 위해 앉는 중
`5`	`DOCKING_SUCCESS`	도킹 완료 — 충전기 물리 연결
`6`	`DOCKING_SUCCESS_CHARGING`	도킹 및 충전 중
`7`	`DOCKING_SUCCESS_NO_CHARGING`	도킹됐으나 미충전

`/rbq/system_log`

항목	내용
타입	`rbq_msgs/SystemLog`
방향	Pub
설명	로봇 측 로그 스트림. 필드: `header`, `string log_level`, `string log_msg`.

상태 추정

`/rbq/odometry`

항목	내용
타입	`nav_msgs/Odometry`
방향	Pub
Hz	500
설명	월드 좌표계에서의 몸체 자세·속도. 원점은 시작 시 리셋. IMU와 다리 오도메트리를 융합.

`/rbq/foot_states`

항목	내용
타입	`rbq_msgs/FootStates`
방향	Pub
Hz	500
설명	몸체 중심 좌표 기준 4개 다리의 발 위치·속도·접촉 상태.

필드:

필드	타입	설명
`header`	`std_msgs/Header`	ROS 헤더
`foot_position_rt_body`	`geometry_msgs/Point[4]`	몸체 중심 기준 발 위치. +X=전방, +Y=좌, +Z=상
`foot_velocity_rt_body`	`geometry_msgs/Point[4]`	몸체 좌표 기준 발 속도
`foot_contact_est`	`uint8[4]`	발별 접촉 상태: `0` = `CONTACT_LOST`, `1` = `CONTACT_MADE`
`foot_force_est`	`float32[4]`	추정 접촉력 [N]

다리 순서: [0] = 전방-좌, [1] = 전방-우, [2] = 후방-좌, [3] = 후방-우

센서 피드백

`/rbq/imu`

항목	내용
타입	`sensor_msgs/Imu`
방향	Pub
Hz	500
설명	원시 IMU 데이터. 몸체 중심 대비 센서 오프셋: `(0.00665, 0.0, -0.0404)` m. 좌표: +X=전방, +Y=좌, +Z=상. 각속도 범위 ±2000 °/s, 가속도 범위 ±16 g.

`/rbq/joint_states`

항목	내용
타입	`sensor_msgs/JointState`
방향	Pub
Hz	500
설명	표준 ROS 포맷의 12개 다리 관절 위치[rad]·속도[rad/s]·토크[Nm].

`/rbq/leg_joint`

항목	내용
타입	`rbq_msgs/LegJointInfo`
방향	Pub
Hz	500
설명	12개 다리 관절의 상세 관절별 상태. `LegJointInfo`는 `JointInfo[12] joint`를 감쌉니다 — 관절당 `JointInfo` 하나 (`JointStatus` 메시지는 없음).

관절 순서(관례): [0]HRR [1]HRP [2]HRK [3]HLR [4]HLP [5]HLK [6]FRR [7]FRP [8]FRK [9]FLR [10]FLP [11]FLK — 단, 각 joint[i]는 자체 3글자 name을 가지며 이것이 authoritative 식별자입니다.

JointInfo 필드 (joint[12]의 각 원소):

필드	타입	단위	설명
`pos`	`float32`	rad	측정 위치
`vel`	`float32`	rad/s	각속도
`acc`	`float32`	rad/s²	각가속도
`torque`	`float32`	N·m	측정 토크
`kp`	`float32`	Nm/rad	위치 게인
`kd`	`float32`	Nm·s/rad	감쇠 게인
`owner`	`int8`	—	관절을 소유한 프로세스 (`0`–`40`)
`ref_ff_torque`	`float32`	N·m	기준 피드포워드 토크
`ref_position`	`float32`	rad	기준(목표) 위치
`ref_vel`	`float32`	rad/s	기준 속도
`current`	`float32`	A	모터 전류
`temperature_board`	`int8`	°C	제어 보드 온도
`temperature_coil`	`int8`	°C	모터 코일 온도
`name`	`string≤3`	—	3글자 관절 이름, 예: `"HRR"`
`status`	`string≤3`	—	3글자 라이프사이클: `NON`/`CON`/`HOM`/`RUN`
`error_msg`	`string≤3`	—	3글자 에러 코드, 예: `"JAM"`, `"OK"`

토크 한계: Roll/Pitch ±104 Nm — Knee −70 / +140 Nm

전원 제어

`/rbq/cmd/switch_power`

항목	내용
타입	`std_msgs/Int8MultiArray`
방향	Sub
설명	PDU 전원 포트 토글. `data: [port_id, state]` — `state`: `1`=ON, `0`=OFF.

포트 ID 레퍼런스:

`port_id`	포트
`0` (`0x00`)	48 V — 다리 액추에이터
`1` (`0x01`)	48 V — 애드온 장치 (상단)
`2` (`0x02`)	48 V — 외부 포트 (상단)
`16` (`0x10`)	12 V — 비전 PC (내부)
`17` (`0x11`)	12 V — LAN 통신 포트 (상단)
`18` (`0x12`)	12 V — LiDAR 포트 (상단)
`19` (`0x13`)	12 V — CCTV 포트 (상단)
`20` (`0x14`)	12 V — 열화상 카메라 포트 (상단)
`21` (`0x15`)	12 V — IR LED (전/후면 패널)
`22` (`0x16`)	12 V — 스피커 앰프
`32` (`0x20`)	5 V — 카메라 USB 허브
`33` (`0x21`)	5 V — 오디오 / 사이드캠 USB 허브

cpp

// PDU 포트 ID enum (switch_power의 data[0]으로 사용)
enum PDU_PORT_IDs_e : unsigned char {
    PDU_PORT_48V_LEG                   = 0x00,  // 다리 액추에이터
    PDU_PORT_48V_ADD                   = 0x01,  // 애드온 장치
    PDU_PORT_48V_EXT                   = 0x02,  // 외부 포트
    PDU_PORT_12V_VisionPC              = 0x10,  // 비전 PC
    PDU_PORT_12V_COMM                  = 0x11,  // LAN 통신 포트
    PDU_PORT_12V_Lidar                 = 0x12,  // LiDAR 포트
    PDU_PORT_12V_CCTV                  = 0x13,  // CCTV 포트
    PDU_PORT_12V_THER                  = 0x14,  // 열화상 카메라
    PDU_PORT_12V_IRLed                 = 0x15,  // IR LED
    PDU_PORT_12V_Speaker               = 0x16,  // 스피커 앰프
    PDU_PORT_5V_CAMERAS                = 0x20,  // 카메라 USB 허브
    PDU_PORT_5V_AUDIO_SIDE_CAM_USBHUB  = 0x21,  // 오디오/사이드캠 USB 허브
};

예제: 12V LiDAR 포트 켜기 (PDU_PORT_12V_Lidar = 0x12 → 10진수 18)

bash

ros2 topic pub --once /rbq/cmd/switch_power std_msgs/msg/Int8MultiArray "{data: [18, 1]}"

`/rbq/battery`

항목	내용
타입	`rbq_msgs/BatteryState`
방향	Pub
Hz	500
설명	듀얼 배터리 팩 상태. 모든 필드는 2-원소 배열 (`[0]` = 팩 0, `[1]` = 팩 1).

필드:

필드	타입	설명
`header`	`std_msgs/Header`	ROS 헤더
`identifier`	`uint32[2]`	팩별 식별자
`status`	`uint8[2]`	`0`=Unknown `1`=Missing `2`=Charging `3`=Discharging
`charge_percentage`	`uint8[2]`	충전 상태 `[0, 100]` %
`temperature`	`int8[2]`	팩 온도 [°C]
`current`	`float32[2]`	부하 전류 [A]
`voltage`	`float32[2]`	팩 전압 [V]

비전 — 카메라 센서

모든 카메라 토픽은 로봇이 발행합니다(Pub). 센서는 숫자 id로 식별됩니다 — sensor_0–sensor_5 (기존 이름 기반 sensor_bottom_N / sensor_front / sensor_rear 토픽은 사라짐). 각 스트림은 /compressed, /camera_info, 그리고 스트림별 /tf(geometry_msgs/PoseStamped)를 가집니다.

센서 id	위치	스트림
`sensor_0`–`sensor_3`	하단/몸체 깊이 센서	`depth`, `ir`
`sensor_4`	전방 RGB-D	`depth`, `rgb`
`sensor_5`	후방 RGB-D (ArUco 도킹에도 사용)	`depth`, `rgb`

토픽 패턴: /rbq/vision/sensor_{N}/{stream}/{sub}

토픽	타입	설명
`/rbq/vision/sensor_{N}/{stream}/compressed`	`sensor_msgs/CompressedImage`	압축 프레임 (depth=PNG, ir/rgb=JPEG)
`/rbq/vision/sensor_{N}/{stream}/camera_info`	`sensor_msgs/CameraInfo`	내부 파라미터 + 왜곡
`/rbq/vision/sensor_{N}/{stream}/tf`	`geometry_msgs/PoseStamped`	몸체 기준 센서 자세

{stream}은 sensor_0–sensor_3에서 depth/ir, sensor_4/sensor_5에서 depth/rgb 입니다.

카메라 스레드는 구독자가 붙어 있는 동안에만 발행합니다(hasSubscribers 게이트) — 먼저 구독한 뒤 읽으세요.

TF

`/tf`

항목	내용
타입	`tf2_msgs/TFMessage`
방향	Pub
설명	런타임에 방송되는 동적 변환: `odom → base_link`, 몸체 → 다리 링크, 몸체 → 센서 프레임.

/tf_static(URDF 고정 변환)는 rbq_description의 robot_state_publisher가 발행합니다. 즉 ros2 launch rbq_description description.launch.py를 실행할 때만 나오며, 로봇 코어 소프트웨어가 내보내는 것이 아닙니다.

`/rbq/joy`

항목	내용
타입	`sensor_msgs/Joy`
방향	Pub
설명	로봇의 현재 조이스틱 입력 상태(패스스루). 축 `[0–5]`: 좌-X, 좌-Y, 우-X, 우-Y, L2, R2. 버튼 `[0–15]`.

토픽 구독 예제

bash

# 로봇 상태 (50 Hz)
ros2 topic echo --once /rbq/robot_status

# 관절별 다리 상태 (50 Hz)
ros2 topic echo --once /rbq/leg_joint

# IMU 데이터 (200 Hz)
ros2 topic echo --once /rbq/imu

# 배터리 상태 (10 Hz)
ros2 topic echo --once /rbq/battery

# 발 접촉 상태 (50 Hz)
ros2 topic echo --once /rbq/foot_states

# 오도메트리 (50 Hz)
ros2 topic echo --once /rbq/odometry

ROS 2 토픽 레퍼런스 ​

모션 명령 토픽 ​

/rbq/cmd/auto_start ​

/rbq/cmd/switch_gait ​

/rbq/cmd/switch_control_mode ​

/rbq/cmd/emergency ​

/rbq/cmd/dock ​

/rbq/ref/payload_params ​

보행 상태 레퍼런스 ​

하이레벨 제어 ​

/rbq/cmd/high_level ​

/rbq/cmd/navigate_to ​

/rbq/cmd/target_go ​

로봇 상태 ​

/rbq/robot_status ​

/rbq/system_log ​

상태 추정 ​

/rbq/odometry ​

/rbq/foot_states ​

센서 피드백 ​

/rbq/imu ​

/rbq/joint_states ​

/rbq/leg_joint ​

전원 제어 ​

/rbq/cmd/switch_power ​

/rbq/battery ​

비전 — 카메라 센서 ​

TF ​

/tf ​

/rbq/joy ​

토픽 구독 예제 ​

ROS 2 토픽 레퍼런스

모션 명령 토픽

`/rbq/cmd/auto_start`

`/rbq/cmd/switch_gait`

`/rbq/cmd/switch_control_mode`

`/rbq/cmd/emergency`

`/rbq/cmd/dock`

`/rbq/ref/payload_params`

보행 상태 레퍼런스

하이레벨 제어

`/rbq/cmd/high_level`

`/rbq/cmd/navigate_to`

`/rbq/cmd/target_go`

로봇 상태

`/rbq/robot_status`

`/rbq/system_log`

상태 추정

`/rbq/odometry`

`/rbq/foot_states`

센서 피드백

`/rbq/imu`

`/rbq/joint_states`

`/rbq/leg_joint`

전원 제어

`/rbq/cmd/switch_power`

`/rbq/battery`

비전 — 카메라 센서

TF

`/tf`

`/rbq/joy`

토픽 구독 예제