ROS2:Basic:RobotMonitoringGuideline
로봇 모니터링/제어 시스템 가이드라인
협력로봇(로봇팔)이 설치되는 현장에 Edge Server를 설치하고, CVP Agent와 ROS2를 통해 모니터링 및 제어하는 시스템 아키텍처 가이드라인.
1. 전체 아키텍처
graph TB
subgraph Cloud["CVP Cloud (Cloudflare Workers)"]
HonoAPI["Hono API"]
Supabase["Supabase"]
Realtime["Realtime\n(WebSocket)"]
HonoAPI --- Supabase --- Realtime
end
Cloud -->|"HTTPS / WSS"| SiteA
Cloud -->|"HTTPS / WSS"| SiteB
Cloud -->|"HTTPS / WSS"| SiteC
subgraph SiteA["Edge Site A"]
subgraph AgentA["CVP Agent"]
BridgeA["ROS2 Bridge"]
end
DDSA["ROS2 DDS Network"]
CobotA["Cobot(s)"]
BridgeA --> DDSA --> CobotA
end
subgraph SiteB["Edge Site B"]
subgraph AgentB["CVP Agent"]
BridgeB["ROS2 Bridge"]
end
DDSB["ROS2 DDS Network"]
CobotB["Cobot(s)"]
BridgeB --> DDSB --> CobotB
end
subgraph SiteC["Edge Site C"]
subgraph AgentC["CVP Agent"]
BridgeC["ROS2 Bridge"]
end
DDSC["ROS2 DDS Network"]
CobotC["Cobot(s)"]
BridgeC --> DDSC --> CobotC
end
2. CVP Agent (Edge Server에 설치)
Edge Server에서 실행되는 데몬 프로세스. 별도 리포지토리로 관리 권장.
기술 스택 권장
- 언어: Python (ROS2 생태계와 호환성 최적) 또는 Rust (성능 중요시)
- ROS2 버전: Humble Hawksbill (LTS) 또는 Jazzy Jalisco
- 통신: WebSocket (실시간) + REST (설정/명령)
Agent 핵심 모듈
| 모듈 | 역할 |
| | ROS2 토픽 subscribe/publish, 서비스 호출 |
| | 로봇 상태 데이터 수집 → CVP Cloud 전송 |
| | CVP Cloud → 로봇 명령 수신 및 실행 |
| | Agent 자체 헬스체크, 자동 복구 |
| | 원격 설정 동기화 |
| | 카메라 피드 수집, CV 모델 추론 (on-edge) |
주요 ROS2 토픽/서비스 예시
graph LR
subgraph Subscribe["Subscribe (모니터링)"]
JS["/joint_states"] -->|"sensor_msgs/JointState"| Agent1["CVP Agent"]
RS["/robot_status"] -->|"industrial_msgs/RobotStatus"| Agent1
CI["/camera/image_raw"] -->|"sensor_msgs/Image"| Agent1
DG["/diagnostics"] -->|"diagnostic_msgs/DiagnosticArray"| Agent1
end
subgraph Publish["Publish (제어)"]
Agent2["CVP Agent"] -->|"trajectory_msgs/JointTrajectory"| TC["/trajectory_command"]
Agent2 -->|"custom_msgs/IOCommand"| IO["/io_command"]
end
subgraph Service["Service Call"]
Agent3["CVP Agent"] -->|"std_srvs/Trigger"| EN["/robot/enable"]
Agent3 -->|"std_srvs/Trigger"| ST["/robot/stop"]
Agent3 -->|"custom_srvs/GetRobotState"| GS["/robot/get_state"]
end
3. CVP Cloud Backend (Hono API 확장)
현재 src/worker/index.ts에 API를 추가.
필요한 API 엔드포인트
graph LR
subgraph WebUI["Web UI"]
Browser["브라우저"]
end
subgraph Worker["Cloudflare Worker (Hono)"]
subgraph AgentMgmt["Agent 관리"]
A1["POST /api/projects/:slug/agents\n(등록)"]
A2["GET /api/projects/:slug/agents\n(목록)"]
A3["GET .../agents/:id (상세)"]
A4["PUT .../agents/:id (설정변경)"]
A5["DELETE .../agents/:id (삭제)"]
end
subgraph AgentStatus["Agent 상태 (Agent→Cloud)"]
S1["POST /api/agents/:id/heartbeat"]
S2["POST /api/agents/:id/telemetry"]
S3["POST /api/agents/:id/events"]
end
subgraph Control["로봇 제어 (Cloud→Agent)"]
C1["POST /api/agents/:id/commands"]
C2["GET .../commands/:cmdId"]
end
RT["WS /api/agents/:id/stream\n(실시간 텔레메트리)"]
end
subgraph Edge["Edge Agent"]
EA["CVP Agent"]
end
Browser --> AgentMgmt
Browser --> Control
Browser <-->|"WebSocket"| RT
EA --> AgentStatus
RT <-->|"WebSocket"| EA
인증 방식
- 웹 UI → Cloud: Supabase Auth (기존)
- Edge Agent → Cloud: API Key 기반 인증 (Agent 등록 시 발급)
4. Supabase 데이터 모델
ER 다이어그램
erDiagram
projects ||--o{ agents : "has"
agents ||--o{ robots : "connects"
agents ||--o{ events : "emits"
robots ||--o{ telemetry : "sends"
robots ||--o{ commands : "receives"
robots ||--o{ events : "emits"
users ||--o{ commands : "issues"
agents {
uuid id PK
uuid project_id FK
text slug UK
text name
text description
text api_key_hash
text status
timestamptz last_heartbeat
jsonb config
jsonb metadata
timestamptz created_at
}
robots {
uuid id PK
uuid agent_id FK
text slug
text name
text model
text manufacturer
text ros2_namespace
text status
jsonb config
timestamptz created_at
}
telemetry {
bigint id PK
uuid robot_id FK
timestamptz timestamp PK
float8_arr joint_positions
float8_arr joint_velocities
float8_arr joint_efforts
float8_6 tcp_pose
jsonb status
}
commands {
uuid id PK
uuid robot_id FK
uuid issued_by FK
text type
jsonb payload
text status
jsonb result
timestamptz created_at
timestamptz completed_at
}
events {
uuid id PK
uuid agent_id FK
uuid robot_id FK
text severity
text category
text message
jsonb data
timestamptz created_at
}
SQL 스키마
-- Agent (Edge Server)
create table agents (
id uuid primary key default gen_random_uuid(),
project_id uuid references projects(id),
slug text unique not null,
name text not null,
description text,
api_key_hash text not null, -- Agent 인증용
status text default 'offline', -- online, offline, error
last_heartbeat timestamptz,
config jsonb default '{}',
metadata jsonb default '{}', -- OS, IP, ROS2 distro 등
created_at timestamptz default now()
);
-- Agent에 연결된 로봇
create table robots (
id uuid primary key default gen_random_uuid(),
agent_id uuid references agents(id),
slug text not null,
name text not null,
model text, -- UR5e, Doosan M1013 등
manufacturer text,
ros2_namespace text, -- /robot1, /arm_left 등
status text default 'unknown',
config jsonb default '{}',
created_at timestamptz default now(),
unique(agent_id, slug)
);
-- 텔레메트리 (시계열)
create table telemetry (
id bigint generated always as identity,
robot_id uuid references robots(id),
timestamp timestamptz not null,
joint_positions float8[],
joint_velocities float8[],
joint_efforts float8[],
tcp_pose float8[6], -- x, y, z, rx, ry, rz
status jsonb,
primary key (robot_id, timestamp)
);
-- 명령 이력
create table commands (
id uuid primary key default gen_random_uuid(),
robot_id uuid references robots(id),
issued_by uuid references auth.users(id),
type text not null, -- move, stop, enable, io, custom
payload jsonb not null,
status text default 'pending', -- pending, sent, executing, done, failed
result jsonb,
created_at timestamptz default now(),
completed_at timestamptz
);
-- 이벤트/알람
create table events (
id uuid primary key default gen_random_uuid(),
agent_id uuid references agents(id),
robot_id uuid references robots(id),
severity text not null, -- info, warning, error, critical
category text, -- safety, hardware, communication, vision
message text not null,
data jsonb,
created_at timestamptz default now()
);
5. Frontend 페이지 구조
현재 proj/agents/ stub을 확장.
graph TD
Agents["proj/agents/"]
Agents --> AgentList["index.tsx\nAgent 목록 (상태 대시보드)"]
Agents --> AgentNew["new.tsx\nAgent 등록 (API Key 발급)"]
Agents --> AgentSlug["[agentSlug]/"]
AgentSlug --> AgentIndex["index.tsx\nAgent 상세 → dashboard 리다이렉트"]
AgentSlug --> AgentNav["AgentNavigation.tsx\nAgent 섹션 사이드바"]
AgentSlug --> Dashboard["dashboard/\nindex.tsx\n실시간 모니터링 대시보드"]
AgentSlug --> Robots["robots/"]
AgentSlug --> Events["events/\nindex.tsx\n이벤트/알람 로그"]
AgentSlug --> Settings["settings/\nindex.tsx\nAgent 설정 (API Key 재발급, 삭제)"]
Robots --> RobotList["index.tsx\n연결된 로봇 목록"]
Robots --> RobotSlug["[robotSlug]/"]
RobotSlug --> RobotDetail["index.tsx\n로봇 상세 (조인트 시각화, 제어판)"]
RobotSlug --> Telemetry["telemetry.tsx\n텔레메트리 차트/이력"]
RobotSlug --> Commands["commands.tsx\n명령 이력"]
6. 보안 고려사항
| 영역 | 권장 사항 |
| Agent 인증 | API Key (SHA-256 해시 저장), 주기적 로테이션 |
| 명령 권한 | RBAC — |
| 위험 명령 | E-Stop, 프로그램 실행 등은 2단계 확인 (UI confirm + 서버 검증) |
| 네트워크 | Edge ↔ Cloud: TLS 필수, Agent는 outbound만 (방화벽 친화적) |
| 텔레메트리 | Rate limiting, 배치 전송 (1~10Hz 압축) |
| 감사 로그 | 모든 제어 명령은 |
7. 구현 우선순위
gantt
title CVP 로봇 모니터링/제어 구현 로드맵
dateFormat YYYY-MM-DD
axisFormat %Y-%m
section Phase 1 — 기반 구축
Supabase 테이블/뷰 생성 :p1a, 2026-04-01, 2w
Agent CRUD API (src/worker/) :p1b, after p1a, 2w
Agent 목록/등록 UI (proj/agents/) :p1c, after p1a, 2w
Agent 인증 (API Key 발급/검증) :p1d, after p1b, 1w
section Phase 2 — 모니터링
CVP Agent 데몬 (별도 리포) :p2a, after p1d, 3w
ROS2 Bridge 모듈 :p2b, after p2a, 2w
실시간 대시보드 UI :p2c, after p1c, 3w
이벤트/알람 시스템 :p2d, after p2b, 2w
section Phase 3 — 제어
명령 전송 API + UI :p3a, after p2d, 2w
로봇 제어 패널 (E-Stop 등) :p3b, after p3a, 2w
프로그램 관리 :p3c, after p3b, 2w
section Phase 4 — 비전/ML
카메라 피드 스트리밍 :p4a, after p3c, 2w
On-edge CV 모델 배포/추론 :p4b, after p4a, 3w
품질 검사 결과 대시보드 :p4c, after p4b, 2w