ENIG/Cs_HMI/CLAUDE.md

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를 맵에디터와 시뮬레이터에서 공통 사용

🚨 알려진 이슈

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