블록 추가 / 플랜 실행

플래너의 우측 상단 Plans 타임라인은 블록 카드가 가로로 늘어선 트랙입니다. 카드 한 장이 블록 하나이고, 왼쪽에서 오른쪽 순서로 실행됩니다. 플래너에 담은 워크스페이스는 모두 한 트랙에 모여 차례로 실행됩니다. 여러 플래너를 함께 돌리는 운영은 왼쪽 메뉴의 공정 관리에서 합니다. 각 블록의 결과(완료 · 중지 · 오류)는 실행 후 카드 우측 상단에 아이콘으로 남습니다.

블록 추가하기 #

1. 트랙 머리줄 오른쪽 끝의 + (새 블록) 버튼을 누릅니다.

   블록은 트랙 끝에 추가됩니다. 반복 · 조건 분기 · 묶음처럼 안에 블록을 담는 블록에는 슬롯마다 +(여기에 블록 추가) 버튼이 있어, 그 안에 바로 넣을 수 있습니다.

   

2. 블록 종류를 선택합니다.

   선택한 종류에 따라 다이얼로그 아래쪽 입력 항목이 바뀝니다.

   • 관절 자세 — 워크스페이스 로봇을 저장된 관절 자세로 이동
   • 학습 모델 추론 — 학습된 체크포인트로 추론 실행 (종료 조건이 걸릴 때까지)
   • 물체 위치로 이동 — 카메라로 타겟 물체를 검출해 그 위로 엔드 이펙터를 이동 (depth 카메라 필요)
   • 물체 파지 — 검출한 물체를 ZeroGrasp 확장 모듈이 만든 파지 자세로 잡기 (depth 카메라 · ZeroGrasp 모듈 필요)
   • 비주얼 서보잉 — 손목 카메라로 물체를 계속 검출하며 물체가 화면의 지정 위치·목표 거리(또는 크기)에 올 때까지 엔드 이펙터를 한 걸음씩 이동 (Enterprise 전용, depth 카메라 필요)
   • 시간 대기 — 지정한 초만큼 대기
   • IO 출력 — IO 탭에 등록한 IO 장치의 출력 채널을 켜고 끔 (동작 항목, IO 모듈 필요)
   • IO 감지 조건 — IO 장치의 입력(센서·버튼)이 1인지 0인지 보고 맞으면 / 아니면 갈래를 실행. 켜질 때까지 기다릴 수도 있음 (제어 (조건 · 반복) 항목, IO 모듈 필요)
   • 물체 감지 조건 — 카메라로 물체를 한 번 감지해, 감지되면 then 갈래 · 안 되면 실패 시 갈래를 실행 (제어 (조건 · 반복) 항목)
   • 에이전트 액션 — 에이전트가 카메라를 보고 로봇을 직접 움직여 작업 지시를 수행 (에이전트 항목, Claude · GPT · Gemini 모듈 중 하나 필요)
   • 에이전트 판단 — 질문 하나와 선택지 여러 개를 두면 에이전트가 카메라를 보고 하나를 골라 그 갈래의 블록을 실행 (에이전트 항목, Claude · GPT · Gemini 모듈 중 하나 필요)
   • 플랜 종료 — 실행이 닿으면 플랜을 여기서 끝냄 (제어 (조건 · 반복) 항목)

   이 밖에 동작 항목의 관절 상대 이동 · 엔드이펙터 자세로 이동 · 엔드이펙터 상대 이동 · 에피소드 재생 · ROS 서비스 호출, 제어 (조건 · 반복) 항목의 반복 · 조건 분기 · Case (Switch) · 변수 변경 · 블록으로 이동 · 묶음 블록이 있습니다.

   

3. 종류별 세부 항목을 채우고 다이얼로그 우측 하단의 저장을 누릅니다.

   종류와 무관하게 공통으로 입력하는 항목은 다음 한 가지뿐입니다.

   • 이름 (선택) — 비워 두면 종류와 워크스페이스/체크포인트 이름으로 자동 생성됩니다. 예: 이동 (워크스페이스 A), pick_v3 실행, 2초 대기, 감지 조건: red cup.

   

   나머지 입력 항목은 선택한 블록 종류에 따라 다릅니다. 각 종류별 입력 항목은 아래 관절 자세 블록, 학습 모델 추론 블록, 물체 위치로 이동 블록, 물체 파지 블록, 비주얼 서보잉 블록, 시간 대기 블록, IO 출력 블록, IO 감지 조건 블록, 물체 감지 조건 블록, 에이전트 액션 블록, 에이전트 판단 블록, 플랜 종료 블록 절을 참고하세요. 목록에서 빠진 포즈 조회 블록과 물체 감지 블록도 예전 플랜을 위해 설명을 남겨 두었습니다.

   입력을 마친 뒤 다이얼로그 우측 하단의 저장을 누르면 블록이 트랙에 추가됩니다.

   

관절 자세 블록 #

지정 워크스페이스의 로봇들을 저장된 관절 자세로 이동시킵니다. (예전 이름 Joint Position — 새 블록 카드에는 이동 (워크스페이스 이름) 형식의 자동 이름이 붙습니다.)

1. 워크스페이스를 선택합니다.

   해당 워크스페이스의 어셈블리에 포함된 모든 로봇의 자세를 한 번에 저장합니다. 플래너에 담은 워크스페이스 중에서 고르며, 워크스페이스가 하나뿐이면 자동으로 선택되고 선택 칸은 표시되지 않습니다.

   

2. 로봇 펜던트로 원하는 자세를 만듭니다.

   워크스페이스에 포함된 각 로봇별로 펜던트가 표시됩니다. 로봇이 켜져 있어야 펜던트가 보이며, 꺼져 있으면 안내 문구가 대신 표시됩니다.

   

3. 현재 자세 적용 버튼으로 자세를 저장합니다.

   현재 로봇의 관절값이 저장된 자세 카드(상단 강조 박스)에 표시됩니다. 저장된 자세는 이동 버튼으로 미리 검증해 볼 수 있습니다.

   

엔드이펙터 자세로 이동 블록 #

엔드 이펙터를 로봇 베이스 기준의 절대 위치(x · y · z, 단위 m)로 이동시킵니다. 지금 자세에서 얼마만큼 움직이는 것이 아니라 지정한 좌표로 가므로, 물체 위에 절대 자세로 정렬한 뒤 엔드이펙터 상대 이동 블록으로 내려가는 식으로 씁니다. 블록 종류 목록의 동작 항목에 있습니다.

• 워크스페이스 — 플래너에 담은 워크스페이스가 여러 개일 때만 선택 칸이 표시됩니다.
• 시간 (초) — 목표 자세까지 이동하는 데 걸리는 시간입니다.
• 방향 지정 방식 — 고른 방식에 따라 로봇별 입력 칸이 달라집니다.
  • 현재 방향 유지 — x · y · z. 지금 손목 방향은 그대로 두고 위치만 맞춥니다.
  • 아래 보기 (+ yaw 정렬) — x · y · z · yaw°. 그리퍼 접근축을 똑바로 아래로 향하게 하고, yaw 로 손목을 돌려 물체의 좁은 쪽이 그리퍼 사이에 오게 합니다. 검출한 물체에 맞추려면 yaw 를 obj.yaw 변수로 지정합니다.
  • 직접 지정 (roll/pitch/yaw) — x · y · z · roll° · pitch° · yaw°. 방향까지 모두 직접 정합니다.
• 현재 자세 읽기 — 로봇별 이름 줄 오른쪽 버튼입니다. 지금 엔드 이펙터 위치로 x · y · z 를 채우고, 직접 지정 (roll/pitch/yaw) 방식이면 roll · pitch · yaw 도 채웁니다. 로봇이 꺼져 있으면 비활성입니다.
• 변수로 입력 — 각 값 칸 오른쪽의 Σ 버튼(툴팁 변수로 입력)을 누르면 그 칸이 변수 소스 · 축 · 필드 · + 오프셋 세 칸으로 바뀝니다.
  • 변수 소스 — 값으로 쓸 변수를 고릅니다.
  • 축 · 필드 — 고른 변수가 x · y · z 같은 필드를 가지면 그중 하나를 고릅니다. 예를 들어 물체 위치로 이동 블록의 결과 저장 변수를 고르고 x 를 고릅니다.
  • + 오프셋 — 변수 값에 더할 양입니다. 위치 칸은 m, 각도 칸은 ° 단위입니다. 예를 들어 구멍 위 2cm 로 가려면 z 칸에 0.02 를 넣습니다. 0 이면 변수 값을 그대로 씁니다.
  • 칸 오른쪽 버튼(툴팁 숫자로 입력)을 누르면 다시 숫자 입력으로 돌아갑니다.
• 그리퍼 — 그리퍼(툴)는 절대 관절 값으로 함께 지정합니다.

학습 모델 추론 블록 #

선택한 체크포인트로 워크스페이스에서 실시간 추론을 실행합니다. 이 블록은 그 자체가 루프라서, 언제 끝날지를 종료 조건으로 정해 줘야 합니다. (예전 이름 Checkpoint — 새 블록 카드에는 체크포인트 이름 실행 형식의 자동 이름이 붙습니다.)

1. 워크스페이스와 체크포인트를 선택합니다.

   체크포인트 목록은 선택한 워크스페이스에서 학습된 항목으로 자동으로 좁혀집니다.

2. 추론 설정에서 호출 방식을 정합니다.

   • 추론 Hz — 초당 정책을 호출하는 횟수.
   • 재추론 스텝 — 한 번 추론한 액션을 몇 step 동안 재사용할지.
   • Temporal Ensemble 계수 — 재추론 스텝이 1일 때만 표시. 시간 평활 계수.
   • 청크 실행 방식 — EE 상대 경로 정책(학습할 때 행동 종류를 상대 엔드이펙터 위치로 고른 체크포인트) 전용입니다. 다른 체크포인트에서는 골라도 무시됩니다.
     • 기본 (이동량 누적) (기본값) — 예측한 이동량을 이어서 쌓아 실행합니다. 접촉이 없는 작업은 이 방식으로 충분합니다.
     • 측정 위치 기준 (접촉 작업 권장) — 청크마다 로봇의 실제 측정 위치에서 다시 계산합니다. 끼우기처럼 누르다가 힘이 커지면 정책이 살짝 물러나는 동작이 버려지지 않고 실행됩니다. 대신 이동이 약간 느려집니다.

   자세한 내용은 청크 실행 방식을 참고하세요. 자가학습 롤아웃도 이 블록의 추론 설정을 그대로 따릅니다.

   📸스크린샷 누락/docs/planner/blocks-checkpoint-02-chunk-alignment.png

   학습 모델 추론 블록 추론 설정 — 재추론 스텝 · Temporal Ensemble 계수 아래의 청크 실행 방식 선택(기본 (이동량 누적) / 측정 위치 기준 (접촉 작업 권장))과 안내 문구

3. 종료 조건을 하나 이상 추가합니다.

   조건은 한 줄 요약 목록으로 보입니다. 종료 조건 추가를 누르면 편집 창이 열리고, 이미 있는 조건은 그 줄을 눌러 같은 창에서 고칩니다. 줄 오른쪽 휴지통으로 지웁니다. 조건마다 다음 셋을 정합니다.

   • 조건 종류
     • 시간 — 정한 초가 지나면 끝냅니다.
     • 완료 신호 — 정책의 완료(Done) 점수가 임계값을 넘으면 끝냅니다.
     • 변수 조건 — 변수 비교식이 참이 되면 끝냅니다. 추론 중 변수 입력으로 적어 둔 값이나 작업 단계를 볼 수 있습니다. 로봇의 EE 힘(6축) 변수(robot.N.ee_force)는 원시값이라 fz < 0 같은 조건이 그대로 동작하지만, 모니터링 윈도우에 영점 기준으로 보이는 숫자와는 다릅니다(힘 영점).
     • 오브젝트 감지 — 카메라에서 정한 물체가 감지되면(또는 감지 안 되면) 끝냅니다. 찾는 방법은 검출 엔진으로 고릅니다 — YOLOE·SAM3 는 물체 이름을 적어 찾고, 커스텀 YOLO (비전 모델) 는 학습 → 비전 탭에서 만든 모델과 찾을 물체로 찾고 (커스텀 YOLO (비전 모델) 로 감지하기), 색 범위 (HSV) 는 학습 모델 없이 색과 덩어리 크기로만 찾습니다.
     • 작업 단계 — 정책이 예측한 작업 단계가 고른 단계이면(이 단계이면) 또는 그 단계가 아니면(이 단계가 아니면) 끝냅니다. 단계 목록에는 워크스페이스에 정의된 단계가 시작 전 (id 0), 1. 이름 (id N) 형식으로 보입니다. 단계를 고르지 않으면 "작업 단계 조건에는 단계를 골라야 합니다." 알림이 뜨고 창이 닫히지 않습니다. 작업 단계를 넣어 학습한 체크포인트에서만 동작하며, 워크스페이스에 작업 단계가 없으면 워크스페이스에서 먼저 정의하라는 경고가 표시됩니다. 목록에는 작업 단계가 done (id 2) 이(가) 아니면처럼 요약됩니다.
   • 이 조건으로 끝나면 — 성공 / 실패. 자가학습에서 이 시도의 데이터를 성공 기록으로 쌓을지, 교정 대상으로 보낼지가 여기서 갈립니다.
   • 끝난 뒤 실행할 블록 — 이 조건으로 끝났을 때 이동할 블록. 비우면 바로 다음 블록으로 이어집니다.

   조건은 위에서부터 평가해 먼저 걸린 하나가 판정합니다. 목록의 번호가 곧 우선순위입니다.

   변수 조건이나 작업 단계 조건이 있으면 목록 아래에 작업 단계 확정 프레임(기본 3)이 나옵니다. 정책이 낸 작업 단계가 같은 값으로 이 프레임 수만큼 연속이어야 단계가 바뀐 것으로 인정합니다. 한 프레임짜리 흔들림으로 조건이 걸리면 값을 올립니다.

4. 어떤 조건도 안 걸렸을 때를 정합니다.

   종료 조건 맨 위에 있습니다.

   • 실패 판정 스텝 한도 — 조건이 하나도 안 걸린 채 이 스텝 수에 도달하면 실패로 끝냅니다. 비워두면 안전장치가 없어 로봇이 계속 돕니다.
   • Fallback 블록 — 스텝 한도로 실패했을 때 이동할 블록.

   

검출 엔진 고르기 #

물체를 찾는 블록(물체 위치로 이동 · 물체 파지 · 비주얼 서보잉 · 물체 감지 조건 · 예전 물체 감지)과 이 블록의 오브젝트 감지 종료 조건에는 검출 엔진 선택이 있습니다. 블록 창에서는 카메라 선택 바로 아래에 있습니다.

검출 블록 창에는 엔진과 함께 다음 항목이 공통으로 있습니다.

• 검출 민감도 (conf) — 낮을수록 민감합니다. 엔진을 바꿀 때 값을 기본값 그대로 두었다면 그 엔진의 기본값(YOLOE 0.1 · SAM 3 0.3 · 커스텀 YOLO 0.35)으로 바뀝니다.
• 감지 영역 지정 (드래그) — 카메라 화면에 사각형을 그리면 그 안에서만 물체를 찾고 바깥 검출은 버립니다. 비워 두면 화면 전체에서 찾습니다. 카메라를 옮겼으면 다시 지정합니다.
• 워크스페이스 이미지 필터 적용 (기본 켜짐) — 이 카메라에 저장된 이미지 필터를 검출 입력에 적용합니다. 끄면 원본 이미지로 검출합니다.
• 검출 추적 — 지금 화면에서 타겟을 찾아 검출 결과를 겹쳐 보여 줍니다. 저장하기 전에 잘 잡히는지 확인합니다.

색 범위 (HSV) 로 감지하기 #

색이 뚜렷하고 배경과 잘 갈리는 대상(색 테이프, 단색 부품, 표시등)이라면 학습 모델 없이 색만으로 찾는 편이 훨씬 가볍고 빠릅니다. 오브젝트 감지 조건에서 검출 엔진을 색 범위 (HSV) 로 바꾸면 물체 이름 대신 아래를 정합니다.

• 색상 시작 / 끝 — 0~179 (빨강 0 · 노랑 30 · 초록 60 · 하늘 90 · 파랑 120 · 자주 150). 빨강처럼 눈금 0을 넘어가는 색은 시작을 끝보다 크게 적습니다 (예: 170 → 10).
• 채도 최소 / 최대, 밝기 최소 / 최대 — 0~255. 채도 최소를 올리면 회색·흰색 배경이, 밝기 최소를 올리면 그림자가 걸러집니다.
• 덩어리 크기 (픽셀) — 이 범위에 드는 색 덩어리만 감지로 칩니다. 최소 크기가 작은 얼룩(노이즈)을, 최대 크기가 화면을 뒤덮는 배경을 걸러냅니다. 최대는 비워두면 상한이 없습니다.

커스텀 YOLO (비전 모델) 로 감지하기 #

학습 → 비전 탭에서 학습한 비전 모델(커스텀 YOLO)은 그 현장 물체만 아는 전용 검출 모델이라 YOLOE·SAM3 보다 훨씬 빠릅니다. 물체 이름(프롬프트) 대신 모델과 찾을 물체로 찾습니다.

검출 엔진이 있는 곳(이 종료 조건의 오브젝트 감지, 물체 위치로 이동 · 물체 파지 · 비주얼 서보잉 · 물체 감지 조건 · 물체 감지 블록)이면 어디서나 고르는 방법이 같습니다.

1. 검출 엔진에서 커스텀 YOLO (비전 모델)을 고릅니다.

   학습을 마친 비전 모델이 하나도 없으면 이 항목은 커스텀 YOLO (학습 → 비전 탭에서 먼저 학습) 으로 비활성 표시됩니다. 엔진을 바꿀 때 검출 민감도를 기본값 그대로 두었다면, 커스텀 YOLO 의 기본값(0.35)으로 바뀝니다.

   📸스크린샷 누락/docs/planner/blocks-detect-custom-01-engine.png

   검출 블록 창 — 검출 엔진 select 펼침(YOLOE (내장) / SAM 3 세그멘테이션 (확장 모듈) / 커스텀 YOLO (비전 모델))과 커스텀 YOLO 안내 문구

2. 비전 모델과 찾을 물체를 고릅니다.

   • 비전 모델 — 학습을 마친 모델만 보입니다. 목록에는 이름 (모델 크기 · 물체 목록) 형식으로 표시됩니다.
   • 찾을 물체 — 그 모델이 아는 물체 중 찾을 것을 고릅니다. 비우면 모델이 아는 물체 전부를 찾습니다.

   검출 블록 창에서는 모델을 고른 뒤 카메라 화면 아래의 검출 추적(누르면 추적 중지로 바뀜)으로 지금 화면에서 잘 잡히는지 바로 확인할 수 있습니다.

   📸스크린샷 누락/docs/planner/blocks-detect-custom-02-model.png

   검출 블록 창 — 커스텀 YOLO 선택 시 비전 모델 select(학습을 마친 모델만 보입니다) · 찾을 물체 다중 선택(비우면 모델이 아는 물체 전부) · 검출 추적 버튼, 물체 파지 블록의 주황 안내 문구

포즈 조회 블록 #

외부 ROS2 서비스를 호출해 받은 좌표로 로봇을 이동시킵니다. 비전 인식 노드처럼 매 실행마다 위치가 달라지는 목표(예: 인식된 박스 중심)에 로봇을 보낼 때 사용합니다. 서비스 응답은 어셈블리 슬롯 이름을 키로 하는 JSON 객체로 와야 합니다. (예전 이름 Query Pose — 카드에는 Query 서비스 이름 형식의 자동 이름이 붙습니다.)

1. 워크스페이스를 선택합니다.

   플래너에 담은 워크스페이스 중 하나를 고릅니다. 워크스페이스가 하나뿐이면 자동으로 그 값이 들어가고 셀렉트는 표시되지 않습니다.

2. 포즈 타입을 선택합니다.

   서비스가 응답으로 돌려주는 좌표의 종류입니다.

   • 관절 좌표 — 슬롯별 관절 각도 배열 (예: [0.1, -0.5, 0.7, ...])
   • 엔드 이펙터 좌표 — 슬롯별 EE 위치/자세. 백엔드가 IK로 풀어 관절 값으로 변환합니다 (IK가 활성화된 단일 EE 로봇만 지원).

3. 호출할 서비스 이름을 입력합니다.

   형식은 std_srvs/srv/Trigger입니다. 예: /my_target. 응답 메시지의 message 필드에 JSON 문자열이 담겨 있어야 합니다.

4. 외부 노드 예시 보기 버튼으로 서버 예시 코드를 확인합니다.

   다이얼로그 안에 std_srvs 만으로 동작하는 ROS2 노드 예시 코드가 표시됩니다. 클립보드로 복사한 뒤 호스트에서 python3 my_target_server.py로 실행하면 위 서비스 이름으로 응답을 제공합니다 (별도 colcon build 필요 없음).

5. 이동 시간(초)을 입력합니다.

   서비스에서 받아온 목표 자세까지 보간 이동하는 데 걸리는 시간입니다. 짧을수록 빠르게 움직이지만 속도/저크가 커집니다.

6. 서비스 호출 + 로봇 이동 테스트 버튼으로 실제 동작을 검증합니다.

   서비스를 한 번 호출해서 받아온 좌표로 로봇을 이동시키고, 응답 JSON을 다이얼로그 안에 보여 줍니다. 좌표 형식이 맞지 않거나 IK가 풀리지 않으면 빨간 오류 메시지가 표시되므로, 플랜에 추가하기 전에 미리 검증할 수 있습니다.

물체 위치로 이동 블록 #

카메라로 타겟 물체를 검출해 그 위치로 엔드 이펙터를 보내는 블록입니다. 매 실행마다 물체의 실제 위치를 카메라로 다시 찾아 이동하므로, 물체가 놓인 자리가 달라져도 따라갑니다. 포즈 조회 블록이 외부 비전 노드를 직접 띄워야 했던 데 비해, 이 블록은 EasyTrainer 안에서 검출·역투영·이동을 모두 처리합니다. (예전 이름 Segmentation Reach — 새 블록 카드에는 Segmentation Reach: 대상 형식의 자동 이름이 붙습니다.)

블록은 다음 순서로 동작합니다.

1. 블록이 시작될 때의 자세에서 카메라의 RGB-D(컬러 + 깊이) 영상을 받아 타겟 물체를 검출합니다. 물체가 카메라에 잘 보이도록 앞 블록(예: 관절 자세)에서 자세를 잡아 둡니다.
2. 검출된 영역과 깊이를 로봇 base 기준의 3차원 좌표로 역투영합니다.
3. 그 위치(오프셋만큼 띄운 지점)로 엔드 이펙터를 이동시킵니다.

1. 카메라(depth)와 워크스페이스를 선택하고 검출 엔진을 고릅니다.

   depth를 제공하는 카메라를 고르면 그 아래에 실시간 화면이 표시됩니다. 워크스페이스가 하나뿐이면 자동으로 선택됩니다. 카메라 선택 아래의 검출 엔진은 검출 엔진 고르기를 참고합니다.

   📸스크린샷 누락/docs/planner/blocks-reach-01-camera.png

   물체 위치로 이동 블록 — 카메라(depth) 선택, 검출 엔진, 실시간 스트림

2. 타겟 오브젝트 지정 방식을 고르고 타겟을 지정합니다.

   • 바운딩 박스 (드래그) — 레퍼런스 추가를 누른 뒤 스트림 화면에서 타겟 물체를 드래그해 박스로 감쌉니다. 여러 각도에서 여러 개의 레퍼런스를 추가할수록 다른 시점에서도 같은 물체를 더 잘 찾습니다. YOLOE 에서만 쓸 수 있습니다.
   • 텍스트 프롬프트 — red cube처럼 영어로 물체를 묘사하면 검출 엔진이 그 설명으로 검출합니다. SAM 3 는 이 방식만 쓸 수 있습니다.

   레퍼런스 박스로 찾는데 엉뚱한 물체가 자꾸 잡히면, 그 물체를 비교군(감지하면 안 되는 물체) 으로 지정할 수 있습니다. 잘못 잡힌 물체를 레퍼런스 추가로 박스 친 뒤 썸네일 왼쪽 아래의 금지 아이콘 버튼을 누르면 버튼이 빨갛게 바뀌고 오른쪽 아래에 제외 배지가 붙습니다. 그 레퍼런스는 찾을 물체가 아니라 비교 대상이 되어, 어떤 후보를 비교군 쪽에 더 가깝다고 보면 그 후보를 버립니다. 예를 들어 구멍을 찾는데 반사 볼트를 자꾸 고르면, 잘못 잡힌 볼트를 박스로 꼭 맞게 쳐서 제외로 표시합니다. 버튼을 다시 누르면 다시 찾을 물체로 씁니다. 물체 감지 · 비주얼 서보잉 · 물체 파지 · 물체 감지 조건 블록의 레퍼런스 박스에서도 같습니다.

   카메라 선택 아래의 검출 엔진을 커스텀 YOLO (비전 모델) 로 고르면 지정 방식 대신 비전 모델과 찾을 물체를 고릅니다. 자세한 내용은 커스텀 YOLO (비전 모델) 로 감지하기를 참고하세요.

   📸스크린샷 누락/docs/planner/blocks-reach-02-target.png

   물체 위치로 이동 블록 — 레퍼런스 박스 추가 / 텍스트 프롬프트 입력

3. 검출 추적으로 검출이 되는지 확인합니다.

   검출 추적을 누르면 현재 화면에서 타겟을 찾아 마스크를 겹쳐 보여 주고, 검출 픽셀 수와 중심 좌표를 표시합니다. 뷰를 옮긴 뒤 다시 검출해 같은 물체를 찾는지 확인하세요. 잘 안 잡히면 검출 민감도 (conf) 를 낮춰 봅니다(YOLOE 기본 0.1, 낮을수록 민감). 여러 물체가 잡힐 때 어느 것으로 갈지는 검출 우선순위(가장 신뢰도 높은 물체 / 마스킹 크기 순 / 위치 기준 (X/Y/Z))에서 고릅니다.

   블록 창의 워크스페이스 이미지 필터 적용 토글 오른쪽에는 검출될 때까지 대기 토글 (기본 꺼짐) 이 있습니다.

   • 끔 — 같은 자세에서 몇 번 다시 찍어도 타겟을 찾지 못하면 블록이 실패합니다. 실패하면 실패 시 블록이나 Fallback 블록으로 넘어가고, 둘 다 없으면 플랜이 멈춥니다.
   • 켬 — 타겟을 찾지 못해도 블록이 실패하지 않습니다. 관찰 자세(블록이 시작될 때의 자세)에 머문 채 타겟이 검출될 때까지, 또는 중지를 누를 때까지 계속 다시 찍습니다. 물체가 놓이기를 기다렸다가 가야 하는 공정에 씁니다. 이때 검출하지 못한 것으로는 실패 시 블록이나 Fallback 블록으로 가지 않지만, 카메라 서비스 오류처럼 검출 외의 문제는 그대로 실패로 처리됩니다.

   📸스크린샷 누락/docs/planner/blocks-reach-03-detect.png

   물체 위치로 이동 블록 — 검출 추적 마스크 오버레이와 검출 정보, 워크스페이스 이미지 필터 적용 · 검출될 때까지 대기 토글

4. 시간과 도달 위치 미세조정을 정합니다.

   • 시간 (초) — 목표 위치까지 이동하는 시간입니다. 관찰 전 대기 (초) 는 검출하기 전에 기다리는 시간입니다.
   • 도달 위치 미세조정 접힘 항목:
     • 베이스 기준 / 공구 기준 — 아래 오프셋을 어느 방향 기준으로 더할지 고릅니다. 공구 기준은 엔드이펙터가 보는 방향 기준(X/Y 는 손목 축, Z 는 접근 방향에서 물러나는 양)이라 손목이 기울어도 같은 값이 같은 결과를 냅니다. 새로 만드는 블록은 공구 기준이 기본이고, 전에 만든 블록은 베이스 기준을 그대로 씁니다.
     • X / Y / Z 오프셋 (m) — 검출된 타겟 기준으로 도달 위치를 미세 조정합니다. Z 오프셋은 타겟에서 띄우는 양입니다(물체를 곧장 찍지 않고 살짝 위에서 멈추게 함).
     • 회전 허용 (방향 가중치) (기본 0.05) — 낮을수록 위치 도달을 우선하고 방향은 느슨하게 풉니다(IK가 안정적). 0이면 방향을 무시하고, 1이면 방향을 엄격히 맞춥니다.
     • 엔드이펙터 회전 지정 — 체크하면 아래 롤 · 피치 · 요 값으로 도달합니다(회전 허용을 높여야 반영됩니다). 체크하지 않으면 로봇의 현재 자세 방향을 그대로 씁니다.

5. 카메라 캘리브레이션 상태를 확인합니다.

   블록 창에는 캘리브레이션 완료 또는 미캘리브레이션 칩과 카메라 이름 카메라 · 이 워크스페이스 칩만 표시됩니다. 캘리브레이션은 (워크스페이스, 카메라) 단위로 저장되어 그 카메라를 쓰는 모든 블록이 함께 쓰며, 워크스페이스 페이지의 카메라 카드에 있는 카메라 캘리브레이션(자 모양) 버튼에서 합니다. 캘리브레이션이 안 된 카메라를 고르면 "카메라 캘리브레이션이 되어 있지 않아요. 워크스페이스 페이지에서 카메라 캘리브레이션을 하고 와주세요." 안내가 뜹니다.

   카메라 캘리브레이션 창에서는 먼저 손목(EE 장착) 카메라 토글로 장착 방식을 정합니다(켬 = 엔드이펙터에 달린 카메라, 끔 = 고정 카메라). 그런 다음 방식을 고릅니다.

   • 아루코 마커 사용 (권장) — 아루코 마커를 작업대에 고정한 뒤 팔 자세를 바꿔 가며 마커 촬영만 합니다(표본 최소 4개, 15개 이상 권장).
   • 아루코 마커 미사용 (직접 터치) — 물체가 보이는 자세에서 ① 검출 캡처를 누르고, 엔드이펙터로 그 물체를 직접 터치한 뒤 ② 터치 기록을 누릅니다(W/S/A/D/E/Z = 이동, Shift+키 = 회전, C/V = 그리퍼, Space = 정지). 물체 위치를 바꿔 가며 3회 이상 반복합니다.
   • 시뮬레이션 (정확값) — 시뮬레이션 카메라일 때만 나타납니다. 장착 자세를 시뮬레이터에서 그대로 읽어 표본이 필요 없습니다.

   표본이 모이면 계산을 눌러 카메라 장착 값을 구하고 저장합니다. 계산 뒤에는 잔차(mm)와 표본별 오차가 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-reach-04-calibration.png

   물체 위치로 이동 블록 — 캘리브레이션 상태 칩, 워크스페이스 페이지의 카메라 캘리브레이션 창(손목(EE 장착) 카메라 토글 · 아루코 마커 사용 / 미사용 / 시뮬레이션 탭 · 계산)

물체 파지 블록 #

카메라로 검출한 물체를 ZeroGrasp 파지 생성 확장 모듈이 만든 파지 자세로 잡습니다. 카메라 · 검출 설정은 물체 위치로 이동 블록과 같고, "어디를 어떤 방향으로 잡을지"를 ZeroGrasp 가 정한다는 점이 다릅니다.

블록은 다음 순서로 동작합니다.

1. 그리퍼를 엽니다(열림 값을 정했을 때).
2. 블록이 시작될 때의 자세에서 타겟 물체를 검출하고, 검출 우선순위로 하나를 고릅니다.
3. 물체 주변의 깊이 정보로 ZeroGrasp 가 파지 후보를 만들고, 파지 설정에 따라 하나를 고릅니다.
4. 접근 자세로 간 뒤 파지 자세로 들어가 그리퍼를 닫고 들어 올립니다.

1. 카메라와 검출 설정을 채웁니다.

   카메라(depth) · 검출 엔진 · 타겟 지정 · 검출 추적 · 검출 우선순위 · 시간 (초) · 관찰 전 대기 (초) · 카메라 캘리브레이션 상태는 물체 위치로 이동 블록과 같은 방식으로 정합니다. 검출 엔진으로 커스텀 YOLO 를 고르면 박스 영역이 물체로 잡혀 파지 계산에 배경이 섞일 수 있으므로, 정밀한 파지에는 YOLOE · SAM 3 가 낫습니다.

   📸스크린샷 누락/docs/planner/blocks-grasp-01-detect.png

   물체 파지 블록 — 카메라(depth) 선택, 검출 엔진, 타겟 지정, 실시간 화면과 검출 추적

2. 파지 설정에서 동작과 파지 자세를 정합니다.

   • 동작 — 접근 후 잡기 (기본) / 접근만 (잡지 않음). 접근만은 파지 지점까지 가서 멈추고, 그리퍼를 닫지도 들어 올리지도 않습니다. 자세를 눈으로 확인하거나 뒤에 다른 블록을 붙일 때 씁니다. 카드에는 (접근만) 이 함께 표시됩니다.
   • 파지 자세 — 모델 자세 사용 (6축) / 현재 손목 방향 유지 (위치만) / 일부 축만 현재 손목 유지. 일부 축만 유지는 롤 · 피치 · 요 중 체크한 축만 지금 손목 값을 유지하고 나머지는 모델에서 가져옵니다. 새 블록은 롤 · 피치를 유지하고 요(손가락 정렬)만 모델을 따르는 조합이 기본입니다 — 위에서 잡을 때 안전한 조합입니다. 손목 방향이 고정되면 들어가는 방향도 지금 손목의 앞쪽을 따릅니다.
   • 파지 자세 맞춤 강도 — 1 이 기본이자 권장값입니다. 0.05 처럼 낮으면 팔이 위치만 맞추고 손가락 방향은 버려서 그리퍼가 누운 채 들어옵니다.

   손가락 방향이 늘 틀어져 보이면 블록이 아니라 로봇 → 어셈블리 → 제어 설정 → 일반의 그리퍼 장착 회전으로 맞춥니다.

   📸스크린샷 누락/docs/planner/blocks-grasp-02-action-orient.png

   물체 파지 블록 — 파지 설정의 동작(접근 후 잡기 / 접근만) · 파지 자세(모델 자세 / 현재 손목 유지 / 일부 축만 유지 + 롤·피치·요 체크) · 파지 자세 맞춤 강도

3. 후보 고르기와 위치 보정을 정합니다.

   • 파지 후보 고르기 — 모델 점수 그대로 (기본) / 손가락 여유·깊이 우선. 모델 점수는 물체가 안 빠지는지만 보므로, 팔이 실제로 갈 수 있는 자세인지는 여기서 고릅니다.
   • 물체 가운데 우선 (기본 꺼짐) — 허용된 후보 중 물체 가운데에 가까운 것을 고릅니다. 가운데를 잡으면 들어 올릴 때 덜 기웁니다.
   • 물체 방향과 어긋난 파지 제외 (기본 켜짐) · 허용 어긋남 (도) (기본 35) — 길쭉한 물체를 긴 쪽으로 쥐는(90도 돌아간) 자세를 후보에서 뺍니다. 모두 빠지면 잡지 않고 실패합니다.
   • 위치 보정 — 접근축 깊이 보정 (+ 더 깊이 / − 덜) 과 손가락 닫힘축 은 파지 자세 기준이라 파지 방향이 바뀌어도 따라갑니다. 파지점 보정 x / y / z (m) 는 로봇 베이스 기준으로 잡는 지점을 밉니다(손끝이 한쪽으로 치우칠 때).

   📸스크린샷 누락/docs/planner/blocks-grasp-03-pick-offset.png

   물체 파지 블록 — 후보 고르기(파지 후보 고르기 · 물체 가운데 우선 · 물체 방향과 어긋난 파지 제외 · 허용 어긋남)와 위치 보정(접근축 깊이 보정 · 손가락 닫힘축 · x / y / z)

4. 이동과 모델 · 그리퍼 값을 정합니다.

   • 이동 — 접근 거리 (m) (기본 0.1), 들어올리기 (m) (기본 0.1), 접근 분할 수 (기본 3 — 접근 지점에서 파지 지점까지 직선으로 나눠 들어감, 1 이면 한 번에 이동).
   • 모델 · 그리퍼 — 최소 파지 점수 (기본 -1) 는 모델이 매긴 상대 점수라 정해진 범위가 없습니다(대략 -0.1~0.1, -1 이면 모두 통과). 그리퍼 최대 폭 (m), 그리퍼 (선택) (비워 두면 이 워크스페이스의 첫 그리퍼), 열림 값 / 닫힘 값.

   그리퍼로 등록된 로봇이 없으면 팔의 손끝 명령으로 여닫고, 둘 다 안 되면 잡기 전에 그렇다고 알리고 멈춥니다. 실패 설정에서는 Fallback 블록을 정할 수 있고, 카드 아래 실패 시 슬롯에 블록을 넣을 수 있습니다. 물체를 검출하지 못했거나, 검출 위치의 depth 가 무효이거나, 잡을 자세를 찾지 못했거나(최소 점수 미달), 파지 자세에 도달할 수 없으면 실패입니다.

   📸스크린샷 누락/docs/planner/blocks-grasp-04-motion-gripper.png

   물체 파지 블록 — 이동(접근 거리 · 들어올리기 · 접근 분할 수)과 모델 · 그리퍼(최소 파지 점수 · 그리퍼 최대 폭 · 그리퍼 (선택) · 열림 값 · 닫힘 값), 실패 설정

비주얼 서보잉 블록 #

손목(엔드 이펙터 장착) 카메라로 물체를 계속 검출하면서 엔드 이펙터를 한 걸음씩 움직이는 폐루프 블록입니다. 물체 위치로 이동 블록이 한 번 검출한 위치로 곧장 이동하는 데 비해, 비주얼 서보잉은 매 주기 물체를 다시 찾아 오차를 줄여 가므로 물체가 조금씩 움직이거나 검출 위치에 오차가 있어도 목표에 정확히 맞춰 갑니다.

블록은 다음 두 조건이 동시에 만족되면 끝납니다.

1. 물체 중심이 화면의 지정 위치(가로/세로 비율)에 중심 허용치(px) 안으로 들어오고,
2. 접근 축 — 거리 (뎁스) / 화면상 폭 / 화면상 높이 중 하나 — 가 목표값 ± 허용치 안에 들어온 상태가 수렴 유지 프레임 횟수만큼 연속으로 유지될 때.

1. 카메라(depth)와 워크스페이스를 선택하고 타겟을 등록합니다.

   카메라 선택, 실시간 화면, 타겟 오브젝트 지정 방식(바운딩 박스 (드래그) / 텍스트 프롬프트), 검출 민감도(conf), 워크스페이스 이미지 필터 적용 항목은 물체 위치로 이동 블록과 같은 방식으로 동작하고, 검출 엔진도 같이 고릅니다(검출 엔진 고르기). 새 비주얼 서보잉 블록은 텍스트 프롬프트 방식이 기본으로 선택됩니다 — 서보잉 중에는 카메라 시점이 계속 바뀌므로 시점 변화에 강한 텍스트 프롬프트가 유리합니다.

   📸스크린샷 누락/docs/planner/blocks-servo-01-target.png

   비주얼 서보잉 — 카메라 선택, 실시간 화면, 텍스트 프롬프트 타겟 등록

2. 카메라 캘리브레이션 상태를 확인합니다 (선택).

   타겟 등록 항목 아래에 캘리브레이션 완료 또는 미캘리브레이션 칩이 표시됩니다. 캘리브레이션은 카메라 장착 상태에 대한 정보라 (워크스페이스, 카메라) 단위로 저장되며, 이 워크스페이스에서 같은 카메라를 쓰는 모든 블록이 함께 사용합니다. 비주얼 서보잉에는 캘리브레이션이 없어도 됩니다 — 캘리브레이션이 있으면 아래 이동 방향 추정의 자동이 그 값을 써서 탐색 이동을 건너뛰고 바로 출발하고, 없으면 시작할 때 탐색 이동으로 방향을 익힙니다. 미리 해 두고 싶으면 카메라 캘리브레이션 버튼으로 진행하거나 워크스페이스 페이지에서 해 둡니다.

   📸스크린샷 누락/docs/planner/blocks-servo-02-calib-chip.png

   비주얼 서보잉 — 캘리브레이션 완료 칩과 카메라 캘리브레이션 버튼

3. 물체 중심을 데려올 화면 위치를 정합니다.

   • 가로 위치 (0~1) / 세로 위치 (0~1) — 프레임 비율로 입력합니다. 0.5 / 0.5가 화면 중앙(기본값)입니다.
   • 화면에서 지정 — 버튼을 누른 뒤 위 실시간 화면을 클릭하면 클릭한 지점이 목표 위치로 들어갑니다. 지정된 위치는 화면 위에 십자 마커로 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-servo-03-target-position.png

   비주얼 서보잉 — 가로/세로 위치 입력, 화면에서 지정 버튼, 프리뷰 위 십자 마커

4. 이동 방향 추정 방식을 고릅니다.

   화면 목표 위치 아래, 종료 조건 위에 있는 이동 방향 추정 토글입니다. 화면에서 본 오차를 로봇의 어느 방향으로 움직여 줄일지를 어떻게 알아낼지 정합니다.

   • 자동 (기본) — 카메라 캘리브레이션이 있으면 바로 출발하고, 없으면 시작할 때 상하좌우전후로 작게 움직여 보며 방향을 익힙니다.
   • 탐색 이동 — 캘리브레이션 없이 동작합니다. 시작할 때 세 방향으로 작게(기본 자동, 약 3~20mm) 움직여 보고, 이후 이동하면서 계속 보정합니다. 물체 바로 옆 좁은 공간에서는 탐색 크기를 줄이세요.
   • 캘리브레이션 — 워크스페이스 화면의 손목 카메라 캘리브레이션을 사용합니다. 탐색 이동 없이 첫 프레임부터 목표로 갑니다. 이 항목을 고르면 손목 카메라 캘리브레이션이 있어야 실행할 수 있습니다.

   📸스크린샷 누락/docs/planner/blocks-servo-08-direction.png

   비주얼 서보잉 — 이동 방향 추정 토글(자동 / 탐색 이동 / 캘리브레이션)과 선택지별 설명문

5. 종료 조건(접근 축)과 허용치를 정합니다.

   접근 축은 세 가지 중 하나를 고릅니다. 축을 바꾸면 목표값과 허용치가 그 단위에 맞는 기본값으로 바뀝니다.

   • 거리 (뎁스) — 카메라에서 물체까지의 거리(m)가 목표 거리 (m) ± 거리 허용치 (m) 안에 들면 종료합니다. 깊이 카메라의 뎁스를 사용합니다. 기본 0.15 m ± 0.01 m.
   • 화면상 폭 / 화면상 높이 — 물체가 화면에서 차지하는 크기(px)가 목표 크기 (px) ± 크기 허용치 (px) 안에 들면 종료합니다. 가까워질수록 크게 보이는 원리를 쓰므로 뎁스가 없어도 동작합니다. 기본 200 px ± 10 px.
   • 중심 허용치 (px) — 물체 중심이 지정 위치에서 이 픽셀 수 안에 들어와야 "중심에 왔다"고 봅니다. 기본 8 px.

   📸스크린샷 누락/docs/planner/blocks-servo-04-exit-condition.png

   비주얼 서보잉 — 접근 축 토글(거리/화면상 폭/화면상 높이)과 목표값·허용치·중심 허용치

6. 필요하면 제어 튜닝 접힘 항목을 열어 동작 속도와 안전 한도를 조정합니다.

   매 주기 오차 × 이득만큼 이동하되 한 걸음 상한을 넘지 않습니다. 기본값으로도 동작하므로 처음에는 그대로 두고, 움직임이 너무 느리거나 떨리면 조정합니다.

   • 이득 (0~1) — 오차 대비 이동 비율. 기본 0.5. 높이면 빨라지지만 검출 지연 때문에 진동할 수 있으므로, 속도는 이득보다 한 걸음 상한으로 조절하는 편이 안전합니다.
   • 한 걸음 상한 (m) — 한 주기에 움직이는 최대 거리. 기본 0.01 m.
   • 제어 주기 (Hz) — 초당 검출·이동 횟수. 기본 5 Hz.
   • 시간 제한 (s) — 이 시간 안에 수렴하지 못하면 실패. 기본 30 s.
   • 누적 이동 예산 (m) — 이 블록에서 움직인 누적 거리가 이 값을 넘으면 실패. 캘리브레이션 부호가 틀리거나 방향 추정이 어긋나 팔이 반대 방향으로 달아나는 것을 막는 안전 예산입니다. 시작 시 탐색 이동으로 움직인 거리도 여기에 포함됩니다. 기본 0.3 m.
   • 수렴 유지 프레임 — 종료 조건이 이 횟수만큼 연속으로 유지되어야 완료. 기본 3. 떨리면서 끝나면 늘립니다.
   • 연속 미검출 한도 — 물체를 이 횟수만큼 연속으로 놓치면 실패. 기본 10.
   • 뎁스 없을 때 가정 거리 (m) — 화면상 폭/높이 모드에서 뎁스를 읽지 못할 때 픽셀 오차를 이동량으로 바꾸는 데 쓰는 가정 거리. 기본 0.2 m.
   • 명령 선행 상한 (m) — 명령 위치가 실제 로봇 위치보다 이 값 이상 앞서 나가면 그 주기의 이동을 건너뜁니다. 기본 0.03 m.
   • 탐색 이동 크기 (m, 0=자동) — 이동 방향 추정이 캘리브레이션이 아닐 때만 표시됩니다. 시작 시 한 축당 이만큼 움직여 봅니다. 0이면 거리에 맞춰 자동. 물체 바로 옆 좁은 공간에서 탐색 중 부딪히거나 타겟을 놓치면 줄입니다. 기본 0.

   📸스크린샷 누락/docs/planner/blocks-servo-05-tuning.png

   비주얼 서보잉 — 제어 튜닝 접힘 항목 (이득 / 한 걸음 상한 / 제어 주기 / 시간 제한 / 누적 이동 예산 / 수렴 유지 프레임 / 연속 미검출 한도 / 뎁스 없을 때 가정 거리 / 명령 선행 상한 / 탐색 이동 크기)

7. 실패 설정에서 Fallback 블록을 지정합니다 (선택).

   시간 제한·누적 이동 예산·연속 미검출 한도를 넘어 실패하면 Fallback 블록으로 지정한 블록으로 넘어갑니다. 지정하지 않으면 실행이 중지됩니다.

   📸스크린샷 누락/docs/planner/blocks-servo-06-fallback.png

   비주얼 서보잉 — 실패 설정 접힘 항목의 Fallback 블록 선택

8. 결과를 변수로 저장하려면 결과 저장 변수 (선택) 에 이름을 입력합니다.

   종료 시점 요약이 저장되어 뒤따르는 조건 블록에서 쓸 수 있습니다. 저장되는 값은 done / direction / cx / cy / depth / width_px / height_px / err_px / err_approach / steps / travel 입니다. direction에는 이번 실행에서 방향을 어떤 방식으로 잡았는지(calib 또는 probe)가 들어갑니다.

   📸스크린샷 누락/docs/planner/blocks-servo-07-store-as.png

   비주얼 서보잉 — 결과 저장 변수 입력과 저장되는 값 안내

시간 대기 블록 #

다음 블록까지 지정한 시간만큼 대기합니다. 정책이 끝난 직후 사용자가 결과를 확인하거나 환경을 정리할 시간을 주고 싶을 때 유용합니다. (예전 이름 Time Sleep — 새 블록 카드에는 2초 대기 형식의 자동 이름이 붙습니다.)

1. 시간(초)을 입력하고 저장합니다.

   0보다 큰 숫자여야 합니다.

   

IO 출력 블록 #

IO 탭에 등록한 IO 장치의 출력(밸브·릴레이·램프)을 켜고 끕니다. 예를 들어 로봇이 물체 위에 도착한 뒤 흡착 밸브를 켜고, 내려놓은 뒤 끄는 식으로 동작 순서 중간에 공정 신호를 넣을 때 씁니다. 여러 채널을 고르면 실행할 때 한 번에 동시에 바뀝니다. 워크스페이스·로봇과 무관한 블록이라 워크스페이스는 고르지 않습니다.

1. 블록 종류 목록의 동작 항목에서 IO 출력을 고릅니다.

   IO 모듈이 설치되어 있지 않으면 이 항목은 IO 출력 — 모듈 관리에서 설치 필요로 비활성 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-io-01-type.png

   블록 종류 목록 — 동작 항목의 IO 출력 (설명: IO 장치의 출력을 켜고 끕니다)

2. IO 장치를 고릅니다.

   IO 장치 목록에는 IO 탭에 등록한 장치가 이름 · IP 주소 형식으로 표시됩니다. 등록한 장치가 하나뿐이면 자동으로 선택됩니다. 장치를 고르면 아래에 연결 상태가 나옵니다.

   • 연결됨 · 모델명 · 출력 N채널 — 장치가 알려 준 출력 채널 수만큼 채널이 표시됩니다.
   • 지금 연결되지 않음 — 출력 16채널로 표시합니다 (실행 전에 연결을 다시 확인합니다) — 장치가 꺼져 있어도 블록을 만들 수 있도록 16채널(이미 고른 채널이 더 높으면 그 번호까지)로 표시합니다.

   오른쪽 새로고침 아이콘(장치 상태 다시 읽기)을 누르면 연결 상태와 현재 출력을 다시 읽어 옵니다.

   📸스크린샷 누락/docs/planner/blocks-io-02-device.png

   IO 출력 블록 — 안내 문구 + IO 장치 선택 + 연결됨 · 모델 · 출력 N채널 + 장치 상태 다시 읽기

3. 출력 채널마다 켜기 / 끄기 / —(그대로)를 고릅니다.

   출력 채널 아래에 OUT 0, OUT 1 … 타일이 나오고, IO 탭에서 붙인 채널 이름이 함께 표시됩니다. 타일마다 세 가지 중 하나를 고릅니다.

   선택	실행할 때
   —	지금 상태 그대로 둡니다 (기본값).
   켜기	그 채널을 켭니다.
   끄기	그 채널을 끕니다.

   • 타일 왼쪽의 작은 점은 지금 장치의 실제 출력 상태입니다(마우스를 올리면 지금 켜져 있음 / 지금 꺼져 있음).
   • 위쪽의 모두 켜기 / 모두 끄기 / 선택 지우기는 모든 타일의 선택을 한 번에 바꿉니다. 블록 설정만 바꾸며, 장치에는 아무것도 보내지 않습니다.
   • 타일 아래에 "OUT 0(흡착 밸브), 1 켜기 · OUT 3 끄기 — 동시에 적용"처럼 요약이 표시됩니다. 아무 채널도 고르지 않으면 "켜거나 끌 채널을 하나 이상 고르세요"가 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-io-03-channels.png

   IO 출력 블록 — 출력 채널 타일(— / 켜기 / 끄기, 왼쪽 현재 상태 점) + 모두 켜기 · 모두 끄기 · 선택 지우기 + 요약 문구

4. (선택) 지금 장치에 보내 보기로 배선을 확인합니다.

   지금 장치에 보내 보기를 누르면 블록을 저장하지 않고 지금 고른 설정을 장치에 바로 보냅니다. 보내면 "장치에 보냈습니다" 알림이 뜨고 타일의 상태 점이 다시 읽혀 바뀝니다. 고른 채널이 하나도 없으면 누를 수 없습니다.

   📸스크린샷 누락/docs/planner/blocks-io-04-test-send.png

   IO 출력 블록 — 지금 장치에 보내 보기 버튼 + 적용 후 대기 (초) 입력

5. 적용 후 대기 (초)를 정하고 저장합니다.

   적용 후 대기 (초) 항목은 출력을 바꾼 뒤 다음 블록으로 넘어가기 전에 기다릴 시간입니다. 밸브·실린더가 다 움직일 시간만큼 넣습니다(0이면 기다리지 않음).

   저장할 때 IO 장치를 고르지 않았으면 "IO 장치를 고르세요", 켜거나 끌 채널이 없으면 "켜거나 끌 채널을 하나 이상 고르세요" 알림이 뜨고 저장되지 않습니다. 이름을 비워 두면 IO 작업대 밸브 IO: OUT 0,1 켜기 · OUT 3 끄기 형식으로 자동 생성됩니다.

   트랙의 카드에는 ON 0,1 · OFF 3처럼 켤 채널과 끌 채널 번호가 표시되고, 우클릭 → 상세 보기에서 IO 장치 · 켜기 · 끄기 · 적용 후 대기(설정한 경우) 값을 확인할 수 있습니다.

   📸스크린샷 누락/docs/planner/blocks-io-05-card.png

   트랙의 IO 출력 카드 — 연두색, 부제 ON 0,1 · OFF 3

실행할 때는 다음 순서로 동작합니다.

• 실행 시작 전 검사 — 플랜을 시작하기 전에 장치가 등록되어 있는지, IO 모듈이 설치되어 있는지, 장치가 응답하는지, 고른 채널 번호가 그 장치에 있는지 확인합니다. 하나라도 맞지 않으면 실행이 시작되지 않습니다. 로봇이 몇 블록 움직인 뒤에야 IO 문제로 멈추는 일을 막기 위해서입니다.
• 동시에 적용 — 켜기·끄기로 고른 채널이 명령 한 번으로 한꺼번에 바뀝니다. 그 채널에서 IO 탭의 펄스 출력이 돌고 있으면 먼저 멈춘 뒤 바꿉니다.
• 확인 — 바꾼 뒤 출력을 다시 읽어 실제로 그 상태가 됐는지 확인합니다. 바뀌지 않았거나 장치가 응답하지 않으면 블록이 실패로 끝납니다.
• 대기 — 적용 후 대기 (초) 값만큼 기다린 뒤 다음 블록으로 넘어갑니다.

• 카드 경고 — IO 탭에서 이 블록의 장치를 삭제하면 카드에 "이 블록의 IO 장치가 IO 탭에서 삭제됐습니다 — 다른 장치를 고르세요", IO 모듈이 없으면 "IO 모듈이 설치돼 있지 않아 이 블록을 실행할 수 없습니다" 경고 아이콘이 표시됩니다.
• 자가학습 — 자가학습 롤아웃에서도 같은 방식으로 동작합니다.

IO 감지 조건 블록 #

IO 탭에 등록한 IO 장치의 입력(센서·버튼)이 1(켜짐) 인지 0(꺼짐) 인지 보고 갈래를 나누는 제어 블록입니다. 조건이 맞으면 맞으면 갈래를, 아니면 아니면 갈래를 실행합니다. 지금 값으로 한 번만 볼 수도 있고, 조건이 맞을 때까지 정한 시간만큼 기다릴 수도 있습니다. 예를 들어 "부품 도착 센서(IN 0)가 1이 될 때까지 최대 10초 기다렸다가 집고, 안 오면 경광등을 켜서 알리기"를 블록 하나로 만들 수 있습니다. 워크스페이스·로봇과 무관한 블록이라 워크스페이스는 고르지 않습니다.

1. 블록 종류 목록의 제어 (조건 · 반복) 항목에서 IO 감지 조건을 고릅니다.

   IO 모듈이 설치되어 있지 않으면 이 항목은 IO 감지 조건 — 모듈 관리에서 설치 필요로 비활성 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-ioif-01-type.png

   블록 종류 목록 — 제어 (조건 · 반복) 항목의 IO 감지 조건 (설명: IO 입력(센서·버튼)이 1인지 0인지 보고 갈래를 나눕니다)

2. IO 장치를 고릅니다.

   블록 창 맨 위에 "채널마다 1(켜짐) 또는 0(꺼짐)을 고르세요. 조건이 맞으면 "맞으면" 갈래, 아니면 "아니면" 갈래를 실행합니다. —는 보지 않는 채널입니다." 안내가 있습니다. IO 장치 목록에는 IO 탭에 등록한 장치가 이름 · IP 주소 형식으로 표시되고, 등록한 장치가 하나뿐이면 자동으로 선택됩니다. 장치를 고르면 아래에 연결 상태가 나옵니다.

   • 연결됨 · 모델명 · 입력 N · 출력 N — 장치가 알려 준 채널 수만큼 채널이 표시됩니다.
   • 지금 연결되지 않아 채널 수를 모릅니다 — 입력·출력 각 16채널로 표시합니다 (실행 전에 다시 확인합니다) — 장치가 꺼져 있어도 블록을 만들 수 있도록 16채널(이미 고른 채널이 더 높으면 그 번호까지)로 표시합니다.

   블록 창이 열려 있는 동안 0.5초마다 장치를 읽어 아래의 채널 상태와 판정을 새로 고칩니다.

   📸스크린샷 누락/docs/planner/blocks-ioif-02-device.png

   IO 감지 조건 블록 — 안내 문구 + IO 장치 선택 + 연결됨 · 모델 · 입력 N · 출력 N

3. 입력 채널마다 — / 1 / 0 을 고릅니다.

   입력 채널 아래에 IN 0, IN 1 … 타일이 나오고, IO 탭에서 붙인 채널 이름이 함께 표시됩니다. 타일마다 세 가지 중 하나를 고릅니다.

   선택	뜻
   —	이 채널은 보지 않습니다 (기본값).
   1	이 채널이 켜져 있으면 맞습니다.
   0	이 채널이 꺼져 있으면 맞습니다.

   • 타일 왼쪽의 작은 점은 지금 장치의 값입니다(마우스를 올리면 지금 1 / 지금 0, 연결이 안 되면 지금 값을 모름 (연결 안 됨)). 센서를 손으로 가려 보거나 버튼을 눌러 보며 어느 채널인지 맞출 수 있습니다.
   • 오른쪽 위의 선택 지우기는 모든 채널을 — 로 되돌립니다.
   • 출력이 지금 켜져 있는지(예: 밸브가 열려 있는지)로 나누려면 출력 상태로 판단을 펼칩니다. OUT 0, OUT 1 … 타일이 나오고, 입력과 같은 방식으로 — / 1 / 0 을 고릅니다. 입력이 없는 장치는 "이 장치에는 입력이 없습니다 — 아래 출력 상태로만 판단할 수 있습니다" 안내와 함께 이 항목이 펼쳐진 채로 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-ioif-03-channels.png

   IO 감지 조건 블록 — 입력 채널 타일(— / 1 / 0, 왼쪽 지금 값 점, 채널 이름) + 선택 지우기 + 출력 상태로 판단 펼침

4. 여러 채널을 골랐다면 묶는 방식을 고르고, 요약과 지금 값 판정을 확인합니다.

   두 채널 이상을 고르면 여러 채널일 때 항목이 나타납니다.

   • 모두 맞으면 — 고른 채널이 전부 맞아야 맞으면 갈래로 갑니다 (기본값).
   • 하나라도 맞으면 — 고른 채널 중 하나만 맞아도 맞으면 갈래로 갑니다.

   그 아래 상자에 IN 0(부품 도착) = 1 그리고 IN 1 = 0 이면 "맞으면" 갈래처럼 조건 요약이 표시됩니다(하나라도 맞으면을 고르면 그리고 대신 또는). 장치가 연결되어 있으면 지금 값으로 미리 판정한 결과가 함께 표시됩니다.

   • 지금 값으로는 맞음 — 지금 실행하면 "맞으면" 갈래로 갑니다
   • 지금 값으로는 맞지 않음

   아무 채널도 고르지 않으면 "1 또는 0으로 볼 채널을 하나 이상 고르세요"가 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-ioif-04-summary.png

   IO 감지 조건 블록 — 여러 채널일 때(모두 맞으면 / 하나라도 맞으면) + 조건 요약 + 지금 값으로는 맞음 표시

5. 판단 방식을 고르고 저장합니다.

   판단 방식에서 둘 중 하나를 고릅니다.

   판단 방식	동작
   지금 한 번 확인 (기본값)	블록에 닿은 순간의 값으로 바로 판단합니다. 아니면 갈래가 비어 있으면 그냥 다음 블록으로 갑니다.
   맞을 때까지 기다리기	조건이 맞을 때까지 기다렸다가 맞으면 갈래로 갑니다. 최대 기다리는 시간 (초) 안에 맞지 않으면 아니면 (시간 초과) 갈래로 갑니다. 이 갈래가 비어 있으면 블록이 실패해 멈춥니다.

   맞을 때까지 기다리기를 고르면 최대 기다리는 시간 (초) 입력 칸이 나옵니다(기본값 10초).

   저장할 때 IO 장치를 고르지 않았으면 "IO 장치를 고르세요", 1 또는 0으로 고른 채널이 없으면 "1 또는 0으로 볼 채널을 하나 이상 고르세요", 기다리기인데 기다리는 시간이 비어 있거나 0 이하이면 "기다리는 시간을 0보다 크게 넣으세요" 알림이 뜨고 저장되지 않습니다. 이름을 비워 두면 작업대 IO 감지: IN 0 = 1 그리고 IN 1 = 0(기다리기면 작업대 IO 기다리기: IN 0 = 1) 형식으로 자동 생성됩니다. 우클릭 → 상세 보기에서 IO 장치 · 조건 · 판단 방식(기다리기면 최대 기다리는 시간까지)을 확인할 수 있습니다.

   📸스크린샷 누락/docs/planner/blocks-ioif-05-mode.png

   IO 감지 조건 블록 — 판단 방식 토글(지금 한 번 확인 / 맞을 때까지 기다리기) + 방식별 안내 문구 + 최대 기다리는 시간 (초) 입력

6. 트랙에 생긴 갈래마다 블록을 넣습니다.

   저장하면 이 블록은 다른 블록을 담는 연두색 상자로 표시되고, 머리에 IN0=1 · IN1=0 처럼 조건 배지가 붙습니다(하나라도 맞으면이면 IN0=1 or IN1=0, 기다리기면 뒤에 ≤10s 처럼 최대 기다리는 시간). 블록 아래에 맞으면 갈래와 아니면 갈래(기다리기면 아니면 (시간 초과)), 그리고 실패 시 슬롯이 생깁니다. 갈래 이름 옆의 +(여기에 블록 추가)를 누르거나 블록을 끌어다 넣습니다.

   실패 설정의 Fallback 블록은 다른 제어 블록과 같은 방식으로 정합니다. 이 블록(또는 그 안의 블록)이 실패하면 실패 시 슬롯의 블록을 돌린 뒤 Fallback 블록으로 이동하고, 실패 처리가 없으면 플랜이 그 자리에서 멈춥니다.

   📸스크린샷 누락/docs/planner/blocks-ioif-06-tree.png

   트랙의 IO 감지 조건 블록 — 연두색 상자, IN0=1 ≤10s 배지, 맞으면 / 아니면 (시간 초과) 갈래와 + (여기에 블록 추가), 실패 시 슬롯

실행할 때는 다음과 같이 동작합니다.

• 실행 시작 전 검사 — 플랜을 시작하기 전에 장치가 등록되어 있는지, IO 모듈이 설치되어 있는지, 장치가 응답하는지, 고른 채널이 그 장치에 있는지 확인합니다. 입력이 없는 장치에 입력 조건을 걸었으면 여기서 막힙니다. 하나라도 맞지 않으면 실행이 시작되지 않습니다.
• 지금 한 번 확인 — 블록에 닿은 순간 장치를 한 번 읽어 맞으면 맞으면 갈래, 아니면 아니면 갈래를 실행합니다.
• 맞을 때까지 기다리기 — 0.05초마다 장치를 다시 읽다가 조건이 맞는 순간 맞으면 갈래로 갑니다. 최대 기다리는 시간이 지나면 아니면 (시간 초과) 갈래로 가고, 이 갈래가 비어 있으면 블록이 실패합니다. 부품이 오지 않았는데 로봇이 다음 동작을 그대로 하는 일을 막기 위해서입니다. 기다리는 중에 중지를 누르면 바로 멈춥니다.
• 장치 문제는 실패 — 실행 중 장치가 응답하지 않거나 고른 채널이 장치에 없으면 아니면 갈래로 가지 않고 블록이 실패합니다. 장비가 멈춘 것을 모르고 지나가지 않도록 실패 시 블록 · Fallback 블록으로 처리합니다. 갈래 안의 블록이 실패해도 같은 실패 처리로 옵니다.
• 카드 경고 — 맞을 때까지 기다리기인데 아니면 갈래가 비어 있으면 카드에 "기다리다 시간이 지나면 이 블록이 실패해 멈춥니다 — 계속하려면 "아니면" 갈래에 블록을 넣으세요" 경고 아이콘이 표시됩니다. IO 탭에서 장치를 삭제했거나 IO 모듈이 없을 때의 경고는 IO 출력 블록과 같습니다.
• 자가학습 — 자가학습 롤아웃에서도 같은 방식으로 동작합니다.
• 내보내기 — 이 블록이 든 플래너는 플래너 내보내기(독립 실행 zip)로 내보낼 수 없습니다.

물체 감지 조건 블록 #

카메라로 물체를 한 번 감지해, 감지되면 then 갈래를, 감지 안 되면 실패 시 갈래를 실행하는 제어 블록입니다. 블록 종류 목록의 제어 (조건 · 반복) 항목에 있습니다. 새 블록 카드에는 감지 조건: 대상 형식의 자동 이름이 붙고, 머리에 ∃ 대상 배지가 표시됩니다.

이 블록은 감지됐는지만 봅니다. 위치나 거리 조건이 없고 결과를 변수로 남기지도 않으므로, Depth 를 끈 카메라도, 카메라 캘리브레이션을 하지 않은 카메라도 쓸 수 있습니다. 검출 우선순위와 캘리브레이션 항목도 블록 창에 나오지 않습니다.

1. 카메라를 고르고 검출 설정을 채웁니다.

   카메라를 고르면 아래에 실시간 화면이 표시됩니다. 검출 엔진, 타겟 지정(레퍼런스 박스 / 텍스트 프롬프트 / 커스텀 YOLO 의 비전 모델 · 찾을 물체), 감지 영역, 검출 민감도 (conf), 워크스페이스 이미지 필터 적용은 다른 검출 블록과 같습니다. 검출 추적으로 지금 화면에서 잡히는지 확인한 뒤 저장합니다.

   📸스크린샷 누락/docs/planner/blocks-detectif-01-form.png

   물체 감지 조건 블록 창 — 카메라 선택(Depth 불필요 안내), 검출 엔진, 타겟 지정, 감지 영역, 검출 민감도, '감지되면 then, 감지 안 되면 실패 시(else)로 갑니다' 안내

2. then 과 실패 시 갈래에 블록을 넣습니다.

   저장하면 트랙의 블록 아래에 then 과 실패 시 갈래가 생깁니다. 갈래 이름 옆의 +(여기에 블록 추가)를 누르거나 블록을 끌어다 넣습니다. 비운 갈래는 아무것도 실행하지 않습니다.

   실패 시 갈래로 가는 경우는 다음 셋입니다.

   • 물체가 감지되지 않음
   • 검출 자체가 오류로 끝남(카메라 응답 없음 등)
   • then 갈래 안의 블록이 실패함

   📸스크린샷 누락/docs/planner/blocks-detectif-02-branches.png

   트랙의 물체 감지 조건 블록 — ∃ 대상 배지, then 갈래와 실패 시 갈래, 갈래별 + (여기에 블록 추가) 버튼

3. 필요하면 실패 설정에서 Fallback 블록을 정합니다.

   실패 설정의 Fallback 블록을 정하면 실패 시 갈래의 블록을 다 돌린 뒤(갈래가 비어 있으면 바로) 그 블록으로 이동합니다. 정하지 않으면 다음 블록으로 계속합니다.

   📸스크린샷 누락/docs/planner/blocks-detectif-03-fallback.png

   물체 감지 조건 블록 창 — 실패 설정 펼침: else 슬롯이 곧 실패 시라는 안내와 Fallback 블록 선택

물체 감지 블록 #

로봇을 움직이지 않고 카메라로 물체를 검출해, 결과(found · 개수 · 신뢰도 · 마스크 크기 · 픽셀 중심 · 거리 · 3D 좌표 등)를 결과 저장 변수에 남기는 블록입니다. 새 블록 카드에는 감지: 대상 형식의 자동 이름이 붙습니다.

예전 블록을 열면 다음 항목이 보입니다.

• 카메라(depth) · 검출 엔진 · 타겟 지정 · 감지 영역 · 검출 민감도 · 검출 우선순위 · 카메라 캘리브레이션 — 물체 위치로 이동 블록과 같습니다.
• 결과 저장 변수 (선택) — 검출 결과를 이 변수로 저장합니다(found / count / conf / mask_px / cx / cy / depth / x / y / z 와 물체 주축 방향 yaw · elongation · size_l · size_w). 뒤의 조건 분기 블록에서 씁니다.
• 미검출 시 블록 에러로 중단 — 켜면 물체를 찾지 못했을 때 블록이 오류로 끝납니다. 끄면 found 가 거짓인 채로 다음 블록으로 갑니다.

에이전트 액션 블록 #

플랜이 이 블록에 오면 에이전트가 카메라 영상을 보고 로봇을 직접 움직여 블록의 작업 지시를 수행합니다. 물체가 매번 다른 곳에 놓이는 것처럼 고정된 동작으로 짜기 어려운 구간에 씁니다. 플랜은 에이전트가 끝날 때까지 기다리고, 에이전트가 성공으로 끝내야 다음 블록으로 넘어갑니다.

1. 블록 종류 목록의 에이전트 항목에서 에이전트 액션을 고릅니다.

   플래너에 워크스페이스가 여러 개면 먼저 워크스페이스를 고릅니다. 새 블록은 그 워크스페이스 에이전트 설정의 작업 지시 · 시작할 때 홈포즈로 이동 · 전략 · 카메라 · 고급 설정 · 안전 기능을 그대로 담고 시작합니다.

   📸스크린샷 누락/docs/planner/blocks-agent-00-type.png

   블록 종류 목록 — 에이전트 항목 아래 에이전트 액션 / 에이전트 판단 (Claude · GPT · Gemini 모듈 중 하나 설치 상태)

2. 작업 지시 · 시작할 때 홈포즈로 이동 · 전략을 확인하고 고칩니다.

   • 작업 지시 — 이 블록에서 에이전트가 수행할 일입니다. 예: 빨간 큐브를 집어서 흰 접시 위에 올려 줘. 오른쪽 마이크 버튼을 누르고 말한 뒤 종료를 누르면 말한 내용이 작업 지시 칸에 들어갑니다. 블록 설정이므로 이때 실행되지는 않습니다.
   • 워크스페이스 설정으로 — 작업 지시 칸 아래 오른쪽 버튼입니다. 누르면 작업 지시 · 전략 · 세부 설정을 워크스페이스의 에이전트 설정으로 다시 채웁니다.
   • 시작할 때 홈포즈로 이동 — 켜면 이 블록이 시작할 때 먼저 워크스페이스 홈포즈로 간 뒤 작업합니다.
   • 전략 — 전략 고르기로 이 블록의 에이전트에게 줄 전략을 고릅니다(최대 8개). 고른 전략만 작업 지시와 함께 에이전트에게 갑니다. 전략을 만들고 고치는 방법은 에이전트 설정을 참고하세요.

   📸스크린샷 누락/docs/planner/blocks-agent-01-form.png

   에이전트 액션 블록 — 작업 지시 입력(마이크 버튼) + 워크스페이스 설정으로 버튼 + 시작할 때 홈포즈로 이동 토글 + 전략 고르기

3. 필요하면 세부 설정을 펼쳐 카메라 · 고급 설정 · 안전 기능을 고칩니다.

   세부 설정에는 워크스페이스 에이전트 설정에서 가져온 값이 들어 있습니다. 각 항목의 뜻은 에이전트 설정과 같습니다.

   • 에이전트가 볼 카메라 — 체크한 카메라만 에이전트가 봅니다. 깊이 카메라에는 Depth 배지와 캘리브레이션 상태가 함께 표시됩니다. 체크한 카메라는 블록이 실행될 때 켜져 있어야 합니다.
   • 고급 설정 — EE 오프셋, 모델, 추론 강도, 호출 예산, 이동 속도, 깊이(Depth) 사용, 한 번에 하는 동작, 추가 시스템 프롬프트
   • 안전 기능 — 작업 영역 상자, 한 번 이동 상한, 접촉 멈춤, 엄격 모드. 꺼 둔 안전 기능이 있으면 창 아래에 "안전 기능이 꺼져 있습니다: …" 경고가 빨갛게 표시됩니다.

   📸스크린샷 누락/docs/planner/blocks-agent-02-settings.png

   에이전트 액션 블록 — 세부 설정 펼침(에이전트가 볼 카메라 · 고급 설정 · 안전 기능)

4. 실패 설정을 확인하고 저장합니다.

   Fallback 블록과 카드 아래 실패 시 슬롯은 다른 블록과 같은 방식으로 동작합니다. 반복 모드는 블록에 없습니다. 같은 작업을 되풀이하려면 에이전트 액션 블록을 플래너의 반복 블록 안에 넣습니다.

   저장할 때 작업 지시가 비어 있으면 "작업 지시를 입력하세요"가 표시되고 저장되지 않습니다. 이름을 비워 두면 에이전트: <작업 지시 앞부분> 형식으로 자동 생성되고, 카드에는 작업 지시가 부제로 표시됩니다. 우클릭 → 상세 보기에서 워크스페이스 · 작업 지시 · 모델 · 호출 예산을 확인할 수 있습니다.

   📸스크린샷 누락/docs/planner/blocks-agent-04-fallback.png

   에이전트 액션 블록 — 실패 설정(Fallback 블록) + 저장 버튼, 트랙의 진한 보라 카드(부제: 작업 지시)

실행할 때는 다음과 같이 동작합니다.

• 실행 시작 전 검사 — 플랜을 시작하기 전에 블록의 모델을 쓸 수 있는지, 블록 설정이 올바른지, 워크스페이스의 로봇이 켜져 있는지 확인합니다. 카메라 상태는 블록을 실행할 때 다시 확인합니다.
• 워크스페이스 설정 따르기 — 블록에 적혀 있지 않은 설정(예: 플래너 AI가 작업 지시만 적어 만든 블록)은 실행할 때 워크스페이스 에이전트 설정을 따릅니다.
• 새 대화로 시작 — 블록은 실행할 때마다 새 대화로 시작합니다. 앞선 실행의 대화를 이어 받지 않습니다.
• 성공과 실패 — 에이전트가 성공으로 끝내면 다음 블록으로 넘어갑니다. 에이전트가 실패로 끝내거나, 호출 예산을 다 쓰거나, 오류가 나거나, 작업자가 에이전트 중지를 누르면 블록이 실패합니다. 실패하면 실패 시 블록 / Fallback 블록으로 이어지고, 실패 처리가 없으면 플랜이 그 자리에서 멈춥니다.
• 카드 배지 — 실행 중에는 카드에 4/30처럼 지금까지 쓴 호출 수 / 호출 예산이 붙고, 에이전트가 답을 기다리는 동안에는 주황색 질문 배지가 함께 붙습니다.
• 자가학습 — 자가학습의 모니터에서도 실행 중인 블록이 에이전트 액션 블록이면 아래와 같은 로봇 에이전트 패널이 표시됩니다.

실행 중 끼어들기 — 로봇 에이전트 패널 #

플랜 실행 중 에이전트 액션 블록이 돌면, 블록 트랙과 하단 모니터링 윈도우 사이에 로봇 에이전트 패널이 나타납니다. 같은 패널이 에이전트로 녹화와 자가학습 모니터에도 나타납니다.

• 머리줄 — 로봇 에이전트 · <블록 이름> 제목, 음성 스위치, 상태(실행 중 등), 지금 하는 단계(보는 중 · 생각 중 · 움직이는 중 · 답을 기다리는 중 등), 호출 n/max, 에이전트 중지 버튼이 표시됩니다.
• 작업 지시 / 에이전트의 질문 — 머리줄 아래에 작업 지시가 보이고, 에이전트가 작업자에게 물은 것이 있으면 에이전트의 질문 상자로 강조됩니다.
• 최근 결정 — 에이전트의 최근 결정 몇 개(결정 N)와 그때 한 동작, 작업자가 보낸 말과 전달 상태가 표시됩니다.
• 입력창 — 메시지를 적고 Enter 또는 보내기 버튼을 누르면 에이전트의 다음 결정부터 반영됩니다. 에이전트가 질문한 상태라면 보낸 메시지가 그 질문의 답이 됩니다.
• 말로 보내기 — 마이크 버튼을 누르고 말한 뒤 종료를 누르거나, M 키를 누르고 있는 동안 말하고 떼면 그 내용이 바로 에이전트에게 전달됩니다. 패널이 여러 개면 M 키는 맨 위 패널에만 동작합니다.
• 음성 스위치 — 머리줄의 스피커 모양 스위치입니다. 켜면 에이전트가 결정마다 남기는 말을 읽어 주고, 다 읽은 뒤에 움직입니다. 실행 중에도 켜고 끌 수 있고, 켜고 끈 상태는 이 브라우저의 모든 로봇 에이전트 패널에 함께 적용됩니다. 브라우저가 음성 읽기를 지원할 때만 보이며, 언어 · 이름 · 말투는 워크스페이스 에이전트 설정의 음성 안내 설정을 따릅니다.
• 전략으로 저장 — 에이전트가 성공으로 끝나면 결과 아래에 나타납니다. 누르면 AI가 이번 실행의 진행 기록으로 전략 초안을 쓰고, 이 워크스페이스 태그가 붙은 전략 창이 열립니다. 확인하고 고쳐서 저장하면 버튼이 전략으로 저장됨으로 바뀝니다.

에이전트 판단 블록 #

질문 하나와 선택지 여러 개를 두면, 플랜이 이 블록에 왔을 때 에이전트가 지금 카메라 그림을 보고 선택지 하나를 고릅니다. 플랜은 고른 선택지의 갈래에 넣어 둔 블록들을 실행한 뒤 다음 블록으로 넘어갑니다. "바코드가 보이는지", "상자가 비었는지"처럼 장면을 보고 흐름을 나눠야 할 때 씁니다. 에이전트는 로봇을 움직이지 않고 한 번 보고 고르기만 합니다.

1. 블록 종류 목록의 에이전트 항목에서 에이전트 판단을 고르고 질문을 적습니다.

   플래너에 워크스페이스가 여러 개면 먼저 워크스페이스를 고릅니다. 질문에는 에이전트에게 물을 내용을 적습니다. 예: 지금 바코드가 보이나요?

   📸스크린샷 누락/docs/planner/blocks-decide-01-question.png

   에이전트 판단 블록 — 안내 문구 + 워크스페이스 선택 + 질문 입력

2. 선택지를 2~8개 적고 저장합니다.

   새 블록에는 선택지 1, 선택지 2 칸이 있습니다. 선택지 추가로 최대 8개까지 늘리고, 칸 오른쪽 × 로 뺍니다(선택지가 2개뿐이면 뺄 수 없습니다). 갈래에 블록을 넣어 둔 선택지는 뺄 수 없고, "이 선택지의 갈래에 블록이 있습니다. 블록을 먼저 옮기거나 지우세요."가 표시됩니다. 실패 설정의 Fallback 블록은 다른 블록과 같은 방식으로 정합니다.

   저장할 때 질문이 비어 있으면 "질문을 입력하세요", 빈 선택지가 있거나 선택지가 2개보다 적으면 "선택지를 두 개 이상 채우세요", 같은 선택지가 두 번 있으면 "같은 선택지가 두 번 있습니다."가 표시되고 저장되지 않습니다. 이름을 비워 두면 판단: <질문 앞부분> 형식으로 자동 생성됩니다.

   📸스크린샷 누락/docs/planner/blocks-decide-02-choices.png

   에이전트 판단 블록 — 선택지 (1)(2)… 입력 칸과 × 버튼, 선택지 추가, 갈래 안내 문구, 실패 설정(Fallback 블록)

3. 트랙에 생긴 갈래마다 블록을 넣습니다.

   저장하면 이 블록은 다른 블록을 담는 상자로 표시되고, 머리에 선택지 N개 배지가 붙습니다. 선택지마다 (1) 예, (2) 아니오 같은 갈래가 생기고, 그 아래에 실패 시 슬롯이 있습니다. 갈래의 + 로 그 선택지를 골랐을 때 실행할 블록을 넣습니다. 비워 둔 갈래는 아무것도 하지 않고 다음 블록으로 넘어갑니다.

   📸스크린샷 누락/docs/planner/blocks-decide-03-tree.png

   트랙의 에이전트 판단 블록 — 선택지 N개 배지 + (1) 예 / (2) 아니오 갈래와 갈래 안의 블록 + 실패 시 슬롯

실행할 때는 다음과 같이 동작합니다.

• 실행 시작 전 검사 — 질문과 선택지가 올바른지, 그 워크스페이스에 에이전트 설정이 있고 그 모델을 쓸 수 있는지, 워크스페이스의 로봇이 켜져 있는지 확인합니다.
• 고르기 — 에이전트가 워크스페이스 에이전트 설정의 모델 · 카메라로 지금 그림을 한 번 보고 선택지 하나를 고릅니다. 고른 결과는 에이전트 판단 → (1) 예처럼 알림으로 뜨고, 그 아래에 고른 까닭이 함께 표시됩니다.
• 실패 — 에이전트가 고르지 못하면(모델 오류 · 카메라 그림 없음) 블록이 실패해 실패 시 블록과 Fallback 블록으로 이어집니다. 고른 갈래 안의 블록이 실패해도 같은 실패 처리로 옵니다. 실패 처리가 없으면 플랜이 멈춥니다.
• 끼어들기 없음 — 판단은 한 번의 질문이라 로봇 에이전트 패널이 나타나지 않고, 글이나 말로 바로잡을 수 없습니다. 잘못 고르기 쉬운 장면이라면 갈래 안에 판단 블록을 하나 더 두어 다시 확인하게 구성합니다.
• 자가학습 — 자가학습 롤아웃에서도 같은 방식으로 갈래를 고릅니다.

플랜 종료 블록 #

실행이 이 블록에 닿으면 플랜을 여기서 끝냅니다. 같은 줄에서 뒤에 있는 블록은 실행되지 않고, 반복 실행(무한 반복 포함)의 남은 회차도 돌지 않습니다. "조건이 맞으면 더 할 일이 없으니 끝낸다"처럼 플랜을 중간에 정상 종료시키고 싶을 때 사용합니다.

블록 종류 목록의 제어 (조건 · 반복) 항목에서 플랜 종료를 고릅니다. 설정할 것은 이름뿐이며, 카드는 빨간색에 정지 원 아이콘으로 표시됩니다.

• 어디에 둘 수 있나 — 트랙에 바로 두는 것 외에 조건 분기 · Case · 물체 감지 조건 · 반복 · 묶음 안에도 넣을 수 있습니다. 조건 분기 안에 두면 조건이 맞을 때만 플랜이 끝납니다. 얼마나 깊이 들어 있든 그 안의 흐름만이 아니라 플랜 전체가 끝납니다.
• 결과 표시 — 플랜 종료로 끝난 실행은 완료로 표시됩니다. 사용자가 중지를 눌러 끝낸 것(중지)이나 블록이 실패해 끝난 것(오류)과는 다릅니다.
• 실패 설정과의 관계 — 종료는 실패가 아니므로, Fallback 블록이나 실패 시 슬롯 같은 실패 설정은 플랜 종료를 잡지 않습니다.
• 부분 재생 — 이 블록만 실행이나 묶음만 재생으로 돌려도 똑같이 그 지점에서 끝납니다.

블록 관리 #

추가된 블록은 트랙의 가로 카드로 표시됩니다. 각 카드에서 다음 동작을 할 수 있습니다.

• 클릭 — 카드가 선택되어 초록 테두리가 생기고, 카드 우측 상단에 이 블록만 실행 재생 버튼이 나타납니다. 한 번 더 클릭하면 선택이 풀립니다.
• 드래그 — 카드를 끌어 같은 트랙 안에서 좌우로 옮기면 실행 순서가 바뀝니다. (실행 중에는 비활성화)
• 우클릭 — 컨텍스트 메뉴로 상세 보기, 블록 편집, 블록 복제, 묶음으로 만들기, 블록 삭제 사용. 묶음 카드에서는 묶음 해제 항목이 함께 표시됩니다.
• 배지 — 시간 대기 등 시간이 있는 블록은 Ns 형태로 시간이, 학습 모델 추론 블록은 첫 번째 종료 조건의 요약(조건이 더 있으면 +N)이, 포즈 조회 블록은 호출할 서비스 이름이, 비주얼 서보잉 블록은 <타겟> · <접근 축> <목표값><단위> 형태의 요약(예: red cube · depth 0.15m)이, IO 출력 블록은 ON 0,1 · OFF 3처럼 켤 채널과 끌 채널 번호가 카드 위에 붙습니다. IO 감지 조건 블록은 머리에 IN0=1 · IN1=0 ≤10s처럼 조건(과 기다리기면 최대 기다리는 시간) 배지가 붙습니다. 에이전트 액션 블록은 실행 중에 4/30처럼 호출 수 / 호출 예산 배지가, 에이전트가 답을 기다리면 주황색 질문 배지가 붙습니다. 에이전트 판단 블록은 머리에 선택지 N개 배지가 붙습니다.

카드 좌측의 색 막대는 종류를 색으로 구분합니다 (관절 자세: 파랑, 학습 모델 추론: 보라, 포즈 조회: 남보라, 물체 위치로 이동: 분홍, 물체 파지 · 비주얼 서보잉: 진한 주황, 시간 대기: 주황, IO 출력 · IO 감지 조건: 연두, 물체 감지 조건: 호박색, 에이전트 액션 · 에이전트 판단: 진한 보라, 플랜 종료: 빨강).

여러 블록 한 번에 고르기 #

블록을 Ctrl(맥은 Cmd) + 클릭하면 이미 고른 블록에 더해지고, 고른 블록을 다시 Ctrl + 클릭하면 선택에서 빠집니다. 여러 블록을 고르면 다음 동작이 한꺼번에 적용됩니다.

• 함께 이동 — 고른 블록 중 아무거나 하나를 끌면 나머지도 순서를 유지한 채 같이 따라옵니다. 드래그 한 번으로 여러 블록을 옮길 수 있습니다.
• 개수로 바뀌는 우클릭 메뉴 — 고른 블록 중 하나를 우클릭하면 블록 복제 / 블록 삭제 항목이 3개 복제 / 3개 삭제 처럼 고른 개수로 표시되고, 고른 블록 전체가 한 번에 처리됩니다.

블록 묶음 #

여러 블록을 한 덩어리로 묶어 두는 묶음 블록입니다. 묶음은 실행 순서를 바꾸지 않습니다 — 안에 담긴 블록을 위에서 아래로 한 번 실행할 뿐이고, 여러 블록을 함께 옮기고 복사하고 일부만 돌려 보기 위한 편집과 부분 재생의 단위입니다.

묶음을 만드는 방법은 두 가지입니다.

• 고른 블록을 묶기 — 묶을 블록들을 함께 고른 뒤 우클릭 → 묶음으로 만들기(여러 개를 골랐으면 3개를 묶음으로 만들기 처럼 개수로 표시)를 누릅니다. 블록의 순서는 그대로 유지되고, 떨어져 있던 블록은 가장 앞 블록의 자리에 모입니다.
• 빈 묶음부터 만들기 — + 블록 추가를 누른 뒤 블록 종류 목록의 제어 (조건 · 반복) 항목에서 묶음을 고릅니다. 빈 묶음이 생기면 기존 블록을 끌어다 넣거나 묶음 안의 + 버튼으로 새 블록을 추가합니다.

묶음은 점선 테두리로 둘러싸인 한 덩어리로 표시되며, 다음 동작을 지원합니다.

편집 되돌리기 (Ctrl + Z) #

Ctrl(맥은 Cmd) + Z 를 누르면 방금 한 블록 편집이 되돌아갑니다. 여러 번 누르면 여러 단계까지 거슬러 올라가며, 최대 50단계까지 기억합니다. 되돌릴 수 있는 편집은 다음과 같습니다.

• 블록 추가 · 삭제 · 복제
• 블록 이동과 드래그 재정렬
• 묶음으로 만들기 · 묶음 해제

되돌릴 편집이 남아 있지 않으면 되돌릴 편집이 없습니다, 되돌리고 나면 편집을 되돌렸습니다 안내가 표시됩니다.

축소·확대와 재생 중 따라가기 #

블록 시퀀스 오른쪽 아래에 떠 있는 컨트롤입니다. 블록이 많아 한 화면에 다 들어오지 않는 긴 플랜을 볼 때 사용합니다.

• − / + — 블록 시퀀스의 배율을 한 단계씩 줄이거나 키웁니다. 40%에서 100% 사이로 조절할 수 있습니다.
• 가운데 퍼센트 숫자 — 누르면 배율이 100%로 돌아갑니다.
• 과녁 모양 버튼 — 재생 중인 블록 따라가기 토글입니다. 켜 두면(기본값 켜짐) 실행 중인 블록이 바뀔 때마다 그 카드가 화면 가운데로 오도록 자동으로 스크롤됩니다. 재생 중에 직접 스크롤해서 다른 곳을 보고 싶으면 끕니다.

플랜 실행 #

플래너는 다음 방식으로 실행합니다.

• 전체 실행 (타임라인 상단 우측) — 트랙의 블록을 처음부터 차례로 실행합니다. 버튼의 반복 배지를 누르면 반복 켜짐 — 정지를 누를 때까지 반복 / 반복 꺼짐 — 한 번만 실행이 바뀝니다.
• 이 블록만 실행 — 카드를 선택하면 카드 우측 상단에 나타나는 재생 버튼입니다. 그 블록 하나만 실행합니다.
• 이 묶음만 실행 — 묶음 카드 우측 상단의 초록 재생 버튼입니다(블록 묶음).

실행 중에는 한 스텝씩을 누르면 다음 블록 앞에서 멈춰 스텝 실행으로 바뀌고, 다음 스텝으로 한 블록씩 진행하거나 계속으로 이어서 실행합니다.

1. 실행 방식을 골라 버튼을 누릅니다.

   서버는 시작 직전에 다음을 검증합니다. 하나라도 실패하면 알림으로 원인이 표시되고 실행이 시작되지 않습니다.

   • 사용 중인 워크스페이스가 모두 존재하는지
   • 실행할 블록이 참조하는 로봇이 모두 켜져 있는지
   • 학습 모델 추론 블록의 체크포인트가 존재하고 정책이 연결되어 있는지
   • 완료 신호 종료 조건을 쓴 체크포인트가 has_succeed로 학습되어 있는지
   • 시간 대기 블록의 시간이 0보다 큰지
   • 포즈 조회 블록의 서비스 이름이 비어 있지 않고 (EE 모드일 때) 워크스페이스 로봇이 IK 가능한 단일 EE 로봇인지
   • 검출 블록의 검출 엔진을 쓸 수 있는지 — SAM 3 는 모듈이 설치되어 있는지, 커스텀 YOLO 는 비전 모델을 골랐고 그 모델이 학습되어 있으며 찾을 물체가 그 모델에 있는지
   • 물체 파지 블록이 쓰는 ZeroGrasp 파지 생성 모듈이 설치되어 있는지
   • 비주얼 서보잉 블록의 카메라(depth)가 선택되어 있고, 타겟(텍스트 프롬프트 또는 박스)이 등록되어 있고, 목표값·시간 제한·제어 주기·한 걸음 상한·이득·누적 이동 예산이 0보다 크고, 탐색 이동 크기가 0 이상인지. 이동 방향 추정을 캘리브레이션으로 고른 경우에만 손목 카메라 캘리브레이션이 있어야 합니다 (자동 / 탐색 이동은 캘리브레이션 없이도 통과합니다). 현재 요금제가 Enterprise가 아니면 저장과 실행 모두 거부됩니다
   • IO 출력 블록의 IO 장치가 등록되어 있고, IO 모듈이 설치되어 있고, 장치가 응답하고, 고른 출력 채널이 그 장치에 있는지
   • IO 감지 조건 블록의 IO 장치가 등록되어 있고, IO 모듈이 설치되어 있고, 장치가 응답하고, 조건으로 고른 입력·출력 채널이 그 장치에 있는지(입력이 없는 장치에 입력 조건을 걸면 막힘)
   • 에이전트 액션 블록의 모델을 쓸 수 있고(그 모델의 모듈 — Claude · GPT · Gemini — 이 설치되고 설정 → 에이전트에서 연동됨), 블록 설정이 올바르고, 워크스페이스의 로봇이 켜져 있는지
   • 에이전트 판단 블록의 질문과 선택지가 올바르고, 그 워크스페이스에 에이전트 설정이 있고 그 모델을 쓸 수 있으며, 워크스페이스의 로봇이 켜져 있는지

2. 현재 실행 중인 블록 카드가 파란 테두리와 스피너로 강조됩니다.

   트랙 머리줄에 진행 정보(실행 중 (현재/전체) — 블록 이름)가 표시됩니다.

3. 하단 모니터링 윈도우에서 센서/로봇 상태를 함께 확인합니다.

   학습 모델 추론 블록 실행 시 정책이 보내는 액션이 실시간으로 로봇에 반영됩니다. 모니터링 패널이 타임라인 아래로 배치되어 페이지를 자연 스크롤하면서 보면 됩니다. 에이전트 액션 블록이 실행 중이면 타임라인과 모니터링 윈도우 사이에 로봇 에이전트 패널이 함께 나타납니다. 에이전트 판단 블록이 선택지를 고르면 고른 선택지와 까닭이 알림으로 표시됩니다.

4. 각 블록이 끝나면 카드 우측 상단에 결과 아이콘이 남습니다.

   • check_circle (녹색) — 정상 완료. 플랜 종료 블록에 닿아 중간에 끝난 실행도 여기에 해당합니다.
   • cancel (주황) — 사용자 중지
   • error (빨강) — 오류로 종료. 오류 내용은 알림으로 표시됩니다.

5. 이상하거나 위험해 보이면 중지 버튼을 누릅니다.

   중지를 누르면 플랜이 즉시 중지됩니다. 실행 중인 에이전트도 함께 멈춥니다. 플랜은 계속 두고 에이전트만 멈추려면 로봇 에이전트 패널의 에이전트 중지를 누릅니다.

   

실행 중 제약 #

• 실행 중에는 새 블록 추가, 블록 편집/삭제/복제, 카드 드래그, 블록 선택, 우클릭 메뉴, 되돌리기(Ctrl + Z) 가 모두 비활성화됩니다.
• 축소·확대와 재생 중인 블록 따라가기는 실행 중에도 그대로 사용할 수 있습니다.
• 페이지를 새로 열어도 서버에서 실행 상태를 다시 받아오므로, 다른 탭/창에서도 진행 중임이 그대로 표시됩니다.

잘 안 될 때 #