# 팔레타이징 로봇 프로그램 변경 내역서 (인수인계용)

- **대상 설비**: 책 재단기 라인 팔레타이징 로봇 (JAKA) 제어 프로그램
- **작업일**: 2026-08-07
- **작업 목적**: ① 사이클 중 불필요한 대기 제거로 택타임 단축 ② 유지보수를 위한 전체 주석·문서화
- **변경 파일**: api_routes.py(로봇 제어 전체), app.py(진입점 정리), app.spec(빌드 설정), .gitignore
- **중요**: 로봇의 이동 경로·좌표·속도 파라미터는 일절 변경하지 않았음. 대기시간(sleep)과
  소프트웨어 구조만 변경. **현장 실기 테스트는 미완료 상태이므로 적용 전 반드시 시운전 필요.**

---

## 1. 원본 코드 및 변경분 위치

| 구분 | 위치 |
|---|---|
| 원본(현장에서 받아온 코드) | git `main` 브랜치 / 로컬 `_backup/` 폴더 |
| 이번 변경분 | git `feature/tact-time-optimization` 브랜치 |
| 저장소 | https://backend-dev.podosee.com/palletizing_corever/palletizing.git |
| 전체 차이 확인 | `git diff main feature/tact-time-optimization` |

---

## 2. 대기시간 조정 — 택타임 단축 (책 1권당 약 2.5~3초 단축 예상)

모든 대기시간은 api_routes.py 상단 **"대기시간 설정 (택타임 튜닝 포인트)" 상수 블록**에
모여 있으며, 문제 발생 시 해당 상수 하나만 주석에 적힌 `[기존값]`으로 되돌리면 된다.

| 항목 | 상수명 | 기존 | 변경 | 비고 |
|---|---|---|---|---|
| 픽업 진입 전 그리퍼 후퇴 대기 | GRIPPER_RETRACT_WAIT | 2.0초 | 0.5초 | 가장 큰 단축 요소 |
| 적재 시 수평 푸셔 유지 대기 | PUSH_HOLD_WAIT | 1.0초 | 0.6초 | |
| 포크 인출 후 푸셔 해제 전 대기 | FORK_EXIT_WAIT | 0.5초 | 0.3초 | |
| 적재 후 수직 그리퍼 해제 대기 | RELEASE_WAIT | 0.3/0.2초 | 0.2초 통일 | 0.2는 짝수층에서 기존 검증값 |
| 모션 도달확인 가드 | IN_POS_GUARD_TIME | 0.1초 | 0.05초 | 1권당 8~10회 호출됨 |
| 스태커 픽업 대기 재확인 주기 | STACKER_BACKOFF | 2.0초 | 0.5초 | 픽업 후 스태커 재개 빨라짐 |

**변경하지 않고 유지한 값** (물리 동작과 직결되어 보수적으로 유지, 추가 튜닝 후보):
파지 대기(홀수층 0.3/짝수층 0.1), 책 흔들림 안정화(0.3), 그리드 진입 저속 파라미터
(grid_speed/grid_acc — 책 미끄러짐 방지 목적), 스태커 실린더 스트로크 대기 4종.

---

## 3. 소프트웨어 구조 개선 (멈칫/지연 원인 제거)

1. **busy-wait 제거**: 메인 루프·도달확인(is_in_pose)·높이탐색 폴링이 대기 간격 없이
   돌면서 CPU를 점유해, 센서값을 갱신하는 상태 폴링 스레드가 밀리던 문제 → 폴링 간격
   (10~20ms) 추가로 센서 반응성 개선.
2. **높이탐색 루프의 매회 print 제거**: 권당 수백 회 콘솔 출력이 있었고, 윈도우 콘솔이
   블록되면(마우스 드래그 등) 로봇 루프 전체가 멈추는 위험이 있었음.
3. **경광등 신호 전송 최적화**: 같은 값을 0.1초마다 3회씩 재전송하던 것을 값이 바뀔
   때만 전송(3초마다 1회 재전송으로 자기복구 유지) → 로봇 컨트롤러 통신 부하 제거.
4. **통신 오류 보호(잠재 결함 수정)**: 도달확인·관절값 수신이 통신 오류일 때 오류값을
   그대로 믿고 진행하던 부분을 정상 수신까지 재시도하도록 수정 (적재 높이 오염 방지).
5. **비상정지 중 통신 폭주 방지**: 정지 상태에서 무한 고속 반복되던 컨트롤러 호출에 대기 추가.

---

## 4. 주석·문서화 (동작과 무관)

- api_routes.py 상단에 시스템 개요, 로봇 I/O 맵(DO0~DO5, DI0~DI3), 스태커 동작 원리
  (하부 적층 방식), 스레드 구조, 진행상태 파일(cache.json/oneLine.json) 설명 추가.
- 전 함수 docstring 및 픽업/적재 시퀀스 단계별 주석 추가.
- 스태커 관련 명칭을 실제 구조(리프터/선반) 기준으로 정정, 오타 수정.
- app.py의 방치된 주석 코드 블록 제거(원본은 git main에 보존).

---

## 5. 실행파일 빌드 방법 (app.spec 상단에도 동일 내용 주석 있음)

```
python -m pip install pyinstaller flask waitress pywebview minimalmodbus pyserial
pyinstaller app.spec
```
- 산출물: `dist\app\팔레타이징.exe` — **dist\app 폴더째** 현장 PC에 복사 후 exe 더블클릭 실행.
- 기존 운영 exe는 Python 3.8 빌드였음. SDK의 jkrc.pyd는 Stable ABI라 파이썬 버전 무관하나,
  pywebview 설치가 최신 파이썬에서 실패하면 Python 3.12로 빌드할 것.
- **현 운영 exe는 변경 전 코드로 빌드된 것이므로, 이번 변경을 현장 반영하려면 재빌드 필수.**

---

## 6. 적용 절차 및 이상 발생 시 조치 (인수자 필독)

1. 재빌드 → dist\app 폴더 교체 → 소량으로 시운전:
   홀수층 1권 → 짝수층(그리퍼 회전) 1권 → 비상정지/해제 복구 → 경광등 3색 확인.
2. 증상별 복원 (api_routes.py 상단 상수 수정만으로 해결):

| 증상 | 조치 |
|---|---|
| 스태커 진입 시 그리퍼 실린더 간섭 | GRIPPER_RETRACT_WAIT 0.5 → 1.0 → 2.0 순서로 복원 |
| 적재 후 포크에 책이 딸려 올라옴 | PUSH_HOLD_WAIT 0.6 → 1.0, FORK_EXIT_WAIT 0.3 → 0.5 |
| 동작이 겹치거나 불안정 | IN_POS_GUARD_TIME 0.05 → 0.1 |
| 픽업 시 책을 놓침 | GRIP_CLAMP_WAIT_ODD/EVEN 값 상향 |

3. 완전 원복: git `main` 브랜치(또는 `_backup/` 원본) 코드로 교체 후 재빌드.
