# AgentNILM MQTT Client 시스템 운영 및 개발 매뉴얼

---

## 1. 개요 (System Overview)

**AgentNILM MQTT Client**는 전력 분해/모니터링(NILM: Non-Intrusive Load Monitoring) 센서 디바이스로부터 MQTT 프로토콜을 통해 실시간 계측 데이터를 수신하고, 이를 파싱하여 **PostgreSQL 데이터베이스 저장**, **OPC 서버 메모리 쓰기(PLC 연동)**, **실시간 화면 모니터링**, **히스토리 이력 관리 및 트렌드 차트 분석**을 수행하는 통합 에이전트 프로그램입니다.

### 📌 주요 특징
- **개발 환경**: Delphi 13 (Athens) VCL Application
- **통신 프로토콜**: MQTT (Client), OPC DA / UA (Server Writer), PostgreSQL (FireDAC)
- **전력 결선 방식 지원**: 3상 4선식 (3P4W, 220V 계통), 3상 3선식 (3P3W, 380V 계통), 단상 (Single Phase)
- **고성능 데이터 처리**: 실시간 UPSERT(`nilm_data`), 시계열 이력 저장(`nilm_data_history`), 누적 전력량(Wh) 수치 적분 계산

---

## 2. 시스템 아키텍처 및 데이터 흐름

```mermaid
flowchart LR
    A[NILM 센서 디바이스] -->|MQTT Publish| B[MQTT Broker]
    B -->|Subscribe| C[AgentNILM Client]
    
    C -->|실시간 갱신 & 누적 연산| D[(PostgreSQL DB)]
    C -->|태그/메모리 쓰기| E[OPC Server / PLC]
    C -->|UI 렌더링| F[VCL 화면 GUI]
    
    subgraph UI Features
        F1[실시간 모니터링 그리드]
        F2[디바이스 설정 관리]
        F3[트렌드 차트 분석]
        F4[히스토리 이력 조회]
    end
    F --> UI Features
```

---

## 3. 화면별 상세 기능 및 조작 가이드

### 3.1 상단 연결 및 전역 제어 바
- **Broker IP / Port / Client ID**: MQTT 브로커 연결 정보 설정
- **Auto Start 체크**: 프로그램 실행 시 자동으로 브로커 연결 및 구독 시작
- **Log View / Log Save 체크**: 로그 리치에디트 표시 및 일자별 텍스트 파일 저장 활성화
- **DB 자동 저장 (chkAutoSaveDB)**: MQTT 수신 데이터를 PostgreSQL에 실시간/이력 저장할지 여부 제어

---

### 3.2 탭 1: 모니터링 (실시간 데이터)
등록된 모든 NILM 디바이스의 최신 계측 상태를 한눈에 모니터링합니다.

| 컬럼 번호 | 컬럼명 | 설명 | 비고 |
| :--- | :--- | :--- | :--- |
| **0** | No | 행 번호 | 1부터 시작 |
| **1** | Device ID | 장비 식별 번호 | 고유 ID |
| **2** | Device Name | 장비명 | 디바이스 별칭 |
| **3** | Comm Status | 통신 상태 | 0: 정상, 기타: 통신 이상 |
| **4** | Phase Type | 결선 방식 | 3P4W, 3P3W, SINGLE |
| **5 ~ 7** | PF (A, B, C) | 역률 (Power Factor) | 각 상별 역률 (-1.000 ~ 1.000) |
| **8 ~ 10** | Vrms (A, B, C) | 전압 실효값 (V) | 3P4W: 220V급 선간, 3P3W: 380V급 상간 |
| **11 ~ 13** | Irms (A, B, C) | 전류 실효값 (A) | 각 상별 RMS 전류 |
| **14 ~ 16** | Active P (A, B, C) | 유효전력 (W) | 각 상별 유효전력 소비량 |
| **17 ~ 19** | Reactive P (A, B, C) | 무효전력 (Var) | 각 상별 무효전력 |
| **20 ~ 22** | Apparent P (A, B, C) | 피상전력 (VA) | 각 상별 피상전력 |
| **23** | Temp (°C) | 내부 온도 | 내부 센서 계측 온도 |
| **24** | Energy_Day (Wh) | 당일 누적 전력량 | 00:00부터 현재까지의 적분 전력량 |
| **25** | Last Received | 최종 수신 시각 | YYYY-MM-DD HH:NN:SS |

> [!TIP]
> **핵심 항목 집중 뷰**: 현장 관제 편의성을 위해 고조파(THD), 진동 등 부가 항목을 제외하고 전력 관리에 필수적인 핵심 24개 데이터 필드만을 최적화하여 표시합니다.

---

### 3.3 탭 2: NILM 디바이스 설정
NILM 센서 장비의 등록, 수정, 삭제 및 가동 판단 임계값을 관리합니다.

#### 주요 설정 항목
1. **기본 정보**: 장비 ID, 장비명, 설치 위치, MQTT Topic, 활성 여부
2. **결선 방식 (Phase Type)**:
   - **3상 4선식 (3P4W)**: R, S, T, N 4선 사용. 선간전압(R-N, S-N, T-N) 측정, 공칭 220V RMS 기준
   - **3상 3선식 (3P3W)**: R, S, T 3선 사용. 상간전압(R-S, S-T, T-R) 측정, 공칭 380V RMS 기준
   - **단상 (SINGLE)**: 단상 L-N 측정
3. **가동 판정 파라미터**:
   - **대상 상 (Target Phase)**: L1, L2, L3, 또는 3상 평균(AVG)
   - **꺼진 기준 전류 (Off Current)**: 설비 정지 상태 판정 기준 전류(A)
   - **가동 기준 전류 (Run Current)**: 설비 가동 상태 판정 기준 전류(A)
   - **가동 기준 PF (Run Power Factor)**: 가동 상태 판정 역률 기준

---

### 3.4 탭 3: 트렌드 분석 (Trend Chart)
시간 경과에 따른 전력 파라미터 변화를 시각적인 그래프로 분석합니다.

- **조회 대상 장비**: 등록된 디바이스 선택
- **조회 기간**: 시작 일시 ~ 종료 일시 설정
- **선택 상 (Phase)**: L1, L2, L3 중 분석할 상 선택
- **표시 계측 항목 체크박스**:
  - `pf`: 역률 (주황색 선)
  - `voltage`: 전압 실효값 (빨간색 선)
  - `current`: 전류 실효값 (초록색 선)
  - `Var`: 무효전력 (자주색 선)
  - `Va`: 피상전력 (청록색 선)
  - `W`: **유효전력** (파란색 선)

---

### 3.5 탭 4: 히스토리 로그 검색
`nilm_data_history`에 적재된 시계열 원시 데이터를 조회하고 CSV 등으로 분석할 수 있습니다.
- 특정 장비 및 일자 구간 지정 검색
- 최대 조회 건수(Max Rows) 제한 기능 지원

---

### 3.6 로그 창 (하단)
- **MQTT Log**: 브로커 접속, Topic 구독(Subscribe), 메시지 수신 이벤트
- **DB Log**: PostgreSQL 연결, 실시간 데이터 UPSERT, 일자별 이력 INSERT 오류 로그
- **OPC Log**: OPC Server 연결 상태, 태그 쓰기 결과 및 타임아웃/통신 실패 로그

---

## 4. 데이터 통신 및 포맷 규격

### 4.1 MQTT JSON 수신 데이터 규격
NILM 디바이스는 설정된 토픽으로 다음과 같은 JSON 페이로드를 브로드캐스트합니다.

```json
{
  "seq": 1024,
  "pre_seq": 1023,
  "comm_status": 0,
  "vrms_a": 220.5,
  "vrms_b": 221.2,
  "vrms_c": 219.8,
  "irms_a": 15.32,
  "irms_b": 14.85,
  "irms_c": 15.01,
  "active_power_a": 3200.5,
  "active_power_b": 3120.0,
  "active_power_c": 3180.2,
  "reactive_power_a": 450.1,
  "reactive_power_b": 420.3,
  "reactive_power_c": 440.0,
  "apparent_power_a": 3232.0,
  "apparent_power_b": 3148.1,
  "apparent_power_c": 3210.5,
  "power_factor_a": 0.99,
  "power_factor_b": 0.99,
  "power_factor_c": 0.99,
  "temperature": 32.5,
  "tempExt": 0.0,
  "accX": 0.01,
  "accY": 0.02,
  "accZ": 0.98,
  "vibration": 0.05,
  "gyroX": 0.0,
  "gyroY": 0.0,
  "gyroZ": 0.0,
  "tiltAngle": 1.2
}
```

---

### 4.2 OPC Server 연동 규칙
- NILM에서 수신된 실시간 전력 데이터(`vrms`, `irms`, `active_power`, `reactive_power`, `apparent_power`, `power_factor` 등)를 PLC/OPC 서버 메모리 블록(예: `GW`, `GB` 영역)에 매핑하여 주기적으로 쓰기를 수행합니다.
- 주소 범위 부족 시 그룹당 32개 주소 이상(예: 34개) 확장 구성 지원.

---

## 5. 데이터베이스 구조 (PostgreSQL)

### 5.1 `nilm_device` (디바이스 메타 테이블)
| 컬럼명 | 데이터 타입 | 설명 |
| :--- | :--- | :--- |
| `device_id` | INTEGER (PK) | 디바이스 고유 ID |
| `device_name` | VARCHAR(100) | 디바이스 명칭 |
| `location` | VARCHAR(100) | 설치 위치 |
| `phase_type` | VARCHAR(20) | `3P4W` / `3P3W` / `SINGLE` |
| `mqtt_topic` | VARCHAR(255) | 구독 대상 토픽 |
| `is_active` | BOOLEAN | 사용 여부 |
| `op_target_phase` | VARCHAR(10) | 판정 기준 상 (`L1`, `L2`, `L3`, `AVG`) |
| `op_threshold_off_current` | NUMERIC | 꺼짐 기준 전류(A) |
| `op_threshold_run_current` | NUMERIC | 가동 기준 전류(A) |
| `op_threshold_pf` | NUMERIC | 가동 기준 역률 |

---

### 5.2 `nilm_data` (실시간 최신 상태 - 1 Device 당 1 Row)
`device_id`를 Unique Key로 가지며, 새로운 패킷이 수신될 때마다 `ON CONFLICT (device_id) DO UPDATE`로 실시간 최신값을 갱신합니다.

### 5.3 `nilm_data_history` (시계열 이력 테이블)
초/분 단위 수신 데이터가 지속적으로 누적 저장되는 시계열 이력 데이터입니다.
- **적분 전력량 계산**: `CalculateEnergyConsumption` 프로시저가 이 테이블의 이전 레코드와의 시각 차이(`LAG(received_at)`)와 유효전력(`active_power_a/b/c`)을 이용해 당일 누적 Wh를 산출합니다.

---

## 6. 유지보수 및 트러블슈팅 가이드

### Q1. `ERROR: column "w_l1" does not exist` 발생 시
- **원인**: 과거 버전의 쿼리가 구 컬럼명(`w_l1`, `va_l1`, `var_l1`)을 호출할 때 발생.
- **조치**: `uNILMManager.pas`의 `CalculateEnergyConsumption` 및 `QueryHistoryData`가 신규 스키마(`active_power_a`, `apparent_power_a`, `reactive_power_a`)로 수정되어 있으므로 컴파일 및 재빌드를 수행합니다.

### Q2. `Exception EClassNotFound: Class TChart not found` 발생 시
- **원인**: `uMain.dfm`의 `Chart_Main` 컴포넌트명과 `uMain.pas`의 클래스 선언 변수명이 일치하지 않을 때 발생.
- **조치**: `uMain.pas` 선언부의 차트 변수명이 `Chart_Main: TChart;`로 등록되어 있는지 확인합니다.

### Q3. 3상 3선식(3P3W)과 3상 4선식(3P4W) 전압 표기가 다를 때
- **설명**: 3상 4선식은 220V RMS 선간전압(R-N, S-N, T-N)을 기준으로 하고, 3상 3선식은 380V RMS 상간전압(R-S, S-T, T-R)을 기준으로 계측하는 것이 정상 동작입니다. 디바이스 설정 폼에서 결선 방식을 올바르게 선택했는지 확인하십시오.