Files

junhui324 76ee9a52b6 docs: 인수인계용 변경 내역서 추가 (원본 대비 변경 사항 정리)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-08-07 16:46:23 +09:00

5.5 KiB

Raw Blame History

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

대상 설비: 책 재단기 라인 팔레타이징 로봇 (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. 소프트웨어 구조 개선 (멈칫/지연 원인 제거)

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

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. 적용 절차 및 이상 발생 시 조치 (인수자 필독)

재빌드 → dist\app 폴더 교체 → 소량으로 시운전: 홀수층 1권 → 짝수층(그리퍼 회전) 1권 → 비상정지/해제 복구 → 경광등 3색 확인.
증상별 복원 (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 값 상향

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

5.5 KiB Raw Blame History