안전하개 - 4족 보행 안전 순찰 로봇 플랫폼

산업 현장의 안전을 지키는 4족 보행 로봇과 실시간 모니터링 웹 플랫폼

프로젝트 기간: 2026.02.16 ~ 2026.04.01 팀 구성: 6명 (정지용, 김경한, 김동언, 박세진, 손동완, 오충민)

📌 프로젝트 소개

기획 배경

산업 현장(공장, 건설 현장 등)에서는 가스 누출, 낙상 사고, PPE(개인보호장비) 미착용 등 다양한 안전 위험이 존재합니다. 위험한 가스 유출 현장에 인간 대신 우선적으로 투입되며, 실시간으로 순찰 현장을 확인 및 위험 요소를 모니터링하는 것의 필요성을 절감했습니다.

핵심 가치

자율 순찰: 4족 보행 로봇이 지정 경로를 순찰하며 위험 요소를 실시간 탐지
AI 기반 감지: YOLO11 TensorRT를 활용한 PPE 미착용, 낙상, 배관 손상, 장애물 등 11종 객체 탐지
즉각 대응: 위험 감지 시 음성 경고 + 관리자 알림 + 이벤트 기록의 자동화된 대응 파이프라인
원격 모니터링: 웹 대시보드를 통한 실시간 MJPEG 스트리밍, 로봇 수동 조종, 이벤트 관리

대상 사용자

산업 현장 안전 관리자
시설 관리 운영팀

🛠 기술 스택

분류	기술
Robot (Embedded)	ROS 2 Humble, Python 3.10, C++ 17, STM32 (C)
AI / Vision	YOLO11 (TensorRT 10.3), pyzbar (QR), OpenCV
SLAM / Navigation	Isaac ROS cuVSLAM 3.2.6, RTAB-Map 0.22.1, Nav2 1.1.20, Nvblox 3.2.5
Streaming	aiortc (WebRTC), aiohttp (MJPEG), SSH Reverse Tunnel
Backend	Spring Boot 3.5.11, Java 17, Spring Security (JWT), Spring Data JPA
Frontend	Next.js 16, React 19, TypeScript 5, Tailwind CSS 4, Zustand 5, React Query 5
Database	PostgreSQL 16
Message Broker	Eclipse Mosquitto 2 (MQTT)
Infra	Docker, Docker Compose, Nginx, Jenkins, Let's Encrypt SSL
Hardware	Jetson Orin Nano 8GB, Intel RealSense D435i, STS3215 Servo x12, BNO-085 IMU

🏗 시스템 아키텍처

통신 흐름

구간	프로토콜	설명
Robot ↔ STM32	USB CDC Serial	33.3Hz 관절 명령/피드백 (12 joint x float32)
Robot ↔ Backend	MQTT (QoS 1)	상태, 위치, 이벤트, 명령 (JSON)
Robot → Browser	MJPEG over SSH Tunnel	실시간 카메라 스트리밍
Frontend ↔ Backend	REST API (HTTPS)	JWT 인증, 10초 Polling
Backend → DB	JPA/Hibernate	PostgreSQL 영속성

📊 ERD

erDiagram
    SITES ||--o{ ROBOTS : "보유"
    SITES ||--o{ ZONES : "구역 포함"
    SITES ||--o{ EVENTS : "발생"
    SITES ||--o{ NOTIFICATIONS : "알림"
    SITES ||--o{ PATROL_SCHEDULES : "순찰 일정"
    SITES ||--o{ PPE_LOGS : "PPE 기록"

    ZONES ||--o{ ROBOTS : "배치"
    ZONES ||--o{ PPE_LOGS : "감지 위치"

    ROBOTS ||--o{ ROBOT_STATUS_LOGS : "상태 변경"
    ROBOTS ||--o{ ROBOT_LOCATION_LOGS : "위치 기록"
    ROBOTS ||--o{ ROBOT_COMMANDS : "명령"
    ROBOTS ||--o{ EVENTS : "감지"

    EVENTS ||--o{ EVENT_ACTIONS : "조치 이력"

    USERS ||--o{ USER_SITE_ROLES : "역할"
    USERS ||--o{ EVENT_ACTIONS : "조치자"

    SITES {
        bigint id PK
        string code UK
        string name
        boolean active
    }

    ROBOTS {
        bigint id PK
        string code UK
        string name
        enum current_state "IDLE | PATROLLING | MANUAL | OFFLINE | ERROR"
        timestamp last_heartbeat_at
    }

    EVENTS {
        bigint id PK
        enum event_type "GAS_ALERT | FALL_DETECTED | PIPE_DAMAGE | PPE_EMERGENCY"
        enum severity "CRITICAL | HIGH | MEDIUM | LOW"
        enum status "OPEN | IN_PROGRESS | RESOLVED | CLOSED"
        float x
        float y
        string image_url
    }

    PPE_LOGS {
        bigint id PK
        enum ppe_type "HELMET | SAFETY_VEST | GLOVES | ..."
        string worker_id
        boolean warning_broadcasted
        timestamp detected_at
    }

    ROBOT_COMMANDS {
        bigint id PK
        enum command_type "PATROL_START | MOVE_TO | RETURN_HOME | MANUAL_MOVE | STOP"
        enum command_status "PENDING | SENT | EXECUTING | SUCCESS | FAILED"
        string payload_json
    }

    PATROL_SCHEDULES {
        bigint id PK
        string name
        enum schedule_type "CRON | INTERVAL"
        string schedule_expression
        string waypoint_json
    }

✨ 주요 기능

🦿 4족 보행 제어

12-DOF 역기구학(IK) 기반 보행 알고리즘, Cycloid 스윙 궤적으로 부드러운 착지
IMU 자세 보상(roll/pitch → 다리별 Z 보정) + 모터 전류 기반 접지 감지(300mA 임계값)
Jacobian 기반 속도 오도메트리, Nav2 cmd_vel 입력으로 자율/수동 전환

🔍 AI 객체 탐지 (11종)

YOLO11 TensorRT GPU 추론 (640x480, 15FPS)
탐지 대상: L/T/십자 배관, 소화기, 비상구, 장애물, 낙상자, 헬멧, ID카드, PPE 착용/미착용자
클래스별 개별 신뢰도 임계값 설정 (배관 0.18 ~ 장애물 0.94)

🦺 PPE 안전 관리 + QR 사원 식별

PPE 미착용 감지 시 3단계 에스컬레이션:
- 0초: 음성 경고 + QR 스캔 요청
- 15초: QR 실패 경고 + 안전관리자 호출
- 30초: 비상 이벤트 발행
pyzbar QR 코드 인식으로 사원 식별, 30초 쿨다운

🔧 배관 손상 감지 + 로봇 arm 연동

YOLO 배관 탐지 → OpenCV Hough Circle 기반 구멍 검출
구멍 좌표 + 배관 종류를 MQTT로 전송, 로봇 arm 파지 제어 연동
감지 시 음성 알림 (120초 쿨다운)

📡 실시간 스트리밍 & 원격 조종

MJPEG 스트리밍: WebRTC(aiortc) 서버, SSH Reverse Tunnel로 외부 접속
웹 UI에서 전진/후진/좌우/회전 수동 조종 (MQTT → cmd_vel)
스트림 세션 관리: 시작/종료/헬스체크/자동 재연결

🔥 가스 누출 감지 & 대응

MQ-2 가스 센서 기반 실시간 감지
감지 시 로봇 퍼포먼스 반응 (앉기→일어서기 3회) + 웹 이벤트 알림
이벤트센터에서 가스 누출 이력 확인 및 조치 관리

🗺 자율 내비게이션

cuVSLAM (Isaac ROS): GPU 가속 Visual SLAM, 스테레오 + IMU 융합
RTAB-Map: CPU 기반 대안, 루프 클로저 지원
Nav2: RegulatedPurePursuit 컨트롤러, 웨이포인트 순찰
Nvblox: 실시간 3D 점유 격자 맵핑

📊 웹 대시보드

대시보드: 현장 요약 지표, 최근 이벤트, PPE 준수율 차트 (10초 폴링)
로봇 모니터링: 로봇 목록 + 실시간 스트리밍 + 수동 조종 + 활동 로그
이벤트센터: 안전 이벤트 필터/상태 관리/조치 이력 (이미지 첨부)
알림 시스템: 실시간 알림 (로봇 상태, 이벤트, PPE 위반)
PPE 로그: 기간별/구역별/장비별 PPE 감지 기록
관리 페이지: 현장(Site), 구역(Zone), 로봇 관리

📁 프로젝트 구조

gae_jjy/
├── gae_ws/                          # ROS 2 워크스페이스
│   └── src/
│       ├── stm_bridge/              # C++ STM32 시리얼 통신 노드
│       ├── gait/                    # 보행 제어 (walk_node_v2, teleop)
│       ├── yolo_detect/             # YOLO 객체 탐지 + 배관 검출 + 스트리밍
│       ├── mqtt_bridge/             # MQTT ↔ ROS2 브릿지 (8개 핸들러)
│       ├── gae_performances/        # 퍼포먼스 시퀀스 (인사, 가스 반응)
│       ├── gae_description/         # URDF 로봇 모델
│       ├── vslam_launch/            # cuVSLAM + Nvblox + Nav2 런치
│       ├── gae_rtabmap/             # RTAB-Map SLAM 런치
│       ├── realsense_splitter/      # RealSense 이미터 분리 처리
│       └── gae_test/                # 진단 도구 (IMU, 관절, 궤적)
│
├── web/
│   ├── backend/                     # Spring Boot REST API
│   │   └── src/main/java/.../
│   │       ├── auth/                # JWT 인증
│   │       ├── robot/               # 로봇 관리 + 스트림 프록시
│   │       ├── event/               # 안전 이벤트 CRUD
│   │       ├── ppe/                 # PPE 로그
│   │       ├── notification/        # 알림 시스템
│   │       ├── patrol/              # 순찰 스케줄
│   │       ├── mqtt/                # MQTT 수신 핸들러
│   │       └── dashboard/           # 대시보드 집계
│   │
│   └── frontend/                    # Next.js 웹 클라이언트
│       └── src/
│           ├── app/                 # App Router 페이지
│           ├── features/            # 기능별 모듈 (API + 상태 + UI)
│           ├── widgets/             # 페이지 레벨 조합 컴포넌트
│           ├── entities/            # 도메인 모델
│           └── shared/              # 공통 유틸, API 클라이언트
│
├── stm_code/                        # STM32 펌웨어 (C)
│   └── gae/
│
├── infra/
│   ├── web/compose/                 # 웹 Docker Compose (dev/prod) + Nginx
│   ├── robot/compose/               # 로봇 Docker Compose (NVIDIA GPU)
│   └── jenkins/                     # Jenkins CI/CD
│
├── scripts/                         # 운영 스크립트
│   ├── run.sh                       # 개발 컨테이너 진입
│   ├── gae_monitor.sh               # 리소스 모니터링
│   ├── bt_auto_connect.sh           # BT 스피커 자동 연결
│   └── ssh_reverse_tunnel.sh        # MJPEG 스트림 터널링
│
├── docs/                            # 프로젝트 문서
├── Jenkinsfile.ci                   # CI 파이프라인 (develop)
└── Jenkinsfile.cd                   # CD 파이프라인 (main)

⚙️ 시작하기

사전 요구사항

구분	요구사항
로봇	Jetson Orin Nano (JetPack 6.2), Docker, NVIDIA Container Runtime
웹 (개발)	Java 17 (JDK), Node.js 20+, Docker (PostgreSQL, Mosquitto)
웹 (배포)	Docker, Docker Compose

로봇 실행

# 1. 개발 컨테이너 진입
./scripts/run.sh

# 2. 컨테이너 내부에서 빌드
cd /workspace/gae/gae_ws
colcon build --symlink-install
source install/setup.bash

# 3. 전체 스택 실행 (SLAM + Nav2 + Gait + MQTT)
ros2 launch vslam_launch full_stack.launch.py

# 4. 텔레옵 (별도 터미널)
ros2 run gait teleop_keyboard

웹 개발 환경

# 1. 인프라 (PostgreSQL + Mosquitto)
cd infra/web/compose
docker compose -f docker-compose.dev.yml up -d

# 2. Backend
cd web/backend
cp .env.example .env
./mvnw spring-boot:run -Dspring-boot.run.profiles=local

# 3. Frontend
cd web/frontend
cp .env.example .env.local
npm install
npm run dev    # http://localhost:3000

웹 프로덕션 배포

cd infra/web/compose
docker compose -f docker-compose.prod.yml up -d --build

환경 변수

변수	설명	기본값 (개발)
`SPRING_DATASOURCE_URL`	PostgreSQL 접속 URL	`jdbc:postgresql://localhost:5432/safetydb`
`SPRING_DATASOURCE_USERNAME`	DB 사용자	`safety_user`
`SPRING_DATASOURCE_PASSWORD`	DB 비밀번호	`safety_pass`
`JWT_SECRET`	JWT 서명 키 (Base64)	개발용 기본값
`MQTT_BROKER_URL`	MQTT 브로커 주소	`tcp://localhost:1883`
`NEXT_PUBLIC_API_BASE_URL`	프론트엔드 API 주소	`http://localhost:8080/api`

🔗 API 명세 (주요)

인증

Method	Endpoint	설명
POST	`/api/auth/login`	로그인 (사번 + 비밀번호)
GET	`/api/auth/me`	현재 사용자 정보

로봇

Method	Endpoint	설명
GET	`/api/robots`	로봇 목록
GET	`/api/robots/{id}/summary`	로봇 요약
POST	`/api/robots/{id}/commands`	명령 전송 (이동, 정지, 순찰)
POST	`/api/robots/{id}/stream/start`	스트리밍 시작
GET	`/api/robots/{id}/stream/mjpeg`	MJPEG 스트림

이벤트

Method	Endpoint	설명
GET	`/api/events`	이벤트 목록 (필터: 상태, 심각도, 유형, 기간)
GET	`/api/events/{id}`	이벤트 상세
PATCH	`/api/events/{id}/status`	상태 변경
POST	`/api/events/{id}/actions`	조치 이력 추가

대시보드 / PPE / 알림

Method	Endpoint	설명
GET	`/api/dashboard/summary`	현장 요약 지표
GET	`/api/dashboard/ppe-summary`	PPE 준수 요약
GET	`/api/ppe-logs`	PPE 감지 로그
GET	`/api/notifications`	알림 목록
GET	`/api/notifications/unread-count`	읽지 않은 알림 수

MQTT 토픽

방향	토픽	설명
Robot → Server	`robot/{id}/heartbeat`	5초 간격 생존 신호
Robot → Server	`robot/{id}/status`	로봇 상태 변경
Robot → Server	`robot/{id}/location`	위치 (x, y, heading)
Robot → Server	`robot/{id}/event`	탐지 이벤트 (이미지 포함)
Robot → Server	`robot/{id}/ppe-log`	PPE 위반 기록
Server → Robot	`robot/{id}/command/request`	명령 전송
Robot → Server	`robot/{id}/command/response`	명령 실행 결과

👥 팀 소개

이름	역할
정지용	PM / ROS 통합 / 인프라
박세진	역기구학 / 강화 학습 / HW
오충민	로봇암 / 강화 학습 / HW
손동완	보행 로직 / MCU 제어 / HW
김경한	Sim2real / 강화 학습 / HW
김동언	Web

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.claude		.claude
docs		docs
exec		exec
firmware/gae		firmware/gae
gae_ws		gae_ws
infra		infra
scripts		scripts
web		web
.gitattributes		.gitattributes
.gitignore		.gitignore
Jenkinsfile.cd		Jenkinsfile.cd
Jenkinsfile.ci		Jenkinsfile.ci
README.md		README.md
gae.code-workspace		gae.code-workspace

Folders and files

Latest commit

History

Repository files navigation

안전하개 - 4족 보행 안전 순찰 로봇 플랫폼

📌 프로젝트 소개

기획 배경

핵심 가치

대상 사용자

🛠 기술 스택

🏗 시스템 아키텍처

통신 흐름

📊 ERD

✨ 주요 기능

🦿 4족 보행 제어

🔍 AI 객체 탐지 (11종)

🦺 PPE 안전 관리 + QR 사원 식별

🔧 배관 손상 감지 + 로봇 arm 연동

📡 실시간 스트리밍 & 원격 조종

🔥 가스 누출 감지 & 대응

🗺 자율 내비게이션

📊 웹 대시보드

📁 프로젝트 구조

⚙️ 시작하기

사전 요구사항

로봇 실행

웹 개발 환경

웹 프로덕션 배포

환경 변수

🔗 API 명세 (주요)

인증

로봇

이벤트

대시보드 / PPE / 알림

MQTT 토픽

👥 팀 소개

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages