Призначення та межі відповідальності

codroid-api — це низькорівневий Python-клієнт для контролера Codroid, який поєднує:

  1. WebSocket-керування (команди, стани, IO, події).
  2. HTTP-операції (обмін login-ключами, читання/збереження .crp-проєктів).
  3. Уніфікований API для прикладного ПЗ (зокрема codroid-ball-picker).

Пакет не є веб-інтерфейсом (UI) і не замінює логіку прикладної програми: він надає керовані примітиви руху, моніторингу, OnRobot-викликів та доступу до даних проєкту.

Основні класи і як вони взаємодіють

  1. CodroidConfig (codroid_api/client.py)
    • зберігає host/port, токен, дані авторизації, коди команд і шляхи setparam;
    • формує ws_url.
  2. CodroidAPI (codroid_api/client.py)
    • головний асинхронний клієнт;
    • встановлює WebSocket, надсилає/читає повідомлення, виконує рухи, IO-опитування, допоміжні HTTP-операції.
  3. CodroidSettings (codroid_api/settings.py)
    • джерело конфігурації з .env (CODROID_*);
    • збирає окремі конфігурації для user-каналу і robot-каналу.
  4. RobotSession (codroid_api/robot_session.py)
    • довгоживуча сесія з фоновими задачами прослуховування і опитування (listener/poll);
    • знімає з UI необхідність вручну керувати reconnect, posture/DI/status snapshots, release/acquire control.

Канали підключення і модель авторизації

У поточній реалізації використовуються два WebSocket-канали:

  1. Канал користувача (User channel) (типово ws://<host>:9098/)
    • ws_login_with_password() або ws_login();
    • призначений для користувацьких дій і узгодження з веб-сесією.
  2. Канал робота (Robot channel) (типово ws://<host>:9000/)
    • robot_login();
    • виконує команди руху/стану робота.

Паралельно застосовується HTTP-процедура login (handshake):

  1. GET /code/init (отримання pub/pri ключів),
  2. POST /user/login (шифровані дані запиту через _asencode()),
  3. передача отриманого usercode у wslogin.

Ця схема реалізована в http_login() + ws_login_with_password().

Структура WebSocket-повідомлень

Метод build_message() формує уніфікований формат:

  • id — ідентифікатор повідомлення (message id);
  • time — unix-time в ms;
  • token — токен сесії;
  • type — простір імен (namespace) повідомлення (user, Robot, common, IOManager, projexecute …);
  • action — команда;
  • data — дані повідомлення (payload).

Ключові транспортні примітиви:

  1. send_message() — надсилання JSON у WebSocket;
  2. recv(timeout=…) — читання черги вхідних повідомлень;
  3. listen() — асинхронний стрім усіх повідомлень;
  4. send_and_wait(…, predicate=…) — патерн request/response із фільтрацією відповіді.

Командна модель Robot/Control/*

Керування реалізоване через common.setparam і шляхи Robot/Control/….

ПараметрПризначенняДе у коді
Robot/Control/commandзапуск команд (power/mode/move/error clear)RobotControlPaths.command
Robot/Control/commandHeartheartbeat для утримуваних командsend_command_heartbeat()
Robot/Control/manualMoveRateмножник ручної швидкостіset_manual_move_rate()
Robot/Control/jogModeрежим jog (stop/joint/tcp)RobotJogMode
Robot/Control/jogIndexвісь jogset_jog_index()
Robot/Control/jogSpeedнапрям/швидкість jog (-1/0/1)set_jog_speed()
Robot/Control/jogReferencereference frame (coordinate/tool)RobotJogReference
Robot/Control/targetPosTypeтип цілі (none/apos/cpos)RobotTargetPosType
Robot/Control/targetAPosціль у joint-spaceset_target_apos()
Robot/Control/targetCPosціль у cartesian-spaceset_target_cpos()

Набір кодів команд за замовчуванням (RobotCommandSet):

  1. 1 power on, 2 power off, 3 manual mode, 4 rescue mode, 5 auto mode;
  2. 501 clear error;
  3. 104/1001/1002/105 — preset moves (home/safe/candle/package);
  4. 106/107 — цільові переміщення (linear/optimal).

Рух: від jog до цільових траєкторій

Jog-режим

start_joint_jog() і start_tcp_jog() виконують послідовність:

  1. виставити jogMode,
  2. виставити jogSpeed (напрям),
  3. виставити jogIndex (вісь),
  4. за потреби надіслати heartbeat.

hold_jog() підтримує рух впродовж hold_seconds і завершує stop_jog().

Цільові переміщення (Target moves)

move_to_*_target_*() використовують двоетапну модель:

  1. запис цілі (targetPosType + targetAPos/targetCPos),
  2. подача команди 106 або 107.

Після виконання (за reset_after=True) API очищає вибір цілі (target selection, targetPosType = none) і скидає команду.

Формування даних позицій (payload)

  • build_target_apos([…]) — joint payload (jntpos1..7, exjntpos1..10).
  • build_target_cpos(x,y,z,a,b,c,…) — cartesian payload (x,y,z,a,b,c,e,poscfg,…).
  • build_poscfg(mode, cf) — posture-конфігурація для CPOS.

Калібрування координат у codroid-api

Код реалізує повний 3-точковий цикл:

  1. підготовка трьох CPOS-точок;
  2. coordinate_calibration(points, coordinate_id, …):
    • валідує рівно 3 точки;
    • (опційно) активує слот координат (coordinate slot) через SetCurrentCoordinateId;
    • надсилає Robot/CoordinateCalibration і чекає відповідь.
  3. change_coordinate_parameter(coordinate_id, frame):
    • зберігає обчислений frame у користувацький слот координат контролера (user coordinate slot).

Для швидкого підходу до початку користувацької СК передбачено move_to_coordinate_origin(coordinate_id, linear=…, hold_seconds=…).

Моніторинг IO, DI і аварійних станів

Моніторинг DI (DI monitoring)

watch_di_changes():

  1. запускає GetIOInfo для імен портів;
  2. циклічно опитує IOManager/GetIOValue;
  3. детектує фронтові події (edge) (зміну 0->1 або 1->0) і повертає port/value/label.

Типовий набір портів за замовчуванням (default) у коді: 0–15, 32, 33, 40–45.

Моніторинг попереджень і помилок робота (Robot warning/error monitoring)

У CodroidAPI є детектори:

  1. emergency stop,
  2. overspeed,
  3. joint protection (колізійна подія),
  4. drag-not-allowed,
  5. wrong tool/payload.

Є два режими:

  1. monitor_robot_errors() — тільки стрім детектованих подій;
  2. auto_recover_from_errors(auto_clear=True) — спроба автоматичного clear через recovery sequence.

RobotSession: рекомендований шар для UI і сервісів

RobotSession додає експлуатаційну поведінку (production) поверх CodroidAPI:

  1. довгоживучі user/robot підключення;
  2. контрольний автомат станів (state machine) acquired/released;
  3. acquire_control() / release_control() з перевіркою закриття websocket;
  4. API-знімків стану (snapshot API):
    • position_snapshot();
    • robot_status_snapshot();
    • coordinate_frame_snapshot();
    • calibration_frame_snapshot();
    • robot_warning_snapshot() / robot_error_snapshot();
  5. фонове опитування IO (poll) для flange-кнопки і черга натискань (next_flange_press()).

У лабораторних застосунках рекомендовано працювати саме через RobotSession, а не через одноразові ad-hoc підключення.

Робота з .crp-проєктами через HTTP

CodroidAPI містить допоміжні CRUD-методи для robot project:

  1. read_project(project_id);
  2. save_project(project_doc);
  3. create_project(label, …);
  4. upsert_point(project_id, point);
  5. delete_point(project_id, point_id/label);
  6. delete_project(project_id).

Ці методи використовуються для автоматизації сценаріїв без ручного редагування в teach pendant/UI.

Практичний мінімум для інтеграції в лабораторії

Рекомендований порядок при старті нового модуля:

  1. Ініціалізувати CodroidSettings з .env.
  2. Встановити RobotSession.
  3. acquire_control().
  4. Перевірити наявність свіжих даних знімків стану (snapshot: posture_seen, robot_status_age_seconds).
  5. Перед автоматичним циклом перевірити калібрування та інструментальний профіль.
  6. Після завершення циклу виконати release_control(power_off=True).

Обмеження та зауваження

  1. Мапінг OnRobot у codroid-api позначений як попередній (provisional) і може відрізнятись між ревізіями прошивки (firmware).
  2. Деякі методи очікують конкретний формат повідомлень контролера; при зміні firmware необхідна повторна валідація.
  3. Для одночасного використання listen()/recv() у кількох задачах потрібно чітко планувати, хто споживає потік (щоб не «перехопити» повідомлення іншого споживача, consumer).
  4. API протестований під стек, сумісний з Codroid Web UI v1.6.3c (згідно README).