# Быстрый старт

За 10 минут подключим устройство к платформе ARTEX: оно появится в списке подключений, будет передавать телеметрию и видео и принимать команды из веб-интерфейса.

## Что понадобится

- Устройство с Python 3.8+ (Raspberry Pi, ноутбук, мини-ПК).
- Сетевой доступ от устройства к серверу ARTEX.
- USB- или CSI-камера (необязательно).

## Шаг 1. Установка

```bash
python3 -m venv ~/artex-env
source ~/artex-env/bin/activate

pip install artex-robot
pip install opencv-python numpy        # нужны для работы с видео
```

<p class="callout warning">В текущей версии SDK (0.1.1) модуль видео импортирует <code>cv2</code> при любом запуске, поэтому <code>opencv-python</code> нужен даже устройствам без камеры. На Raspberry Pi без графической оболочки используйте <code>opencv-python-headless</code>.</p>

## Шаг 2. Конфигурация

Создайте рядом со скриптом файл `params.json`:

```json
{
  "name": "tank-01",
  "type": "Robot",
  "server": "http://artex.arcon",
  "port": 80,
  "logger_type": "console",
  "logger_level": "skip_TODO"
}
```

`server` и `port` — адрес сервера платформы (узнайте у администратора). Все параметры описаны на странице [Конфигурация](https://docs.mephi-ai.ru/books/po-dlia-robota/page/konfiguraciia).

## Шаг 3. Программа робота

Создайте файл `robot.py`:

```python
import cv2
from artex_robot import Robot

robot = Robot()                      # параметры берутся из params.json

# 1. Обработка команд от оператора и моделей ИИ
@robot.com_handler
def on_command(type_command, command, author=None):
    print(f"Команда {command} (тип {type_command}) от {author}")
    if command == "stop":
        pass                          # остановить двигатели

# 2. Телеметрия: значение, которое вернёт функция, уйдёт на сервер под ключом "battery"
@robot.telemetry("battery")
def read_battery():
    return 12.1                       # здесь чтение реального датчика

# 3. Видео: кадр, который вернёт функция, уйдёт на сервер как камера "rgb"
@robot.video("rgb")
def send_frame(frame):
    return frame                      # numpy-массив BGR, SDK сам сожмёт его в JPEG

# Камеру кладём в контекст робота, чтобы получить её в основном цикле
cam = cv2.VideoCapture(0)
robot["cam"] = cam

# 4. Основной цикл: вызывается каждые 0,1 с
@robot.mainloop
def main_loop(context):
    read_battery()
    ok, frame = context["cam"].read()
    if ok:                            # пустой кадр отправлять нельзя
        send_frame(frame)

robot.init_connector()                # подключение к серверу
robot.start()                         # запуск основного цикла (Ctrl+C — остановка)
```

<p class="callout danger">Обработчик <code>@robot.com_handler</code> и основной цикл <code>@robot.mainloop</code> обязательны: без них SDK версии 0.1.1 завершится с ошибкой <code>AttributeError</code>. Если команды не нужны, объявите пустой обработчик. Функция основного цикла всегда принимает аргумент <code>context</code>.</p>

<p class="callout warning">Функция с декоратором <code>@robot.video</code> не должна возвращать <code>None</code>: SDK пытается сжать результат в JPEG, и пустой кадр вызывает ошибку OpenCV, которая останавливает программу. Поэтому кадр читается и проверяется в основном цикле, а в декорированную функцию передаётся только успешно прочитанный кадр.</p>

## Шаг 4. Запуск и проверка

```bash
python robot.py
```

В консоли появятся сообщения `[INFO] -- connected` и `[INFO] -- in heartbeat recieved [...]`. Откройте веб-интерфейс платформы: устройство `tank-01` появится на странице «Подключения». Откройте его — вы увидите видео и телеметрию `{"battery": 12.1}`. Отправьте команду `stop` из поля ввода команд — в консоли робота появится `Команда stop (тип com) от ...`.

## Шаг 5. Автозапуск (systemd)

```ini
# /etc/systemd/system/artex-robot.service
[Unit]
Description=ARTEX robot
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/home/pi/robot
ExecStart=/home/pi/artex-env/bin/python robot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable --now artex-robot
journalctl -u artex-robot -f
```

`WorkingDirectory` обязателен: SDK ищет `params.json` в текущем рабочем каталоге. `Restart=always` перезапускает программу при сбое; чтобы перезапуск срабатывал и при долгой потере связи с сервером, добавьте в основной цикл сторожевую проверку — см. [Устранение неполадок](https://docs.mephi-ai.ru/books/po-dlia-robota/page/ustranenie-nepoladok).

## Что дальше

- [Обработка команд](https://docs.mephi-ai.ru/books/po-dlia-robota/page/obrabotka-komand) — как превратить команды в движение.
- [Примеры роботов](https://docs.mephi-ai.ru/books/po-dlia-robota/page/primery-robotov) — готовые шаблоны для LED, колёсного робота, виртуального робота.