# HC900 Crawler

Honeywell HC900 공정 컨트롤러를 **Modbus TCP로 직접** 폴링하여 PostgreSQL에 적재하고,
웹 UI · RAG · NL2SQL · 피드포워드 제어 권고를 제공하는 산업용 모니터링 플랫폼.

기존 Experion R530의 OPC UA 데이터 경로를 HC900 직접 통신으로 대체한 프로젝트로,
**물리 플랜트·공정·계기·로직은 동일**하고 통신 계층만 교체되었다.

```
변경 전:  HC900 ──Modbus TCP──▶ Experion R530 ──OPC UA──▶ ExperionCrawler ──▶ PostgreSQL
변경 후:  HC900 ──Modbus TCP──▶ C++ Gateway ──gRPC──▶ HC900Crawler ──▶ PostgreSQL
```

---

## 저장소

```bash
git clone https://git.hanmocnn.co.kr/windpacer/HC900-Crawler.git
```

> 사내 git 서버. HTTPS 자격증명(사번 계정)으로 접근한다.

---

## 아키텍처

```
┌──────────┐  Modbus TCP   ┌──────────────┐   gRPC    ┌──────────────┐   EF Core   ┌────────────┐
│  HC900   │ ◀───────────▶ │ C++ Gateway  │ ◀───────▶ │ C# Crawler   │ ◀─────────▶ │ PostgreSQL │
│ C70 PLC  │   :502        │ hc900_gateway│  :50051   │ ASP.NET 8    │             │ (hc900)    │
└──────────┘               └──────────────┘           │  + Web UI    │             │ TimescaleDB│
                                                       └──────┬───────┘             └────────────┘
                                                              │ HTTP :5001
                                                       ┌──────▼───────┐
                                                       │ Python MCP   │  RAG / NL2SQL / P&ID
                                                       │ FastMCP      │
                                                       └──────────────┘
```

### 구성 요소

| 디렉토리 | 설명 |
|---|---|
| `industrial-comm/cpp/` | **C++ 게이트웨이** — Modbus TCP 폴러 + gRPC 서버 (`hc900_gateway` 바이너리) |
| `src/Hc900Crawler/` | **C# .NET 8 ASP.NET Core** — gRPC 클라이언트 + 웹 UI + KB/P&ID/FF (포트 5000) |
| `src/Core/`, `src/Infrastructure/` | 도메인 엔티티 · DB · 서비스 (3-Layer 아키텍처) |
| `mcp-server/` | **Python FastMCP 서버** (포트 5001) — RAG, NL2SQL, P&ID 처리 |
| `scripts/`, `test/` | 레지스터 맵 생성 · 테스트 유틸 |
| `prompts/`, `knowledge/` | LLM 시스템 컨텍스트 · RAG 기본 문서 |

다중 컨트롤러(N-Controller) 지원: `config/gateway-config.json`의 `controllers[]`에
컨트롤러를 추가하면 게이트웨이 인스턴스가 컨트롤러별 gRPC 포트로 개별 기동된다.

---

## 빠른 시작

### 1. C++ 게이트웨이 빌드

gRPC · abseil은 `/tmp/grpc_local`, `/tmp/absl_local`(aarch64)에 사전 설치되어 있다.

```bash
cd industrial-comm/cpp
mkdir -p build && cd build
cmake .. && make -j$(nproc)
# 산출물: build/hc900_gateway, build/libcomm_core.so
```

직접 실행:
```bash
./build/hc900_gateway [host] [register-map] [poll_ms] [grpc_port] [modbus_port]
# 기본값: 192.168.0.240  docs/register-map.json  1000  50051  502
# 로그: /tmp/hc900_gateway.log,  gRPC: 0.0.0.0:50051
```

### 2. C# 크롤러 빌드 · 실행

```bash
cd src/Hc900Crawler
dotnet build
dotnet run        # 웹 UI: http://0.0.0.0:5000
```

> 크롤러는 부팅 시 `config/gateway-config.json`을 읽어 게이트웨이 프로세스를 직접 기동·감시한다.
> 게이트웨이를 따로 실행할 필요 없이 크롤러만 띄우면 된다.

설정: `src/Hc900Crawler/appsettings.json`
- `ConnectionStrings.DefaultConnection` — PostgreSQL (`Search Path=hc900`)
- `Hc900.PollIntervalMs`, `Kb.*`, `DocBrowser.*` 등

### 3. MCP 서버 (RAG / NL2SQL)

```bash
cd mcp-server
uv sync                       # 의존성 (최초 1회)
uv run python server.py --http   # 포트 5001
```

### 4. 레지스터 맵 생성

HC Designer CSV 내보내기 → `docs/register-map.json` (게이트웨이가 기동 시 로드):

```bash
python3 scripts/build_register_map.py \
    --loop-csv docs/SummaryFucntionBlockReport.csv \
    --signal-csv docs/SignalTags.csv \
    --variable-csv docs/Variables.csv \
    -o docs/register-map.json
```

---

## 웹 UI 탭

| 탭 | 기능 |
|---|---|
| Setup | 게이트웨이 프로세스 제어 · 다중 컨트롤러 설정 · 로그 |
| 태그 관리 | HC900 등록 태그 조회 · 폴링 활성화 관리 |
| 이력 조회 | `history_table` 시계열 조회 (TimescaleDB 하이퍼테이블) |
| Text-to-SQL | 자연어 → SQL (MCP) |
| fastRecord | 고속 샘플링 세션 수집 · CSV 내보내기 |
| P&ID 추출 | 도면 파싱 · 계기 추론 |
| 이벤트 히스토리 | 디지털 포인트 상태 변경 (TRIP/ALARM/RUN) |
| 로컬 LLM 채팅 | Ollama/vLLM 기반 플랜트 지식 채팅 |
| RAG 관리 | 지식 문서 업로드 · Qdrant 색인 |
| 태그 쓰기 | gRPC `WriteTag` (SP/OP/MODE) |
| 문서 탐색기 | 리포지토리 문서 브라우징 |
| 트렌드 | 실시간/이력 차트 + 이벤트 오버레이 |
| 유량 권장(FF) | 측류추출 피드포워드 제어 권고 |

---

## 데이터베이스 (PostgreSQL, 스키마 `hc900`)

`Hc900DbContext.InitializeAsync()`가 모든 테이블·뷰·하이퍼테이블을 자동 생성한다.

| 테이블 | 용도 |
|---|---|
| `hc900_map_master` | OPC UA `tagname` ↔ HC900 레지스터 매핑 (Modbus addr 포함) |
| `realtime_table` | 실시간 값 (`controller_id`, `tagname` UNIQUE) |
| `history_table` | 60초 이력 스냅샷 (TimescaleDB 하이퍼테이블) |
| `event_history_table` | 디지털 태그 상태 변경 이벤트 |
| `tag_metadata` | 태그 메타 (description, area, state 레이블) |
| `pid_*`, `kb_*`, `ff_*` | P&ID · Knowledge Base · 피드포워드 |

---

## HC900 하드웨어

- 컨트롤러: HC900-C70, Modbus TCP 포트 502, 최대 동시 연결 10
- Float 포맷은 컨트롤러에서 **FP B** (IEEE 754 big-endian, 워드 순서 4·3·2·1)로 설정 필요
- 레지스터 주소: Loop N base = `0x40 + (N-1)*0x100` (1–24), `0x7840 + (N-25)*0x100` (25–32)

---

## 라이선스

Proprietary — 내부 사용.