TurtleBot3 PyQt GUI 미니 프로젝트 안내

1. 프로젝트 개요

이번 미니 프로젝트는 PyQt와 ROS 2를 연동하여 TurtleBot3 제어용 GUI 프로그램을 제작하는 실습입니다.

GUI는 단순한 버튼 화면이 아니라, 로봇 상태 확인, 토픽 모니터링, 경유점 이동, trajectory 주행, TTS 출력, bringup/nav2/teleop 실행, 로그 출력 기능을 포함하는 통합 제어 도구 형태로 구현합니다.

프로젝트 기간은 총 2일이며, 별도 평가는 진행하지 않습니다.
각 팀은 최종 결과물로 다음 항목을 제출합니다.

GUI 소스 코드
GUI 설계 문서
README 파일
실행 화면 캡처
필요한 설정 파일
주행 동영상

2. 프로젝트 목표

이번 프로젝트의 핵심 목표는 다음과 같습니다.

PyQt 기반 ROS 2 GUI 프로그램 작성
TurtleBot3 배터리 잔량 및 전압 표시
/cmd_vel 값 모니터링
TurtleBot3 주요 토픽 상태 표시
경유점 등록 및 선택 이동 기능 구현
2개 이상의 trajectory 선택 주행 기능 구현
gTTS 기반 음성 출력 기능 구현
bringup, nav2, teleop 실행 버튼 추가
프로그램 상태 및 이벤트 로그 출력
팀별 자유 기능 추가

3. 팀 구성

전체 인원은 10개 팀으로 나누어 진행합니다.

각 팀은 2명 또는 3명으로 구성합니다.
2명 팀: GUI 담당, ROS 2 연동 담당
3명 팀: GUI 담당, ROS 2 연동 담당, 문서 및 테스트 담당

팀별 역할은 명확히 나누되, README와 테스트는 모든 팀원이 함께 확인하는 것을 권장합니다.

4. 공통 필수 기능

모든 팀은 아래 기능을 반드시 포함해야 합니다.

1) PyQt 메인 GUI

GUI는 다음 영역을 기준으로 구성합니다.

로봇 상태 표시 영역
배터리 및 전압 표시 영역
/cmd_vel 표시 영역
ROS 2 토픽 모니터링 영역
경유점 표시 및 이동 영역
trajectory 선택 및 실행 영역
gTTS 출력 영역
bringup/nav2/teleop 실행 버튼 영역
로그 출력 영역
팀별 자유 기능 영역

화면은 복잡하게 꾸미기보다, 사용자가 로봇 상태와 조작 기능을 한눈에 확인할 수 있도록 구성합니다.

2) 배터리 상태 표시

TurtleBot3의 배터리 정보를 GUI에 표시합니다.

표시 항목 예시는 다음과 같습니다.

배터리 전압
배터리 잔량
배터리 상태 메시지
저전압 경고

배터리 전압이 기준 이하로 내려가면 GUI에 경고 문구를 표시하거나 로그에 경고 메시지를 출력할 수 있습니다.

3) `/cmd_vel` 모니터링

현재 발행 중인 /cmd_vel 값을 GUI에 표시합니다.

주요 표시 항목은 다음과 같습니다.

linear.x
angular.z

TurtleBot3에서는 일반적으로 전진 속도는 linear.x, 회전 속도는 angular.z를 주로 사용합니다.
GUI에서는 로봇이 전진 중인지, 회전 중인지, 정지 상태인지 쉽게 확인할 수 있어야 합니다.

4) 주요 ROS 2 토픽 표시

TurtleBot3에서 사용하는 주요 토픽 중 3개 이상을 선택하여 GUI에 표시합니다.

예시 토픽은 다음과 같습니다.

/odom
/scan
/imu
/joint_states
/battery_state
/cmd_vel
/amcl_pose
/goal_pose
/map

권장 표시 항목은 다음과 같습니다.

현재 위치 x, y
현재 방향 yaw
선속도
각속도
배터리 전압
LiDAR 최소 거리
현재 navigation 상태
현재 goal 위치

5) 로봇 상태 표시

GUI에는 로봇의 현재 상태를 표시하는 영역을 만듭니다.

상태 예시는 다음과 같습니다.

연결 대기
로봇 연결 완료
bringup 실행 중
nav2 실행 중
teleop 실행 중
경유점 이동 중
trajectory 주행 중
목표 지점 도착
장애물 감지
오류 발생

상태 표시는 텍스트 라벨, 색상, 아이콘 등을 사용할 수 있습니다.
단, 디자인보다 상태를 명확하게 보여주는 것이 더 중요합니다.

6) 경유점 등록 및 이동

GUI에서 경유점을 등록하고, 선택한 경유점으로 로봇을 이동시킵니다.

경유점 정보는 다음 형식을 사용합니다.

경유점 이름
x 좌표
y 좌표
yaw 방향

GUI 기능은 다음을 포함합니다.

x, y, yaw 값 입력
등록된 경유점 목록 표시
선택 경유점 이동 버튼
경유점 삭제 버튼
전체 초기화 버튼

Nav2를 사용하는 경우, 선택한 경유점 정보를 goal pose 또는 action client로 전달하여 이동시킵니다.

7) Trajectory 선택 주행

각 팀은 2개 이상의 trajectory를 미리 정의하고, GUI에서 선택하여 실행할 수 있도록 구현합니다.

예시 trajectory는 다음과 같습니다.

경유점은 중복 가능
특정 위치 방문 포함 경로
특정 지역만 이동

GUI 기능은 다음을 포함합니다.

trajectory 선택 콤보박스
선택한 trajectory 정보 표시
trajectory 실행 버튼
trajectory 정지 버튼
현재 이동 중인 waypoint 표시
trajectory 완료 로그 출력

8) gTTS 음성 출력

gTTS 기능은 GUI에서 별도 그룹으로 구성합니다.

구성 요소는 다음과 같습니다.

텍스트 입력창
언어 선택 옵션
TTS 출력 버튼
출력 상태 표시
로그 출력

예시 출력 문장은 다음과 같습니다.

“터틀봇이 출발합니다.”
“목표 지점에 도착했습니다.”
“배터리를 확인해 주세요.”
“장애물이 감지되었습니다.”
“미션을 완료했습니다.”

로봇 상태와 연동하여 자동 음성 출력 기능을 추가해도 됩니다.

9) Bringup/Nav2/Teleop 실행 버튼

GUI에는 다음 실행 버튼을 포함합니다.

Bringup 실행 / 종료
Nav2 실행 / 종료
Teleop 실행 / 종료
긴급 정지

예시 명령어는 다음과 같습니다.

ros2 launch turtlebot3_bringup robot.launch.py

ros2 launch turtlebot3_navigation2 navigation2.launch.py use_sim_time:=False map:=map.yaml

ros2 run turtlebot3_teleop teleop_keyboard

Python에서는 subprocess.Popen()을 사용하여 외부 명령을 실행할 수 있습니다.
단, 실행한 프로세스를 종료할 수 있도록 프로세스 객체를 따로 관리해야 합니다.

10) 로그 출력

GUI에는 프로그램 동작 상태와 로봇 이벤트를 확인할 수 있는 로그 영역을 만듭니다.

로그 예시는 다음과 같습니다.

[10:15:22] GUI 프로그램 시작
[10:15:30] ROS 2 노드 초기화 완료
[10:16:03] 경유점 P1 등록 완료
[10:16:20] Trajectory 1 실행 시작
[10:16:45] 목표 지점 도착
[10:17:10] TTS 출력 완료

로그 출력은 QListWidget 또는 QTextEdit을 사용할 수 있습니다.

5. 팀별 자유 기능 예시

공통 기능 구현 후, 각 팀은 자유 기능을 하나 이상 추가합니다.

예시는 다음과 같습니다.

배터리 저전압 경고 및 자동 TTS 알림
LiDAR 기반 장애물 감지 표시
GUI 기반 원격 조작 패널
긴급 정지 기능
로그 파일 저장
경유점/trajectory JSON/YAML 저장 및 불러오기
미션 진행률 progress bar 표시
LiDAR 거리 시각화
로봇 연결 상태 자동 확인
실행 중인 ROS 2 노드 목록 표시
토픽 목록 자동 표시
미션 완료 후 자동 복귀 기능

2일 프로젝트이므로 자유 기능은 너무 어렵게 잡지 않는 것이 좋습니다.
먼저 공통 기능을 완성한 뒤 시간이 남으면 추가 기능을 구현합니다.

6. 프로젝트 진행 계획

1일 차

1일 차에는 기본 구조를 빠르게 완성합니다.

팀 구성 및 역할 분담
공통 기능과 자유 기능 결정
GUI 화면 설계
ROS 2 토픽 목록 확인
PyQt 메인 화면 작성
배터리 표시 영역 구현
/cmd_vel 표시 영역 구현
주요 토픽 3개 이상 표시
로봇 상태 표시 기능 구현
로그 출력 리스트 구현
bringup/nav2/teleop 버튼 배치

1일 차 목표는 GUI가 실행되고, ROS 2 토픽 일부가 GUI에 표시되는 상태까지 만드는 것입니다.

2일 차

2일 차에는 로봇 제어 기능과 문서화를 마무리합니다.

경유점 등록 기능 구현
선택 경유점 이동 기능 구현
trajectory 2개 이상 생성
trajectory 선택 및 실행 기능 구현
gTTS 텍스트 입력 및 음성 출력 구현
bringup/nav2/teleop 실행 버튼 동작 구현
팀별 자유 기능 구현
전체 기능 테스트
GUI 설계 문서 작성
README 작성
소스 코드 정리
제출 파일 압축

2일 차에는 기능을 더 늘리기보다, 이미 만든 기능이 안정적으로 동작하도록 정리하는 것이 중요합니다.

7. README 포함 내용

README에는 사용자가 프로그램을 실행하고 사용할 수 있도록 다음 내용을 정리합니다.

프로젝트 이름
프로젝트 소개
팀명 및 팀원
개발 환경
설치해야 하는 패키지
패키지 빌드 방법
실행 방법
GUI 사용 방법
주요 기능 설명
경유점 등록 방법
trajectory 실행 방법
gTTS 사용 방법
bringup/nav2/teleop 버튼 사용 방법
로그 확인 방법
팀별 추가 기능 설명
주의 사항(옵션)
실행 화면 예시

실행 명령 예시는 다음과 같습니다.

cd ~/ros2_ws

colcon build --packages-select turtlebot3_pyqt_gui

source install/setup.bash

ros2 run turtlebot3_pyqt_gui main_gui

8. GUI 설계 문서 포함 내용

ppt로 작성하는 GUI 설계 문서에는 다음 내용을 포함합니다.

프로젝트 제목
팀명, 팀원 이름
프로젝트 개요
개발 환경
GUI 전체 화면 구성
각 영역별 기능 설명
사용한 ROS 2 토픽 목록
사용한 메시지 타입
경유점, trajectory 구성 방식
gTTS 출력 방식
bringup/nav2/teleop 실행 방식
로그 출력 방식
팀별 자유 기능 설명
테스트 결과
실행 화면 캡처
구현 중 발생한 문제와 해결 방법

손그림, 캡처 이미지, 다이어그램, 표 모두 사용할 수 있습니다.

9. 권장 제출 파일 구조

최종 제출 파일은 다음 구조를 권장합니다.

team_01_turtlebot3_pyqt_gui/
├── README.md
├── docs/
│   └── gui_design.ppt
├── src/
│   └── turtlebot3_pyqt_gui/
├── config/
│   ├── waypoints.yaml
│   └── trajectories.yaml
├── images/
│   ├── gui_main.png
│   └── test_result.png
├── requirements.txt
├── package.xml
└── setup.py

압축 파일 이름은 다음 형식을 사용합니다.

team-name_turtlebot3_pyqt_gui.zip