이 문서는 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: 오류

개발 워크플로우

맵 생성: AGVMapEditor로 맵 노드 배치 및 RFID 매핑 설정
경로 테스트: AGVSimulator로 AGV 동작 시뮬레이션 및 검증
실제 적용: 검증된 맵 데이터를 실제 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 (전진으로 잘못 계산)

문제 원인 분석

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

필요한 수정사항

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

🎯 향후 구현 계획

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

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

핵심 방향 계산 함수들

LiftCalculator.cs - 리프트 방향 계산
- CalculateLiftAngleRadians(Point currentPos, Point targetPos, AgvDirection motorDirection) :1022행
- CalculateLiftInfoWithPathPrediction() :1024행
- 파일 위치: AGVNavigationCore\Utils\LiftCalculator.cs
AGVPathfinder.cs - 모터 방향 결정
- PlanDirectionChanges(List<string> path) :414행 - 경로별 모터방향 계획
- GetRequiredDirectionForNode(MapNode node) :280행 - 노드타입별 요구방향
- 파일 위치: AGVNavigationCore\PathFinding\AGVPathfinder.cs
VirtualAGV.cs - 시뮬레이터 AGV 위치/방향 관리
- SetPosition(Point newPosition) :293행 - ⚠️ TargetPosition 설정 문제 위치
- 파일 위치: AGVSimulator\Models\VirtualAGV.cs
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 - 마우스 연결 삭제 기능

주요 기능:

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

핵심 클래스:

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

🔧 빌드 환경 이슈

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

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

꼭 지켜야 할 사항:

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

다음 개발 우선순위:

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

중요 개발 패턴:

이벤트 기반 아키텍처: 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/

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

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

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

🚨 알려진 이슈

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