문제 해결

증상에서 시작하세요.

증상	먼저 볼 것
Robot Control Setup 에 로봇 목록이 비어 있다	납품 시 설정된 프로필이 보이지 않는 상태 — 지원팀 문의. 화면 설명은 기동 구성
s 를 눌렀는데 스택이 안 뜬다	로봇 스택 기동 §안 뜰 때
로봇이 멈춰서 안 움직인다	아래 §로봇이 멈췄다
웹 화면(:8080)이 안 열린다	아래 §웹 화면이 안 열린다
카메라 영상이 없다	아래 §ZED X Mini 카메라가 잡히지 않는다
터미널의 ros2 topic list 에 로봇이 안 보인다	아래 §ros2 가 로봇을 못 본다
펜던트·Lab 대신 「PLEM 을 사용할 수 없습니다」가 뜬다 · 토큰이 거부된다	아래 §라이선스·토큰 오류
plem 이 ros_domain_id 오류를 보이며 시작하지 않는다	~/.plem/settings.yaml 의 ros_domain_id 를 1–101 정수로 고치거나 그 줄을 지우세요. 화면에 파일 경로와 허용 범위가 나옵니다
그리퍼·카메라 목록이 비어 있다	PLEM 환경이 잡혀 있는지와 로봇 패키지가 설치돼 있는지 확인하세요(필요하면 plem update). 그래도 비면 지원팀에 문의하세요
업데이트한 뒤 동작이 달라졌다	변경 이력 확인 — 되돌리기는 없습니다 (업데이트)

로봇이 멈췄다

TUI 앞이시라면 원인에 따라 순서가 다릅니다. 자세한 설명은 정지와 복구에 있습니다.

• 물리 원인 (비상정지 버튼, 팔을 누르는 외력, 필드버스 이상) — 원인을 먼저 제거한 뒤 R 로 복구를 보내세요. 안전 상태가 정상으로 돌아오면 f 로 프리드라이브에 들어가거나 r 로 궤적 추종으로 돌아갑니다.
• 관절·작업영역 한계 — R 만으로는 풀리지 않습니다. 보호정지 중에도 프리드라이브는 허용되므로 f 로 프리드라이브에 들어가 손으로 팔을 범위 안으로 옮긴 뒤 R 로 해제하세요. 해제 뒤에는 로봇이 프리드라이브(브레이크 열림)에 남아 있으니, 안전 상태가 NORMAL 이고 화면 모드가 FREE 일 때만 f 를 한 번 눌러 브레이크를 거세요. 보호정지가 그대로면 브레이크가 열려 있으니 팔을 더 안쪽으로 옮기고 R 을 다시 누르거나 s 또는 비상정지로 멈추세요.

원인이 남아 있으면 다음 제어 주기에 다시 걸립니다. 물리 원인으로 멈췄다가 오류 표시가 사라졌는데도 로봇이 멈춰 있으면 모드가 BRAKED 로 돌아왔는지 확인한 뒤 목표 모드를 다시 고르세요.

드라이브가 퀵스톱 등으로 멈춘 채 풀리지 않는 경우를 푸는 명령은 이번 릴리스에 없습니다. 스택을 끄기 전에 로봇이 실제로 멈췄는지 직접 확인하세요(정지·안전 §풀리지 않는 드라이브와 정지 보류).

브레이크 해제가 거부되고 로그에 [RT] SLAVE_NOT_OPERATIONAL 이 뜨면, 기동 직후라면 잠시 뒤 다시 해제해 보세요. 계속되면 sudo dmesg | grep -i ethercat 의 내용과 함께 지원팀에 문의하세요.

Teaching Pendant 를 보고 계시다면 하단 로봇 제어 바의 P-STOP 표시 옆 ↻ (P-STOP 복구)가 같은 경로입니다. P-STOP 표시는 상태가 정상이 된 것만으로는 사라지지 않고, ↻ 로 복구해 확인하셔야 사라집니다.

원인 식별과 ROS 2 클라이언트용 계약은 정지·안전에 있습니다.

웹 화면이 안 열린다

순서대로 확인하세요.

1. 스택이 떠 있는지 — Robot Control 에서 s 로 기동한 상태여야 합니다. 웹 화면은 스택과 함께 뜹니다.
2. 구성 요소를 켠 채 기동했는지 — Robot Control Setup 의 Teaching Pendant · Plem Lab (기본값은 둘 다 켜짐). 끈 채로 기동하셨으면 스택을 내리고 켠 뒤 다시 기동하세요.
3. 주소가 맞는지 — Robot Control 에서 i 를 누르면 이 기기의 주소가 나옵니다. 끝 슬래시까지 포함해야 합니다 — /web/, /lab/.

펜던트·Lab 대신 「PLEM 을 사용할 수 없습니다」 페이지가 뜨면 라이선스 문제입니다 — 아래 §라이선스·토큰 오류를 보세요.

셋 다 맞는데 안 열리면 웹 브릿지만 빠진 경우입니다. 기동 로그에 브릿지 관련 경고가 있으면 나머지 스택이 정상이어도 웹 화면만 안 뜹니다. 스택을 내리고 다시 기동하세요.

ZED X Mini 카메라가 잡히지 않는다

이 카메라는 GMSL2 로 연결되며, 기기의 카메라 데몬 상태가 어긋나면 영상이 나오지 않습니다. 로봇 스택을 띄울 때 자동으로 점검과 복구가 돌지만, 수동으로도 확인하실 수 있습니다. 다른 카메라를 쓰신다면 로봇 스택 기동의 실패 신호 표를 보세요.

/usr/share/plem/plem-camera-recover.sh --check   # 판정만 (아무것도 바꾸지 않습니다)
sudo /usr/share/plem/plem-camera-recover.sh      # 필요하면 복구까지

제조사 도구의 "정상" 표시를 근거로 삼지 마세요

카메라 제조사 진단 도구가 장치를 정상으로 보고해도 이 상태를 놓칠 수 있습니다. 판정은 위 스크립트로 하세요.

충돌 회피 구성요소(Isaac ROS)를 설치한 기기에서 영상이 없고 기동 로그에 libgxf_serialization.so: cannot open shared object file 이 있으면, sudo /usr/share/plem/setup-cumotion.sh 를 한 번 실행하세요. plem update 로 업데이트했다면 이미 적용돼 있고, apt 로 직접 업그레이드한 기기에만 필요합니다.

ros2 가 로봇을 못 본다

1. 업데이트한 뒤 처음이라면 새 터미널에서 ros2 daemon stop 을 한 번 실행하세요. 이전 설정을 기억하는 ros2 데몬이 남아 있으면 로봇이 보이지 않습니다.
2. ~/.bashrc 등에 ROS_DOMAIN_ID·CYCLONEDDS_URI·RMW_IMPLEMENTATION 을 export 한 줄이 있으면 지우고 새 터미널을 여세요. 남겨 두면 그 셸의 ros2 만 로봇과 갈라집니다. 도메인은 plem 설정(,)에서 바꿉니다.
3. 설정을 바꿨다면 plem 을 다시 시작한 뒤 새 터미널을 여세요. 그 전에 열어 둔 터미널은 옛 값을 그대로 씁니다. CycloneDDS 설정 파일(네트워크 인터페이스)을 바꿨다면 새 터미널에서 ros2 daemon stop 을 한 번 실행하세요.
4. 다른 PC 에서 보려면 ROS 2 통합 §다른 호스트에서 접속하기대로 /etc/plem/cyclonedds.xml 을 만드세요. 예전의 PLEM_CYCLONEDDS_SYSTEM_DEFAULT 값은 더 이상 읽지 않습니다.

라이선스·토큰 오류

「PLEM 을 사용할 수 없습니다」 페이지. 기기 라이선스가 없거나 만료됐거나 확인할 수 없으면, :8080 의 펜던트·Lab 자리에 이 안내 페이지가 뜨고 서버 기능이 모두 막힙니다. 페이지에 적힌 사유와 조치를 따르세요 — 만료라면 담당자에게 연장을 요청한 뒤 sudo plem-register --refresh 를 실행하고, 그 밖의 사유(다른 기기·검증 실패·손상된 파일 등)는 담당자에게 문의하세요. 라이브러리 누락이나 비정상 종료·시간 초과로 판정 자체를 못 했다면 페이지 안내대로 sudo apt install --reinstall plem-core 로 다시 설치하세요. 조치한 뒤에는 plem 에서 로봇 스택을 다시 시작해야 적용됩니다.

토큰 거부. plem update·plem-register·plem code 가 토큰 거부를 받으면 안내가 흔한 두 원인을 각각의 조치와 함께 보여 줍니다. 서버가 둘을 구별해 주지 않으므로 어느 쪽인지는 담당자에게 확인하세요.

원인	뜻	할 일
토큰 폐기	폐기는 영구입니다. 담당자가 기기를 삭제하면 그 기기에 쓴 토큰도 함께 폐기됩니다	새 토큰을 받으세요
라이선스 만료	기기에 등록된 토큰은 라이선스 만료일을 따릅니다. 만료되면 plem update 가 거부되고 plem code 도 다음 키 갱신부터 거부됩니다(원격 지원 plem remote 는 열립니다)	담당자에게 연장을 요청한 뒤 sudo plem-register --refresh 로 새 라이선스를 받고 로봇 스택을 다시 시작하세요

등록은 Depot 마다 따로입니다. 이미 등록된 기기를 다른 Depot 주소에 새 토큰으로 등록하면 그 Depot 에 새 기기로 등록되고, 기기의 라이선스(/etc/plem/license.key)와 등록 정보(/etc/plem/depot.json)는 새 것으로 바뀝니다. 다시 등록하기 전에 지금 등록처가 어디인지 담당자에게 확인하세요.

제거와 재설치. 패키지만 갱신하려면 제거하지 말고 plem update 를 쓰세요. plem uninstall 은 기본으로 라이선스와 plem code 기기 키까지 지우지만, 기기 등록은 PLEM 서버에 그대로 남습니다. 다시 설치하려면 담당자에게 기존 등록 삭제를 요청한 뒤 새 토큰으로 설치하세요. --keep-license 는 라이선스와 기기 키 파일을 남길 뿐입니다 — 기기 키는 서버도 다시 알려 주지 않으니 남긴 파일이 유일한 사본입니다. 자세한 내용은 plem uninstall에 있습니다.

원격 지원을 받고 싶다

기기에서 다음을 실행하시면 지원 엔지니어가 접속할 수 있는 임시 통로가 열립니다. 명령을 끝내시면(Ctrl+C) 통로도 함께 닫힙니다.

plem remote

지원을 요청할 때

문의는 william@wimcorp.co.kr 로 보내 주세요.

TUI 와 로봇 스택 로그는 ~/.plem/log 에 있습니다. 이 폴더를 묶어 함께 보내 주시면 진단이 빠릅니다.

tar czf plem-log.tar.gz -C ~/.plem log

로그	위치
TUI (조작·기동·정지·로봇 이벤트)	~/.plem/log/plem_tui_<시각>.log (plem 을 켤 때마다 새 파일)
로봇 스택 (launch·노드·서버 출력)	~/.plem/log/<시각>/ (로봇 스택을 기동할 때마다 새 폴더)

두 종류 모두 가장 최근 20개만 남고 그보다 오래된 것은 다음 실행 때 지워집니다. 문제가 난 기동의 로그가 지워지지 않도록 되도록 빨리 보내 주세요.

여기에 plem version 결과와 어떤 조작에서 문제가 났는지를 덧붙여 주세요.