import os import docx from docx import Document from docx.shared import Inches, Pt, RGBColor from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.enum.table import WD_TABLE_ALIGNMENT from docx_builder_base import ( add_header_banner, add_heading_1, add_heading_2, add_heading_3, add_body_p, add_bullet_item, add_callout, add_code_block, format_table ) def create_operation_manual(): doc = Document() # Page Margins for sec in doc.sections: sec.top_margin = Inches(0.8) sec.bottom_margin = Inches(0.8) sec.left_margin = Inches(0.9) sec.right_margin = Inches(0.9) # Title & Metadata add_header_banner( doc, title="스마트팜 HMI 시스템 운영 매뉴얼", subtitle="환경 모니터링, 장비 제어, 자동 제어 규칙, 순차 관수 스케줄 및 로그 관리 가이드", doc_type="사용자 및 현장 운영 매뉴얼", version="v1.1", date_str="2026년 8월" ) # ========================================================================= # 제1장 시스템 개요 및 구성 # ========================================================================= add_heading_1(doc, "제1장 시스템 개요 및 구성") add_heading_2(doc, "1.1 시스템 소개") add_body_p(doc, "스마트팜 HMI(Human-Machine Interface) 시스템은 시설원예, 온실 및 스마트팜 환경에서 센서 데이터를 실시간으로 모니터링하고, 환기·차광·난방·관수 등 주요 시설 장비를 직관적으로 제어할 수 있도록 설계된 다중 플랫폼 통합 제어 소프트웨어입니다.") add_body_p(doc, "주요 특징은 다음과 같습니다:") add_bullet_item(doc, " 온실 내부의 환경 데이터(온도, 습도, CO2, 양액 EC/pH, 토양 온습도 등)를 직관적인 게이지 및 수치로 실시간 시각화합니다.", bold_prefix="실시간 환경 모니터링:") add_bullet_item(doc, " 팬, 조명, 밸브, 펌프 등 디지털 출력(DO) 장비를 터치 및 클릭 한 번으로 원격 On/Off 제어합니다.", bold_prefix="장비 원격 수동 제어:") add_bullet_item(doc, " 시간대 및 센서 임계값, 드라이 접점(DI) 상태를 결합한 다중 조건식 룰을 기반으로 전자동 운전을 지원합니다.", bold_prefix="지능형 자동 운전(Auto Control):") add_bullet_item(doc, " 다수 구역에 대해 시작/정지/종료 조건, 쿨다운(지연) 시간, 유량 펄스 계산(리터/Kg)을 반영한 순차 관수 스케줄링을 제공합니다.", bold_prefix="고도화된 순차 관수(Irrigation):") add_bullet_item(doc, " 표준 MQTT v3.1.1 비동기 메시징 프로토콜을 사용하여 저대역폭 및 불안정한 통신망에서도 신뢰성 높은 데이터 통신을 보장합니다.", bold_prefix="MQTT 표준 통신:") add_bullet_item(doc, " Delphi FireMonkey(FMX) 엔진을 탑재하여 Windows PC뿐만 아니라 Android 태블릿, 스마트폰, iOS, macOS, Linux 등 다양한 단말에서 동일한 UX로 구동됩니다.", bold_prefix="크로스 플랫폼 지원:") add_bullet_item(doc, " 한국어 및 영어를 원터치로 전환하여 글로벌 사용자 및 다문화 농가에서도 편리하게 이용 가능합니다.", bold_prefix="다국어 인터페이스:") add_heading_2(doc, "1.2 전체 시스템 아키텍처 및 데이터 흐름") add_body_p(doc, "스마트팜 HMI는 현장의 스마트팜 IoT 게이트웨이 및 MQTT 브로커와 유무선 네트워크로 연동되어 작동합니다.") arch_tbl = doc.add_table(rows=1, cols=3) format_table( arch_tbl, col_widths=[1.5, 2.0, 3.0], headers=["구성 요소", "주요 역할", "통신 및 데이터 인터페이스"], data=[ ["스마트팜 센서/구동기", "온습도/토양/유량 센서 계측 및 릴레이 구동기", "RS-485 Modbus, Analog(4-20mA/0-10V), Digital In/Out"], ["스마트팜 게이트웨이", "현장 센서 수집 및 구동기 제어 명령 중계", "MQTT 프로토콜(PUB/SUB)을 통해 브로커와 통신"], ["MQTT 브로커", "센서 데이터 및 제어 메시지 라우팅 중계 서버", "TCP Port 1883 (Mosquitto, EMQX 등 표준 브로커)"], ["스마트팜 HMI (본 앱)", "운영자 모니터링, 수동/자동 제어, 관수 설정, 로그 관리", "비동기 TCP/IP MQTT Client (구독: PUB 토픽, 발행: SUB 토픽)"] ] ) add_heading_2(doc, "1.3 지원 플랫폼 및 권장 시스템 사양") spec_tbl = doc.add_table(rows=1, cols=4) format_table( spec_tbl, col_widths=[1.3, 1.8, 1.8, 1.6], headers=["플랫폼", "최소 운영체제", "권장 하드웨어 사양", "배포 형태"], data=[ ["Windows PC", "Windows 10 (32/64-bit) 이상", "Intel Core i3 / RAM 4GB 이상", "단일 실행 파일 (.exe)"], ["Android", "Android 8.0 (Oreo) 이상", "RAM 3GB 이상 (10인치 태블릿 권장)", "설치 패키지 (.apk)"], ["macOS", "macOS 10.15 (Catalina) 이상", "Apple Silicon / Intel Mac", "앱 번들 (.app)"], ["Linux", "Ubuntu 20.04 LTS x64 이상", "RAM 2GB 이상", "바이너리 실행 파일"] ] ) # ========================================================================= # 제2장 설치 및 초기 실행 # ========================================================================= add_heading_1(doc, "제2장 설치 및 초기 실행") add_heading_2(doc, "2.1 플랫폼별 설치 및 실행 방법") add_bullet_item(doc, " 별도의 복잡한 설치 과정 없이 'SmartFarmHMI.exe' 파일을 원하는 폴더에 복사한 후 더블클릭하여 바로 실행합니다. 최초 실행 시 방화벽 알림이 표시되면 '액세스 허용'을 선택합니다.", bold_prefix="Windows 환경:") add_bullet_item(doc, " 제공된 'SmartFarmHMI.apk' 파일을 기기에 전송한 후 파일 관리자에서 터치하여 설치합니다. ('출처를 알 수 없는 앱 설치 허용' 필요)", bold_prefix="Android 환경:") add_bullet_item(doc, " HMI 프로그램과 MQTT 브로커(게이트웨이) 간 정상적인 데이터 통신을 위해 유선 LAN 또는 동일한 농장 내부 Wi-Fi 망에 접속되어 있어야 합니다.", bold_prefix="네트워크 연결:") add_heading_2(doc, "2.2 화면 레이아웃 및 인터페이스 구성") add_body_p(doc, "스마트팜 HMI는 농장 현장에서 한눈에 상황을 파악하고 터치 조작이 용이하도록 4개 주요 영역으로 구성되어 있습니다.") add_bullet_item(doc, " 현재 활성화된 화면의 제목, 실시간 시스템 시계(yyyy-mm-dd hh:nn:ss), 다국어 전환 버튼(KO/EN), 전체화면 토글 버튼이 배치되어 있습니다.", bold_prefix="1. 상단 헤더 (Header):") add_bullet_item(doc, " 환경 모니터링(Dashboard), 노드 설정, CCTV, 자동운전, 관수제어, 시스템 로그, 네트워크 설정 화면으로 즉시 이동할 수 있는 내비게이션 메뉴입니다.", bold_prefix="2. 좌측 사이드바 (Navigation):") add_bullet_item(doc, " 각 메뉴별 상세 기능(위젯 그리드, 설정 테이블, 룰 편집기, 로그 뷰어 등)이 표시되는 메인 작업 영역입니다.", bold_prefix="3. 중앙 컨텐츠 (Main Content):") add_bullet_item(doc, " MQTT 브로커 통신 상태(녹색: 연결됨 / 주황: 연결중... / 적색: 연결 끊김) 및 자동 운전 전체 활성화 여부가 상시 표시됩니다.", bold_prefix="4. 하단 상태창 (Status Bar):") add_heading_2(doc, "2.3 다국어 및 디스플레이 모드 전환") add_bullet_item(doc, " 상단 헤더 우측의 'KO / EN' 버튼을 누르면 모든 메뉴, 라벨, 팝업, 상태 메시지가 한국어와 영어로 실시간 전환됩니다.", bold_prefix="언어 전환:") add_bullet_item(doc, " 상단 헤더의 전체화면 아이콘을 누르면 윈도우 창 테두리 및 작업표시줄이 숨겨지고 전체화면(Kiosk 모드)으로 전환되어 현장 전용 터치스크린에 최적화됩니다.", bold_prefix="전체화면 모드:") # ========================================================================= # 제3장 주요 기능 및 화면별 운영 가이드 # ========================================================================= add_heading_1(doc, "제3장 주요 기능 및 화면별 운영 가이드") add_heading_2(doc, "3.1 환경 모니터링 대시보드 (Dashboard)") add_body_p(doc, "대시보드는 활성화된 모든 센서의 현재 측정값과 제어 장비의 On/Off 상태를 실시간 카드형 위젯으로 표시합니다.") add_heading_3(doc, "센서 모니터링 위젯") add_body_p(doc, "온도, 습도, CO2, 토양 온습도 등 등록된 센서의 현재 수치, 측정 단위(℃, %, ppm 등), 최대값 대비 비율 게이지(Progress Bar)를 시각적으로 보여줍니다. 데이터 미수신 상태일 때는 '--'로 표시됩니다.") add_heading_3(doc, "장비 수동 제어 위젯") add_body_p(doc, "환기팬, 조명, 개폐기, 관수 밸브 등 디지털 출력(DO) 장비의 스위치를 터치/클릭하여 즉시 켜거나(ON) 끌(OFF) 수 있습니다. 스위치 조작 시 즉시 MQTT 제어 명령이 전송되며, 게이트웨이로부터 최종 수신 확인(피드백) 시 UI 색상이 녹색(ON) 또는 회색(OFF)으로 갱신됩니다.") add_heading_2(doc, "3.2 노드 설정 (Node Settings)") add_body_p(doc, "노드 설정 화면에서는 온실에 실제 설치된 센서 및 제어 장치만을 선택하여 대시보드에 노출하고, 각 장치에 농가 맞춤형 이름을 부여할 수 있습니다.") node_tbl = doc.add_table(rows=1, cols=5) format_table( node_tbl, col_widths=[1.0, 1.2, 1.2, 1.5, 1.6], headers=["노드 타입", "기본 명칭(한)", "기본 명칭(영)", "단위 / 제어형태", "설명 및 용도"], data=[ ["TM", "온도", "Temperature", "℃ (0 ~ 60)", "온실 내부/외부 대기 온도"], ["HM", "습도", "Humidity", "% (0 ~ 100)", "온실 내부 상대 습도"], ["CD", "CO2", "CO2", "ppm (0 ~ 2000)", "온실 내부 이산화탄소 농도"], ["NT", "양액 EC", "EC", "dS/m (0 ~ 10)", "양액 공급기 전기전도도"], ["PH", "양액 pH", "pH", "pH (0 ~ 14)", "양액 산도/수소이온농도"], ["GT / GT2", "토양 온도", "Soil Temp", "℃ (0 ~ 60)", "근권부/토양 1·2 구역 온도"], ["GM", "토양 습도", "Soil Moisture", "% (0 ~ 100)", "토양/배지 수분 함량"], ["GNT", "토양 EC", "Soil EC", "dS/m (0 ~ 10)", "토양/배지 잔존 비료 농도"], ["WP", "토양 pH", "Soil pH", "pH (0 ~ 14)", "토양/배지 산도"], ["AI", "아날로그 입력", "Analog In", "스케일 값", "일사량, 풍속, 수위 센서 등"], ["DI", "디지털 입력", "Digital In", "ON / OFF 접점", "도어센서, 플로트스위치, 유량펄스"], ["DO", "디지털 출력", "Digital Out", "ON / OFF 릴레이", "모터, 밸브, 펌프, 조명 구동기"] ] ) add_body_p(doc, "노드 설정 조작 방법:") add_bullet_item(doc, " 사용 토글 스위치: 해당 노드를 대시보드 및 제어 대상에 포함할지 여부를 설정합니다.", bold_prefix="1)") add_bullet_item(doc, " 사용자 정의 이름 입력: '1동 온실 온도', 'A구역 급수밸브' 등 직관적인 명칭을 입력 후 포커스를 이동하면 즉시 저장됩니다.", bold_prefix="2)") add_bullet_item(doc, " 맞춤형 아이콘 선택: 드롭다운에서 장치에 어울리는 대표 아이콘을 지정할 수 있습니다.", bold_prefix="3)") add_heading_2(doc, "3.3 자동 운전 제어 (Auto Control)") add_body_p(doc, "자동 운전 기능은 센서 계측값과 시간 조건에 따라 사람이 개입하지 않고도 자동으로 장비를 가동·정지시키는 지능형 룰 엔진입니다.") add_bullet_item(doc, " 사이드바 좌측 하단의 '자동 운전' 토글 버튼을 켜면 등록된 모든 활성 룰이 주기적으로 평가되어 자동 제어가 수행됩니다.", bold_prefix="마스터 활성화:") add_bullet_item(doc, " 규칙 추가 버튼을 눌러 새 룰을 생성하고 규칙명, 대상 DO 채널, 목표 상태(ON/OFF)를 지정합니다.", bold_prefix="룰 생성:") add_bullet_item(doc, " 시작 시각(시:분)과 종료 시각(시:분)을 설정합니다. 종료 시각이 시작 시각보다 이른 경우(예: 20:00 ~ 06:00) 야간 자정 넘김 시간대로 자동 처리됩니다.", bold_prefix="작동 시간대 설정:") add_bullet_item(doc, " 온도 28℃ 초과(>), 습도 80% 미만(<), 접점 ON 등 복수의 조건을 등록할 수 있으며, 결합 모드(AND: 모든 조건 충족 / OR: 하나라도 충족)를 지정할 수 있습니다.", bold_prefix="복합 조건식 (Conditions):") add_bullet_item(doc, " 작동 시간(분)과 휴식 시간(분)을 입력하면, 조건이 충족된 동안 장비가 지속 작동하는 대신 설정된 주기대로 On/Off를 반복하여 과열이나 과습을 방지합니다.", bold_prefix="스케줄 반복 제어:") add_heading_2(doc, "3.4 순차 관수 제어 (Irrigation Control)") add_body_p(doc, "순차 관수 모듈은 농장의 여러 관수 구역(전자밸브 DO)을 정해진 순서와 조건에 맞추어 체계적으로 급수하는 전문 관수 스케줄러입니다.") add_bullet_item(doc, " 스케줄 명칭, 유효 실행 기간(시작일~종료일), 시작 시간(시:분), 반복 주기(1: 매일, 2: 격일 등)를 설정합니다.", bold_prefix="스케줄 기본 설정:") add_bullet_item(doc, " 자동 시작(시간 도달 시 즉시 관수 시작) 또는 수동 승인(시간 도달 시 사용자 확인 알림 팝업 후 승인 시 관수 시작) 모드를 선택합니다.", bold_prefix="시작 모드:") add_bullet_item(doc, " 구역 1 -> 구역 2 -> 구역 3 순서대로 동작할 구역별 액션(Action)을 추가합니다.", bold_prefix="순차 구역 액션 구성:") add_bullet_item(doc, " 특정 구역 시작 조건, 1회 급수 후 다음 재가동까지의 쿨다운 대기 시간(분), 최대 급수 제한시간(Timeout)을 독립 설정할 수 있습니다.", bold_prefix="구역별 세부 조건:") add_bullet_item(doc, " 유량 센서(DI 펄스)와 연동하여 펄스당 리터(L) 또는 Kg 단위의 목표 유량이 공급되면 자동으로 밸브를 차단하도록 설정할 수 있습니다.", bold_prefix="유량 기반 관수 제어:") add_heading_2(doc, "3.5 CCTV / 영상 모니터링") add_body_p(doc, "온실 내부 및 주변에 설치된 네트워크 IP 카메라의 실시간 영상을 조회할 수 있습니다.") add_bullet_item(doc, " 'CCTV 설정' 메뉴에서 RTSP 스트림 주소(예: rtsp://admin:pass@192.168.1.50:554/stream1) 및 카메라 이름을 등록합니다.", bold_prefix="카메라 등록:") add_bullet_item(doc, " Windows 및 Android 환경에서는 전용 고성능 비디오 플레이어 앱과 원터치 연동되어 딜레이 없는 고화질 스트리밍을 제공합니다.", bold_prefix="영상 재생:") add_heading_2(doc, "3.6 네트워크 및 MQTT 통신 설정") add_body_p(doc, "사이드바 하단의 '설정' 아이콘을 더블클릭하거나 설정 팝업을 열어 통신 파라미터를 구성합니다.") mqtt_tbl = doc.add_table(rows=1, cols=3) format_table( mqtt_tbl, col_widths=[1.8, 1.8, 2.9], headers=["항목명", "기본값 예시", "설정 설명 및 주의사항"], data=[ ["GateWay ID", "GW_0001", "현장 IoT 게이트웨이의 고유 식별자 ID"], ["Broker IP", "192.168.0.100", "MQTT 브로커 서버의 IP 주소 또는 도메인"], ["Broker PORT", "1883", "MQTT 표준 통신 포트 (기본: 1883)"], ["User ID / Password", "admin / 1234", "브로커 접근 인증 계정 정보 (미사용 시 공란)"], ["Topic HEAD", "SFARM/", "토픽 최상위 접두어 (조직/농장 구분자)"], ["Topic TAIL", "NODE/", "토픽 세부 구분자"] ] ) add_callout(doc, "설정 변경 후 '저장/닫기' 버튼을 누르면 백그라운드에서 기존 MQTT 연결을 안전하게 해제한 후 새 파라미터로 즉시 재접속을 시도합니다.", title="통신 설정 변경 시 유의사항") # ========================================================================= # 제4장 로그 시스템 및 데이터 관리 # ========================================================================= add_heading_1(doc, "제4장 로그 시스템 및 데이터 관리") add_heading_2(doc, "4.1 분리형 로그 관리 체계") add_body_p(doc, "스마트팜 HMI는 대량으로 유입되는 센서 데이터와 중요한 장비 제어 이력, 시스템 오류가 서로 뒤섞이지 않도록 4개의 독립된 카테고리 폴더와 일자별 파일로 분리하여 저장합니다.") log_tbl = doc.add_table(rows=1, cols=4) format_table( log_tbl, col_widths=[1.2, 1.8, 1.8, 1.7], headers=["로그 유형", "저장 하위 폴더", "생성 파일명 형식", "주요 기록 내용"], data=[ ["Sensor (센서)", "SmartFarmHMI_Logs/Sensor/", "Sensor_YYYYMMDD.log", "MQTT 실시간 수신 센서값, DI 접점 수신 데이터 전량"], ["Control (제어)", "SmartFarmHMI_Logs/Control/", "Control_YYYYMMDD.log", "운영자 수동 제어, 자동 룰 구동기(DO) On/Off 명령 및 피드백"], ["System (시스템)", "SmartFarmHMI_Logs/System/", "System_YYYYMMDD.log", "프로그램 시작/종료, MQTT 연결/재연결, 노드 설정 변경 이력"], ["Error (오류)", "SmartFarmHMI_Logs/Error/", "Error_YYYYMMDD.log", "네트워크 단절, 패킷 파싱 오류, 예외 발생 내역"] ] ) add_heading_2(doc, "4.2 플랫폼별 실제 저장 경로") add_body_p(doc, "각 운영체제의 표준 보안 샌드박스 및 전용 저장 경로에 안전하게 보관됩니다:") path_tbl = doc.add_table(rows=1, cols=2) format_table( path_tbl, col_widths=[1.8, 4.7], headers=["플랫폼", "실제 로그 저장 절대 경로"], data=[ ["Windows PC", "C:\\Users\\[사용자명]\\AppData\\Roaming\\SmartFarmHMI_Logs\\"], ["Android", "/data/data/[앱 패키지명]/files/SmartFarmHMI_Logs/ (내부 저장소)"], ["macOS", "/Users/[사용자명]/Library/Application Support/SmartFarmHMI_Logs/"], ["iOS", "[앱 샌드박스 홈]/Documents/SmartFarmHMI_Logs/"], ["Linux", "/home/[사용자명]/.config/SmartFarmHMI_Logs/"] ] ) add_heading_2(doc, "4.3 화면 로그 뷰어 및 백업 요령") add_bullet_item(doc, " 사이드바의 '로그(Logs)' 메뉴를 클릭하면 일자별/유형별 로그를 화면에서 즉시 조회할 수 있으며, '새로고침' 버튼으로 최신 내역을 동기화합니다.", bold_prefix="화면 조회:") add_bullet_item(doc, " 텍스트 형식(UTF-8)으로 저장되므로 엑셀(Excel)이나 메모장으로 직접 열어 데이터 분석 및 보고서 작성에 활용할 수 있습니다.", bold_prefix="데이터 백업:") # ========================================================================= # 제5장 장애 진단 및 문제 해결 (Troubleshooting) # ========================================================================= add_heading_1(doc, "제5장 장애 진단 및 문제 해결 (FAQ)") faq_tbl = doc.add_table(rows=1, cols=3) format_table( faq_tbl, col_widths=[1.8, 2.2, 2.5], headers=["현상 / 문제점", "예상 원인", "점검 및 해결 절차"], data=[ ["상태창이 '연결중...'에 머무르고 센서값이 갱신되지 않음", "1. 브로커 IP/포트 오입력\n2. 게이트웨이 전원 꺼짐\n3. 방화벽 차단", "1. 설정 팝업에서 브로커 IP 및 1883 포트 확인\n2. 게이트웨이 전원 및 LAN 케이블 확인\n3. PC 방화벽에서 포트 개방"], ["스위치를 조작해도 실제 장비가 작동하지 않음", "1. DO 채널 번호 불일치\n2. 게이트웨이 릴레이 제어 배선 불량", "1. 노드 설정에서 대상 DO 번호 재확인\n2. Control 로그 파일에서 전송 성공 여부 확인\n3. 현장 릴레이 보드 수동 스위치 점검"], ["자동 운전 룰이 시간에 맞춰 실행되지 않음", "1. 자동 운전 마스터 스위치 OFF\n2. 룰 개별 활성화 OFF\n3. HMI 단말 시계 오류", "1. 좌측 하단 '자동 운전' 버튼이 녹색인지 확인\n2. 룰 목록에서 체크박스 활성화 확인\n3. 시스템 날짜 및 시간 동기화 확인"], ["특정 센서값만 '--'로 표시됨", "1. 해당 노드가 '미사용' 상태\n2. 센서 결선 불량 또는 고장", "1. 노드 설정에서 해당 센서 InUse 토글 확인\n2. 게이트웨이의 센서 Modbus 통신 LED 확인"] ] ) doc.save(r"c:\Users\MyName\Desktop\SmartFarmHMI_SOURCE\docs\SmartFarmHMI_운영매뉴얼.docx") print("Operation manual generated successfully.") if __name__ == "__main__": create_operation_manual()