# Обзор SDK artex-robot

**artex-robot** — Python-библиотека (SDK), которая подключает устройство к платформе ARTEX. SDK берёт на себя соединение с сервером, регистрацию устройства, отправку видео и телеметрии и приём команд. Разработчику остаётся описать три вещи: **как читать датчики**, **как получать кадры с камеры** и **как выполнять команды**.

| Параметр | Значение |
|---|---|
| Пакет | `artex-robot` (PyPI) |
| Импорт | `from artex_robot import Robot` |
| Текущая версия | 0.1.1 |
| Python | 3.8+ |
| Зависимости | `python-socketio` ≥ 5.10 (устанавливается автоматически); `opencv-python` и `numpy` — для видео (устанавливаются вручную) |
| Протокол | Socket.IO (WebSocket), namespace `/robot` |
| Разработчики | ИЦИИ МИФИ |

## Поддерживаемые устройства

SDK работает на любом устройстве, где запускается Python 3: Raspberry Pi, Jetson, мини-ПК, ноутбук. Микроконтроллеры (ESP32, STM32, Arduino) подключаются через бортовой компьютер — SDK работает на компьютере и передаёт команды контроллеру по UART / I2C / USB. Виртуальные роботы в симуляторе подключаются тем же SDK.

## Как устроен SDK

```
┌──────────────────────── Robot (Conductor) ─────────────────────────┐
│                                                                     │
│  Ваш код:  @robot.mainloop   @robot.telemetry   @robot.video        │
│            @robot.com_handler                                       │
│                 │                   │                │              │
│                 ▼                   ▼                ▼              │
│  ┌──────────────────┐   ┌───────────────────────────────────────┐  │
│  │  Основной цикл   │   │ Vault — хранилище последних значений  │  │
│  │  (каждые 0,1 с)  │   │ s_meta · d_meta · телеметрия · видео  │  │
│  └──────────────────┘   └───────────────────────────────────────┘  │
│                                   │ чтение (только изменения)      │
│                                   ▼                                 │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │ Connector (Socket.IO клиент)                                  │  │
│  │  поток telem ─▶ emit("telem")   поток video ─▶ emit("video")  │  │
│  │  on("heartbeat") · on("command") · on("token_ask")            │  │
│  └──────────────────────────────────────────────────────────────┘  │
│  Logger — консоль или файлы all.log / error.log                     │
└─────────────────────────────────────────────────────────────────────┘
                                   │  Socket.IO /robot
                                   ▼
                            Сервер ARTEX (ХАБ)
```

| Компонент | Назначение |
|---|---|
| **Robot (Conductor)** | Главный объект. Читает конфигурацию, хранит контекст, запускает основной цикл, регистрирует обработчики через декораторы |
| **Vault** | Хранит паспорт устройства (`s_meta`), состояние (`d_meta`), последние значения телеметрии и последние кадры. Кадры сразу кодируются в JPEG |
| **Connector** | Клиент Socket.IO: подключение, авто-переподключение, обработка heartbeat и команд, фоновые потоки отправки телеметрии и видео |
| **Logger** | Журнал событий: в консоль или в файлы `all.log` / `error.log` |

## Принцип работы

1. Вы создаёте объект `Robot` с конфигурацией (имя, тип, адрес сервера).
2. Декоратором `@robot.telemetry("ключ")` помечаете функции, которые читают датчики; декоратором `@robot.video("камера")` — функции, которые возвращают кадр.
3. В функции `@robot.mainloop` вызываете эти функции — их результаты автоматически попадают в Vault.
4. `robot.init_connector()` подключается к серверу; `robot.start()` запускает бесконечный основной цикл.
5. Получив от сервера сигнал готовности, SDK в фоне отправляет на сервер всё новое из Vault.
6. Команды от оператора или модели ИИ вызывают вашу функцию `@robot.com_handler`.

<p class="callout info">Отправка данных и основной цикл независимы: основной цикл только обновляет значения в Vault, а отдельные потоки отправляют на сервер последние значения со своей частотой. Если значение не менялось, повторно оно не отправляется.</p>

## Содержание раздела

- [Быстрый старт](https://docs.mephi-ai.ru/books/po-dlia-robota/page/bystryi-start) — установка и первый запуск.
- [Конфигурация](https://docs.mephi-ai.ru/books/po-dlia-robota/page/konfiguraciia) — параметры `params.json`.
- [Справочник API](https://docs.mephi-ai.ru/books/po-dlia-robota/page/spravocnik-api) — все методы и декораторы.
- [Обработка команд](https://docs.mephi-ai.ru/books/po-dlia-robota/page/obrabotka-komand) — типы команд и их обработка.
- [Протокол обмена с сервером](https://docs.mephi-ai.ru/books/po-dlia-robota/page/protokol-obmena-s-serverom) — события Socket.IO и форматы сообщений.
- [Примеры роботов](https://docs.mephi-ai.ru/books/po-dlia-robota/page/primery-robotov) — LED, колёсный робот с камерой, виртуальный робот.
- [Устранение неполадок](https://docs.mephi-ai.ru/books/po-dlia-robota/page/ustranenie-nepoladok).