ENIG/Cs_HMI/README.md

ENIG AGV Control System Documentation

개요

이 문서는 ENIG AGV (Automated Guided Vehicle) 제어 소프트웨어의 동작 및 기능에 대한 기술 문서입니다. 본 시스템은 C# 기반의 상태 머신(State Machine) 아키텍처를 사용하여 AGV의 주행, 충전, 자재 이송 등의 작업을 제어합니다.

참고: 현재 기능 개발이 진행 중이며, 일부 시퀀스는 변경될 수 있습니다.

핵심 기능 (Core Functionality)

1. 대기 및 준비 (IDLE / READY)

• 상태 파일: _SM_RUN_READY.cs
• 기능:
  • AGV가 작업을 수행하지 않을 때의 기본 상태입니다.
  • 자동 충전 모니터링: 배터리 레벨을 지속적으로 확인하여 설정된 임계값 이하로 떨어지거나, 유휴 시간이 길어지면 자동으로 충전 시퀀스로 전환합니다.
  • 충전 완료 체크: 충전 중일 경우 최대 충전 시간 또는 목표 전압에 도달하면 충전을 중단하고 대기 상태로 복귀합니다.
  • 정차 유지: 대기 모드에서 AGV가 움직이지 않도록 지속적으로 정지 명령을 수행합니다.

2. 목적지 이동 (GOTO)

• 상태 파일: _SM_RUN_GOTO.cs
• 기능:
  • 지정된 RFID 태그(노드)로 이동하는 주행 로직입니다.
  • 경로 예측 (Prediction): 현재 위치에서 목적지까지의 경로를 계산하고, 필요한 회전(Turn)이나 분기 동작을 결정합니다.
  • 속도 제어: 직선 구간, 코너, 정지 전 감속 등 상황에 맞춰 속도(High, Mid, Low)를 조절합니다.
  • 장애물 감지: 주행 중 전방 장애물이 감지되면 즉시 정지하거나 감속합니다.

3. 충전 시퀀스 (CHARGE)

• 상태 파일: _SM_RUN_GOCHARGE.cs, _SM_RUN_GOCHARGECHECK.cs
• 기능:
  • 충전기 이동: 충전 스테이션의 RFID 위치를 찾아 이동합니다.
  • 정밀 도킹: 충전기 앞에서 정밀하게 위치를 조정하여 도킹합니다.
  • 충전 시작/종료: BMS(Battery Management System)와 통신하여 충전을 시작하고 상태를 모니터링합니다.

특수 시퀀스 (Special Sequences)

버퍼(Buffer) 스테이션에서의 자재 로딩/언로딩을 위한 특수 동작 시퀀스입니다.

1. 버퍼 진입 (BUFFER IN)

• 상태 파일: _SM_RUN_BUFFER_IN.cs
• 동작 순서:
  1. 진입 전 확인: 하드웨어 상태 및 위치 확인.
  2. 회전 (Turn): 버퍼 진입을 위해 필요한 각도로 회전 (주로 180도 턴).
  3. 리프트 다운 (Lift Down): 자재 적재를 위해 리프트를 하강 (코드상 확인 필요).
  4. 후진 진입: 저속으로 후진하여 버퍼 스테이션에 진입.
  5. 마크 감지 정지: 정지 마크를 감지하여 정확한 위치에 정차.

2. 버퍼 이탈 (BUFFER OUT)

• 상태 파일: _SM_RUN_BUFFER_OUT.cs
• 동작 순서:
  1. 전진 이동: 저속으로 전진하여 버퍼 스테이션을 빠져나옵니다.
  2. 마크 스톱: 이탈 완료 지점의 마크를 감지하여 정지합니다.
  3. 회전 (Turn): 주행 방향으로 복귀하기 위해 우측 180도 회전을 수행합니다.

3. 동기화 (SYNC)

• 상태 파일: _SM_RUN_SYNC.cs
• 기능:
  • 프로그램 시작 시 또는 연결 복구 시 AGV 하드웨어와 소프트웨어 간의 설정을 동기화합니다.
  • 속도 PID 제어값, 주행 파라미터 등을 장비로 전송하고 확인(ACK) 받습니다.
  • UI 표시: 동기화 진행률을 화면에 표시하여 사용자가 상태를 알 수 있게 합니다.

안전 기능 (Safety Features)

• 장애물 감지: LiDAR 또는 센서를 통해 전방 물체 감지 시 음성 안내("전방에 물체가 감지되었습니다")와 함께 정지.
• 통신 타임아웃: 하드웨어(AGV, BMS, XBee)와의 통신이 끊기면 에러 상태로 전환하거나 재연결을 시도.
• 비상 정지: 소프트웨어적 비상 정지 및 하드웨어 E-Stop 상태 감지.

개발 상태

• 현재 기본 주행 및 충전 기능은 구현되어 있으나, 버퍼 시퀀스 및 예외 처리에 대한 고도화 작업이 진행 중입니다.
• 맵 에디터(UnifiedAGVCanvas)와 연동하여 실시간 모니터링 및 시뮬레이션 기능을 강화하고 있습니다.

---

기존 CLAUDE.md 내용 (참고용)

이 파일은 이 저장소의 코드로 작업할 때 Claude Code (claude.ai/code)를 위한 지침을 제공합니다. 맵데이터는 C:\Data\Source(5613#) ENIG AGV\Source\Cs_HMI\Data\NewMap.agvmap 파일을 기준으로 사용

빌드 및 개발 명령어

프로젝트 빌드 및 실행

• 메인 빌드: build.bat 파일 참고
• **빌드후 이벤트 예제) rem xcopy "$(TargetDir)*.exe" "\192.168.1.80\Amkor\AGV2" /Y

프로젝트 구조 및 빌드 설정

• 메인 애플리케이션: Project/AGV4.csproj - "Amkor"라는 실행 파일명으로 컴파일
• 타겟 플랫폼: .NET Framework 4.8, x86/x64 아키텍처
• 출력 경로:
  • Debug: ..\..\..\..\..\Amkor\AGV4\
  • Release: ..\..\..\ManualMapEditor\

고수준 코드 아키텍처

솔루션 구조

이 프로젝트는 ENIG AGV (자동 유도 차량) 시스템을 위한 C# HMI (Human-Machine Interface) 애플리케이션입니다.

AGVCSharp.sln (메인 솔루션)
├── Project/AGV4.csproj (메인 HMI 애플리케이션)
├── StateMachine/ (상태 머신 라이브러리)
├── AGVMapEditor/ (맵 에디터 - 2024.09 추가)
├── AGVSimulator/ (AGV 시뮬레이터 - 2024.09 추가)
└── SubProject/ (서브 프로젝트 모듈들)
    ├── AGVControl/ (AGV 제어)
    ├── BMS/ (배터리 관리 시스템)
    ├── NARUMI/ (AGV 하드웨어)
    ├── CommData/ (통신 데이터)
    ├── ENIGProtocol/ (ENIG 프로토콜)
    └── 기타 모듈들

메인 애플리케이션 아키텍처 (Project/)

핵심 폼 구조

• fMain.cs: 메인 UI 폼 - AGV 시스템의 중앙 제어판
• fSetup.cs: 설정 화면 - 시스템 파라미터 및 구성
• ViewForm/: 각종 모니터링 화면들
  • fAuto.cs - 자동 모드 화면
  • fManual.cs - 수동 모드 화면
  • fAgv.cs - AGV 상태 화면
  • fBms.cs - 배터리 상태 화면
  • fIO.cs - I/O 상태 화면

상태 머신 시스템 (StateMachine/)

AGV의 동작을 제어하는 상태 기반 시스템:

• _Loop.cs: 메인 상태 머신 루프
• _AGV.cs: AGV 제어 로직
• _BMS.cs: 배터리 관리 상태
• _SPS.cs: SPS(Stored Program Sequencer) 제어
• Step/: 각 상태별 구현 클래스들
  • _SM_RUN_*.cs - 실행 상태들 (INIT, READY, GOTO, CHARGE 등)

핵심 클래스들

• PUB.cs: 전역 변수 및 공통 함수
• CSetting.cs: 설정 데이터 관리
• Manager/DataBaseManager.cs: 데이터베이스 관리
• Device/: 하드웨어 인터페이스 클래스들

통신 및 프로토콜

• XBee 무선 통신: call button 및 충전기 통신
• ENIG Protocol: 자체 정의 프로토콜
• Socket 통신: 네트워크 기반 데이터 교환
• Database: 운영 데이터 저장 및 관리

의존성 및 라이브러리

• arCommUtil: AR 통신 유틸리티
• arControl.Net4: AR 제어 라이브러리
• Newtonsoft.Json: JSON 데이터 처리
• Microsoft.Speech: 음성 처리
• System.Management: 시스템 관리

빌드 후 처리

프로젝트는 빌드 후 네트워크 위치로 파일을 자동 복사하는 설정이 있습니다 (현재 주석 처리됨).

Git 업데이트

SubProject 내의 GitUpdate.bat을 사용하여 모든 하위 프로젝트를 일괄 업데이트할 수 있습니다.

새로 추가된 AGV 개발 도구 (2024.09)

AGVMapEditor (맵 에디터)

위치: AGVMapEditor/AGVMapEditor.csproj
실행파일: AGVMapEditor/bin/Debug/AGVMapEditor.exe

핵심 기능

• 맵 노드 관리: 논리적 노드 생성, 연결, 속성 설정
• RFID 매핑 분리: 물리적 RFID ID ↔ 논리적 노드 ID 매핑 관리
• 시각적 맵 편집: 드래그앤드롭으로 노드 배치 및 연결
• JSON 파일 저장: 맵 데이터를 JSON 형식으로 저장/로드

핵심 클래스

• MapNode: 논리적 맵 노드 (NodeId, 위치, 타입, 연결 정보)
• RfidMapping: RFID 물리적 ID ↔ 논리적 노드 매핑
• NodeResolver: RFID ID를 통한 노드 해석기
• PathCalculator: A* 알고리즘 기반 AGV 경로 계산
• MapCanvas: 시각적 맵 편집 컨트롤

AGV 특화 제약사항

• 방향성 제약: 전진/후진, 회전은 마크센서 위치에서만 가능
• 도킹 제약: 충전기(전진 도킹), 장비(후진 도킹)
• RFID 기반 네비게이션: 물리적 RFID와 논리적 의미 분리

AGVSimulator (AGV 시뮬레이터)

위치: AGVSimulator/AGVSimulator.csproj
실행파일: AGVSimulator/bin/Debug/AGVSimulator.exe

핵심 기능

• 가상 AGV 시뮬레이션: 실시간 AGV 움직임 및 상태 관리
• 맵 시각화: 맵 에디터에서 생성한 맵 파일 로드 및 표시
• 경로 실행: 계산된 경로를 따라 AGV 시뮬레이션
• 상태 모니터링: AGV 상태, 위치, 배터리 등 실시간 모니터링

핵심 클래스

• VirtualAGV: 가상 AGV 동작 시뮬레이션 (이동, 회전, 도킹, 충전)
• SimulatorCanvas: AGV 및 맵 시각화 캔버스
• SimulatorForm: 시뮬레이터 메인 인터페이스
• SimulationState: 시뮬레이션 상태 관리

AGV 상태

• Idle: 대기, Moving: 이동 중, Rotating: 회전 중
• Docking: 도킹 중, Charging: 충전 중, Error: 오류

개발 워크플로우

1. 맵 생성: AGVMapEditor로 맵 노드 배치 및 RFID 매핑 설정
2. 경로 테스트: AGVSimulator로 AGV 동작 시뮬레이션 및 검증
3. 실제 적용: 검증된 맵 데이터를 실제 AGV 시스템에 적용

RFID 매핑 아키텍처 원칙

중요: 물리적 RFID ID는 의미없는 고유값으로 관리하고, 논리적 노드 ID와 별도 매핑 테이블로 분리하여 현장 유지보수성 향상

AGV 방향 제어 및 도킹 시스템 (2024.12.16)

🔄 AGV 방향 체계 및 하드웨어 구조

하드웨어 레이아웃

LIFT --- AGV --- MONITOR
  ↑       ↑        ↑
후진시   AGV본체   전진시
도달위치          도달위치

모터 방향과 이동 방향

• 전진 모터 (Forward): AGV가 모니터 방향으로 이동 (→)
• 후진 모터 (Backward): AGV가 리프트 방향으로 이동 (←)

도킹 방향 규칙

• 충전기 (Charging): 전진 도킹 (Forward) - 모니터가 충전기 면
• 장비 (Docking): 후진 도킹 (Backward) - 리프트가 장비 면

🧭 방향 계산 핵심 파일 및 함수

1. 리프트 방향 계산

파일: AGVNavigationCore\Utils\LiftCalculator.cs

• 핵심 메서드: CalculateLiftAngleRadians(Point currentPos, Point targetPos, AgvDirection motorDirection)
• 수정된 로직 (2024.12.16):

  // 후진 모터: 현재→목표 벡터 (리프트가 이동 방향 향함)
  var dx = currentPos.X - targetPos.X;
  var dy = currentPos.Y - targetPos.Y;
  

2. 도킹 방향 결정

파일: AGVNavigationCore\PathFinding\DirectionChangePlanner.cs

• 핵심 메서드: GetRequiredDockingDirection(string targetNodeId)
• 로직:

  case NodeType.Charging: return AgvDirection.Forward;  // 충전기
  case NodeType.Docking: return AgvDirection.Backward;  // 장비
  

3. 경로 계산 시 방향 고려

파일: AGVNavigationCore\PathFinding\AdvancedAGVPathfinder.cs

• 핵심 메서드: FindAdvancedPath(string startNodeId, string targetNodeId, AgvDirection currentDirection)
• 로직:

  var requiredDirection = _directionChangePlanner.GetRequiredDockingDirection(targetNodeId);
  bool needDirectionChange = (currentDirection != requiredDirection);
  

⚠️ 현재 발견된 문제점 (2024.12.16)

문제 상황

AGV가 후진 상태로 006 → 005 → 004 이동 중, 037(버퍼)에 도킹 필요한 상황에서:

• 기대: 006 → 005 → 037 (후진 직진 도킹)
• 실제: 006 → ... → 041 → 037 (전진으로 잘못 계산)

문제 원인 분석

1. 도킹 방향 계산: 037은 NodeType.Docking이므로 후진 도킹 필요 ✅
2. 현재 방향: AGV가 후진(Backward) 상태 ✅
3. 경로 계산 오류: 알고리즘이 현재 후진 상태를 제대로 고려하지 못함 ❌

필요한 수정사항

1. 경로 검증 시스템: 계산된 경로의 마지막 도킹 방향이 올바른지 검증
2. UI 피드백: 잘못된 도킹 방향 시 목적지 노드에 X 표시
3. 알고리즘 개선: 현재 방향을 유지하며 직진 가능한 경로 우선 탐색

🎯 향후 구현 계획

1. 도킹 방향 검증 시스템 구현
2. UI 시각적 피드백 (X 표시) 추가
3. 경로 계산 알고리즘 개선
4. 통합 테스트 및 검증

AGV 방향 계산 관련 주요 파일 및 함수 (Legacy)

핵심 방향 계산 함수들

1. LiftCalculator.cs - 리프트 방향 계산

   • CalculateLiftAngleRadians(Point currentPos, Point targetPos, AgvDirection motorDirection) :1022행
   • CalculateLiftInfoWithPathPrediction() :1024행
   • 파일 위치: AGVNavigationCore\Utils\LiftCalculator.cs

2. AGVPathfinder.cs - 모터 방향 결정

   • PlanDirectionChanges(List<string> path) :414행 - 경로별 모터방향 계획
   • GetRequiredDirectionForNode(MapNode node) :280행 - 노드타입별 요구방향
   • 파일 위치: AGVNavigationCore\PathFinding\AGVPathfinder.cs

3. VirtualAGV.cs - 시뮬레이터 AGV 위치/방향 관리

   • SetPosition(Point newPosition) :293행 - ⚠️ TargetPosition 설정 문제 위치
   • 파일 위치: AGVSimulator\Models\VirtualAGV.cs

4. UnifiedAGVCanvas.Events.cs - AGV 시각적 표현

   • DrawAGVLiftAdvanced(Graphics g, IAGV agv) :1011행 - 리프트 그리기
   • 파일 위치: AGVNavigationCore\Controls\UnifiedAGVCanvas.Events.cs

📋 변경 내역

최신 패치 및 개발 내역은 CHANGELOG.md 파일을 참조하세요.

• 최근 업데이트: 2024.12.16 - AGV 방향 표시 수정 및 타겟계산 기능 추가

개발시 주의사항

• 메인 애플리케이션은 Windows .NetFramework Forms 기반의 터치 인터페이스로 설계됨
• 실시간 AGV 제어 시스템이므로 상태 머신 로직 수정시 신중히 접근
• 통신 관련 코드 변경시 하드웨어 호환성 고려 필요
• 맵 에디터/시뮬레이터: AGVMapEditor 프로젝트에 의존성이 있으므로 먼저 빌드 필요
• JSON 파일 형식: 맵 데이터는 MapNodes, RfidMappings 두 섹션으로 구성

최근 구현 완료 기능 및 중요사항 (2024.12.09)

✅ 회전 구간 회피 기능 (PathFinding)

파일: AGVNavigationCore/PathFinding/PathfindingOptions.cs (신규)

• 목적: AGV 회전 오류를 피하기 위한 선택적 회전 구간 회피
• 구현: PathfindingOptions 클래스로 회전 회피 설정 관리
• UI: AGVSimulator에 "회전 구간 회피" 체크박스 추가
• 알고리즘: A* 경로탐색에서 회전 노드 가중치 증가 또는 필터링

✅ 맵 에디터 마우스 좌표 오차 수정

파일: AGVNavigationCore/Controls/UnifiedAGVCanvas.Mouse.cs

• 문제: 줌 인/아웃 시 노드 선택 히트 영역이 너무 작아짐
• 해결: 최소 화면 히트 영역(20픽셀) 보장으로 정확한 노드 선택 가능
• 적용: 원형, 5각형, 삼각형 모든 노드 타입 히트 감지 개선

✅ 노드 연결 관리 시스템 (신규 구현)

파일들:

• AGVMapEditor/Forms/MainForm.cs - UI 및 이벤트 처리
• AGVNavigationCore/Controls/UnifiedAGVCanvas.cs - 편집 모드 및 이벤트 정의
• AGVNavigationCore/Controls/UnifiedAGVCanvas.Mouse.cs - 마우스 연결 삭제 기능

주요 기능:

1. 노드 연결 목록 표시: lstNodeConnection 리스트박스에 모든 연결 정보 표시
2. 버튼 연결 삭제: btNodeRemove 버튼으로 선택된 연결 삭제
3. 더블클릭 연결 삭제: 목록에서 더블클릭으로 빠른 삭제
4. 마우스 직접 삭제: 맵에서 연결선 클릭으로 직접 삭제

핵심 클래스:

• NodeConnectionInfo: 연결 정보 표현 클래스 (From/To 노드, 연결 타입)
• EditMode.DeleteConnection: 새로운 편집 모드 추가
• ConnectionDeleted 이벤트: 연결 삭제 시 발생하는 이벤트

🔧 빌드 환경 이슈

• Visual Studio 2022: MSBuild 경로 문제로 빌드 실패
• 권장: Visual Studio Community/Professional 2022 설치 필요
• 대안: 기존 빌드된 실행파일로 테스트 가능

📋 개발 우선순위 및 권장사항

꼭 지켜야 할 사항:

1. PathFinding 로직 변경시: 반드시 시뮬레이터에서 테스트 후 적용
2. 노드 연결 관리: 물리적 RFID와 논리적 노드 ID 분리 원칙 유지
3. UI 편집 모드: 동시에 여러 편집 모드 활성화하지 않도록 주의
4. 이벤트 처리: MapChanged, NodeAdded/Deleted, ConnectionDeleted 이벤트 체인 확인

다음 개발 우선순위:

1. 방향 전환 기능: AGV 현재 방향과 목표 방향 불일치 시 회전 노드 경유 로직
2. 맵 검증 기능: 연결 무결성, 고립된 노드, 순환 경로 등 검증
3. 성능 최적화: 대형 맵에서 경로 계산 및 연결 목록 표시 성능 개선
4. 실시간 동기화: 맵 에디터와 시뮬레이터 간 실시간 맵 동기화

중요 개발 패턴:

• 이벤트 기반 아키텍처: UI 업데이트는 이벤트를 통해 자동화
• 상태 관리: _hasChanges 플래그로 변경사항 추적
• 에러 처리: 사용자 확인 다이얼로그와 상태바 메시지 활용
• 코드 재사용: UnifiedAGVCanvas를 맵에디터와 시뮬레이터에서 공통 사용

AGVNavigationCore 프로젝트 구조 (함수 및 클래스 배치 가이드)

📁 AGVNavigationCore 폴더 구조

AGVNavigationCore/
├── Controls/           # UI 컨트롤 및 캔버스
├── Models/            # 데이터 모델 및 Enum 정의
├── Utils/             # 유틸리티 클래스
└── PathFinding/       # 경로 탐색 관련 모든 기능
    ├── Analysis/      # 경로 분석 관련 클래스
    ├── Core/          # 핵심 경로 탐색 알고리즘
    ├── Planning/      # 경로 계획 및 방향 변경 로직
    └── Validation/    # 검증 관련 클래스 (DockingValidationResult, PathValidationResult 등)

🎯 클래스 배치 원칙

PathFinding/Validation/

• 검증 결과 클래스: *ValidationResult.cs 패턴 사용
• 검증 로직: 결과를 반환하는 검증 메서드 포함
• 네임스페이스: AGVNavigationCore.PathFinding.Validation
• 패턴: 정적 팩토리 메서드 (CreateValid, CreateInvalid, CreateNotRequired)
• 속성: IsValid, ValidationError, 관련 상세 정보

PathFinding/Planning/

• 경로 계획 클래스: 실제 경로 탐색 및 계획 로직
• 방향 변경 로직: DirectionChangePlanner.cs 등
• 경로 최적화: 경로 생성과 관련된 전략 패턴

PathFinding/Core/

• 핵심 알고리즘: A* 알고리즘 등 기본 경로 탐색
• 기본 경로 탐색: 단순한 점-to-점 경로 계산

PathFinding/Analysis/

• 경로 분석: 생성된 경로의 품질 및 특성 분석
• 성능 분석: 경로 효율성 및 최적화 분석

📋 새 클래스 생성 시 체크리스트

1. 기능별 분류: 검증(Validation), 계획(Planning), 분석(Analysis), 핵심(Core)
2. 네임스페이스 일치: 폴더 구조와 네임스페이스 일치 확인
3. 명명 규칙: 기능을 명확히 나타내는 클래스명 사용
4. 의존성: 순환 참조 방지 및 계층적 의존성 유지
5. 테스트 가능성: 단위 테스트가 가능한 구조로 설계

🚨 알려진 이슈

• 빌드 환경: MSBuild 2022가 설치되지 않은 환경에서 빌드 불가
• 좌표 시스템: 줌/팬 상태에서 좌표 변환 정확성 지속 모니터링 필요