From 76ee9a52b6197c4cc6bbb8e0eeb1ff4383ace97f Mon Sep 17 00:00:00 2001 From: junhui324 Date: Fri, 7 Aug 2026 16:46:23 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=9D=B8=EC=88=98=EC=9D=B8=EA=B3=84?= =?UTF-8?q?=EC=9A=A9=20=EB=B3=80=EA=B2=BD=20=EB=82=B4=EC=97=AD=EC=84=9C=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80=20(=EC=9B=90=EB=B3=B8=20=EB=8C=80=EB=B9=84?= =?UTF-8?q?=20=EB=B3=80=EA=B2=BD=20=EC=82=AC=ED=95=AD=20=EC=A0=95=EB=A6=AC?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- 변경내역_20260807.md | 94 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 변경내역_20260807.md diff --git a/변경내역_20260807.md b/변경내역_20260807.md new file mode 100644 index 0000000..60f59e8 --- /dev/null +++ b/변경내역_20260807.md @@ -0,0 +1,94 @@ +# 팔레타이징 로봇 프로그램 변경 내역서 (인수인계용) + +- **대상 설비**: 책 재단기 라인 팔레타이징 로봇 (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/` 원본) 코드로 교체 후 재빌드.