# Home Move Sequence 분석 (Home Move Sequence Analysis)

## 1. 개요 (Overview)
이 문서는 AGV의 "Home Move" 기능에 대한 분석 결과를 기술합니다. UI 트리거부터 내부 상태 머신(State Machine) 로직 및 이동 제어 흐름을 포함합니다.

## 2. UI 트리거 (UI Trigger)
*   **버튼 컨트롤**: `btHome` (in `fMain.Designer.cs`)
*   **이벤트 핸들러**: `brHome_Click` (in `fMain.cs`)
*   **동작**:
    *   사용자가 "홈" 버튼 클릭 시 실행됩니다.
    *   **이미 Home 이동 중인 경우**: "홈 이동을 취소 할까요?" 팝업 → 확인 시 `IDLE` 상태로 전환 및 정지 (`AGVMoveStop`).
    *   **대기 상태인 경우**: "홈 이동을 실행 할까요?" 팝업 → 확인 시 `GOHOME` RunStep으로 설정 및 `RUN` 상태 시작.
    *   **조건**: 자동 충전 중이거나 수동 충전 모드가 아니어야 함 (`PUB.CheckManualChargeMode`).

## 3. 상태 머신 로직 (State Machine Logic)
*   **핵심 파일**: `Project\StateMachine\Step\_SM_RUN_GOHOME.cs`
*   **함수**: `_SM_RUN_GOHOME(bool isFirst, TimeSpan stepTime)`
*   **상태 흐름**:

### 초기 검사
1.  **하드웨어 연결**: `PUB.AGV.IsOpen` 체크. 연결 끊김 시 에러 처리.
2.  **충전 상태**: `_SM_RUN_CHGOFF`를 호출하여 충전기가 분리되었는지 확인.
3.  **장애물 감지**: `PUB.AGV.system1.stop_by_front_detect` (Lidar 감지)
    *   감지 시 "전방에 물체가 감지되었습니다" 음성 출력.
    *   **주의**: 이 단계에서 명시적인 소프트웨어 정지 명령(`AGVMoveStop`)은 코드상에 보이지 않으며, 함수가 `false`를 리턴하여 이동 로직 진입을 막습니다. (하드웨어 자체 정지 기능에 의존하는 것으로 추정됨)

### 시퀀스 단계 (Sequence Steps)
상태 머신은 `PUB.sm.RunStepSeq`를 통해 단계별로 진행됩니다.

**단계 1: 이동 준비**
*   음성 안내: "홈으로 이동합니다"
*   **목표 설정**: `PUB.setting.NodeMAP_RFID_Home` 값을 읽어 목표 노드(`TargetNode`)로 설정.
*   에러 처리: 홈 위치 설정이 없는 경우 에러 로그 기록 후 `READY` 상태로 복귀.

**단계 2: 이동 (Moving)**
*   **이동 함수**: `UpdateMotionPositionForMark("funcName")` 호출 (in `_Util.cs`)
*   이 함수가 `true`를 반환할 때까지 반복 호출됨.
*   이동 완료 시 `AGVMoveStop` 호출 후 다음 단계로 진행.

**단계 3: 완료 (Completion)**
*   음성 안내: "홈 검색 완료"
*   로그 기록: 홈 위치 도착 기록.
*   상태 종료: `true` 반환 → 메인 루프에서 `READY` 상태로 전환.

## 4. 이동 제어 상세 (Movement Control Details)
*   **핵심 함수**: `UpdateMotionPositionForMark` (in `Project\StateMachine\Step\_Util.cs`)
*   **경로 계산**: 현재 위치와 목표 노드 간의 경로(`CalcPath`)를 계산.
*   **주행 예측 (Predict)**: `PUB._virtualAGV.Predict()`를 사용하여 다음 동작(직진, 회전, 정지 등)을 결정.
*   **제어 명령**:
    *   `Predict` 결과에 따라 모터(`Forward/Backward`), 분기(Magnetic Guide), 속도를 설정.
    *   변경된 명령이 있을 경우에만 `PUB.AGV.AGVMoveSet`으로 하드웨어에 전송.
    *   AGV가 정지 상태라면 `PUB.AGV.AGVMoveRun`으로 구동 시작.
*   **정지 조건**:
    *   `Predict`가 `Stop` 명령을 반환하고,
    *   위치가 확정(`IsPositionConfirmed`)되었으며,
    *   현재 노드가 목표 노드와 일치하고,
    *   실제 AGV 하드웨어가 정지(`agv_run == false`)한 경우.

## 5. 잠재적 이슈 (Potential Issues)
1.  **장애물 감지 시 정지 처리**:
    *   `_SM_RUN_GOHOME`에서 장애물 감지 시(`stop_by_front_detect`), 음성 출력 후 `return false`만 수행합니다.
    *   이전에 이동 명령이 전송된 상태라면, 소프트웨어에서 명시적으로 `AGVMoveStop`을 보내지 않으므로 AGV가 계속 이동하려 할 수 있습니다. (단, 하드웨어 센서가 직접 모터를 차단하도록 설계되었을 가능성이 높음)
    *   **권장**: 안전을 위해 장애물 감지 루틴 내에서도 명시적으로 `AGVMoveStop`을 호출하는 것을 검토할 필요가 있습니다.

2.  **경로 재생성 시 멈춤**:
    *   `UpdateMotionPositionForMark`에서 경로를 재생성해야 할 경우, `AGVMoveStop("경로재생성")`을 호출하여 일시 정지 후 경로를 다시 계산합니다. 이는 안전한 동작입니다.