Skip to content

ROS 2 토픽 레퍼런스 ​

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

따로 실행할 드라이버 노드가 없습니다. 코어 소프트웨어(Network)가 ROS 2 호환 DDS로 직접 통신하므로, 브리지 프로세스 없이 ros2 topic, rviz2, rqt가 로봇과 그대로 연동됩니다. (구형 rbq_driver 노드는 제거되었습니다. scripts/start_ros_driver.bash는 자리만 남은 스크립트로, 멈출 때까지 10초마다 deprecated 안내를 출력합니다.)

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

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

bash
source rbq_sdk/ros2/install/setup.bash

이름에 _로 시작하는 토큰이 있는 토픽(예: /rbq/_sim, /rbq/_user_command, /rbq/ref/motion/_0)은 숨김 토픽입니다 — ros2 topic list에서는 --include-hidden-topics를 줄 때만 보입니다.

발행 주기 — Network가 모든 Pub 상태 토픽을 DDS 구독자가 하나라도 붙어 있는 동안 ~500 Hz로 재발행하므로(구독자가 없으면 보내지 않습니다), 아래 Hz는 그 발행 주기(ros2 topic hz로 측정)이며 센서/값의 실제 갱신 주기가 아닙니다.

Zenoh — 이 가운데 일부는 같은 이름·같은 메시지로 Zenoh 에도 있어 rmw_zenoh 를 쓰는 ROS 2 노드에도 보입니다: /rbq/odometry(500 Hz), /rbq/robot_status·/rbq/battery(50 Hz), /rbq/led_bottom(1 Hz), 그리고 명령 /rbq/cmd/high_level·/rbq/cmd/switch_gait·/rbq/cmd/switch_control_mode·/rbq/cmd/dock·/rbq/cmd/auto_start·/rbq/cmd/led_bottom·/rbq/cmd/ptz. 나머지는 DDS 에만 있습니다.

모션 명령 토픽 ​

/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 → 조이스틱 모드 (기본값). 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 마커를 봐야 합니다(권장 3 m 이내, 5 m 초과 시 펌웨어가 중단). robot_status.docking_state로 확인.

/rbq/ref/payload_params ​

항목내용
타입std_msgs/Float64MultiArray
방향Sub
설명CoM 보상을 위한 외부 페이로드 파라미터 설정. data: [mass_kg, com_x, com_y, com_z] (미터). 추가 하중을 실을 때 사용. /rbq/motion/set_param의 payload.*와는 다른 칸이라, 이 토픽으로 넣은 값은 get_param으로 읽히지 않습니다.

/rbq/ref/payload_slot ​

항목내용
타입std_msgs/Float64MultiArray
방향Sub
설명페이로드 칸 하나를 설정. data: [slot, mass_kg, com_x, com_y, com_z] (미터). PUT /api/payload/parameters 와 같은 검사를 하고, 다른 칸은 그대로 둔다.

/rbq/option/status ​

항목내용
타입std_msgs/String
방향Sub
설명깔린 옵션의 프로그램이 보내는 상태(JSON): {"items":[{"key","label","value","unit","level"}]} (level 은 ok·warn·error, 64 개까지). 앱은 GET /api/option/status 로 읽는다. 5초 안에 받은 error 항목이 있으면 통신 끊김 램프가 켜진다.

/rbq/option/command ​

항목내용
타입std_msgs/String
방향Pub
설명깔린 옵션의 프로그램에 보내는 명령(JSON {"key","value"}). POST /api/option/command 가 보낸다.

보행 상태 레퍼런스 ​

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

gait_id이름설명
-3Fall Recovery낙상 후 자동 복구 시도
-2Fall Mode예기치 않은 균형 상실로 트리거
-1Control Off모든 제어 비활성
0Sitting낮은 자세, 지면에 착지
1Standing중립 자세, 보행 준비
3Walk (Trot)트롯 보행
4Stairs계단 보행 (카메라 사용)
5Wave웨이브 보행
10Docking자동 도킹 시퀀스
48RL Walk (Vision)비전 기반 지형 적응 학습 보행
49RL Walk학습 기반 보행

-3, -2, -1 은 상태 보고 전용입니다 — switch_gait 와 HighLevelCommand 모두 무시합니다. 10 은 switch_gait 로만 도킹(wave, blind)을 시작하며 HighLevelCommand 는 무시합니다. 보행·비전 모드를 고르려면 /rbq/cmd/dock을 쓰세요.

RL Gait 지정 방법

STATE_RL_WALK_VISION(48) 또는 STATE_RL_WALK(49)를 사용하세요. 나머지 STATE_RL_* 상수(30–47)는 지원하지 않습니다.

보행 상태 전환 다이어그램

하이레벨 제어 ​

/rbq/cmd/high_level ​

항목내용
타입rbq_msgs/HighLevelCommand
방향Sub
설명속도 및 자세 명령. 동작과 유효 범위는 현재 보행 모드에 따라 다릅니다. 하이레벨 모드 필요 (switch_control_mode: true). 마지막 명령이 1초 이상 오래되면 vel_x · vel_y · omega_z는 0으로 처리됩니다 (자세·높이는 마지막 값 유지).

필드:

필드타입단위설명
headerstd_msgs/Header—타임스탬프 포함 ROS 헤더
identifierstring—로깅/추적용 선택 라벨
rollfloat32deg몸체 롤. Standing [-25, +25]
pitchfloat32deg몸체 피치. Standing [-20, +20], Walk (몸체 기울임 각), RL Walk [-25, +25]
yawfloat32deg몸체 요 트위스트. Standing [-25, +25]
vel_xfloat32m/s전진 속도. Walk [-1.0, +1.2] / RL Walk [-1.5, +2.5] / Stairs [-1.0, +1.0]
vel_yfloat32m/s측면 속도. Walk [-0.4, +0.4] / RL Walk [-1.0, +1.0] / Stairs [-0.4, +0.4]
omega_zfloat32deg/s요 각속도. Walk [-75, +75] / Stairs [-17, +17] / Wave [-20, +20] / RL Walk [-86, +86]
delta_body_hfloat32m기본 대비 몸체 높이 오프셋. Standing/Walk [-0.15, +0.05] / RL Walk [-0.25, +0.10]
delta_foot_hfloat32m스윙 발 들림 오프셋. [-0.06, +0.04]
gait_stateint8—목표 보행 ID (보행 상태 레퍼런스 참조)
gait_transitionbool—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}'

지속 주행은 주기 발행이 필요합니다

안전을 위해 마지막 명령이 1초를 넘기면 속도가 0으로 처리되므로, --once로 보낸 속도 명령은 1초 안에 멈춥니다. 계속 걷게 하려면 ros2 topic pub -r 50 … 처럼 주기적으로 발행하세요 (중단은 Ctrl+C). gait_transition: true이고 현재 모드가 gait_state와 다르면 그 메시지는 모드 전환만 수행하고 속도는 적용하지 않습니다 — 모드를 먼저 바꾼 뒤 속도를 스트리밍하세요.

/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
Hz500
설명전반적인 로봇 상태 플래그, 보행 상태, 도킹 진행 상황.

필드:

필드타입설명
headerstd_msgs/HeaderROS 헤더
con_startbool모터 제어 활성
ready_posbool준비 자세 도달
ground_posbool지면/착지 자세
force_conbool힘 제어 모드 활성
ext_joybool외부 조이스틱 연결
is_standingbool로봇이 실제로 서 있음
can_checkboolCAN 통신 확인됨
find_homebool엔코더 홈 탐색 완료
gait_idint8현재 보행. 보행 상태 레퍼런스 참조.
is_fallbool낙상 감지
docking_stateint8도킹 진행 상황 (아래 표 참조)
imu_successboolIMU 연결·정상 동작

도킹 상태 값:

값상수설명
-5DOCKING_ABORTED사용자 또는 외부 명령으로 취소 — 중단
-4DOCKING_MAX_FAIL_CNT_REACHED최대 재시도(10회) 도달 — 중단
-3DOCKING_MARKER_POS_INVALID_TOO_FAR마커 > 5 m — 중단
-2DOCKING_MARKER_NOT_FOUND마커 미발견 — 중단
-1DOCKING_FAILED도킹 실패 — 자동 재시도
0DOCKING_OPERATION_MODE정상 동작 (도킹 아님)
1DOCKING_APPROACH_OFFSET1단계: 오프셋 접근
2DOCKING_APPROACH2단계: 직접 접근
3DOCKING_APPROACH_WIDE3단계: 넓은 스탠스 접근
4DOCKING_SIT_DOWN연결을 위해 앉는 중
5DOCKING_SUCCESS도킹 완료 — 충전기 물리 연결
6DOCKING_SUCCESS_CHARGING도킹 및 충전 중
7DOCKING_SUCCESS_NO_CHARGING도킹됐으나 미충전

/rbq/system_log ​

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

하트비트 ​

diagnostic_msgs/DiagnosticArray 토픽 세 개가 1초에 한 번 로봇 각 부분이 살아 있는지 알립니다 — 500 Hz 상태 토픽까지는 필요 없는 감시 도구용입니다. 각 토픽은 구독자가 붙어 있는 동안에만 발행됩니다. level은 0 정상, 1 경고, 2 오류이고, values에 문자열 key/value 쌍이 담깁니다.

/rbq/motion/heartbeat ​

항목내용
타입diagnostic_msgs/DiagnosticArray
방향Pub
Hz1
설명Network가 발행합니다. 상태 하나, motion: 넘어져 있는 동안 level 1·message fall detected, 아니면 0·ok. values는 /rbq/robot_status의 플래그를 0/1 문자열로 되풀이합니다: gait, gait_name, control_mode(= ext_joy), con_start, ready_pos, is_standing, is_fall, can_check, find_home, imu_success, docking_state.

/rbq/vision/heartbeat ​

항목내용
타입diagnostic_msgs/DiagnosticArray
방향Pub
Hz1
설명비전 PC 의 Streamer가 발행합니다. 상태 하나, vision.programs에 비전 프로그램마다 값 하나 — handler, hal, streamer, handeye, heightmap, slamnav, cctv, ptz, thermal, human_following, obstacleavoid — 가 running, idle(프로세스는 떠 있고 작업 스레드는 안 도는 상태) 또는 stopped로 실립니다. 프로그램 표를 읽지 못하면 level 2·message vision ipc unavailable.

/rbq/sensor/heartbeat ​

항목내용
타입diagnostic_msgs/DiagnosticArray
방향Pub
Hz1
설명비전 PC 의 HAL이 발행합니다. 켜져 있거나 동작 중인 센서 슬롯마다 상태 하나, 이름은 sensor_{N}. 센서가 실패하면 level 2(message failed), 켜져 있는데 감지되지 않으면 1, 아니면 0.

값:

키설명
name센서 이름
typeusbcam, realsense, oak, lidar, lan 또는 unknown
enabled, detected, run1 또는 0
fps_rgb, fps_ir, fps_depth스트림별 프레임 속도(카메라만)
day, projector_on1 또는 0(카메라만)
fps_pointcloud포인트클라우드 속도(lidar만)

상태 추정 ​

/rbq/odometry ​

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

/rbq/foot_states ​

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

필드:

필드타입설명
headerstd_msgs/HeaderROS 헤더
foot_position_rt_bodygeometry_msgs/Point[4]몸체 중심 기준 발 위치. +X=전방, +Y=좌, +Z=상
foot_velocity_rt_bodygeometry_msgs/Point[4]몸체 좌표 기준 발 속도
foot_contact_estuint8[4]발별 접촉 상태: 0 = CONTACT_LOST, 1 = CONTACT_MADE
foot_force_estfloat32[4]추정 접촉력 [N]

다리 순서: [0] = 후방-우, [1] = 후방-좌, [2] = 전방-우, [3] = 전방-좌 — 관절과 같은 HR, HL, FR, FL 순서

센서 피드백 ​

/rbq/imu ​

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

/rbq/joint_states ​

항목내용
타입sensor_msgs/JointState
방향Pub
Hz500
설명표준 ROS 포맷의 12개 다리 관절 이름과 위치[rad]. velocity·effort는 비어 있습니다 — /rbq/leg_joint에서 읽으세요.

/rbq/leg_joint ​

항목내용
타입rbq_msgs/LegJointInfo
방향Pub
Hz500
설명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]의 각 원소):

필드타입단위설명
posfloat32rad측정 위치
velfloat32rad/s각속도
accfloat32rad/s²항상 0 — 채우지 않음
torquefloat32N·m측정 토크
kpfloat32Nm/rad위치 게인
kdfloat32Nm·s/rad감쇠 게인
ownerint8—관절을 소유한 프로세스 (0–40)
ref_ff_torquefloat32N·m기준 피드포워드 토크
ref_positionfloat32rad기준(목표) 위치
ref_velfloat32rad/s레퍼런스 속도 — 일반 CAN 기체는 0(CAN FD 전용)
currentfloat32A모터 전류
temperature_boardint8°C제어 보드 온도
temperature_coilint8°C모터 코일 온도
namestring≤3—3글자 관절 이름, 예: "HRR"
statusstring≤3—3글자 라이프사이클: NON/CON/HOM/RUN
error_msgstring≤3—3글자 에러 코드, 예: "JAM", "OK"

레퍼런스 한계: 토크는 플랫폼 프로필 TORQUE_LIMIT_Nm 의 ±값(rbq10: Roll/Pitch 100 Nm, Knee 150 Nm, Wheel 30 Nm. 무릎 접는 방향은 T_LIM_K_L −70 Nm), ref_vel 은 플랫폼 프로필 VELOCITY_LIMIT_rad_s 의 ±값(rbq10: Roll/Pitch 44 rad/s, Knee 33 rad/s, Wheel 144 rad/s), pos 는 물리 관절 한계를 양쪽으로 TORQUE_LIMIT_Nm / kp 만큼 넓힌 범위(kp 가 0 이면 자르지 않고, 바퀴는 위치 한계가 없다). 한계를 넘는 값은 거부되지 않고 잘린다. 어느 필드든 NaN 이나 Inf 가 오면 그 관절은 멈춰 선다. pos·kp·kd 는 이전 값을 유지하고 torque 와 ref_vel 은 0 이 되며 경고가 기록된다.

전원 제어 ​

/rbq/cmd/switch_power ​

항목내용
타입std_msgs/Int8MultiArray
방향Sub
설명PDU 전원 포트 토글. data: [port_id, state] — state: 1=ON, 0=OFF. 보드 펌웨어 업데이트 중에는 포트 0·1 켜기를 무시합니다.

포트 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
Hz500
설명듀얼 배터리 팩 상태. 모든 필드는 2-원소 배열 ([0] = 팩 0, [1] = 팩 1).

필드:

필드타입설명
headerstd_msgs/HeaderROS 헤더
identifieruint32[2]팩별 식별자
statusuint8[2]팩별 값이 아닙니다: [0] = 수동 충전기, [1] = 충전 스테이션 — 그 충전기가 연결돼 있으면 2(Charging), 아니면 3(Discharging). 0(Unknown)·1(Missing)은 보내지 않습니다
charge_percentageuint8[2]충전 상태 [0, 100] %
temperatureint8[2]팩 온도 [°C]
currentfloat32[2]부하 전류 [A]
voltagefloat32[2]팩 전압 [V]

하단 LED ​

몸통 아래 양쪽의 상태 LED 두 개입니다. CAN FD 기체 전용 — 다른 기체에서는 명령이 거부되고 상태도 발행되지 않습니다. 시뮬레이터에서는 Motion 이 IF 보드 역할을 대신하고 MuJoCo 가 몸통 밑 LED 두 개를 보여 줍니다. 같은 설정을 REST GET / PUT /api/led/bottom 으로도 다룰 수 있습니다.

/rbq/cmd/led_bottom ​

항목내용
타입rbq_msgs/LedBottom
방향Sub
설명하단 LED 한쪽 또는 양쪽을 설정합니다. side: 1=오른쪽 2=왼쪽 3=양쪽(고르지 않은 쪽은 그대로). mode: 0=꺼 두기 1=켜 두기 2=깜빡이기. rgb: uint8[3]. on_ms / off_ms: 깜빡일 때 켜는·끄는 시간 10~2550 ms(10 ms 단위). count: 깜빡이는 횟수, 0=계속. 범위 밖 값은 거부됩니다(로봇 Network 로그). 하단 LED 예제 참조.

예: 양쪽을 빨강으로 0.5 초 켜고 0.5 초 끄기를 계속

bash
ros2 topic pub --once /rbq/cmd/led_bottom rbq_msgs/msg/LedBottom "{side: 3, mode: 2, rgb: [255, 0, 0], on_ms: 500, off_ms: 500, count: 0}"

/rbq/led_bottom ​

항목내용
타입rbq_msgs/LedBottomState
방향Pub
Hz1
설명IF 보드가 마지막으로 알려 준 값 — 보드가 쥐고 있는 설정, 전력 제한을 거친 실제 출력, 펌웨어 버전.

필드:

필드타입설명
age_msint32마지막 응답 뒤 지난 ms, -1 = 아직 응답 없음
configuredboolfalse = IF 보드가 재부팅해 설정이 없음(Motion 이 마지막 설정을 다시 보냄)
if_fwuint32IF 펌웨어 버전(yyyymmddnn), 0 = 모름
right, leftLedBottomSide아래 LED 별 상태

rbq_msgs/LedBottomSide:

필드타입설명
modeuint80=꺼 두기 1=켜 두기 2=깜빡이기
rgbuint8[3]설정한 색
on_ms, off_msuint16깜빡임 시간 [ms], 깜빡이기가 아니면 0
countuint8깜빡이는 횟수, 0=계속, 깜빡이기가 아니면 0
actualuint8[3]전력 제한을 거친 마지막 출력, 꺼져 있으면 0
limitedbool최근 1 초 안에 전력 제한이 출력을 줄였음
legacybool옛 명령으로 설정됨 — 보이는 설정은 근사값
lpf_wfloat32필터를 거친 LED 전력 [W]

비전 — 카메라 센서 ​

모든 카메라 토픽은 로봇이 발행합니다(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-Ddepth, rgb
sensor_5후방 RGB-D (ArUco 도킹에도 사용)depth, rgb

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

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

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

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

비전 — 라이다 ​

라이다(Livox)가 달린 로봇은 라이다마다 스캔과 내장 IMU 를 발행합니다. 로봇에서는 HAL이 발행하고, 시뮬레이터는 --payload livox로 띄우면 같은 토픽을 발행합니다. 카메라처럼 구독자가 붙어 있는 동안에만 보냅니다.

토픽타입설명
/rbq/lidar/lidar_frontsensor_msgs/PointCloud2전방 라이다 스캔
/rbq/lidar/lidar_front/imusensor_msgs/Imu전방 라이다 내장 IMU, 센서 자체 속도로
/rbq/lidar/lidar_rearsensor_msgs/PointCloud2후방 라이다 스캔
/rbq/lidar/lidar_rear/imusensor_msgs/Imu후방 라이다 내장 IMU, 센서 자체 속도로
  • 로봇에서는 스캔 하나가 0.1초 분량입니다(약 10 Hz).
  • 점과 IMU 는 센서 원래 좌표계(frame_id lidar_front 또는 lidar_rear)입니다 — 센서→몸체 변환은 직접 적용하세요. IMU 가속도 단위는 m/s² 입니다.
  • 점 필드(point_step 28): x, y, z, intensity, time(float32, time = header.stamp부터의 초)과 timestamp(float64, 절대 초).

GPS ​

GNSS 수신기가 달려 있고 HAL 설정에서 켰을 때만 쓸 수 있습니다(configs/HAL/config.ini: [GPS] ENABLED=true, 수신기 주소는 [GPS] ADDR·PORT). HAL은 수신기 문장을 해석하지 않고 받는 대로 넘깁니다.

토픽타입설명
/rbq/gps/nmeanmea_msgs/SentenceNMEA GGA, RMC, GST 원문, frame_id gps
/rbq/gps/insstd_msgs/String수신기 INS 의 DRPVAA 원문

nmea_msgs는 ROS 2 기본 설치에 없습니다 — /rbq/gps/nmea를 보려면 ros-<distro>-nmea-msgs를 설치하세요.

비전 — PTZ 카메라 ​

옵션인 PTZ 카메라 페이로드가 장착되고 Ptz 앱이 실행 중일 때만 사용할 수 있습니다. 이 토픽들은 모션 상태 토픽의 500 Hz가 아니라 20 Hz로 발행됩니다.

카메라에 직접 접속해 제어하는 방법(SUNAPI · RTSP · ONVIF) — 프리셋·초점·오디오·타사 VMS — 은 PTZ 카메라 API에 정리되어 있습니다.

두 토픽 모두 std_msgs/Float64MultiArray이며 배열 구성과 단위가 같습니다. 즉 보낸 값을 그대로 되읽습니다.

인덱스항목단위범위
data[0]panrad[-175°, +175°]
data[1]tiltrad[-90°, +23°] — 비대칭, 위로는 23°까지만
data[2]zoom배[1, 32]

/rbq/ptz ​

항목값
타입std_msgs/Float64MultiArray
방향Pub
Hz20
설명실측 pan/tilt 각도와 카메라 줌 배율. data[2] == 0이면 페이로드에 CCTV 카메라가 설정되지 않아 보고할 줌이 없다는 뜻입니다. 줌 값은 pan/tilt보다 갱신이 느려 수백 밀리초 지연될 수 있습니다.

/rbq/cmd/ptz ​

항목값
타입std_msgs/Float64MultiArray
방향Sub
설명절대 pan/tilt/zoom 지령. 위 범위를 벗어난 값은 펌웨어가 잘라냅니다. data가 유한한 값 정확히 3개가 아니면 메시지는 무시됩니다. 지령은 래치되므로 한 번 보내면 그 자세를 유지합니다.

세 값이 동시에 적용됩니다. pan만 바꾸려고 [new_pan, 0, 0]을 보내면 tilt도 0으로 가고 줌도 초기화됩니다. /rbq/ptz를 먼저 읽어서 바꾸지 않을 항목은 현재값을 그대로 실어 보내세요.

PTZ 점검이 도는 동안에는 DDS 든 Zenoh 든 /rbq/cmd/ptz가 무시됩니다. 점검이 끝날 때까지 PTZ 는 점검만 씁니다.

예제:

bash
# 현재 상태 읽기
ros2 topic echo --once /rbq/ptz

# 좌측 20°, 하향 10°, 4배 줌  (0.349 rad, -0.175 rad)
ros2 topic pub --once /rbq/cmd/ptz std_msgs/msg/Float64MultiArray "{data: [0.349, -0.175, 4.0]}"

# 중앙 복귀, 1배 줌
ros2 topic pub --once /rbq/cmd/ptz std_msgs/msg/Float64MultiArray "{data: [0.0, 0.0, 1.0]}"

TF ​

/tf ​

항목내용
타입tf2_msgs/TFMessage
방향Pub
Hz50
설명local_world → base_link 하나뿐입니다 — /rbq/odometry와 같은 자세. /tf에는 다리·센서 프레임이 없고, 카메라 스트림은 각자의 …/tf 토픽으로 자세를 냅니다(비전 — 카메라 센서 참고). 시뮬레이터에서는 MuJoCo 가 base_link → <lidar>를 2 Hz 로 함께 방송합니다.

/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–14]. 앱에서 전체 버튼 전송(개발자 모드)이 꺼져 있으면 L2·R2는 0으로, 버튼은 L1·R1만 [8]·[10] 자리로 실립니다. 프레임이 올 때 나가고, 조이스틱 링크가 끊기면(0.5초 동안 프레임 없음) 전부 0 인 메시지가 한 번 더 나가 마지막 값이 남지 않습니다.

토픽 구독 예제 ​

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

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

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

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

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

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

# 모션 하트비트 (1 Hz)
ros2 topic echo --once /rbq/motion/heartbeat

This user manual is intended for RBQ users.