사무실 안내·순찰 로봇 인터페이스 명세서 작성 예시

1. 문서 개요

본 문서는 터틀봇3 버거(TurtleBot3 Burger)를 이용한 사무실 안내·순찰 로봇 시스템의 ROS 2 인터페이스를 정의한다.

로봇 본체에서는 센서 처리, 주행, 상태 관리, 순찰, 이상 상황 감지 등의 노드를 실행한다. 원격 PC에서는 관리자 GUI, 실시간 영상 확인, 원격 조종, 순찰 제어, 이벤트 승인 및 보고서 확인 기능을 실행한다.

인터페이스 명세를 따르지 않을 경우 다음 문제가 발생할 수 있다.

토픽 이름 불일치
메시지 자료형 불일치
거리, 각도, 속도 단위 불일치
로봇 운용 상태 이름 불일치
서비스 성공 및 실패 기준 불일치
로봇 PC와 원격 PC 간 통신 오류
통합 단계에서 대규모 코드 수정 발생

2. 시스템 구성

2.1 로봇 플랫폼

항목	내용
로봇	TurtleBot3 Burger
운영체제	Ubuntu
미들웨어	ROS 2 DDS
이동 방식	차동 구동 방식
주행 제어	OpenCR 기반 모터 제어
거리 센서	LDS 라이다
카메라	USB 카메라 또는 라즈베리파이 카메라
위치 추정	SLAM 또는 AMCL
지도	ROS 2 OccupancyGrid 형식
원격 제어	원격 PC 관리자 GUI
네트워크	동일 LAN 또는 동일 Wi-Fi 네트워크

2.2 로봇 PC 실행 기능

로봇 본체 또는 로봇에 탑재된 컴퓨터에서 다음 기능을 실행한다.

TurtleBot3 하드웨어 드라이버
라이다 드라이버
카메라 드라이버
SLAM 또는 AMCL
Nav2 내비게이션
로봇 상태 관리
배터리 상태 관리
순찰 관리
방문자 감지
이상 상황 감지
증거 이미지 저장
속도 명령 선택
비상정지 처리

2.3 원격 PC 실행 기능

원격 PC에서 다음 기능을 실행한다.

관리자 GUI
로봇 상태 표시
지도 및 현재 위치 표시
실시간 카메라 영상 표시
원격 조종
운용 모드 변경
순찰 시작 및 중지
이상 이벤트 확인
관리자 판단 입력
방문자 메모 작성
보고서 생성 및 조회
비상정지 명령 전송

3. ROS 2 네임스페이스 규칙

사무실 로봇 전용 인터페이스는 /office_robot 네임스페이스를 사용한다.

예시는 다음과 같다.

/office_robot/operation_mode
/office_robot/patrol/status
/office_robot/anomaly/event
/office_robot/admin/decision
/office_robot/cmd_vel/remote

TurtleBot3와 Nav2에서 기본으로 제공하는 표준 인터페이스는 기존 이름을 유지한다.

/cmd_vel
/odom
/scan
/map
/tf
/tf_static
/amcl_pose
/navigate_to_pose

토픽과 서비스 이름은 영문 소문자와 밑줄을 사용한다.

올바른 예
/office_robot/patrol/status
/office_robot/emergency_stop

잘못된 예
/OfficeRobot/PatrolStatus
/officeRobot/emergencyStop

4. 노드 구성 명세

노드명	실행 위치	역할
`turtlebot3_node`	로봇 PC	OpenCR 통신, 모터 및 배터리 상태 관리
`lidar_driver`	로봇 PC	라이다 데이터 발행
`camera_driver`	로봇 PC	카메라 영상 발행
`robot_state_publisher`	로봇 PC	로봇 TF 발행
`slam_toolbox`	로봇 PC	지도 작성
`amcl`	로봇 PC	지도 기반 위치 추정
`bt_navigator`	로봇 PC	Nav2 이동 명령 처리
`controller_server`	로봇 PC	로봇 주행 제어
`robot_state_manager`	로봇 PC	전체 운용 모드와 상태 관리
`patrol_manager`	로봇 PC	순찰 경로 및 순찰 상태 관리
`entrance_monitor`	로봇 PC	출입구 방문자 감지 및 인원 수 계산
`greeting_manager`	로봇 PC	방문자 인사 및 안내 처리
`anomaly_monitor`	로봇 PC	침입, 장시간 체류, 이동 물체 등 이상 상황 감지
`evidence_manager`	로봇 PC	이상 상황 이미지 저장
`battery_monitor`	로봇 PC	배터리 상태 판단 및 저전압 경고
`cmd_vel_selector`	로봇 PC	자율주행과 원격주행 속도 명령 선택
`safety_manager`	로봇 PC	비상정지 및 안전 조건 관리
`admin_gui`	원격 PC	관리자 화면 제공
`admin_request_manager`	원격 PC	관리자 판단 및 승인 명령 처리
`remote_teleop`	원격 PC	키보드 또는 GUI 원격 조종
`report_manager`	원격 PC	순찰 및 이상 상황 보고서 생성
`visitor_memo_manager`	원격 PC	방문자 메모 저장 및 조회

5. 운용 모드 명세

로봇의 운용 모드는 문자열로 관리한다.

운용 모드	값	설명
대기 모드	`IDLE`	이동하지 않고 명령을 대기하는 상태
주간 안내 모드	`DAY`	방문자 감지와 안내 기능을 수행하는 상태
야간 순찰 모드	`NIGHT`	지정된 경로를 반복 순찰하는 상태
원격 조종 모드	`REMOTE`	원격 PC의 속도 명령으로 주행하는 상태
충전 복귀 모드	`RETURN_TO_CHARGE`	충전 위치로 이동하는 상태
비상정지 모드	`EMERGENCY_STOP`	모든 이동 명령을 차단하는 상태
오류 모드	`ERROR`	시스템 오류로 정상 동작이 불가능한 상태

운용 모드 변경은 /office_robot/set_mode 서비스를 통해 수행한다.

6. 토픽 인터페이스 명세

6.1 로봇 운용 및 상태 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/office_robot/operation_mode`	`std_msgs/msg/String`	`robot_state_manager`	전체 임무 노드, `admin_gui`	현재 운용 모드
`/office_robot/system/status`	`office_robot_msgs/msg/SystemStatus`	`robot_state_manager`	`admin_gui`, `report_manager`	시스템 전체 상태
`/office_robot/emergency_stop/status`	`std_msgs/msg/Bool`	`safety_manager`	전체 주행 노드, `admin_gui`	비상정지 활성화 여부
`/office_robot/heartbeat`	`std_msgs/msg/UInt32`	`robot_state_manager`	`admin_gui`	로봇 시스템 생존 확인용 카운터
`/office_robot/error/event`	`office_robot_msgs/msg/ErrorEvent`	전체 로봇 노드	`robot_state_manager`, `admin_gui`	노드 오류 및 장비 오류 이벤트

6.2 방문자 및 출입구 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/office_robot/entrance/person_count`	`std_msgs/msg/Int32`	`entrance_monitor`	`greeting_manager`, `admin_gui`	최근 감지된 인원 수
`/office_robot/entrance/person_detected`	`std_msgs/msg/Bool`	`entrance_monitor`	`greeting_manager`	방문자 감지 여부
`/office_robot/visitor/event`	`office_robot_msgs/msg/VisitorEvent`	`entrance_monitor`	`greeting_manager`, `admin_gui`, `visitor_memo_manager`	방문자 감지 이벤트
`/office_robot/greeting/status`	`std_msgs/msg/String`	`greeting_manager`	`admin_gui`	현재 안내 상태
`/office_robot/visitor/memo`	`office_robot_msgs/msg/VisitorMemo`	`visitor_memo_manager`	`admin_gui`, `report_manager`	방문자 메모 정보

6.3 이상 상황 및 관리자 판단 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/office_robot/anomaly/event`	`office_robot_msgs/msg/AnomalyEvent`	`anomaly_monitor`	`evidence_manager`, `admin_gui`, `report_manager`	이상 상황 이벤트
`/office_robot/anomaly/status`	`std_msgs/msg/String`	`anomaly_monitor`	`robot_state_manager`, `admin_gui`	이상 감지 노드 상태
`/office_robot/admin/decision`	`office_robot_msgs/msg/AdminDecision`	`admin_request_manager`	`anomaly_monitor`, `robot_state_manager`, `report_manager`	관리자 판단 결과
`/office_robot/evidence/status`	`office_robot_msgs/msg/EvidenceStatus`	`evidence_manager`	`admin_gui`, `report_manager`	증거 이미지 저장 결과
`/office_robot/alarm/status`	`std_msgs/msg/Bool`	`safety_manager`	`admin_gui`	경고음 또는 경고 상태

6.4 순찰 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/office_robot/patrol/status`	`office_robot_msgs/msg/PatrolStatus`	`patrol_manager`	`admin_gui`, `report_manager`, `robot_state_manager`	현재 순찰 상태
`/office_robot/patrol/route`	`office_robot_msgs/msg/PatrolRoute`	`patrol_manager`	`admin_gui`	현재 순찰 경로
`/office_robot/patrol/current_point`	`std_msgs/msg/String`	`patrol_manager`	`admin_gui`, `anomaly_monitor`	현재 이동 중인 순찰 지점
`/office_robot/patrol/event`	`office_robot_msgs/msg/PatrolEvent`	`patrol_manager`	`report_manager`, `admin_gui`	순찰 시작, 도착, 실패, 완료 이벤트
`/office_robot/patrol/progress`	`std_msgs/msg/Float32`	`patrol_manager`	`admin_gui`	전체 순찰 진행률
`/office_robot/patrol/recovery_count`	`std_msgs/msg/Int32`	`patrol_manager`	`admin_gui`, `report_manager`	이동 실패 후 복구 시도 횟수

/office_robot/patrol/progress 값은 0.0부터 1.0까지 사용한다.

0.0: 순찰 시작
0.5: 전체 경로의 50% 완료
1.0: 전체 순찰 완료

6.5 배터리 및 안전 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/battery_state`	`sensor_msgs/msg/BatteryState`	`turtlebot3_node`	`battery_monitor`	TurtleBot3 기본 배터리 상태
`/office_robot/battery/status`	`office_robot_msgs/msg/RobotBatteryStatus`	`battery_monitor`	`robot_state_manager`, `patrol_manager`, `admin_gui`	가공된 배터리 상태
`/office_robot/battery/low`	`std_msgs/msg/Bool`	`battery_monitor`	`robot_state_manager`, `patrol_manager`, `admin_gui`	저전압 상태
`/office_robot/battery/critical`	`std_msgs/msg/Bool`	`battery_monitor`	`safety_manager`, `robot_state_manager`	위험 배터리 상태
`/office_robot/bumper/contact`	`std_msgs/msg/Bool`	`safety_manager`	`cmd_vel_selector`, `admin_gui`	충돌 또는 접촉 감지
`/office_robot/obstacle/too_close`	`std_msgs/msg/Bool`	`safety_manager`	`cmd_vel_selector`, `patrol_manager`	근거리 장애물 감지

6.6 카메라 및 영상 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/office_robot/camera/image_raw`	`sensor_msgs/msg/Image`	`camera_driver`	`entrance_monitor`, `anomaly_monitor`, `admin_gui`	실시간 원본 영상
`/office_robot/camera/image_compressed`	`sensor_msgs/msg/CompressedImage`	`camera_driver`	`admin_gui`	원격 PC 전송용 압축 영상
`/office_robot/camera/camera_info`	`sensor_msgs/msg/CameraInfo`	`camera_driver`	영상 처리 노드	카메라 내부 파라미터
`/office_robot/camera/detection_image`	`sensor_msgs/msg/CompressedImage`	`anomaly_monitor`	`admin_gui`	객체 검출 결과가 표시된 영상

원격 PC GUI에서는 네트워크 부하를 줄이기 위해 /office_robot/camera/image_compressed 사용을 권장한다.

6.7 이동 및 위치 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/odom`	`nav_msgs/msg/Odometry`	`turtlebot3_node`	Nav2, `robot_state_manager`	바퀴 오도메트리
`/scan`	`sensor_msgs/msg/LaserScan`	`lidar_driver`	SLAM, AMCL, Nav2, `safety_manager`	라이다 스캔 데이터
`/map`	`nav_msgs/msg/OccupancyGrid`	`slam_toolbox` 또는 `map_server`	Nav2, `admin_gui`	사무실 지도
`/amcl_pose`	`geometry_msgs/msg/PoseWithCovarianceStamped`	`amcl`	`patrol_manager`, `admin_gui`	지도 기준 추정 위치
`/tf`	`tf2_msgs/msg/TFMessage`	TF 관련 노드	전체 위치 관련 노드	동적 좌표 변환
`/tf_static`	`tf2_msgs/msg/TFMessage`	`robot_state_publisher`	전체 위치 관련 노드	정적 좌표 변환
`/office_robot/pose`	`geometry_msgs/msg/PoseStamped`	`robot_state_manager`	`admin_gui`, `report_manager`	GUI 및 기록용 로봇 위치
`/office_robot/current_location`	`std_msgs/msg/String`	`patrol_manager`	`admin_gui`, `greeting_manager`	현재 위치의 논리적 이름

6.8 속도 명령 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/office_robot/cmd_vel/navigation`	`geometry_msgs/msg/Twist`	Nav2 속도 출력 노드	`cmd_vel_selector`	자율주행 속도 명령
`/office_robot/cmd_vel/remote`	`geometry_msgs/msg/Twist`	`remote_teleop`	`cmd_vel_selector`	원격 PC 속도 명령
`/office_robot/cmd_vel/safety`	`geometry_msgs/msg/Twist`	`safety_manager`	`cmd_vel_selector`	안전 정지 또는 회피 명령
`/cmd_vel`	`geometry_msgs/msg/Twist`	`cmd_vel_selector`	`turtlebot3_node`	TurtleBot3에 전달되는 최종 속도 명령
`/office_robot/cmd_vel/source`	`std_msgs/msg/String`	`cmd_vel_selector`	`admin_gui`	현재 선택된 속도 명령 출처

속도 명령 출처는 다음 값을 사용한다.

NAVIGATION
REMOTE
SAFETY
STOP

6.9 원격 GUI 토픽

토픽명	자료형	발행 노드	구독 노드	설명
`/office_robot/gui/connected`	`std_msgs/msg/Bool`	`admin_gui`	`robot_state_manager`	원격 GUI 연결 상태
`/office_robot/gui/operator_name`	`std_msgs/msg/String`	`admin_gui`	`admin_request_manager`, `report_manager`	현재 관리자 이름
`/office_robot/gui/selected_location`	`std_msgs/msg/String`	`admin_gui`	`patrol_manager`	GUI에서 선택한 이동 목적지
`/office_robot/gui/message`	`std_msgs/msg/String`	로봇 관리 노드	`admin_gui`	GUI 표시용 안내 메시지

7. 토픽 QoS 명세

ROS 2 통신 안정성을 위해 토픽 특성에 따라 QoS를 구분한다.

토픽 종류	Reliability	Durability	History	Depth
카메라 영상	Best Effort	Volatile	Keep Last	2
라이다 스캔	Best Effort	Volatile	Keep Last	5
속도 명령	Reliable	Volatile	Keep Last	10
로봇 상태	Reliable	Volatile	Keep Last	10
이벤트	Reliable	Volatile	Keep Last	50
지도	Reliable	Transient Local	Keep Last	1
운용 모드	Reliable	Transient Local	Keep Last	1
순찰 경로	Reliable	Transient Local	Keep Last	1

카메라와 라이다 데이터는 최신 데이터 전달이 중요하므로 오래된 메시지를 누적하지 않는다.

이상 상황 이벤트, 관리자 판단, 순찰 이벤트는 손실되면 안 되므로 Reliable을 사용한다.

8. 서비스 인터페이스 명세

8.1 운용 및 시스템 서비스

서비스명	서비스 자료형	서버 노드	클라이언트 노드	역할
`/office_robot/set_mode`	`office_robot_msgs/srv/SetOperationMode`	`robot_state_manager`	`admin_gui`	주간, 야간, 원격, 대기 모드 변경
`/office_robot/get_system_status`	`office_robot_msgs/srv/GetSystemStatus`	`robot_state_manager`	`admin_gui`	현재 시스템 상태 조회
`/office_robot/reset_error`	`std_srvs/srv/Trigger`	`robot_state_manager`	`admin_gui`	오류 상태 초기화
`/office_robot/emergency_stop`	`std_srvs/srv/SetBool`	`safety_manager`	`admin_gui`	비상정지 설정 또는 해제
`/office_robot/system/shutdown`	`std_srvs/srv/Trigger`	`robot_state_manager`	`admin_gui`	로봇 프로그램 정상 종료 요청

8.2 순찰 서비스

서비스명	서비스 자료형	서버 노드	클라이언트 노드	역할
`/office_robot/patrol/start`	`office_robot_msgs/srv/StartPatrol`	`patrol_manager`	`admin_gui`	순찰 시작
`/office_robot/patrol/stop`	`std_srvs/srv/Trigger`	`patrol_manager`	`admin_gui`	현재 순찰 중지
`/office_robot/patrol/pause`	`std_srvs/srv/Trigger`	`patrol_manager`	`admin_gui`	현재 위치에서 순찰 일시정지
`/office_robot/patrol/resume`	`std_srvs/srv/Trigger`	`patrol_manager`	`admin_gui`	일시정지된 순찰 재개
`/office_robot/patrol/get_route`	`office_robot_msgs/srv/GetPatrolRoute`	`patrol_manager`	`admin_gui`	현재 순찰 경로 조회
`/office_robot/patrol/set_route`	`office_robot_msgs/srv/SetPatrolRoute`	`patrol_manager`	`admin_gui`	순찰 경로 설정

8.3 증거 및 보고서 서비스

서비스명	서비스 자료형	서버 노드	클라이언트 노드	역할
`/office_robot/evidence/capture`	`office_robot_msgs/srv/CaptureEvidence`	`evidence_manager`	`anomaly_monitor`, `admin_gui`	현재 카메라 영상 저장
`/office_robot/evidence/get_path`	`office_robot_msgs/srv/GetEvidencePath`	`evidence_manager`	`admin_gui`, `report_manager`	이벤트별 증거 파일 경로 조회
`/office_robot/report/create`	`office_robot_msgs/srv/CreateReport`	`report_manager`	`admin_gui`	순찰 또는 야간 보고서 생성
`/office_robot/report/get_latest`	`office_robot_msgs/srv/GetLatestReport`	`report_manager`	`admin_gui`	최근 보고서 조회

8.4 방문자 서비스

서비스명	서비스 자료형	서버 노드	클라이언트 노드	역할
`/office_robot/visitor/save_memo`	`office_robot_msgs/srv/SaveVisitorMemo`	`visitor_memo_manager`	`admin_gui`	방문자 메모 저장
`/office_robot/visitor/get_memo`	`office_robot_msgs/srv/GetVisitorMemo`	`visitor_memo_manager`	`admin_gui`	방문자 메모 조회
`/office_robot/visitor/complete_guidance`	`std_srvs/srv/Trigger`	`greeting_manager`	`admin_gui`	방문자 안내 완료 처리

9. 서비스 공통 응답 규칙

사용자 정의 서비스 응답은 다음 필드를 기본으로 사용한다.

bool success
int32 result_code
string message

success는 요청의 최종 처리 성공 여부를 나타낸다.

result_code는 다음 기준을 사용한다.

코드	이름	설명
`0`	`SUCCESS`	정상 처리
`1`	`INVALID_REQUEST`	잘못된 요청값
`2`	`INVALID_MODE`	현재 운용 모드에서 실행할 수 없음
`3`	`ROBOT_BUSY`	다른 임무 수행 중
`4`	`NAVIGATION_FAILED`	이동 명령 실패
`5`	`SENSOR_ERROR`	센서 오류
`6`	`LOW_BATTERY`	배터리 부족
`7`	`EMERGENCY_STOP_ACTIVE`	비상정지 활성화 상태
`8`	`NOT_FOUND`	요청한 데이터 또는 파일 없음
`9`	`TIMEOUT`	제한 시간 초과
`10`	`INTERNAL_ERROR`	내부 처리 오류

서비스 실패 시 message에는 관리자 GUI에 바로 표시할 수 있는 설명을 작성한다.

success: false
result_code: 6
message: "배터리 잔량이 부족하여 순찰을 시작할 수 없습니다."

10. 액션 인터페이스 명세

장시간 이동, 순찰, 방문자 안내와 같이 완료까지 시간이 필요한 작업은 ROS 2 서비스가 아닌 액션을 사용한다.

액션명	액션 자료형	액션 서버	액션 클라이언트	역할
`/navigate_to_pose`	`nav2_msgs/action/NavigateToPose`	Nav2	`patrol_manager`	좌표로 지정된 위치 이동
`/office_robot/navigate_to_named_location`	`office_robot_msgs/action/NavigateToNamedLocation`	`patrol_manager`	`admin_gui`, `greeting_manager`	이름으로 지정된 장소 이동
`/office_robot/execute_patrol`	`office_robot_msgs/action/ExecutePatrol`	`patrol_manager`	`admin_gui`, `robot_state_manager`	전체 순찰 경로 수행
`/office_robot/guide_visitor`	`office_robot_msgs/action/GuideVisitor`	`greeting_manager`	`admin_gui`	방문자를 지정 장소까지 안내
`/office_robot/execute_errand`	`office_robot_msgs/action/ExecuteErrand`	`patrol_manager`	`admin_gui`	지정 장소로 이동하는 심부름 임무 수행

11. 이름 기반 장소 이동 액션

11.1 NavigateToNamedLocation.action

string location_name
float32 timeout_sec
bool return_to_start
---
bool success
int32 result_code
string message
string final_location
---
string navigation_state
float32 distance_remaining
float32 progress
string current_location

11.2 Goal 필드

필드	설명
`location_name`	이동할 장소 이름
`timeout_sec`	이동 제한 시간
`return_to_start`	목적지 도착 후 출발지로 복귀할지 여부

11.3 Result 필드

필드	설명
`success`	이동 성공 여부
`result_code`	결과 코드
`message`	결과 설명
`final_location`	최종 도착 위치

11.4 Feedback 필드

필드	설명
`navigation_state`	현재 이동 상태
`distance_remaining`	목적지까지 남은 거리
`progress`	이동 진행률
`current_location`	현재 논리적 위치 이름

12. 순찰 수행 액션

12.1 ExecutePatrol.action

string route_id
int32 repeat_count
bool detect_anomaly
bool return_to_start
---
bool success
int32 result_code
string message
int32 completed_cycle_count
int32 detected_anomaly_count
---
string patrol_state
string current_location
int32 current_point_index
int32 total_point_count
int32 completed_cycle_count
float32 progress

12.2 순찰 처리 기준

repeat_count가 1이면 순찰 경로를 한 번 수행한다.
repeat_count가 0이면 관리자 중지 요청 전까지 반복한다.
detect_anomaly가 true이면 순찰 중 이상 감지 기능을 활성화한다.
return_to_start가 true이면 순찰 종료 후 시작 위치로 복귀한다.
액션 취소 요청을 받으면 현재 이동 목표를 취소하고 정지한다.
비상정지가 활성화되면 액션은 즉시 실패 처리한다.

13. 방문자 안내 액션

13.1 GuideVisitor.action

string visitor_id
string destination_name
string guidance_message
float32 timeout_sec
---
bool success
int32 result_code
string message
string final_location
---
string guidance_state
string current_location
float32 distance_remaining
float32 progress

13.2 방문자 안내 상태

WAITING
GREETING
MOVING
ARRIVED
COMPLETED
CANCELED
FAILED

14. 사용자 정의 메시지 패키지

사용자 정의 인터페이스는 다음 패키지에 작성한다.

office_robot_msgs

패키지 기본 구조는 다음과 같다.

office_robot_msgs/
├── CMakeLists.txt
├── package.xml
├── msg/
├── srv/
└── action/

15. AnomalyEvent.msg

string event_id
builtin_interfaces/Time detected_time
string event_type
string severity
string location_name
geometry_msgs/PoseStamped robot_pose
float32 confidence
string image_path
string description
bool admin_confirmation_required
string detection_node

15.1 필드 설명

필드	설명
`event_id`	이상 이벤트 고유 번호
`detected_time`	감지 시각
`event_type`	이상 상황 종류
`severity`	위험도
`location_name`	이상 상황이 감지된 장소
`robot_pose`	감지 당시 로봇 위치
`confidence`	감지 신뢰도
`image_path`	증거 이미지 저장 경로
`description`	이상 상황 설명
`admin_confirmation_required`	관리자 판단 필요 여부
`detection_node`	이벤트를 생성한 노드 이름

15.2 event_type 값

UNKNOWN_PERSON
RESTRICTED_AREA_ENTRY
LONG_STAY
FALL_DETECTED
SMOKE_DETECTED
FIRE_DETECTED
ABANDONED_OBJECT
MOVED_OBJECT
DOOR_OPEN
SENSOR_FAILURE
ROBOT_BLOCKED
OTHER

15.3 severity 값

INFO
WARNING
CRITICAL

15.4 confidence 범위

0.0 이상 1.0 이하

16. AdminDecision.msg

string event_id
string decision
string operator_name
string comment
builtin_interfaces/Time decision_time
bool alarm_required
bool patrol_continue

16.1 decision 값

CONFIRMED
FALSE_ALARM
IGNORE
CALL_SECURITY
CALL_EMERGENCY
RECHECK

16.2 필드 설명

필드	설명
`event_id`	판단 대상 이벤트 번호
`decision`	관리자 판단 결과
`operator_name`	판단을 입력한 관리자 이름
`comment`	관리자 의견
`decision_time`	판단 입력 시각
`alarm_required`	로봇 경고 동작 필요 여부
`patrol_continue`	판단 후 순찰 계속 여부

17. PatrolStatus.msg

bool patrol_active
bool patrol_paused
string route_id
string current_location
int32 current_point_index
int32 total_point_count
int32 completed_cycle_count
int32 target_cycle_count
string navigation_state
float32 progress
float32 distance_remaining
builtin_interfaces/Time started_time
builtin_interfaces/Time updated_time

17.1 navigation_state 값

IDLE
STARTING
NAVIGATING
ARRIVED
WAITING
PAUSED
RECOVERING
RETURNING
COMPLETED
CANCELED
FAILED

17.2 필드 설명

필드	설명
`patrol_active`	순찰 활성화 여부
`patrol_paused`	순찰 일시정지 여부
`route_id`	현재 순찰 경로 번호
`current_location`	현재 순찰 위치
`current_point_index`	현재 순찰 지점 인덱스
`total_point_count`	전체 순찰 지점 수
`completed_cycle_count`	완료한 순찰 횟수
`target_cycle_count`	목표 순찰 횟수
`navigation_state`	현재 이동 상태
`progress`	순찰 진행률
`distance_remaining`	현재 목적지까지 남은 거리
`started_time`	순찰 시작 시각
`updated_time`	상태 갱신 시각

18. PatrolRoute.msg

string route_id
string route_name
string[] location_names
geometry_msgs/PoseStamped[] poses
float32[] wait_times
bool loop
builtin_interfaces/Time updated_time

location_names, poses, wait_times 배열의 크기는 동일해야 한다.

예시는 다음과 같다.

location_names:
- entrance
- meeting_room
- server_room
- office_center

wait_times:
- 5.0
- 3.0
- 10.0
- 5.0

19. PatrolEvent.msg

string event_id
string patrol_event_type
string route_id
string location_name
int32 point_index
string description
builtin_interfaces/Time event_time

patrol_event_type 값은 다음을 사용한다.

PATROL_STARTED
POINT_REACHED
POINT_SKIPPED
NAVIGATION_FAILED
RECOVERY_STARTED
RECOVERY_COMPLETED
PATROL_PAUSED
PATROL_RESUMED
PATROL_COMPLETED
PATROL_CANCELED

20. VisitorEvent.msg

string visitor_id
builtin_interfaces/Time detected_time
int32 person_count
string entrance_name
float32 confidence
string image_path
bool guidance_requested
string description

방문자 식별이 불가능한 경우에도 visitor_id는 이벤트별 고유값을 생성한다.

VISITOR_20260718_143015_001

21. VisitorMemo.msg

string visitor_id
string visitor_name
string company_name
string contact
string purpose
string destination_name
string operator_name
string memo
builtin_interfaces/Time created_time

개인정보가 포함된 방문자 메모는 원격 PC 또는 승인된 저장 장치에 저장한다.

22. RobotBatteryStatus.msg

float32 voltage
float32 percentage
string battery_state
bool charging
bool low_battery
bool critical_battery
float32 estimated_operation_time_min
builtin_interfaces/Time updated_time

battery_state 값은 다음을 사용한다.

NORMAL
LOW
CRITICAL
CHARGING
FULL
UNKNOWN

배터리 기준값은 다음과 같이 설정한다.

구분	배터리 백분율
정상	30% 초과
낮음	15% 초과 30% 이하
위험	15% 이하

실제 배터리 기준은 TurtleBot3 배터리 특성과 실험 결과에 따라 조정할 수 있다.

23. SystemStatus.msg

string operation_mode
string system_state
bool navigation_ready
bool camera_ready
bool lidar_ready
bool battery_ready
bool gui_connected
bool emergency_stop_active
string current_task
string error_message
builtin_interfaces/Time updated_time

system_state 값은 다음을 사용한다.

INITIALIZING
READY
RUNNING
WARNING
ERROR
SHUTTING_DOWN

24. EvidenceStatus.msg

string event_id
bool capture_success
string image_path
string file_name
string error_message
builtin_interfaces/Time captured_time

25. ErrorEvent.msg

string error_id
string source_node
int32 error_code
string severity
string description
bool recovery_possible
builtin_interfaces/Time occurred_time

26. SetOperationMode.srv

string requested_mode
string operator_name
---
bool success
int32 result_code
string message
string previous_mode
string current_mode

26.1 모드 변경 제한

현재 모드	요청 모드	처리
`IDLE`	`DAY`	허용
`IDLE`	`NIGHT`	허용
`IDLE`	`REMOTE`	허용
`DAY`	`NIGHT`	허용
`NIGHT`	`REMOTE`	순찰 중지 후 허용
`REMOTE`	`NIGHT`	원격 속도 명령 정지 후 허용
모든 모드	`EMERGENCY_STOP`	즉시 허용
`EMERGENCY_STOP`	일반 모드	비상정지 해제 후 허용

27. StartPatrol.srv

string route_id
int32 repeat_count
bool detect_anomaly
bool return_to_start
---
bool success
int32 result_code
string message
string patrol_id

27.1 순찰 시작 성공 조건

로봇 운용 모드가 NIGHT 또는 순찰 허용 모드여야 한다.
비상정지가 해제되어 있어야 한다.
Nav2가 정상 상태여야 한다.
지도와 현재 위치가 설정되어 있어야 한다.
배터리가 위험 상태가 아니어야 한다.
요청한 순찰 경로가 등록되어 있어야 한다.
다른 이동 임무가 실행 중이지 않아야 한다.

28. CaptureEvidence.srv

string event_id
string file_prefix
bool include_detection_overlay
---
bool success
int32 result_code
string message
string image_path
builtin_interfaces/Time captured_time

이미지 파일명은 다음 규칙을 사용한다.

{event_id}_{YYYYMMDD}_{HHMMSS}.jpg

예시는 다음과 같다.

ANOMALY_20260718_001_20260718_231532.jpg

29. SaveVisitorMemo.srv

office_robot_msgs/VisitorMemo memo
---
bool success
int32 result_code
string message
string memo_id

30. CreateReport.srv

string report_type
builtin_interfaces/Time start_time
builtin_interfaces/Time end_time
bool include_images
string operator_name
---
bool success
int32 result_code
string message
string report_id
string report_path

report_type 값은 다음을 사용한다.

DAILY
NIGHT_PATROL
ANOMALY
VISITOR
SYSTEM

31. 좌표계 명세

31.1 표준 좌표계

좌표계	역할
`map`	사무실 지도 기준 전역 좌표계
`odom`	로봇 이동에 따른 연속 지역 좌표계
`base_footprint`	지면에 투영된 로봇 중심 좌표계
`base_link`	TurtleBot3 본체 중심 좌표계
`base_scan`	라이다 센서 좌표계
`camera_link`	카메라 본체 좌표계
`camera_optical_frame`	영상 처리용 카메라 좌표계

31.2 TF 연결 구조

map
└── odom
    └── base_footprint
        └── base_link
            ├── base_scan
            ├── camera_link
            │   └── camera_optical_frame
            └── wheel_left_link
            └── wheel_right_link

31.3 위치 기준

지도 기반 목적지, 순찰 지점, 이상 상황 위치는 모두 map 좌표계를 사용한다.

로봇 기준 장애물 위치 또는 센서 측정값은 센서 좌표계 또는 base_link 좌표계를 사용할 수 있다.

관리자 GUI에 표시되는 위치는 map 좌표계로 변환한 후 사용한다.

32. 좌표축 방향

ROS REP-103 기준을 사용한다.

축	방향
X축	로봇 전방
Y축	로봇 좌측
Z축	로봇 위쪽

회전 방향은 오른손 법칙을 사용한다.

평면 주행 시 회전은 Z축 기준 Yaw 값을 사용한다.

양의 Yaw: 반시계 방향 회전
음의 Yaw: 시계 방향 회전

33. 단위 명세

항목	기준 단위
위치 좌표	미터 `m`
거리	미터 `m`
선속도	미터/초 `m/s`
가속도	미터/초² `m/s²`
각도	라디안 `rad`
각속도	라디안/초 `rad/s`
시간	ROS 2 Time
제한 시간	초 `s`
온도	섭씨 `°C`
배터리 전압	볼트 `V`
배터리 잔량	`0.0`부터 `1.0`
신뢰도	`0.0`부터 `1.0`
진행률	`0.0`부터 `1.0`

GUI에서 배터리를 백분율로 표시할 경우 다음과 같이 변환한다.

화면 표시값 = percentage × 100

34. TurtleBot3 Burger 속도 제한

안전한 실내 운용을 위해 소프트웨어 속도 제한을 적용한다.

운용 상태	최대 선속도	최대 각속도
자율 순찰	`0.18 m/s`	`1.0 rad/s`
방문자 안내	`0.12 m/s`	`0.8 rad/s`
원격 조종	`0.15 m/s`	`1.0 rad/s`
출입구 근처	`0.08 m/s`	`0.5 rad/s`
이상 상황 접근	`0.05 m/s`	`0.4 rad/s`

최종 속도 명령은 TurtleBot3 Burger의 하드웨어 최대 속도를 초과해서는 안 된다.

35. 원격 조종 명세

원격 PC의 remote_teleop 노드는 /office_robot/cmd_vel/remote 토픽으로 속도 명령을 발행한다.

원격 조종은 운용 모드가 REMOTE일 때만 허용한다.

원격 속도 명령이 일정 시간 이상 수신되지 않으면 로봇은 자동 정지해야 한다.

항목	기준
원격 명령 발행 주기	10 Hz 이상
명령 타임아웃	0.5초
타임아웃 발생 시 처리	선속도와 각속도 0으로 설정
비상정지 우선순위	원격 명령보다 높음
안전 센서 우선순위	원격 명령보다 높음

36. 속도 명령 우선순위

cmd_vel_selector 노드는 여러 속도 명령 중 하나를 선택하여 /cmd_vel로 발행한다.

우선순위는 다음과 같다.

1순위: 비상정지
2순위: 안전 정지 또는 충돌 방지
3순위: 원격 조종
4순위: Nav2 자율주행
5순위: 정지

36.1 선택 규칙

비상정지가 활성화되면 항상 정지 명령을 출력한다.
근거리 장애물이 감지되면 전진 명령을 차단한다.
REMOTE 모드에서는 원격 속도 명령을 선택한다.
DAY, NIGHT, RETURN_TO_CHARGE 모드에서는 Nav2 속도 명령을 선택한다.
유효한 속도 명령이 없으면 정지 명령을 출력한다.
출력 명령은 반드시 속도 제한을 적용한 후 발행한다.

37. 논리적 장소 이름 명세

지도상의 주요 장소에는 고유한 영문 이름을 지정한다.

장소 이름	설명
`home`	로봇 시작 위치
`charging_station`	충전 위치
`entrance`	사무실 출입구
`reception`	안내 데스크
`office_center`	사무실 중앙
`meeting_room_1`	회의실 1
`meeting_room_2`	회의실 2
`server_room`	서버실
`storage_room`	창고
`emergency_exit`	비상구

장소 이름은 코드, YAML 파일, GUI 및 보고서에서 동일하게 사용한다.

장소 좌표는 YAML 파일로 관리할 수 있다.

locations:
  home:
    x: 0.0
    y: 0.0
    yaw: 0.0

  entrance:
    x: 2.5
    y: 1.2
    yaw: 1.57

  meeting_room_1:
    x: 4.8
    y: -1.3
    yaw: 0.0

  server_room:
    x: 7.2
    y: 2.1
    yaw: 3.14

38. 순찰 경로 명세

순찰 경로는 경로 번호와 장소 이름 배열로 구성한다.

patrol_routes:
  night_route_01:
    route_name: "야간 기본 순찰"
    repeat_count: 3
    return_to_start: true
    points:
      - location: entrance
        wait_time: 5.0
      - location: meeting_room_1
        wait_time: 3.0
      - location: server_room
        wait_time: 10.0
      - location: storage_room
        wait_time: 5.0
      - location: office_center
        wait_time: 3.0

경로 번호는 영문 소문자, 숫자, 밑줄을 사용한다.

night_route_01
day_route_01
security_route_02

39. 이벤트 식별자 규칙

이벤트마다 중복되지 않는 식별자를 생성한다.

39.1 이상 이벤트

ANOMALY_{YYYYMMDD}_{HHMMSS}_{순번}

예시:

ANOMALY_20260718_231532_001

39.2 방문자 이벤트

VISITOR_{YYYYMMDD}_{HHMMSS}_{순번}

39.3 순찰 이벤트

PATROL_{YYYYMMDD}_{HHMMSS}_{순번}

39.4 오류 이벤트

ERROR_{YYYYMMDD}_{HHMMSS}_{순번}

40. 시간 명세

모든 ROS 2 메시지 시간은 builtin_interfaces/msg/Time을 사용한다.

로봇 PC와 원격 PC의 시스템 시간은 동기화해야 한다.

동일 네트워크에서 NTP 또는 Chrony를 사용하여 시간을 맞춘다.

로그와 보고서에서 시간 문자열을 표시할 경우 다음 형식을 사용한다.

YYYY-MM-DD HH:MM:SS

예시는 다음과 같다.

2026-07-18 23:15:32

41. 원격 PC 통신 조건

로봇 PC와 원격 PC는 동일한 ROS 도메인을 사용해야 한다.

export ROS_DOMAIN_ID=30

양쪽 PC에서 동일한 값을 설정한다.

로봇 PC:

export ROS_DOMAIN_ID=30
export TURTLEBOT3_MODEL=burger

원격 PC:

export ROS_DOMAIN_ID=30
export TURTLEBOT3_MODEL=burger

ROS_LOCALHOST_ONLY는 원격 접속을 위해 0으로 설정한다.

export ROS_LOCALHOST_ONLY=0

42. 원격 GUI 표시 항목

관리자 GUI는 다음 정보를 표시해야 한다.

화면 영역	표시 내용
로봇 상태	운용 모드, 시스템 상태, 현재 임무
지도	사무실 지도, 로봇 위치, 순찰 경로
배터리	전압, 잔량, 충전 상태
카메라	실시간 압축 영상
순찰	현재 위치, 목표 위치, 진행률, 순찰 횟수
방문자	감지 인원, 방문자 이벤트, 메모
이상 상황	이벤트 유형, 위치, 신뢰도, 증거 이미지
관리자 판단	승인, 오탐, 경비 호출, 재확인
원격 조종	전진, 후진, 좌회전, 우회전, 정지
안전	비상정지, 장애물 경고, 통신 상태
보고서	최근 순찰 및 이상 상황 보고서

43. 원격 GUI 명령 제한

GUI 버튼은 로봇 상태에 따라 활성화 또는 비활성화해야 한다.

버튼	활성화 조건
주간 모드	비상정지 해제 상태
야간 모드	비상정지 해제 및 Nav2 준비 상태
원격 모드	비상정지 해제 상태
순찰 시작	야간 모드, 배터리 정상, Nav2 준비
순찰 중지	순찰 실행 중
원격 조종	원격 모드
증거 촬영	카메라 정상 상태
보고서 생성	이벤트 또는 순찰 기록 존재
비상정지	항상 활성화
비상정지 해제	로봇 주변 안전 확인 후 활성화

44. 통신 끊김 처리

원격 PC와 로봇 PC 간 통신이 끊어졌을 때 로봇은 안전하게 동작해야 한다.

44.1 원격 조종 중 통신 끊김

원격 속도 명령 수신이 0.5초 이상 중단되면 즉시 정지한다.
운용 모드를 IDLE로 변경한다.
통신 끊김 이벤트를 기록한다.

44.2 자율 순찰 중 GUI 통신 끊김

순찰은 설정에 따라 계속 수행할 수 있다.
관리자 승인이 필요한 이상 이벤트가 발생하면 로봇은 안전 위치에서 정지한다.
GUI 재연결 후 이벤트를 다시 전송한다.

44.3 heartbeat 기준

/office_robot/heartbeat 토픽은 1 Hz 이상의 주기로 발행한다.

원격 GUI는 3초 이상 heartbeat가 수신되지 않으면 통신 끊김으로 판단한다.

45. 비상정지 처리

비상정지 요청이 발생하면 다음 순서로 처리한다.

/office_robot/emergency_stop 서비스 요청을 수신한다.
safety_manager가 비상정지 상태를 활성화한다.
모든 Nav2 이동 목표를 취소한다.
실행 중인 순찰 액션을 취소한다.
/cmd_vel에 정지 명령을 반복 발행한다.
/office_robot/emergency_stop/status를 true로 발행한다.
관리자 GUI에 비상정지 상태를 표시한다.
비상정지 발생 시간과 원인을 기록한다.

정지 명령은 다음과 같다.

linear.x = 0.0
linear.y = 0.0
linear.z = 0.0
angular.x = 0.0
angular.y = 0.0
angular.z = 0.0

비상정지는 관리자가 주변 안전을 확인한 후 명시적으로 해제해야 한다.

46. 배터리 부족 처리

46.1 낮은 배터리

배터리 잔량이 30% 이하이면 다음을 수행한다.

GUI에 배터리 경고를 표시한다.
새로운 장거리 임무 시작을 제한할 수 있다.
현재 순찰을 마친 후 충전 위치 복귀를 준비한다.

46.2 위험 배터리

배터리 잔량이 15% 이하이면 다음을 수행한다.

새로운 순찰 시작을 거부한다.
실행 중인 순찰을 중지한다.
운용 모드를 RETURN_TO_CHARGE로 변경한다.
charging_station으로 이동한다.
충전 위치 이동 실패 시 안전한 위치에 정지한다.

47. 이상 상황 처리 절차

anomaly_monitor가 이상 상황을 감지한다.
이벤트 번호를 생성한다.
현재 위치와 감지 시간을 기록한다.
evidence_manager에 이미지 저장을 요청한다.
/office_robot/anomaly/event를 발행한다.
관리자 확인이 필요하면 로봇을 안전 위치에 정지시킨다.
원격 GUI에서 이벤트 정보와 증거 이미지를 표시한다.
관리자가 판단 결과를 입력한다.
/office_robot/admin/decision 토픽으로 판단 결과를 발행한다.
판단 결과에 따라 순찰 계속, 경고, 재확인 또는 임무 중지를 수행한다.
모든 결과를 보고서에 기록한다.

48. 관리자 판단 처리 기준

판단값	로봇 처리
`CONFIRMED`	이상 상황 확정, 이벤트 기록 유지
`FALSE_ALARM`	오탐 처리 후 순찰 계속
`IGNORE`	추가 동작 없이 이벤트 종료
`CALL_SECURITY`	경비 호출 상태 표시 후 대기
`CALL_EMERGENCY`	긴급 상황 상태로 전환 후 대기
`RECHECK`	동일 장소 재촬영 또는 재탐색

49. 순찰 이동 실패 처리

Nav2 이동 실패 시 patrol_manager는 다음 순서로 복구를 시도한다.

현재 이동 목표 취소
로봇 정지
장애물 제거 대기
제자리 회전
비용지도 초기화
동일 목표 재요청
재시도 횟수 초과 시 다음 순찰 지점으로 이동하거나 순찰 실패 처리

기본 재시도 횟수는 3회로 한다.

1회 실패: 동일 목표 재시도
2회 실패: 비용지도 초기화 후 재시도
3회 실패: 순찰 실패 또는 해당 지점 건너뛰기

50. 로그 및 보고서 기록 항목

다음 정보는 파일 또는 데이터베이스에 기록한다.

시스템 시작 및 종료 시간
운용 모드 변경 기록
순찰 시작 및 종료 시간
순찰 경로
순찰 지점별 도착 시간
이동 실패 및 복구 횟수
배터리 상태
방문자 감지 기록
방문자 메모
이상 상황 이벤트
증거 이미지 경로
관리자 판단 결과
비상정지 발생 기록
노드 오류 기록
원격 GUI 연결 및 해제 기록

51. 파일 저장 경로

기본 저장 경로는 다음과 같이 구성한다.

~/office_robot_data/
├── maps/
├── routes/
├── evidence/
│   ├── anomaly/
│   └── visitor/
├── reports/
├── logs/
└── config/

예시는 다음과 같다.

~/office_robot_data/maps/office_map.yaml
~/office_robot_data/routes/night_route_01.yaml
~/office_robot_data/evidence/anomaly/ANOMALY_20260718_231532_001.jpg
~/office_robot_data/reports/NIGHT_PATROL_20260718.pdf

52. 인터페이스 개발 규칙

모든 개발자는 본 명세에 정의된 토픽명과 자료형을 그대로 사용한다.
임의로 토픽명을 변경하지 않는다.
사용자 정의 메시지는 office_robot_msgs 패키지에 통합한다.
문자열 상태값은 대문자 영문과 밑줄을 사용한다.
위치와 거리는 미터를 사용한다.
각도는 라디안을 사용한다.
시간은 ROS 2 Time을 사용한다.
모든 서비스는 성공 여부와 결과 코드를 반환한다.
장시간 작업은 액션으로 구현한다.
GUI와 로봇 노드가 동일한 상태값을 사용한다.
토픽과 서비스 변경 시 전체 개발자에게 변경 내용을 공유한다.
기존 인터페이스를 변경해야 할 경우 버전 번호를 증가시킨다.

53. 인터페이스 버전 관리

인터페이스 버전은 다음 형식을 사용한다.

MAJOR.MINOR.PATCH

예시는 다음과 같다.

1.0.0

변경 유형	버전 증가
토픽명 또는 자료형 변경	MAJOR
필드 추가 또는 서비스 추가	MINOR
설명 수정 또는 오류 수정	PATCH

인터페이스 버전은 다음 토픽으로 발행할 수 있다.

/office_robot/interface_version

자료형:

std_msgs/msg/String

발행값 예시:

1.0.0

54. 최종 인터페이스 목록

54.1 핵심 토픽

/office_robot/operation_mode
/office_robot/system/status
/office_robot/entrance/person_count
/office_robot/visitor/event
/office_robot/anomaly/event
/office_robot/admin/decision
/office_robot/patrol/status
/office_robot/battery/status
/office_robot/camera/image_compressed
/office_robot/cmd_vel/navigation
/office_robot/cmd_vel/remote
/office_robot/emergency_stop/status
/cmd_vel
/odom
/scan
/map
/amcl_pose
/tf
/tf_static

54.2 핵심 서비스

/office_robot/set_mode
/office_robot/get_system_status
/office_robot/patrol/start
/office_robot/patrol/stop
/office_robot/patrol/pause
/office_robot/patrol/resume
/office_robot/evidence/capture
/office_robot/report/create
/office_robot/visitor/save_memo
/office_robot/emergency_stop

54.3 핵심 액션

/navigate_to_pose
/office_robot/navigate_to_named_location
/office_robot/execute_patrol
/office_robot/guide_visitor
/office_robot/execute_errand

54.4 핵심 사용자 정의 메시지

AnomalyEvent.msg
AdminDecision.msg
PatrolStatus.msg
PatrolRoute.msg
PatrolEvent.msg
VisitorEvent.msg
VisitorMemo.msg
RobotBatteryStatus.msg
SystemStatus.msg
EvidenceStatus.msg
ErrorEvent.msg

작성 파일 견본 :

휴머노이드시스템_사무실_안내_순찰_로봇_인터페이스_명세서_v1.0.0 다운로드