# 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):
  ```csharp
  // 후진 모터: 현재→목표 벡터 (리프트가 이동 방향 향함)
  var dx = currentPos.X - targetPos.X;
  var dy = currentPos.Y - targetPos.Y;
  ```

#### 2. 도킹 방향 결정
**파일**: `AGVNavigationCore\PathFinding\DirectionChangePlanner.cs`
- **핵심 메서드**: `GetRequiredDockingDirection(string targetNodeId)`
- **로직**:
  ```csharp
  case NodeType.Charging: return AgvDirection.Forward;  // 충전기
  case NodeType.Docking: return AgvDirection.Backward;  // 장비
  ```

#### 3. 경로 계산 시 방향 고려
**파일**: `AGVNavigationCore\PathFinding\AdvancedAGVPathfinder.cs`
- **핵심 메서드**: `FindAdvancedPath(string startNodeId, string targetNodeId, AgvDirection currentDirection)`
- **로직**:
  ```csharp
  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](./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가 설치되지 않은 환경에서 빌드 불가
- **좌표 시스템**: 줌/팬 상태에서 좌표 변환 정확성 지속 모니터링 필요