본문으로 건너뛰기

로봇 스택 기동

기동 절차​

기기에서 plem 을 실행해 로봇 프로필을 고르고 기동합니다. 로봇이 한 대든 여러 대든 같은 launch 파일 하나를 씁니다.

plem 은 기동 직전에 고른 EtherCAT 마스터의 슬레이브를 조회합니다. 슬레이브가 0개면 스택을 시작하지 않습니다.

무엇이 내 인터페이스를 바꾸는가​

plem 의 선택launch 인자기본값 (plem / launch 파일)추가로 생기는 것먼저 켜야 하는 것
MoveItmoveit켜짐 / falseplem/plan_trajectory—
충돌 회피enable_cumotion꺼짐 / true지원 모델에 cuMotion 계획 파이프라인 등록. ROS 2 Humble(JetPack 6) 기기만(아래 경고)MoveIt
카메라·인식perception_stack꺼짐 / false지원 카메라의 토픽. 캘리브레이션이 끝나 있어야 환경 지도(ESDF)까지 올라옴MoveIt · 인식 지원 카메라
Teaching Pendant · Plem Labteaching_pendant · plem_lab켜짐 / true웹 UI 연결 (ROS 2 통합에는 필요 없음)—

plem 은 마지막 선택을 기억합니다. ros2 launch 로 직접 띄울 때는 필요한 값을 모두 적으세요. MoveIt 사용 여부와 충돌 회피는 launch 파일의 기본값이 plem 과 반대입니다.

JetPack 7(Jazzy) 기기에서는 충돌 회피를 켜지 마세요

cuMotion 플래너는 ROS 2 Humble(JetPack 6) 기기에서만 씁니다. Jazzy(JetPack 7) 기기에는 아직 설치되지 않습니다. 지원 모델에서 이 옵션을 켜고 기동하면 cuMotion 플러그인을 찾지 못해 로봇 스택 기동이 실패합니다. 미리 경고하지 않습니다.

  • MoveIt 옵션을 끄면 cuMotion, 카메라, 인식 노드가 아예 뜨지 않습니다. 카메라만 켜서는 아무것도 뜨지 않습니다. 실제 물체를 피하려면 MoveIt, 충돌 회피, 카메라, 캘리브레이션이 모두 필요합니다.
  • COLLISION_AWARE 계획은 지원 모델에서 자기 충돌을 피합니다. 계획 장면에 등록한 물체(Teaching Pendant 셀 물체 포함)를 피하는 것은 보장하지 않습니다(셀 물체).
  • COLLISION_AWARE 계획 요청은 수락된 뒤에도 abort 될 수 있습니다. 모델 지원과 파이프라인 상태를 수락 뒤에 검사하기 때문입니다. 결과까지 확인하세요.

떴는지 확인하기​

기동은 여러 단계로 진행됩니다. 로봇은 1초 간격으로 차례로 올라오고, 그 위 계층이 순서대로 붙습니다.

시점올라오는 것
하드웨어 활성화 직후plem/set_mode · plem/control_command · status_broadcaster · rt_*
약 3–4초웹 UI 연결 (펜던트·Lab 옵션을 켠 경우)
약 5초카메라·인식 노드, MoveIt
인식 사용 시기동 6초 뒤부터 환경 지도 서비스를 최대 60초 기다린 뒤 MoveIt 기동

가장 확실한 신호는 plem/set_mode 액션의 응답입니다. 응답하면 하드웨어 인터페이스가 활성화된 상태입니다. 클라이언트는 정해진 시간을 기다리지 말고 wait_for_server 로 기다리세요.

안 뜰 때​

증상 (로그 줄)뜻할 일
기동 전에 EtherCAT 슬레이브가 없다고 막힘슬레이브 0개 또는 상태 조회 실패로봇 컨트롤 박스 전원과 EtherCAT 케이블을 확인하고 다시 기동
마스터를 잡지 못함 (Failed to request EtherCAT master <번호> … possible causes: …)다른 프로세스가 마스터를 쥐고 있음, IgH 마스터가 실행 중이 아님, 이 사용자가 /dev/EtherCAT<n> 을 열 수 없음 중 하나. 로그 줄에 가능한 원인이 나옴이전 스택이 완전히 내려갔는지 확인하고(재기동) 다시 기동
인식이 「driver-only」로 강등 (안내 바로 위 [launch.extrinsic] WARNING 줄)실패가 아님. 카메라 토픽만 뜬 채 기동함. 카메라 캘리브레이션 기록이 없거나, 측정 뒤 카메라 모델·툴 회전이 바뀜그대로 써도 됨. 인식이 필요하면 지금 구성으로 다시 캘리브레이션. 부품을 바꾸지 않았다면 로봇 설정의 카메라·툴 회전 값을 확인
카메라 캘리브레이션 기록 오류로 기동 실패프로필이 가리키는 기록이 없거나 읽을 수 없음, 또는 다른 로봇 모델로 측정한 기록로봇 설정에서 캘리브레이션 값을 해제하거나 맞는 기록을 고른 뒤 다시 기동
환경 지도 준비 실패로 종료인식 스택이 제때 뜨지 못해 launch 전체가 멈춤카메라 연결을 확인하고(문제 해결) 다시 기동
PDO 매핑 거부 (declared PDO layout rejected·cannot read the slave's PDO mapping 등 refusing to initialize 를 담은 줄. 대소문자는 줄마다 다름)드라이브의 PDO 매핑이 로봇 모델 선언과 다르거나 읽을 수 없음. 로봇이 움직이기 전에 멈춤고른 로봇 모델과 드라이브 펌웨어를 확인. 계속되면 지원팀에 문의
드라이브 식별 불일치 (the configuration declares vendor 0x… product 0x…, but the slave at that ring position is …)그 링 위치에 다른 드라이브가 있거나 배선 순서가 다름고른 로봇 모델과 EtherCAT 배선 순서를 확인
실측 기구학 거부 ([measured] <로봇> rejected: <사유> — <조치>)이 로봇에 등록된 개체별 실측 기구학이 검증을 통과하지 못함. 잘못된 기하로 움직이지 않도록 기동을 멈춤로그 줄의 조치를 따름. 정상 기동이면 대신 geometry: measured record applied (measured <날짜>) 나 geometry: model nominal (<모델>) 줄이 남음
perception_overrides.yaml 오류로 기동 실패현장 인식 설정 덮어쓰기 파일에 알 수 없는 섹션·프로필·키가 있음파일을 고치거나 지우고 다시 기동
MoveIt·웹 연결 관련 경고 뒤 계속 진행그 구성 요소만 빠지고 나머지는 정상 기동웹 화면이 필요하면 스택을 내리고 다시 기동

재기동​

이전 스택이 완전히 내려간 뒤에 다시 띄우세요. 아직 살아 있으면 EtherCAT 마스터를 잡지 못해 기동이 실패합니다. 반쯤 뜬 스택은 같은 네임스페이스에 중복 노드를 남깁니다. 내려가는 데는 시간이 걸릴 수 있고, 카메라를 쓰는 구성은 특히 그렇습니다.

controller_manager 로 로봇 하드웨어를 비활성화하면 같은 스택에서 다시 활성화할 수 없습니다. 로봇 스택을 재시작하세요.

경고
plem kill 은 최후 수단입니다

정상 정지는 로봇에 BRAKED 모드를 요청한 뒤 프로세스를 내립니다. 요청이 성공했는지는 확인하지 않습니다. launch 쪽에서 잠시 뒤 보내는 SIGTERM 신호를 받으면 브레이크 체결 확인도 건너뜁니다(정지·안전). plem kill 은 그 요청조차 보내지 않고 곧 강제 종료로 넘어갑니다. 정상 정지가 듣지 않을 때만 쓰세요. 무엇이 함께 끊기는지는 plem kill에 있습니다.

현장 인식 설정 덮어쓰기​

충돌 격자 크기·중심, nvblox 범위·복셀 크기처럼 현장에 맞춰야 하는 인식 설정이 있습니다. 이 값을 ~/.plem/perception_overrides.yaml 에 적으면 PLEM 패키지가 설치한 인식 프로필 위에 덮어씁니다. PLEM_HOME 을 지정했다면 그 아래에 둡니다. 설치 파일은 고치지 마세요.

common: # 모든 프로필 — 현장 기하
cumotion:
grid_size_m: [1.8, 2.2, 1.4]
grid_center_m: [0.0, 0.0, 0.6]
profiles: # 그다음 한 프로필에만 — 그 프로필 튜닝
thin_object_precise:
nvblox:
voxel_size_m: 0.02
  • 적용 순서는 설치 프로필 → common → profiles.<이름> 입니다. 현장 기하는 common 에 두세요. profiles.<이름> 아래 두면 다른 프로필을 고르는 순간 빠집니다.
  • 하위 항목이 있는 키는 키 단위로 합쳐집니다. 그 밖의 값은 목록을 포함해 통째로 바뀝니다.
  • 파일이 없으면 설치 프로필을 그대로 씁니다.
  • 알 수 없는 섹션, 없는 프로필 이름, 설치 프로필에 없는 키가 있으면 기동을 거부합니다. 오타가 조용히 무시되지 않게 하기 위해서입니다.
  • 카메라·인식 노드와 MoveIt(cuMotion 격자)이 같은 결과를 읽습니다. 적용되면 기동 로그에 [perception] … overridden at [...] 줄이 남습니다.
  • plem 시작 화면의 Camera quality 미리보기는 덮어쓴 인식 거리·해상도를 반영하고, 덮어쓴 키 이름을 한 줄로 보여 줍니다.

직접 기동할 때​

plem 없이 ros2 launch 로 띄울 때 챙길 인자

프로필이 없거나 시리얼·마스터 개수가 맞지 않으면 기동 전에 오류로 멈춥니다.

  • 프로필 디렉터리: robots/ 를 담은 상위 폴더입니다. robots/ 자체를 넘기면 프로필을 찾지 못합니다. 생략하면 ~/.plem, PLEM_HOME 을 지정했다면 그 경로를 씁니다. 로봇마다 그 아래에 robots/<로봇 이름>.yaml 이 있어야 합니다.
  • 로봇 이름: 각 이름이 그대로 네임스페이스가 됩니다.
  • 로봇 시리얼: 로봇 이름과 같은 개수·순서로 적습니다. 시리얼이 없는 로봇은 ,S2 처럼 빈 칸으로 자리를 남깁니다. 등록 모델은 시리얼이 필수입니다. 관절 오프셋을 기기별 관절 캘리브레이션 프로필(~/.plem/profiles/<시리얼>.json)에서 가져오기 때문입니다. 시리얼을 빼면 기본값으로 넘어가지 않고 드라이버가 로봇 구성을 거부합니다.
  • EtherCAT 마스터: 같은 순서로 로봇마다 하나씩 적습니다. 로봇 수보다 적으면 기동 전에 멈춥니다. 생략하면 로봇 순번(0부터)을 씁니다.

로그 위치를 지정하지 않으면 ROS 기본 위치(~/.ros/log)에 쌓이고 오래된 로그가 지워지지 않습니다. plem 처럼 ~/.plem/log 아래에 기동마다 폴더를 두려면 폴더를 만들어 ROS_LOG_DIR 로 넘기세요. 로봇 스택은 이 폴더를 포함해 최근 20개만 남깁니다.

export ROS_LOG_DIR=~/.plem/log/$(date +%Y-%m-%d_%H-%M-%S)
mkdir -p "$ROS_LOG_DIR"
ros2 launch …