로봇 스택 기동
기동 절차
기기에서 plem 을 실행해 로봇 프로필을 고르고 기동합니다. 로봇이 한 대든 여러 대든 같은 launch 파일 하나를 씁니다.
plem 은 기동 직전에 고른 EtherCAT 마스터의 슬레이브를 조회합니다. 슬레이브가 0개면 스택을 시작하지 않습니다.
무엇이 내 인터페이스를 바꾸는가
plem 의 선택 | launch 인자 | 기본값 (plem / launch 파일) | 추가로 생기는 것 | 먼저 켜야 하는 것 |
|---|---|---|---|---|
| MoveIt | moveit | 켜짐 / false | plem/ | — |
| 충돌 회피 | enable_ | 꺼짐 / true | 지원 모델에 cuMotion 계획 파이프라인 등록. ROS 2 Humble(JetPack 6) 기기만(아래 경고) | MoveIt |
| 카메라·인식 | perception_ | 꺼짐 / false | 지원 카메라의 토픽. 캘리브레이션이 끝나 있어야 환경 지도(ESDF)까지 올라옴 | MoveIt · 인식 지원 카메라 |
| Teaching Pendant · Plem Lab | teaching_ · plem_ | 켜짐 / true | 웹 UI 연결 (ROS 2 통합에는 필요 없음) | — |
plem 은 마지막 선택을 기억합니다. ros2 launch 로 직접 띄울 때는 필요한 값을 모두 적으세요. MoveIt 사용 여부와 충돌 회피는 launch 파일의 기본값이 plem 과 반대입니다.
cuMotion 플래너는 ROS 2 Humble(JetPack 6) 기기에서만 씁니다. Jazzy(JetPack 7) 기기에는 아직 설치되지 않습니다. 지원 모델에서 이 옵션을 켜고 기동하면 cuMotion 플러그인을 찾지 못해 로봇 스택 기동이 실패합니다. 미리 경고하지 않습니다.
- MoveIt 옵션을 끄면 cuMotion, 카메라, 인식 노드가 아예 뜨지 않습니다. 카메라만 켜서는 아무것도 뜨지 않습니다. 실제 물체를 피하려면 MoveIt, 충돌 회피, 카메라, 캘리브레이션이 모두 필요합니다.
COLLISION_계획은 지원 모델에서 자기 충돌을 피합니다. 계획 장면에 등록한 물체(Teaching Pendant 셀 물체 포함)를 피하는 것은 보장하지 않습니다(셀 물체).AWARE COLLISION_계획 요청은 수락된 뒤에도 abort 될 수 있습니다. 모델 지원과 파이프라인 상태를 수락 뒤에 검사하기 때문입니다. 결과까지 확인하세요.AWARE
떴는지 확인하기
기동은 여러 단계로 진행됩니다. 로봇은 1초 간격으로 차례로 올라오고, 그 위 계층이 순서대로 붙습니다.
| 시점 | 올라오는 것 |
|---|---|
| 하드웨어 활성화 직후 | plem/ · plem/ · status_ · rt_* |
| 약 3–4초 | 웹 UI 연결 (펜던트·Lab 옵션을 켠 경우) |
| 약 5초 | 카메라·인식 노드, MoveIt |
| 인식 사용 시 | 기동 6초 뒤부터 환경 지도 서비스를 최대 60초 기다린 뒤 MoveIt 기동 |
가장 확실한 신호는 plem/ 액션의 응답입니다. 응답하면 하드웨어 인터페이스가 활성화된 상태입니다. 클라이언트는 정해진 시간을 기다리지 말고 wait_ 로 기다리세요.
안 뜰 때
| 증상 (로그 줄) | 뜻 | 할 일 |
|---|---|---|
| 기동 전에 EtherCAT 슬레이브가 없다고 막힘 | 슬레이브 0개 또는 상태 조회 실패 | 로봇 컨트롤 박스 전원과 EtherCAT 케이블을 확인하고 다시 기동 |
마스터를 잡지 못함 (Failed to request EtherCAT master <번호> … possible causes: …) | 다른 프로세스가 마스터를 쥐고 있음, IgH 마스터가 실행 중이 아님, 이 사용자가 /dev/ 을 열 수 없음 중 하나. 로그 줄에 가능한 원인이 나옴 | 이전 스택이 완전히 내려갔는지 확인하고(재기동) 다시 기동 |
인식이 「driver-only」로 강등 (안내 바로 위 [launch. 줄) | 실패가 아님. 카메라 토픽만 뜬 채 기동함. 카메라 캘리브레이션 기록이 없거나, 측정 뒤 카메라 모델·툴 회전이 바뀜 | 그대로 써도 됨. 인식이 필요하면 지금 구성으로 다시 캘리브레이션. 부품을 바꾸지 않았다면 로봇 설정의 카메라·툴 회전 값을 확인 |
| 카메라 캘리브레이션 기록 오류로 기동 실패 | 프로필이 가리키는 기록이 없거나 읽을 수 없음, 또는 다른 로봇 모델로 측정한 기록 | 로봇 설정에서 캘리브레이션 값을 해제하거나 맞는 기록을 고른 뒤 다시 기동 |
| 환경 지도 준비 실패로 종료 | 인식 스택이 제때 뜨지 못해 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_ 오류로 기동 실패 | 현장 인식 설정 덮어쓰기 파일에 알 수 없는 섹션·프로필·키가 있음 | 파일을 고치거나 지우고 다시 기동 |
| MoveIt·웹 연결 관련 경고 뒤 계속 진행 | 그 구성 요소만 빠지고 나머지는 정상 기동 | 웹 화면이 필요하면 스택을 내리고 다시 기동 |
재기동
이전 스택이 완전히 내려간 뒤에 다시 띄우세요. 아직 살아 있으면 EtherCAT 마스터를 잡지 못해 기동이 실패합니다. 반쯤 뜬 스택은 같은 네임스페이스에 중복 노드를 남깁니다. 내려가는 데는 시간이 걸릴 수 있고, 카메라를 쓰는 구성은 특히 그렇습니다.
controller_ 로 로봇 하드웨어를 비활성화하면 같은 스택에서 다시 활성화할 수 없습니다. 로봇 스택을 재시작하세요.
현장 인식 설정 덮어쓰기
충돌 격자 크기·중심, nvblox 범위·복셀 크기처럼 현장에 맞춰야 하는 인식 설정이 있습니다. 이 값을 ~/. 에 적으면 PLEM 패키지가 설치한 인식 프로필 위에 덮어씁니다. PLEM_ 을 지정했다면 그 아래에 둡니다. 설치 파일은 고치지 마세요.
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 기본 위치(~/.)에 쌓이고 오래된 로그가 지워지지 않습니다. plem 처럼 ~/. 아래에 기동마다 폴더를 두려면 폴더를 만들어 ROS_ 로 넘기세요. 로봇 스택은 이 폴더를 포함해 최근 20개만 남깁니다.
export ROS_LOG_DIR=~/.plem/log/$(date +%Y-%m-%d_%H-%M-%S)
mkdir -p "$ROS_LOG_DIR"
ros2 launch …