로봇 스택 기동
스택은 기기에서 plem 으로 띄웁니다. 통합 사용자에게 필요한 것은 세 가지입니다.
- 어떤 선택이 내가 쓸 인터페이스를 바꾸는가
- 떴는지 어떻게 확인하는가
- 안 떴을 때 무엇을 보는가
기동 절차
plem 을 실행해 로봇 프로필을 고르고 기동합니다. 단일 로봇이든 여러 대든 같은 launch 파일 하나로 통일돼 있습니다. 기동 직전에 선택된 EtherCAT 마스터의 슬레이브를 조회하고, 결과가 0이면 스택을 시작하지 않습니다.
무엇이 내 인터페이스를 바꾸는가
plem 의 선택 | launch 인자 | 추가로 생기는 것 | 선행 조건 |
|---|---|---|---|
| MoveIt | moveit | plem/plan_trajectory | — |
| 충돌 회피 | enable_cumotion | 지원 모델에 cuMotion 계획 파이프라인 등록 — ROS 2 Humble(JetPack 6) 트레인 한정: Jazzy(JetPack 7) 장비에는 cuMotion 이 아직 프로비저닝되지 않았습니다. 지원 모델에서 이 옵션을 켜고 기동하면 cuMotion 플러그인을 찾지 못해 로봇 스택 기동이 실패합니다(사전 경고 없음) — 켜지 마세요 | MoveIt |
| 카메라·지각 | perception_stack | 지원 카메라의 토픽 — 캘리브레이션이 끝나 있어야 환경 지도(ESDF)까지 올라옴 | MoveIt · 지각 지원 카메라 |
| Teaching Pendant · Plem Lab | teaching_pendant · plem_lab | 웹 UI 브릿지 (ROS 2 통합에는 불필요) | — |
세 가지를 주의하세요.
MoveIt 이 꺼지면 cuMotion 과 카메라, 지각 노드가 아예 뜨지 않습니다. 카메라 옵션만 켜도 소용없습니다. 실제 환경 회피에는 MoveIt·충돌 회피·카메라·캘리브레이션이 모두 필요합니다.
COLLISION_AWARE 요청의 수락 여부는 goal 단계에서 결정되지 않습니다. 모델 지원과 파이프라인 상태는 수락 뒤에 검사되므로 goal 이 abort 될 수 있습니다. 결과까지 확인하세요.
저장된 선택이 없을 때 plem 은 MoveIt 켜짐·충돌 회피 꺼짐으로 시작하지만, launch 파일 자체의 기본값은 그 반대(moveit=false, enable_cumotion=true)입니다. plem 은 마지막 선택을 기억하므로, 직접 ros2 launch 로 띄우신다면 원하는 값을 명시하세요.
떴는지 확인하기
기동은 단번에 끝나지 않습니다. 로봇은 1초 간격으로 엇갈려 올라오고, 그 위의 계층이 차례로 붙습니다.
| 시점 | 올라오는 것 |
|---|---|
| 하드웨어 활성화 직후 | plem/set_mode · plem/control_command · status_broadcaster · rt_* |
| 약 3–4초 | 웹 UI 브릿지 (Pendant·Lab 을 켠 경우) |
| 약 5초 | 카메라·지각 노드, MoveIt |
| 지각 사용 시 | 기동 6초 뒤부터 환경 지도 서비스가 광고되기를 최대 60초 대기 후 MoveIt 기동 |
가장 확실한 신호는 plem/set_mode 액션이 응답하는 것입니다. 여기까지 왔으면 하드웨어 인터페이스가 활성화된 상태입니다. 클라이언트는 고정 시간을 기다리지 말고 wait_for_server 로 대기하세요.
안 뜰 때
| 증상 | 뜻 | 할 일 |
|---|---|---|
| 기동 전에 EtherCAT 슬레이브가 없다고 막힘 | 슬레이브 0 또는 상태 조회 실패 | 로봇 컨트롤 박스 전원과 EtherCAT 케이블을 확인하고 다시 기동 |
로그의 [EtherCATBus] Failed to request master. | 마스터를 잡지 못함 — 원인은 구분되지 않음 | 이전 스택이 완전히 내려갔는지 확인하고(§재기동) 다시 기동 |
| 지각이 "driver-only" 로 강등됐다는 안내 | 카메라 캘리브레이션 기록이 없거나, 측정 뒤 카메라 모델·툴 회전이 바뀌어 기록이 제쳐짐(바로 위에 [launch.extrinsic] WARNING 한 줄) — 실패가 아니라 축소 기동 | 그대로 쓰셔도 됩니다. 지각 기능이 필요하면 지금 구성으로 캘리브레이션을 다시 하세요. 부품을 바꾸지 않았다면 로봇 설정의 카메라·툴 회전 값을 확인하세요 |
| 카메라 캘리브레이션 기록 오류로 기동 실패 | 프로필이 가리키는 기록 파일이 없거나 읽을 수 없음, 또는 다른 로봇 모델로 측정한 기록 | 로봇 설정에서 캘리브레이션 값을 해제하거나 맞는 기록을 고른 뒤 다시 기동 |
| 환경 지도 준비 실패로 종료 | 지각 스택이 제때 뜨지 못해 launch 전체가 멈춤 | 카메라 연결을 확인하고(문제 해결) 다시 기동 |
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: <사유> — <조치> | 이 로봇에 등록된 기체별 실측 기구학이 검증을 통과하지 못해, 잘못된 기하로 움직이지 않도록 기동을 멈춤 | 줄에 적힌 조치를 따르세요. 정상 기동이면 대신 [measured] <로봇> geometry: measured record applied (measured <날짜>) 이나 geometry: model nominal (<모델>) 한 줄이 남습니다 |
perception_overrides.yaml 오류로 기동 실패 | 현장 인식 설정 덮어쓰기 파일에 알 수 없는 섹션·프로파일·키가 있음 | 파일을 고치거나 지우고 다시 기동 |
| MoveIt·웹 브릿지 관련 경고 후 계속 진행 | 해당 구성 요소만 빠지고 나머지는 정상 기동 | 웹 화면이 필요하면 스택을 내리고 다시 기동 |
재기동
이전 스택이 완전히 내려간 뒤에 다시 띄우세요. 아직 살아 있으면 EtherCAT 마스터를 잡지 못해 실패하고, 반쯤 뜬 스택이 같은 네임스페이스에 중복 노드를 남겨 이후 관측을 오염시킵니다. 정지에는 시간이 걸릴 수 있습니다. 카메라를 쓰는 구성은 특히 그렇습니다.
controller_manager 로 로봇 하드웨어를 비활성화한 뒤 같은 스택에서 다시 활성화하는 요청은 거부됩니다. 다시 쓰려면 로봇 스택을 재시작하세요.
plem kill 은 최후 수단입니다정상 정지는 로봇에 BRAKED 를 요청한 뒤 프로세스를 내립니다(요청은 최선 노력이며 성공을 확인하지는 않습니다). 브레이크 그룹을 선언한 모델(현재 Huayan Elfin)의 드라이버는 내려가기 전에 체결 확인을 기다리지만, launch 가 잠시 뒤 보내는 SIGTERM 에 확인 없이 진행합니다 — 정지·안전.
plem kill 은 그 요청조차 없이 기기 전체에서 매칭되는 프로세스를 종료하고 곧 강제 종료로 올립니다. 따로 띄워 두신 RViz·PlotJuggler 같은 도구도 함께 끊깁니다. 정상 정지가 듣지 않을 때만 쓰세요.
현장 인식 설정 덮어쓰기
충돌 격자 크기·중심이나 nvblox 범위·복셀 크기처럼 현장에 맞춰야 하는 인식 설정은 ~/.plem/perception_overrides.yaml(PLEM_HOME 을 지정했다면 그 아래)에 적으면, 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설정 화면의 인식 프로파일 미리보기에서도 적용될 값을 볼 수 있습니다.
직접 기동할 때
plem 을 거치지 않고 ros2 launch 로 띄우신다면 네 가지를 챙기세요. 프로필이 없거나 시리얼·마스터 개수가 맞지 않으면 기동 전에 오류로 멈춥니다.
- 프로필 디렉터리:
robots/를 담고 있는 루트입니다. 생략하면~/.plem(PLEM_HOME을 지정했다면 그 경로)을 씁니다. 그 아래robots/<로봇 이름>.yaml이 없는 로봇이 있으면 기동 전에 오류로 멈춥니다.robots/자체를 넘기면 프로필을 찾지 못해 멈춥니다. - 로봇 이름: 목록의 각 이름이 곧 네임스페이스가 됩니다.
- 로봇 시리얼: 로봇 목록과 같은 개수·순서로 지정합니다 — 시리얼이 없는 로봇은
,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 …