ROS 2 서비스 레퍼런스

로봇 소프트웨어가 CycloneDDS로 제공하는 ROS 2 서비스의 레퍼런스입니다.

토픽과 마찬가지로 별도 드라이버 노드가 필요 없습니다. 로봇의 각 프로세스가 ROS 2 호환 DDS로 서비스를 직접 제공하므로, 프로세스가 실행 중이면 ros2 service list와 ros2 service call을 바로 쓸 수 있습니다. RMW_IMPLEMENTATION=rmw_cyclonedds_cpp와 네트워크 인터페이스는 토픽과 같게 맞춥니다(네트워크 & DDS 참고).

모든 서비스는 표준 rcl_interfaces 타입 두 가지만 쓰므로 별도 워크스페이스가 필요 없습니다.

타입	쓰는 곳
rcl_interfaces/srv/SetParameters	set_param — 값 설정, set_service — 동작 실행·기능 전환
rcl_interfaces/srv/GetParameters	get_param — 값 읽기

요청·응답 규칙

• 파라미터마다 결과가 하나입니다. SetParameters는 parameters[i]마다 results[i]를 같은 순서로 돌려줍니다. 실패는 파라미터 단위라서, 한 요청 안의 다른 파라미터는 그대로 적용됩니다.
• 실패 사유. 실패한 항목은 successful: false와 짧은 영어 reason(예: unknown parameter, expects number)을 담습니다. 성공한 항목의 reason은 비어 있습니다.
• 요청당 파라미터는 64개까지입니다. 넘으면 요청 전체를 거부합니다. set_*는 모든 항목이 too many parameters (max 64)로 실패하고, get_param은 모든 값이 미설정으로 돌아옵니다.
• 값 타입. value.type을 명시합니다(1=bool, 2=정수, 3=실수, 4=문자열). 0으로 두면 로봇이 채워진 값 필드 하나를 골라 씁니다. 다만 0 값(0, 0.0, 빈 문자열)은 이렇게 판별할 수 없으므로, 0을 보낼 때는 반드시 타입을 지정합니다.
• get_param에 없는 이름은 type: 0(미설정)으로 돌아옵니다.
• set_service는 bool 값을 받습니다. 이름에 따로 적힌 경우(gait, stream_live)만 예외입니다. true만 표시된 항목에 false를 보내면 true only로 실패합니다.

서비스	프로세스	사용 조건
/rbq/motion/*	Network	로봇 소프트웨어 실행 중
/rbq/vision/*	Streamer	비전 소프트웨어 실행 중
/rbq/camera/*	HAL	비전 소프트웨어 실행 중
/rbq/ptz/*	Ptz	PTZ 카메라 페이로드 장착 시

모션

/rbq/motion/set_param

항목	내용
타입	rcl_interfaces/srv/SetParameters
설명	페이로드·보행·도킹 파라미터를 설정합니다. 값은 모두 숫자(정수 또는 실수)입니다.

이름	단위	설명
payload.mass	kg	추가 페이로드 질량. 무게중심 보상에 씁니다
payload.com_x / payload.com_y / payload.com_z	m	페이로드 무게중심(몸체 기준)
dynamics.max_speed	m/s	보행 속도 상한
dynamics.body_height	m	기본 자세 대비 서 있는 높이 오프셋
dynamics.body_tilt	deg	보행 중 몸체 고정 피치
dock.offset_x / dock.offset_y	m	도킹 목표 오프셋
dock.count_req	—	도킹 전 마커 검출 시도 횟수
dock.count_try	—	포기하기 전까지 허용하는 도킹 실패 횟수

dynamics.*의 범위는 앱의 주행 파라미터와 같습니다. payload.* 값이 페이로드 한계를 벗어나면 reason: validation_error로 실패합니다. 무게중심 한계는 |x| ≤ 0.5 m, |y| ≤ 0.3 m, |z| ≤ 0.4 m이고, 질량 한계는 로봇 모델에 따라 다릅니다.

dynamics.max_speed를 먼저 설정하세요

로봇은 dynamics.* 세 값을 한꺼번에 적용합니다. dynamics.max_speed를 한 번도 설정하지 않았으면 body_height와 body_tilt는 dynamics.max_speed not set yet - set it first로 실패합니다. 세 값을 한 요청에 함께 보내는 것이 안전합니다. 저장된 값은 로봇 소프트웨어가 재시작되면 초기화됩니다.

payload.*는 첫 번째 사용자 페이로드 슬롯을 설정합니다.

/rbq/motion/get_param

항목	내용
타입	rcl_interfaces/srv/GetParameters
설명	위 set_param 이름의 현재 값을 읽습니다. 값은 실수(type: 3)로 돌아옵니다.

dynamics.max_speed는 set_param으로 설정하기 전까지 미설정으로 돌아옵니다.

/rbq/motion/set_service

항목	내용
타입	rcl_interfaces/srv/SetParameters
설명	모션 동작을 실행하고 모드를 전환합니다.

이름	값	설명
estop	bool, true만	비상 정지 — 모든 관절이 고댐핑 상태가 됩니다. 로봇이 주저앉습니다. /rbq/cmd/emergency와 같습니다
auto_start	bool, true만	CAN 확인 → Find Home → Control Start. /rbq/cmd/auto_start와 같습니다
control_mode	bool	true → HighLevel Command 모드, false → 조이스틱 모드. /rbq/cmd/switch_control_mode와 같습니다
power_ch<N>	bool	PDU 전원 포트 N(0~31)을 켜거나 끕니다. 포트 번호는 전원 제어에 있습니다
gait	정수 또는 문자열	Gait를 전환합니다. 정수는 Gait State ID의 id, 문자열은 아래 이름 중 하나입니다

gait가 받는 이름(대소문자 무관): sitting, standing, aiming, trotting, trot_stairs, waving, trot_running, docking, rl_trot, rl_front_walk, rl_left_walk, rl_right_walk, rl_bound, rl_pace, rl_pronk, rl_3leg_hr, rl_trot_vision, rl_trot_run, rl_silent, rl_trot_vision_slow, rl_walk, rl_walk_vision. 그 밖의 id나 이름은 unknown gait id / unknown gait name으로 실패합니다.

DANGER

estop은 관절 토크를 즉시 끊어 로봇이 넘어집니다. 시험할 때는 로봇을 먼저 앉히세요.

예시:

# 보행 파라미터 — 세 값을 함께 보냅니다
ros2 service call /rbq/motion/set_param rcl_interfaces/srv/SetParameters \
  "{parameters: [
    {name: 'dynamics.max_speed',   value: {type: 3, double_value: 1.0}},
    {name: 'dynamics.body_height', value: {type: 3, double_value: 0.0}},
    {name: 'dynamics.body_tilt',   value: {type: 3, double_value: 0.0}}]}"

# 페이로드 질량 읽기
ros2 service call /rbq/motion/get_param rcl_interfaces/srv/GetParameters "{names: ['payload.mass']}"

# 이름으로 서기 자세 전환
ros2 service call /rbq/motion/set_service rcl_interfaces/srv/SetParameters \
  "{parameters: [{name: 'gait', value: {type: 4, string_value: 'standing'}}]}"

비전

/rbq/vision/set_param · /rbq/vision/get_param

항목	내용
타입	rcl_interfaces/srv/SetParameters · rcl_interfaces/srv/GetParameters
설명	WebRTC 영상 스트림 설정입니다. 바꾼 값은 재시작 후에도 유지됩니다.

이름	값	설명
webrtc.width / webrtc.height	정수, 16~7680	스트림 해상도(픽셀). 하나만 바꾸면 다른 하나는 그대로입니다
webrtc.preset	문자열	x264 인코더 프리셋: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo

/rbq/vision/set_service

항목	내용
타입	rcl_interfaces/srv/SetParameters
설명	비전 기능과 라이브 뷰를 전환합니다.

이름	값	설명
stream_live	정수	라이브 뷰를 id로 선택합니다 — 0 없음, 1 전방, 2 후방, 3 좌측, 4 우측, 11 스택, 12 파노라마, 13 계단, 14 좌우 나란히, 15 도킹
face_detect	bool	얼굴 검출 오버레이
point2go	bool	Point-to-go 오버레이
guide	bool	가이드 오버레이
day	bool	true → 주간 모드, false → 야간(IR) 모드
heightmap.stairs	bool	높이 맵 계단 검출
heightmap.edge	bool	높이 맵 모서리 검출
heightmap.align	bool	높이 맵을 몸체 yaw에 맞춰 정렬

TIP

stream_live: 0(뷰 없음)은 다른 시청자가 스트림을 보고 있으면 성공으로 응답하지만 실제로는 무시됩니다.

카메라

/rbq/camera/set_param · /rbq/camera/get_param

항목	내용
타입	rcl_interfaces/srv/SetParameters · rcl_interfaces/srv/GetParameters
설명	카메라 설정을 <SECTION>.<key> 이름으로 읽고 씁니다. 예: MAIN.RS_PRESET_HIGH_DENSITY

• set_param은 이미 있는 키만 바꿉니다. 오타는 unknown section 또는 unknown key로 실패합니다. 스칼라 값이면 무엇이든 받아 텍스트로 저장하고, 변경에 성공하면 카메라 설정을 다시 불러옵니다.
• get_param은 저장된 텍스트(type: 4)를 돌려주고, 키가 없으면 미설정으로 돌려줍니다.

/rbq/camera/set_service

항목	내용
타입	rcl_interfaces/srv/SetParameters
설명	카메라 동작입니다.

이름	값	설명
ir_projector	bool	모든 깊이 카메라의 IR 프로젝터를 켜거나 끕니다
reload_config	bool, true만	카메라 설정을 다시 불러옵니다
sensor_<N>.enabled	bool	카메라 센서 N을 엽니다(true) 또는 닫습니다(false). 센서 id는 비전 — 카메라 센서에 있습니다

PTZ

/rbq/ptz/set_param

항목	내용
타입	rcl_interfaces/srv/SetParameters
설명	PTZ 위치와 속도입니다. 값은 모두 숫자입니다.

이름	단위	설명
pan / tilt	rad	목표 각도. 범위는 /rbq/cmd/ptz와 같습니다
zoom	×	목표 줌. 범위는 /rbq/cmd/ptz와 같습니다
pan_vel / tilt_vel	deg/s	이 속도로 회전합니다
zoom_vel	—	이 비율로 연속 줌합니다

/rbq/cmd/ptz와 달리 이름마다 따로 적용됩니다. pan만 보내면 tilt와 zoom은 그대로입니다.

PTZ에는 get_param이 없습니다. 현재 위치는 /rbq/ptz에서 읽습니다.

/rbq/ptz/set_service

항목	내용
타입	rcl_interfaces/srv/SetParameters
설명	PTZ 동작입니다. 두 이름 모두 true를 보낼 때만 동작합니다.

이름	설명
return_center	pan·tilt를 중앙으로 되돌리고 줌을 1×로 맞춥니다
stop	pan·tilt 이동을 멈춥니다