PTZ 카메라 API

PTZ 카메라는 독립형 한화비전 XNZ-L6320AG이며, 로봇 소프트웨어를 거치지 않고 카메라에 직접 제어합니다. 카메라는 로봇 내부 네트워크(기본 192.168.0.100)에 연결되어 있으며 세 가지 표준 인터페이스를 지원합니다.

RTSP — H.264 / H.265 라이브 영상
SUNAPI — 팬 / 틸트 / 줌, 프리셋, 초점, 오디오를 제어하는 한화 HTTP CGI API
ONVIF — 타사 VMS·도구 연동을 위한 Profile S / T

카메라의 기구·광학 사양은 PTZ 카메라에서 확인하세요.

제어 경로

PTZ 카메라를 코드로 제어하는 방법은 두 가지입니다.

	카메라에 직접 (이 페이지)	로봇 경유 (ROS2 / DDS)
인터페이스	SUNAPI (HTTPS CGI) · RTSP · ONVIF Profile S / T	`/rbq/cmd/ptz` · `/rbq/ptz` (`std_msgs/Float64MultiArray`)
접속 대상	카메라 `192.168.0.100`	로봇의 DDS 도메인
팬 / 틸트 / 줌	절대·연속 이동, 프리셋, 초점	절대 팬 / 틸트 / 줌 setpoint — 세 값이 함께 적용됨
영상	카메라 RTSP, H.264 / H.265, 프로파일 선택	로봇 Streamer RTSP — 미디어 참고
오디오	스피커·마이크 (SUNAPI 오디오, RTSP 백채널)	없음
타사 VMS 연동	ONVIF	없음
전제 조건	카메라 계정, 로봇 내부 네트워크 접근	로봇에서 `Ptz` 앱 실행 중

로봇 SDK 코드의 한 흐름으로 카메라를 움직인다면 ROS2 토픽을 사용하세요. 프리셋·초점·오디오·ONVIF 등 카메라 고유 기능이 필요하다면 직접 제어를 사용합니다.

계정 정보

카메라는 HTTP Digest 인증(SUNAPI 기본)을 사용합니다. 예시의 --anyauth가 이를 자동으로 협상합니다 — -u만 쓰면 Basic만 전송되어 401로 거부됩니다. 로봇과 함께 제공되는 계정을 사용하고 <user> / <password>를 실제 계정으로 바꿔 주세요. 카메라는 신뢰할 수 있는 네트워크에서만 사용하세요.

라이브 영상 (RTSP)

bash

ffplay "rtsp://<user>:<password>@192.168.0.100:554/profile2/media.smp"

프로파일 번호로 스트림(해상도 / 코덱)을 선택합니다. 카메라의 프로파일 목록은 카메라 자체 웹 UI에서 확인할 수 있습니다.

팬 / 틸트 / 줌 (SUNAPI)

SUNAPI는 HTTPS로 제공됩니다. 카메라는 자체 서명 인증서를 사용하므로 아래 예시에서는 -k(검증 생략)를 사용합니다. 자주 쓰는 호출:

bash

# 현재 줌 값 읽기
curl -k --anyauth -u <user>:<password> \
  "https://192.168.0.100/stw-cgi/ptzcontrol.cgi?msubmenu=query&action=view&Channel=0&Query=Zoom"

# 절대 줌 8배  (범위 1-32)
curl -k --anyauth -u <user>:<password> \
  "https://192.168.0.100/stw-cgi/ptzcontrol.cgi?msubmenu=absolute&action=control&Zoom=8"

# 연속 줌: 인 / 정지 / 아웃  ->  1 / 0 / -1
curl -k --anyauth -u <user>:<password> \
  "https://192.168.0.100/stw-cgi/ptzcontrol.cgi?msubmenu=continuous&action=control&Zoom=1"

팬·틸트·프리셋은 동일한 ptzcontrol.cgi 엔드포인트에서 Pan / Tilt 파라미터와 msubmenu=preset으로 제어합니다. 팬·틸트 범위, 프리셋, 초점, 오디오 입출력, 이벤트, 영상 설정 등 전체 명령은 XNZ-L6320AG의 한화 SUNAPI 레퍼런스를 참고하세요.

스피커 & 마이크

25 W 스피커와 마이크는 카메라 자체의 양방향 오디오이며, SUNAPI 오디오와 RTSP 백채널로 사용할 수 있습니다. 오디오 입출력은 한화 SUNAPI 레퍼런스를 참고하세요.

참고

위 인터페이스는 카메라에 직접 통신합니다. 로봇 소프트웨어도 합성 화면을 만들기 위해 카메라를 읽지만, 그 경로는 내부용입니다 — 연동에는 위의 표준 인터페이스나 ROS2 PTZ 토픽을 사용하세요.

함께 보기

PTZ 카메라 — 기구·광학·열화상 사양
PTZ 카메라 — 앱에서 카메라 조작하기
토픽 레퍼런스 — 비전 — PTZ 카메라 — 로봇 경유 팬 / 틸트 / 줌 (ROS2)
미디어 — 로봇이 직접 발행하는 RTSP 스트림

PTZ 카메라 API ​

제어 경로 ​

라이브 영상 (RTSP) ​

팬 / 틸트 / 줌 (SUNAPI) ​

스피커 & 마이크 ​