Мета

Цей розділ описує повний практичний сценарій роботи з ПЗ Estun Codroid Pick-and-Place на основі фактичної реалізації в репозиторіях:

  • codroid-ball-picker — веб-інтерфейс (Dash), оркестрація калібрування, детекції, pick-and-place, моніторинг.
  • codroid-api — низькорівневий websocket/HTTP клієнт для керування роботом Codroid.
  • onrobot-api — API керування гріпером OnRobot 2FG7 через Compute Box.

Документація нижче орієнтована на роботу в лабораторній комірці з Jetson Orin Nano, OAK-D Pro та OnRobot 2FG7.

Склад ПЗ і відповідальність компонентів

  1. Веб-інтерфейс (UI) та прикладна логіка (codroid-ball-picker)
    • вкладки Applications / Monitoring / Calibration;
    • панель Setup (drawer) для підключень і конфігурації;
    • програми Verification, Manual Pick, Auto Pick & Place, Plate Pick & Place Test;
    • збереження артефактів у data/.
  2. Робот (codroid-api)
    • підключення до контролера Codroid;
    • переміщення в координатах, jog, службові команди;
    • моніторинг стану/поз.
  3. Гріпер (onrobot-api)
    • підключення до OnRobot Compute Box (XML-RPC, порт 41414);
    • команди move/grip/halt, читання стану (ширина, force, busy, gripped).

Запуск, зупинка і оновлення контейнера (Jetson)

Старт контейнера

У каталозі codroid-ball-picker:

docker compose pull

docker compose up -d

Після запуску інтерфейс доступний за адресою:

http://<IP_JETSON>:8050

Перевірка стану:

docker compose ps

docker compose logs -f ui

Зупинка контейнера

Зупинити тільки UI:

docker compose stop ui

Зупинити весь стек:

docker compose down

Оновлення контейнера

Рекомендований ручний цикл оновлення:

docker compose pull ui

docker compose up -d –force-recreate ui

Після оновлення перевірте:

docker compose ps

docker compose logs --tail=200 ui

Автоматичне оновлення (systemd timer) у цьому проєкті:

./scripts/setup_jetson_auto_update.sh

./scripts/jetson_auto_update_check.sh

Перший запуск інтерфейсу: що ви побачите

Після відкриття http://<IP_JETSON>:8050 інтерфейс стартує з вкладки Applications. У верхньому рядку відображаються статуси Camera / Robot / Gripper, а внизу — аварійні та програмні кнопки керування.

Рисунок 10.4.1. Головний екран Applications (реальний запуск UI)

Панель Setup: підключення та базова конфігурація

Кнопка Setup відкриває панель налаштувань (drawer) із ключовими групами:

  1. Camera connection (підключення камери): Scan for camera, Enable live camera stream, параметри width/height/FPS, autofocus lock.
  2. Robot connection (підключення робота): WebSocket URI, Test robot connection, Acquire robot control, Release robot control.
  3. OnRobot 2FG7: IP Compute Box, Enable gripper connection, Test gripper, орієнтація пальців.
  4. Calibration & settings (калібрування і налаштування): marker IDs/size, шляхи до calibration/workspace/robot calibration, автопараметри pick-and-place, camera safety mode.

Рисунок 10.5.1. Setup drawer: камера, робот, гріпер і збережені налаштування

Калібрування (Calibration): обов’язковий порядок перед автоматикою

Вкладка Calibration є критичною для точного pick-and-place. Вона налаштовує геометричний ланцюг:

камера -> площина робочої сцени -> система координат робота.

Призначення двох 3D-друкованих калібрувальних плит

У лабораторії використовуються дві різні плити, і вони вирішують різні задачі:

  1. Плита камерного калібрування (ChArUco board)
    Її призначення: отримати стабільні параметри камери (intrinsics) і базову прив’язку зображення до сцени.
    Без цього кроку координати об’єктів у кадрі мають систематичну похибку.
  2. Плита калібрування робота (robot calibration plate)
    Її призначення: зв’язати координати, які бачить камера, з координатами, у яких рухається робот.
    Саме цей крок дає коректне перетворення для підходу захватом до реальної точки в просторі.

Практично: перша плита калібрує «як камера бачить», друга калібрує «куди має рухатись робот».

Детальний порядок калібрування камери (Camera calibration, ChArUco)

  1. Встановіть камерну ChArUco-плиту у поле зору OAK-D Pro.
  2. На вкладці Calibration перевірте індикатор Markers detected (плата має впевнено детектуватись).
  3. Натисніть Calibrate (або Use saved calibration, якщо валідна калібровка вже є).
  4. Після завершення перевірте, що створено data/calibration_bundle.npz.

Примітка: у поточній реалізації під час камерного калібрування використовується ізольований процес захоплення; після нього живий потік (live stream) може залишитись на паузі, і його потрібно увімкнути через Setup -> Enable live camera stream.

Детальний порядок калібрування робота (Robot calibration, robot plate)

  1. Замініть ChArUco-плиту на robot calibration plate і зафіксуйте її у робочій зоні.
  2. Переконайтесь, що крайові ArUco-маркери плити стабільно видно в кадрі.
  3. Натисніть Begin calibrating robot і пройдіть модальний сценарій навчання точок.
  4. У процесі робот послідовно прив’язується до контрольних точок плити (паза 1-3).
  5. Після завершення виконайте Run verification move для валідації геометрії.
  6. Переконайтесь, що збережено data/robot_calibration.json.

Що перевірити після завершення обох кроків

  1. calibration_bundle.npz існує і завантажується без помилок.
  2. robot_calibration.json існує і verification move виконується коректно.
  3. На камері накладення (overlay) не мають помітного зсуву відносно реальної плити.
  4. Після калібрування не змінюйте положення камери або плити без повторної процедури.

Після успішного проходження система зберігає артефакти в data/ (типово: calibration_bundle.npz, workspace_definition.npz, robot_calibration.json).

Рисунок 10.6.1. Вкладка Calibration із кроками калібрування

Вкладка Applications: детальний посібник із функціоналу pick-and-place

Структура вкладки Pick & Place

Секція містить:

  1. Tracking Controls (Move target / Segmented tracking, параметри segment min/max/fraction).
  2. Розкривні блоки (accordion):
    • Detect (YOLO-модель, confidence/IOU/max detections/filter);
    • Drop Location (teach/return drop pose);
    • Auto pick & place (target class, drop ignore radius);
    • Plate Pick & Place Test (контрольований тест по plate-цілях 1 -> 2 -> 3).
  3. Pick & Drop Controls:
    • Pick closest object;
    • Drop;
    • Pick & Drop closest;
    • Reset if stuck.

Рисунок 10.7.1. Вкладка Applications: розкриті блоки Detect і Auto pick & place

Рекомендований сценарій ручного запуску pick-and-place

  1. У Setup підтвердити, що camera/robot/gripper у стані online.
  2. У Calibration переконатися, що калібрування камери й робота валідні.
  3. У Applications → Drop Location виконати Teach drop position.
  4. У Applications → Detect перевірити активну модель і параметри детекції.
  5. Виконати Pick closest object або Pick & Drop closest для перевірки одиночного циклу.
  6. Лише після успішного одиночного циклу переходити до Start Auto у футері.

Автоматичний режим (Auto pick & place): футер і перевірка передумов

Кнопки Start Auto / Stop Auto у футері активуються тільки коли виконані передумови (камера, калібрування, workspace, robot online, model, gripper, drop target). Це реалізовано через внутрішній callback prerequisites-state.

Вкладка Monitoring: інтерпретація стану системи

Вкладка Monitoring надає:

  1. System Summary — загальний стан вузлів.
  2. Detection Summary — зведення по детекції.
  3. Pick & Drop Summary — метрики циклів pick/drop.
  4. Auto Plan Summary — короткий стан планувальника автоматичного режиму.
  5. Detection Trend / Cycle Time Trend — графіки трендів.

Рисунок 10.8.1. Вкладка Monitoring: summary-картки та трендові графіки

Керування безпекою та станом виконання програми

У футері реалізовано окремі групи керування:

  1. STOP / Robot power — аварійна й силова логіка.
  2. Program control — Pause / Stop / Reset активної програми.
  3. Rescue mode / speed sliders — службові режими для відновлення контролю.
  4. Gripper fine controls — ширина, сила (force), швидкість (speed) у межах профілю гріпера.

Під час активних програм інтерфейс підсвічує стан виконання; при критичних станах (emergency stop, overspeed, joint protection, wrong tool, drag-not-allowed) відпрацьовують відповідні модальні сценарії обробки помилок.

Типові проблеми та швидка діагностика

  1. Веб-інтерфейс (UI) не відкривається
    • docker compose ps;
    • docker compose logs -f ui;
    • перевірити доступність :8050 на Jetson.
  2. Camera offline / нестабільна камера
    • перевірити Setup → Scan for camera;
    • перевірити USB кабель/порт, живлення;
    • перевірити lsusb у контейнері/на хості.
  3. Robot not connected / control released
    • Test robot connection;
    • за потреби Acquire robot control;
    • перевірити мережевий маршрут до контролера.
  4. Gripper not connected
    • перевірити IP Compute Box;
    • Test gripper;
    • переконатися, що порт 41414 досяжний.
  5. Auto не стартує
    • перевірити всі індикатори передумов (prereq badges) у футері (camera/calib/workspace/robot/model/gripper/drop).

Примітка до скріншотів цього розділу

Скріншоти 10.4.1–10.8.1 зняті з реального запуску веб-інтерфейсу (UI) на локальному стенді. Стан Camera: off, Robot: idle, Gripper: off у кадрах є очікуваним для середовища без підключеної апаратури під час документаційного запуску.

Приймальні випробування (acceptance tests) після оновлення

Після кожного оновлення обов’язково виконати:

  1. Інфраструктурна перевірка (smoke test): UI відкривається на Jetson; камера, робот і gripper проходять тест підключення.
  2. Функціональна перевірка (smoke test): індикатори передумов (prereq badges) для Auto у валідному стані; завантаження збережених калібрувань/workspace без помилок.
  3. Контрольний робочий цикл: один ручний або програмний pick -> drop; перевірка коректності позиціонування та release.
  4. Перевірка безпеки (safety check): відпрацьовує логіка pause/stop/reset; відсутні латентні emergency/overspeed-стани після тесту.

Матриця усунення несправностей

Таблиця 10.13.1. Мінімальна матриця усунення несправностей

СимптомЙмовірна причинаПеревіркаДіяЕскалація
camera offlineUSB/живлення OAK-D, завислий відеопотік (stream)lsusb, стан stream у UIперепідключити/перезапустити stream або контейнерінженер з комп’ютерного зору/Jetson
robot control releasedсесія керування (control session) не захопленастан Acquire/Release у Setupвиконати Acquire robot control і повторити тестінженер robot API
gripper timeoutCompute Box недосяжний, механічна перешкодаping/nc до Compute Box, Test gripperперевірити мережу/механіку, повторити командуінженер onrobot-api/механіки
auto start blockedне виконані передумови (prerequisites)badges у футері / стан артефактівзакрити відсутні передумови (calib/workspace/drop/model)викладач/інтегратор
overspeed/emergencyаварійний стан контролераmodal state + controller statuspause/reset, clear-процедура, повторна безпечна перевіркаінженер з безпеки/робота

Пріоритет дій завжди:

  1. Безпечна зупинка.
  2. Локалізація причини.
  3. Контрольоване відновлення.
  4. Документування інциденту.

Формат звіту про помилку

Структура звіту про помилку (обов’язкові поля):

  1. Ідентифікація: дата/час інциденту, стенд/локація, відповідальний оператор.
  2. Версії: версія образу codroid-ui, версії пакетів (за потреби), прошивка (firmware) Controller/Compute Box (якщо відомо).
  3. Кроки відтворення: точна послідовність дій, очікуваний результат, фактичний результат.
  4. Докази: витяг логів, скріншоти UI/Monitoring, релевантні файли з data/.
  5. Наслідки і пріоритет: блокуюча/критична/некритична; чи можливий тимчасовий обхід.