GitHub - Scout2Map/S2M-Web-Monitoring

다른 레포 형식에 맞추려면 네 레포도 시스템 내 위치 → 구성 → 설치 → 실행 → 통신 구조 → 기능 → 주의사항 순서로 작성하면 된다.

아래 내용은 현재까지 확인된 네 웹 관제 기능을 기준으로 작성한 README 초안이다. 그대로 README.md에 넣고, 실제 파일명이나 토픽명이 다르면 해당 부분만 수정하면 된다.

# S2M-Web-Monitoring

Scout2Map UGV의 지도, 로봇 위치, 센서 이벤트를 실시간으로 표시하는 웹 관제 시스템이다.

React 기반으로 동작하며, ROS2의 데이터를 rosbridge WebSocket을 통해 수신한다.  
관제 사용자는 웹 브라우저에서 SLAM 지도, 로봇 위치, 센서 상태, 위험 이벤트를 확인할 수 있다.

---

## 1. 시스템 내 위치

```text
[ 센서 퓨전 MCU ]       [ RPi5 / ROS2 ]                [ 관제 PC ]
센서 데이터 ─────────▶ pico_bridge ──▶ /sensors/* ┐
                                                   │
[ SLAM / 위치 추정 ]                              │
LiDAR ────────────────▶ SLAM 노드 ──▶ /map        ├─▶ rosbridge
                                  └─▶ /tf         │    WebSocket
                                                   │
[ 이벤트 엔진 ]                                   │
센서 임계값 판단 ────────────────▶ /events ───────┘
                                                          │
                                                          ▼
                                                S2M-Web-Monitoring
                                                지도·마커·이벤트 표시

ROS2 노드는 센서 데이터와 지도, 위치, 이벤트 정보를 발행한다.

웹 관제 시스템은 ROS2 노드에 직접 연결하지 않고 rosbridge_server가 제공하는 WebSocket을 통해 ROS2 토픽을 구독한다.

이 레포의 목적은 ROS2 내부 데이터를 사용자가 브라우저에서 실시간으로 확인할 수 있도록 시각화하는 것이다.

2. 주요 기능

ROS2와 WebSocket 연결 상태 표시
SLAM 지도 표시
지도 위 로봇 위치 표시
센서 이벤트 마커 누적 표시
이벤트 목록 및 상세 정보 표시
이벤트 종류별 구분
시간순 이벤트 확인
센서 임계값 설정 UI
ROS2 토픽을 통한 임계값 전달
통신 상태 및 데이터 수신 상태 확인

대표 이벤트는 다음과 같다.

환경 이벤트

고온
가스 고농도
저조도

주행 이벤트

요철 또는 과도한 진동
슬립 의심
회전 곤란

통신 이벤트

통신 품질 저하
통신 두절

실제 이벤트 종류는 ROS2 이벤트 엔진의 정의에 따라 변경될 수 있다.

3. 사용 기술

구분	기술
Frontend	React
Build Tool	Vite
ROS2 통신	rosbridge_suite
ROS2 JavaScript Client	roslib
지도 시각화	Leaflet
데이터 형식	JSON
패키지 관리	npm
ROS2 환경	ROS2 Jazzy

4. 레포 구성

S2M-Web-Monitoring/
├── public/
│   ├── index.html
│   └── map/
│       └── 지도 이미지 파일
├── src/
│   ├── components/
│   │   ├── MapView
│   │   ├── EventList
│   │   ├── ConnectionStatus
│   │   └── ThresholdControl
│   ├── App.jsx
│   ├── main.jsx
│   └── App.css
├── package.json
├── package-lock.json
├── vite.config.js
├── .gitignore
└── README.md

실제 디렉토리와 파일 이름은 현재 구현 상태에 따라 다를 수 있다.

5. 설치

5-1. 레포 클론

git clone https://github.com/Scout2Map/S2M-Web-Monitoring.git
cd S2M-Web-Monitoring

5-2. Node.js 확인

node -v
npm -v

Node.js가 설치되어 있지 않다면 먼저 설치해야 한다.

권장 환경은 다음과 같다.

Node.js 20 이상
npm 10 이상

5-3. 의존 패키지 설치

npm install

package.json에 정의된 React, roslib, Leaflet 등의 패키지가 설치된다.

node_modules/는 용량이 크고 npm install로 다시 생성할 수 있으므로 GitHub에 커밋하지 않는다.

6. ROS2 측 준비

웹을 실행하기 전에 ROS2와 rosbridge가 실행되어 있어야 한다.

6-1. ROS2 환경 등록

source /opt/ros/jazzy/setup.bash

Scout2Map 워크스페이스를 사용하는 경우 다음 명령도 실행한다.

source ~/scout2map_ws/install/setup.bash

6-2. rosbridge 실행

ros2 launch rosbridge_server rosbridge_websocket_launch.xml

기본 WebSocket 포트는 다음과 같다.

정상적으로 실행되면 웹은 다음 주소 형태로 접속한다.

ws://ROS2_IP:9090

ROS2와 웹을 같은 컴퓨터에서 실행하는 경우 다음 주소를 사용할 수 있다.

ws://localhost:9090

ROS2와 웹을 서로 다른 컴퓨터에서 실행하는 경우 localhost 대신 ROS2가 실행되는 장치의 IP 주소를 사용해야 한다.

예시:

ws://192.168.0.10:9090

두 장치는 같은 네트워크에 연결되어 있어야 하며, 방화벽에서 9090 포트가 차단되지 않아야 한다.

7. 웹 실행

개발 서버를 실행한다.

npm run dev

정상적으로 실행되면 콘솔에 접속 주소가 표시된다.

예시:

Local: http://localhost:5173/

브라우저에서 해당 주소로 접속한다.

8. 전체 실행 순서

Scout2Map 시스템은 다음 순서로 실행한다.

1. 센서 퓨전 MCU 및 UGV 전원 연결
2. ROS2 워크스페이스 환경 등록
3. 센서 브릿지 노드 실행
4. SLAM 및 위치 추정 노드 실행
5. 이벤트 엔진 실행
6. rosbridge_server 실행
7. S2M-Web-Monitoring 실행
8. 브라우저에서 관제 화면 접속

웹 화면이 실행되더라도 rosbridge가 실행되지 않았다면 ROS2 데이터는 표시되지 않는다.

9. ROS2 통신 구조

웹은 roslib을 이용해 rosbridge WebSocket에 연결한다.

ROS2 Topic
    │
    ▼
rosbridge_server
    │
    │ JSON / WebSocket
    ▼
roslib
    │
    ▼
React Component
    │
    ▼
지도, 센서값, 이벤트 목록 표시

ROS2 메시지는 rosbridge에서 JSON 형태로 변환되어 웹에 전달된다.

10. 사용 토픽

현재 웹 관제 시스템에서 사용하는 주요 토픽은 다음과 같다.

토픽	용도
`/map`	SLAM 지도
`/tf`	로봇 좌표 변환
`/events`	센서 및 상태 이벤트
`/sensors/env_snapshot`	통합 센서 상태
`/bridge/status`	센서 브릿지 연결 상태
임계값 설정 토픽	웹에서 ROS2로 임계값 전달

실제 토픽 이름과 메시지 타입은 ROS2 노드 구현에 따라 변경될 수 있다.

현재 사용 중인 토픽은 다음 명령으로 확인할 수 있다.

ros2 topic list

특정 토픽의 메시지 타입은 다음 명령으로 확인한다.

ros2 topic type /events

실제 데이터는 다음과 같이 확인한다.

ros2 topic echo /events

11. 이벤트 데이터 형식

이벤트는 이벤트 종류, 발생 위치, 센서값, 발생 시간 등을 포함한다.

예시는 다음과 같다.

{
  "id": "event-001",
  "type": "high_temp",
  "x": 2.4,
  "y": 1.8,
  "value": 68.5,
  "unit": "C",
  "timestamp": "2026-08-05T14:30:00"
}

각 필드의 의미는 다음과 같다.

필드	설명
`id`	이벤트 식별값
`type`	이벤트 종류
`x`	지도 기준 X 좌표
`y`	지도 기준 Y 좌표
`value`	이벤트 발생 당시 측정값
`unit`	측정 단위
`timestamp`	이벤트 발생 시간

이벤트 메시지의 실제 필드는 이벤트 엔진의 메시지 정의와 일치해야 한다.

12. 지도 및 좌표 표시

SLAM 지도는 ROS2의 지도 좌표계를 기준으로 한다.

웹 화면에 지도 이미지를 표시할 경우 다음 정보가 필요하다.

지도 이미지
해상도 resolution
지도 원점 origin
지도 크기
로봇의 지도 좌표
이벤트의 지도 좌표

ROS2의 지도 좌표와 이미지 픽셀 좌표는 기준점과 Y축 방향이 다를 수 있으므로 변환 과정이 필요하다.

ROS2 지도 좌표
      │
      ▼
origin 및 resolution 적용
      │
      ▼
이미지 픽셀 좌표
      │
      ▼
Leaflet 지도 위 마커 표시

지도 정보가 변경되면 웹의 좌표 변환 설정도 동일하게 수정해야 한다.

13. 임계값 설정

관제 화면에서는 환경 이벤트 판단에 사용되는 임계값을 설정할 수 있다.

예시는 다음과 같다.

고온 기준값
가스 농도 기준값
저조도 기준값

웹에서 입력한 임계값은 ROS2 토픽으로 발행되며, 이벤트 엔진은 전달받은 값을 기준으로 이벤트를 판단한다.

웹은 임계값을 직접 판단하는 역할보다 사용자 입력과 상태 표시를 담당한다. 실제 이벤트 판정은 ROS2 측 이벤트 엔진에서 수행하는 것을 원칙으로 한다.

14. 동작 확인

WebSocket 연결 확인

웹 화면의 연결 상태가 Connected로 표시되는지 확인한다.

연결되지 않을 경우 다음 항목을 확인한다.

ros2 node list

목록에 rosbridge 관련 노드가 있는지 확인한다.

9090 포트가 열렸는지는 다음과 같이 확인할 수 있다.

ss -lntp | grep 9090

이벤트 수신 확인

ros2 topic echo /events

터미널에는 이벤트가 출력되는데 웹에는 나오지 않는다면 다음을 확인한다.

웹에서 구독하는 토픽 이름
메시지 타입
JSON 필드 이름
rosbridge 연결 주소
브라우저 개발자 도구 콘솔 오류

지도 표시 확인

지도가 표시되지 않으면 다음을 확인한다.

지도 이미지 파일 경로
파일 이름의 대소문자
public/ 폴더 위치
지도 크기 설정
Leaflet 이미지 오버레이 범위

15. 트러블슈팅

ROS2 연결이 되지 않는 경우

증상: WebSocket connection failed

확인 항목:

rosbridge가 실행 중인지 확인
WebSocket 주소와 포트 확인
ROS2 장치 IP 주소 확인
두 장치가 같은 네트워크인지 확인
방화벽의 9090 포트 확인

화면은 나오지만 데이터가 없는 경우

확인 항목:

ROS2 토픽이 실제로 발행되고 있는지 확인
웹 코드의 토픽 이름 확인
ROS2 메시지 타입 확인
이벤트 JSON 형식 확인

npm 실행 오류

의존성 설치 상태를 초기화하고 다시 설치한다.

Windows CMD:

rmdir /s /q node_modules
del package-lock.json
npm install

Ubuntu:

rm -rf node_modules
rm package-lock.json
npm install

수정 내용이 반영되지 않는 경우

개발 서버를 종료한 뒤 다시 실행한다.

npm run dev

브라우저 캐시가 남아 있으면 강력 새로고침을 수행한다.

Ctrl + Shift + R

16. 빌드

배포용 파일을 생성하려면 다음 명령을 실행한다.

npm run build

정상적으로 빌드되면 dist/ 디렉토리가 생성된다.

로컬에서 배포 결과를 확인하려면 다음 명령을 사용한다.

npm run preview

dist/는 빌드할 때 다시 생성할 수 있으므로 일반적으로 GitHub에 커밋하지 않는다.

17. 커밋하지 않는 것

다음 파일과 디렉토리는 GitHub에 올리지 않는다.

node_modules/
dist/
.env
.env.local
.vscode/
*.log

.gitignore 예시는 다음과 같다.

node_modules/
dist/
.env
.env.local
.vscode/
*.log

WebSocket IP 주소나 환경별 설정값을 .env에 저장하는 경우 실제 .env 파일은 올리지 않고 예시 파일만 제공한다.

.env.example

예시:

VITE_ROSBRIDGE_URL=ws://localhost:9090

18. 개발 시 권장 작업 방식

팀 저장소의 최신 변경 사항을 먼저 가져온다.

git pull

기능별 브랜치를 만든다.

git checkout -b feature/event-filter

수정 후 커밋한다.

git add .
git commit -m "Add event type filter"
git push origin feature/event-filter

그다음 GitHub에서 Pull Request를 생성해 main 브랜치에 병합한다.

여러 명이 동시에 main 브랜치를 직접 수정하면 충돌이 발생할 수 있으므로 기능별 브랜치 사용을 권장한다.


README에서 특히 수정이 필요한 부분은 다음이야.

1. 실제 폴더 구조  
2. 현재 사용 중인 토픽 이름  
3. `/events` 메시지의 실제 JSON 필드  
4. ROS WebSocket 주소를 코드에 직접 적었는지 `.env`로 관리하는지  
5. CRA를 쓰는지 Vite를 쓰는지  
6. 실제 지도 파일 경로  

네 레포는 다른 MCU·브릿지 레포와 달리 **하드웨어 설치 설명보다 ROS2-WebSocket 연결 방식, 토픽, 실행 순서, 화면 기능 설명**이 중심이 되어야 한다.

Navigation Menu

Uh oh!

Repository files navigation

2. 주요 기능

환경 이벤트

주행 이벤트

통신 이벤트

3. 사용 기술

4. 레포 구성

5. 설치

5-1. 레포 클론

5-2. Node.js 확인

5-3. 의존 패키지 설치

6. ROS2 측 준비

6-1. ROS2 환경 등록

6-2. rosbridge 실행

7. 웹 실행

8. 전체 실행 순서

9. ROS2 통신 구조

10. 사용 토픽

11. 이벤트 데이터 형식

12. 지도 및 좌표 표시

13. 임계값 설정

14. 동작 확인

WebSocket 연결 확인

이벤트 수신 확인

지도 표시 확인

15. 트러블슈팅

ROS2 연결이 되지 않는 경우

화면은 나오지만 데이터가 없는 경우

npm 실행 오류

수정 내용이 반영되지 않는 경우

16. 빌드

17. 커밋하지 않는 것

18. 개발 시 권장 작업 방식

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
public		public
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

2. 주요 기능

환경 이벤트

주행 이벤트

통신 이벤트

3. 사용 기술

4. 레포 구성

5. 설치

5-1. 레포 클론

5-2. Node.js 확인

5-3. 의존 패키지 설치

6. ROS2 측 준비

6-1. ROS2 환경 등록

6-2. rosbridge 실행

7. 웹 실행

8. 전체 실행 순서

9. ROS2 통신 구조

10. 사용 토픽

11. 이벤트 데이터 형식

12. 지도 및 좌표 표시

13. 임계값 설정

14. 동작 확인

WebSocket 연결 확인

이벤트 수신 확인

지도 표시 확인

15. 트러블슈팅

ROS2 연결이 되지 않는 경우

화면은 나오지만 데이터가 없는 경우

npm 실행 오류

수정 내용이 반영되지 않는 경우

16. 빌드

17. 커밋하지 않는 것

18. 개발 시 권장 작업 방식

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages