16fc7a2598
Honeywell HC900을 Modbus TCP로 직접 폴링 → gRPC → C# 크롤러 → PostgreSQL. 기존 Experion OPC UA 데이터 경로를 HC900 직접 통신으로 대체. - industrial-comm/cpp: C++ Modbus 게이트웨이 (gRPC 서버) - src: C# .NET 8 ASP.NET Core 크롤러 + 웹 UI (3-Layer) - mcp-server: Python FastMCP (RAG/NL2SQL/P&ID) - 다중 컨트롤러(N-Controller) 지원 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
173 lines
8.0 KiB
Markdown
173 lines
8.0 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
This project replaces the Experion OPC UA data path with a direct Modbus TCP connection to the Honeywell HC900 process controller:
|
||
|
||
```
|
||
Before: HC900 ──Modbus TCP──▶ Experion R530 ──OPC UA──▶ ExperionCrawler ──▶ PostgreSQL
|
||
After: HC900 ──Modbus TCP──▶ C++ Gateway ──gRPC──▶ HC900Crawler ──▶ PostgreSQL
|
||
```
|
||
|
||
Four active components:
|
||
- **`industrial-comm/cpp/`** — C++ gateway: Modbus TCP poller + gRPC server (`hc900_gateway` binary)
|
||
- **`src/Hc900Crawler/`** — C# .NET 8 ASP.NET Core web app: full monitoring platform (gRPC client + web UI + KB/P&ID/FF)
|
||
- **`mcp-server/`** — Python FastMCP server (port 5001): RAG, NL2SQL, P&ID processing tools
|
||
- **`scripts/`** + **`test/`** — Python utilities for register map generation and testing
|
||
|
||
## Commands
|
||
|
||
### C++ Gateway (build)
|
||
|
||
gRPC and abseil are pre-installed to `/tmp/grpc_local` and `/tmp/absl_local` (aarch64).
|
||
|
||
```bash
|
||
cd industrial-comm/cpp
|
||
mkdir -p build && cd build
|
||
cmake ..
|
||
make -j$(nproc)
|
||
```
|
||
|
||
Produces `build/hc900_gateway` and `build/libcomm_core.so`.
|
||
|
||
Run the gateway:
|
||
```bash
|
||
./build/hc900_gateway [host] [register-map-path] [poll_ms]
|
||
# defaults: 192.168.0.240, docs/register-map.json, 1000
|
||
```
|
||
|
||
Log file: `/tmp/hc900_gateway.log`. gRPC listens on `0.0.0.0:50051`.
|
||
|
||
### C# Crawler (build + run)
|
||
|
||
```bash
|
||
cd src/Hc900Crawler
|
||
dotnet build
|
||
dotnet run
|
||
```
|
||
|
||
Configuration via `appsettings.json`: `Hc900.GatewayAddress` (default `http://localhost:50051`), `Hc900.PollIntervalMs`, `ConnectionStrings.DefaultConnection` (PostgreSQL, `Search Path=hc900`). Serves web UI at `http://0.0.0.0:5000`.
|
||
|
||
### Register Map Generation
|
||
|
||
Converts HC Designer CSV exports → `docs/register-map.json` used by the gateway at startup:
|
||
|
||
```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
|
||
```
|
||
|
||
Load state labels (StatusPoint descriptors from xlsx) into DB:
|
||
```bash
|
||
python3 scripts/load_state_labels.py
|
||
```
|
||
|
||
### Test Utilities
|
||
|
||
```bash
|
||
# Start Modbus TCP simulator (port 5020, loads register-map.json)
|
||
python3 test/modbus_sim.py
|
||
|
||
# Read tags directly via Modbus TCP
|
||
python3 test/read_tags.py FICQ3101.PV FICQ3101.SP FICQ3101.MODE
|
||
python3 test/read_tags.py --port 5020 FICQ3101.PV # against simulator
|
||
python3 test/read_tags.py --all --limit 50
|
||
|
||
# pymodbus must be available; it's expected at /tmp/hc900_venv
|
||
/tmp/hc900_venv/bin/python3 test/read_tags.py FICQ3101.PV
|
||
```
|
||
|
||
## Architecture
|
||
|
||
### C++ Gateway (`industrial-comm/cpp/`)
|
||
|
||
**`Hc900Gateway`** (`src/gateway.cpp`, `include/gateway.h`) is the core class:
|
||
- Loads `register-map.json` at startup into `registers_` (vector of `RegisterEntry`) and `tag_index_` (name→index map)
|
||
- Spawns a poll thread (`PollLoop`) that runs `ReadAllRegisters()` every `poll_interval_ms`
|
||
- `ReadAllRegisters()` groups consecutive registers into batches of ≤120 and issues one `read_raw()` call per batch (~48 batches total for a full HC900 config, ~117 ms round-trip)
|
||
- Cache (`cache_`, protected by `cache_mutex_`) stores `CachedValue` per tag; quality=192=good, quality=0=bad/stale
|
||
- `transport_mutex_` serializes all Modbus transport calls between the poll thread and gRPC `WriteTag` handlers
|
||
|
||
**Key gRPC operations** (all implemented in `gateway.cpp`):
|
||
- `ReadTags` — reads from cache, sub-millisecond, no Modbus I/O
|
||
- `WriteTag` — calls Modbus FC16 directly, then updates cache
|
||
- `StreamTags` — pushes cache snapshot at requested interval
|
||
- `ListTags` — returns metadata from in-memory register list
|
||
- `HealthCheck` — reports connection state, poll count, last poll duration
|
||
|
||
**`Controller`** (`src/controller.cpp`, `include/controller.hpp`) wraps `ITransport` with typed read/write methods. **`ModbusTCP`** (`src/modbus_tcp.cpp`, `include/modbus_tcp.hpp`) implements the transport.
|
||
|
||
**Codec** (`src/codec.cpp`, `include/codec.hpp`) handles byte/word order for float32, int32, int64, double. HC900 uses `VendorFormat::HC900_FLOAT` = `{BigEndian, HighFirst, Normal}` (FP B format per manual).
|
||
|
||
**Proto:** The generated files (`gen/modbus_gateway.pb.{cc,h}` and `gen/modbus_gateway.grpc.pb.{cc,h}`) are pre-built and committed. The source proto is at `proto/modbus_gateway.proto`. The C# copy lives at `src/Hc900Crawler/Proto/modbus_gateway.proto` and is compiled by MSBuild via `Grpc.Tools`.
|
||
|
||
### C# Crawler (`src/Hc900Crawler/`) — 3-Layer Architecture
|
||
|
||
**Project layout** (ExperionCrawler 패턴 적용):
|
||
```
|
||
src/
|
||
Core/ ← Domain entities, interfaces, application services
|
||
Infrastructure/ ← DB (Hc900DbContext), HC900 services, Control, Kb, Mcp, Trend, Docs
|
||
Hc900Crawler/ ← ASP.NET Core web project (Controllers, wwwroot, Program.cs, csproj)
|
||
mcp-server/ ← Python MCP server (copied from ExperionCrawler)
|
||
```
|
||
|
||
**BackgroundServices:**
|
||
- **`Hc900RealtimeService`** (`Infrastructure/Hc900/`) — gRPC 폴링 → `hc900.realtime_table` upsert (500 rows/batch). 상태 노출: `IsConnected`, `PollCount`, `LastPollAt`
|
||
- **`Hc900HistoryService`** — 60초 주기 `realtime_table` → `history_table` 스냅샷 (IsConnected 확인 후 실행)
|
||
- **`Hc900DigitalEventDetectorService`** — 1초 주기로 realtime_table 변화 감지 → `event_history_table` 기록
|
||
|
||
**`Hc900GatewayClient`** (`Infrastructure/Hc900/`) — `IHc900GatewayService` 구현. gRPC 채널 lazy 생성. `GetHealthAsync()`, `ListTagsAsync()`, `WriteTagAsync()`.
|
||
|
||
**`Hc900WriteService`** — FeedforwardSupervisor·FeedforwardController에서 SP 쓰기용.
|
||
|
||
**Value formatting**: 상태 레이블 있으면 `{N | LABEL | }`, 없으면 float/uint16 string.
|
||
|
||
**Web API endpoints** (port 5000):
|
||
- `GET /api/gateway/health` — gRPC HealthCheck
|
||
- `GET /api/gateway/tags` — ListTags
|
||
- `POST /api/gateway/write` — WriteTag
|
||
- `GET /api/gateway/status` — Hc900RealtimeService 상태
|
||
- `GET /api/realtime/points` — realtime_table
|
||
- `POST /api/history/query` — history_table 조회
|
||
- `POST /api/events/query` — event_history_table 조회
|
||
- `/api/pid/*`, `/api/kb/*`, `/api/ff/*`, `/api/t2s/*`, `/api/ollama/*` 등 ExperionCrawler 동일
|
||
|
||
### Database (PostgreSQL, schema `hc900`)
|
||
|
||
`Hc900DbContext` (`Infrastructure/Database/Hc900DbContext.cs`) — `HasDefaultSchema("hc900")` + `Search Path=hc900` 연결문자열. `InitializeAsync()`에서 모든 테이블·뷰·TimeScaleDB 하이퍼테이블 자동 생성.
|
||
|
||
| Table | Purpose |
|
||
|---|---|
|
||
| `hc900_map_master` | OPC UA `tagname` ↔ `hc900_tag` 매핑, Modbus addr, 데이터타입 |
|
||
| `realtime_table` | 실시간 값 (tagname, livevalue, timestamp) — upsert on conflict |
|
||
| `history_table` | 60초 이력 스냅샷 (TimeScaleDB hypertable) |
|
||
| `event_history_table` | 디지털 태그 상태 변경 이벤트 (TRIP/ALARM/RUN 등) |
|
||
| `tag_metadata` | 태그 메타 (description, area, sub_area, state0-7 레이블) |
|
||
| `pid_equipment`, `pid_prefix_rules` | P&ID 추출 데이터 |
|
||
| `kb_*` | Knowledge Base (Qdrant RAG) |
|
||
| `ff_*` | Feedforward 제어 설정/감사 |
|
||
|
||
### Register Map (`docs/register-map.json`)
|
||
|
||
JSON file with a top-level `registers` array. Each entry: `tag`, `addr` (0-based Modbus holding register address), `count` (1=uint16, 2=float32), `type`, `access` ("R"/"RW"), `description`.
|
||
|
||
Sources:
|
||
- **Loops** (PID): `SummaryFucntionBlockReport.csv` → expanded into per-parameter entries using `LOOP_PARAM_OFFSETS` in `build_register_map.py`. Loop #N base address = `0x40 + (N-1)*0x100` (loops 1–24), `0x7840 + (N-25)*0x100` (loops 25–32).
|
||
- **Signal Tags** (read-only): `SignalTags.csv`, addresses `0x2000–0x25E4`
|
||
- **Variables** (R/W): `Variables.csv`, addresses `0x18C0–0x1A10`
|
||
|
||
Float format is `FP_B` (IEEE 754 big-endian, wire order bytes 4,3,2,1).
|
||
|
||
### HC900 Hardware
|
||
|
||
- Controller: HC900-C70, IP `192.168.0.240`, Modbus TCP port 502
|
||
- Maximum simultaneous connections: 10 (R530 uses 1, leaving 9 available)
|
||
- Unit ID: 0x00 (not used in Modbus TCP mode)
|
||
- Float format must be set to **FP B** on the controller
|