ROS2:Basic:RobotMonitoringGuideline

lastmod 2026-03-26created 2026-03-262 edits

Robot monitoring/control system guideline

A system architecture guideline for installing an Edge Server at sites where collaborative robots (robot arms) are installed, and monitoring and controlling them through the CVP Agent and ROS2.

1. Overall architecture

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 (installed on the Edge Server)

A daemon process that runs on the Edge Server. Recommended to manage it in a separate repository.

Recommended tech stack

• Language: Python (best compatibility with the ROS2 ecosystem) or Rust (when performance matters)
• ROS2 version: Humble Hawksbill (LTS) or Jazzy Jalisco
• Communication: WebSocket (real-time) + REST (configuration/commands)

Core Agent modules

Example key ROS2 topics/services

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 (extending the Hono API)

Add the APIs to the current src/worker/index.ts.

Required API endpoints

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

Authentication

• Web UI → Cloud: Supabase Auth (existing)
• Edge Agent → Cloud: API Key-based authentication (issued when the Agent is registered)

4. Supabase data model

ER diagram

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 schema

-- 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 page structure

Extend the current 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. Security considerations

7. Implementation priorities

%%{init: {"themeCSS": ".titleText,[class*=sectionTitle],[class*=taskText]{fill:var(--md-mermaid-label-fg-color)}.task0,.task1,.task2,.task3{fill:var(--md-mermaid-node-bg-color);stroke:var(--md-mermaid-node-fg-color)}.section0,.section2{fill:var(--md-mermaid-node-fg-color);opacity:.08}.section1,.section3{fill:none}.grid .tick line{stroke:var(--md-default-fg-color--lightest)}.grid .tick text{fill:var(--md-default-fg-color--light)}"}}%%
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

See also

• ROS2
• ROS2:Basic
• Cloudflare