Metadata-Version: 2.4
Name: pioneer_sdk2
Version: 0.15.0
Summary: SDK for control and programming Geoscan Pioneer Drones
Author-email: Ilya Danilenko <i.danilenko@geoscan.ru>, Andrey Egorov <an.egorov@geoscan.ru>, Nikolai Zyuzya <n.zyuzya@geoscan.ru>
License-Expression: MIT
Keywords: pioneer,pioneer mini 2,geoscan
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial==3.5
Requires-Dist: numpy==1.26.4
Requires-Dist: opencv-python==4.10.0.84
Dynamic: license-file

# Pioneer SDK 2

## Общее описание
Pioneer SDK 2 - это Python SDK для управления дронами Pioneer (Pioneer Mini 2, Pizero и др.). Класс Pioneer является главным интерфейсом взаимодействия.

### Поддерживаемые платформы
- **Windows:** 10, 11
- **Linux:** любые дистрибутивы c поддержкой Python 3.12
- **macOS:** только на процессорах Apple Silicon (протестировано на macOS 26, macOS 26.1)

**Примечание:** macOS на процессорах Intel не поддерживается.

### Автоматический контроль последовательности команд

SDK автоматически отслеживает состояние полета дрона и контролирует допустимость выполнения команд в текущем состоянии. Цикл состояний: **ON_LAND → ARMED → IN_SKY → ON_LAND**.

**Логика контроля (работает только при `wait_callback=True` и `safety_command=True`):**
- При попытке выполнить команду из предыдущего состояния - команда игнорируется (возвращает False или ничего)
- При попытке пропустить обязательный этап - выбрасывается исключение RuntimeError
- Только команды для текущего состояния выполняются успешно

**Отключение контроля:**
Контроль последовательности команд отключается, если хотя бы один из параметров `wait_callback` или `safety_command` установлен в `False`. При этом все команды выполняются без проверки состояния полета. Используйте отключение контроля только если вы полностью контролируете последовательность команд самостоятельно.

**Важно:**
- Состояния корректно отслеживаются только в рамках одной программы
- При запуске нескольких полетных программ часть состояний может быть не считана
- Рекомендуется использовать `wait_callback=True` и `safety_command=True` (по умолчанию) для безопасной работы

#### Инициализация
```python
pioneer = Pioneer()
```
Параметры:
- serial (str): Подключаемый последовательный порт
- tcp (str): TCP адрес и порт (по умолчанию "127.0.0.1:20556")
- baudrate (int): Скорость передачи данных (по умолчанию 57600)
- wait_callback (bool): Флаг включения блокирования методов на ожидание выполнения callback-функций (по умолчанию True)
- safety_command (bool): Флаг включения проверки разрешенных команд в зависимости от состояния полета (по умолчанию True). При False проверка команд отключается.
- logger (bool): Флаг включения логирования (по умолчанию True)

Примечание:
- Возможно использование лишь одного из методов serial или tcp
- Контроль последовательности команд работает только при `wait_callback=True` и `safety_command=True` 

## Основные методы управления

### Управление полетом. Класс Pioneer

`arm(timeout = 5, retries = 0)`

Запуск моторов дрона
Ожидает события ENGINES_STARTED при параметре Pioneer.wait_callback=True

Параметры:
- timeout (int): Время ожидания (в секундах) для запуска моторов.
- retries (int): Количество повторных попыток ARM при неудаче (0 = без повторов).

Тип результата:
bool

Результат:
True, если команда успешно выполнена, иначе False

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ARMED команда игнорируется (возвращает False)
- При вызове в состоянии IN_SKY команда игнорируется (возвращает False)

`disarm()`

Отключение моторов дрона

Тип результата:
bool

Результат:
True, если успешно отправлена команда, иначе False

`takeoff()`

Запускает процесс взлёта и ждёт его завершения
Ожидает события TAKEOFF_COMPLETE при параметре wait_callback=True

Тип результата:
bool

Результат:
True, если успешно отправлена команда, иначе False

Примечание (только при wait_callback=True и safety_command=True):
- Доступна только после успешного выполнения arm()
- При вызове в состоянии ON_LAND команда игнорируется (возвращает False)
- При вызове в состоянии IN_SKY выбрасывается RuntimeError (пропуск обязательного этапа)

`land()`

Отдает команду на посадку дрона
Ожидает события COPTER_LANDED при параметре wait_callback=True

Тип результата:
bool

Результат:
True, если команда успешно выполнена, иначе False

`go_to_local_point(x, y, z, yaw, time=0)`

Перемещает дрон к локальной точке

Параметры:
- x (int): Координата X в метрах
- y (int): Координата Y в метрах
- z (int): Координата Z в метрах
- yaw (float): Угол рысканья в градусах
- time (int): Желательное время достижения целевой точки. Если равен 0, дрон перемещается с текущей скоростью.

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ON_LAND команда игнорируется (возвращает False)
- При вызове в состоянии ARMED выбрасывается RuntimeError (пропуск обязательного этапа)

`go_to_local_point_body_fixed(x, y, z, yaw, time=0)`

Перемещает дрон к локальной точке относительно его текущей позиции

Параметры:
- x (float): Смещение по оси X в метрах
- y (float): Смещение по оси Y в метрах
- z (float): Смещение по оси Z в метрах
- yaw (float): Угол рысканья в градусах
- time (int): Желательное время достижения целевой точки. Если равен 0, дрон перемещается с текущей скоростью.

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ON_LAND команда игнорируется (возвращает False)
- При вызове в состоянии ARMED выбрасывается RuntimeError (пропуск обязательного этапа)

`go_to_global_point(latitude, longitude, altitude, yaw=0)`

Перемещает дрон к заданной глобальной точке по координатам GPS. Только для системы навигации GPS. 

Параметры:
- latitude (float): Широта целевой точки в градусах
- longitude (float): Долгота целевой точки в градусах
- altitude (float): Высота над уровнем моря в метрах
- yaw (int): Угол рысканья (азимут) в градусах (по умолчанию 0)

Тип результата:
bool

Результат:
True, если команда успешно отправлена, иначе False

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ON_LAND команда игнорируется (возвращает False)
- При вызове в состоянии ARMED выбрасывается RuntimeError (пропуск обязательного этапа)

`go_to_global_point_relative(latitude_offset, longitude_offset, altitude_offset, yaw)`

Перемещает дрон к глобальной точке, заданной смещениями относительно текущего положения. Только для системы навигации GPS.

Параметры:
- latitude_offset (float): Смещение по широте в градусах относительно текущей позиции
- longitude_offset (float): Смещение по долготе в градусах относительно текущей позиции
- altitude_offset (float): Смещение по высоте в метрах относительно текущей позиции
- yaw (int): Угол рысканья (азимут) в градусах

Тип результата:
bool

Результат:
True, если команда успешно отправлена, иначе False

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ON_LAND команда игнорируется (возвращает False)
- При вызове в состоянии ARMED выбрасывается RuntimeError (пропуск обязательного этапа)

`set_manual_speed(vx, vy, vz, yaw_rate, interval=1.0)`

Полёт с заданной скоростью относительно системы координат. Доступна только в состоянии IN_SKY (после взлёта).

Параметры:
- vx (float): Скорость по оси X в м/с
- vy (float): Скорость по оси Y в м/с
- vz (float): Скорость по оси Z в м/с
- yaw_rate (float): Скорость рысканья в рад/с
- interval (float): Время в секундах, в течение которого команда управления скоростью считается активной (по умолчанию 1.0)

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ON_LAND команда игнорируется
- При вызове в состоянии ARMED выбрасывается RuntimeError (пропуск обязательного этапа)

`set_manual_speed_body_fixed(vx, vy, vz, yaw_rate, interval=1.0)`

Полёт с заданной скоростью относительно текущей позиции дрона

Параметры:
- vx (float): Скорость по оси X в м/с
- vy (float): Скорость по оси Y в м/с
- vz (float): Скорость по оси Z в м/с
- yaw_rate (float): Скорость рысканья в рад/с
- interval (float): Время в секундах, в течение которого команда управления скоростью считается активной (по умолчанию 1.0)

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ON_LAND команда игнорируется
- При вызове в состоянии ARMED выбрасывается RuntimeError (пропуск обязательного этапа)

`rtl()`

Возвращение домой (Return To Launch).

Тип результата:
bool

Результат:
True, если успешно, иначе False.

### Дополнительные функции

`get_battery_status()`

Возвращает текущий статус заряда батареи

Тип результата:
tuple[float, float] | None

Результат:
Кортеж с напряжением и температурой батареи в Вольтах или None, если ошибка

`set_logger(value=True)`

Устанавливает флаг логирования

Параметры:
- value (bool): Значение флага логирования (по умолчанию True)

`connect()`

Устанавливает соединение с устройством. Автоматически выполняется при инициализации объекта класса `Pioneer`.

`close_connection()`

Закрывает соединение с устройством

`reboot_board()`

Перезагружает основную плату дрона, закрывает соединение и ждет 5 секунд. Ожидается сигнал с платы после перезапуска.

Тип результата:
bool

Результат:
True, если перезагрузка разрешена и успешно выполнена, иначе False

`point_deceleration()`

Проверяет, достиг ли дрон точки близкой к целевой

Тип результата:
bool

Результат:
True, если замедление осуществлено, иначе False

`point_reached()`

Проверяет, достиг ли дрон целевой точки

Тип результата:
bool

Результат:
True, если точка достигнута, иначе False

### Управление ориентацией

`set_yaw(yaw)`

Устанавливает угол рыскания

Параметры:
- yaw (float): Угол рыскания в градусах

Тип результата:
bool

Результат:
True, если успешно отправлена команда, иначе False

Примечание (только при wait_callback=True и safety_command=True):
- При вызове в состоянии ON_LAND команда игнорируется (возвращает False)
- При вызове в состоянии ARMED выбрасывается RuntimeError (пропуск обязательного этапа)

`get_orientation()`

Возвращает ориентацию дрона по углу крена(roll), тангажа(pitch), рыскания(yaw)

Тип результата:
tuple[float, float, float] | None

Результат:
Кортеж с ориентацией дрона по углу крена (roll), тангажа (pitch) и рыскания (yaw) или None, если ошибка

### Получение данных с датчиков

`get_accel()`

Возвращает ускорение дрона по осям X, Y и Z

Тип результата:
tuple[float, float, float] | None

Результат:
Ускорение по осям или None, если ошибка

`get_gyro()`

Возвращает угловую скорость по осям X, Y, Z в рад/с

Тип результата:
tuple[float, float, float] | None

Результат:
Угловая скорость по осям X, Y, Z в рад/с или None, если ошибка

`get_mag()`

Возвращает показания магнитометра по осям X, Y и Z. Только для GPS.

Тип результата:
tuple[float, float, float] | None

Результат:
Кортеж с угловой скоростью по осям X, Y и Z или None, если ошибка

`get_altitude()`

Возвращает высоту в метрах

Тип результата:
float | None

Результат:
Высота в метрах или None, если ошибка

`get_dist_sensor_data()`

Возвращает информацию с оптического сенсора

Тип результата:
float | None

Результат:
Дальность в метрах или None, если ошибка

`get_motors_rpm()`

Возвращает текущие обороты каждого из 4 двигателей дрона.

Тип результата:
list[float | None]

Результат:
Список из 4 значений оборотов (RPM) для каждого двигателя, или None для каждого двигателя, если произошла ошибка.

`get_ranger_data()`

Возвращает данные с дальномеров модуля Ranger (Только для Мини 2)

Тип результата:
tuple[float, float, float, float, float] | tuple[None, None, None, None, None]

Результат:
Кортеж из пяти значений (в метрах): (право, лево, вперед, назад, сверху/снизу). Если модуль не поддерживается или не установлен — кортеж из None.

### Управление LED

`led_control(led_id=255, r=0., g=0., b=0.)`

Устанавливает цвет для указанного светодиода или всех светодиодов

Параметры:
- led_id (int): Номер светодиода. Если 255, устанавливается для всех светодиодов.
- r (float): Значение красного цвета от 0 до 1.
- g (float): Значение зеленого цвета от 0 до 1.
- b (float): Значение синего цвета от 0 до 1.

Тип результата:
bool

Результат:
True, если успешно отправлена команда, иначе False

### Управление захватом

Доступен только для Мини 2.

`grab_open(movement_time=0, velocity=100)`

Открывает захват дрона

Параметры:
- movement_time (float): Время движения в секундах. Если 0, открытие захвата происходит до упора (по умолчанию 0).
- velocity (int): Скорость движения в процентах от 0 до 100 (по умолчанию 100).

Тип результата:
bool

Результат:
True, если успешно, иначе False

`grab_close(movement_time=0, velocity=100)`

Закрывает захват дрона

Параметры:
- movement_time (float): Время движения в секундах. Если 0, закрытие захвата происходит до упора (по умолчанию 0).
- velocity (int): Скорость движения в процентах от 0 до 100 (по умолчанию 100).

Тип результата:
bool

Результат:
True, если успешно, иначе False

`grab_stop()`

Останавливает движение захвата

Тип результата:
bool

Результат:
True, если успешно, иначе False

### Управление магнитным захватом груза

Доступно только для Базового Пионера.

`cargo_set(grab)`

Устанавливает состояние магнитного захвата груза (вкл/выкл).

Параметры:
- grab (bool): True — включить магнитный захват, False — выключить.

Тип результата:
bool

Результат:
True, если успешно, иначе False

`cargo_grab()`

Включает магнитный захват груза.

Тип результата:
bool

Результат:
True, если успешно, иначе False

`cargo_release()`

Выключает магнитный захват груза.

Тип результата:
bool

Результат:
True, если успешно, иначе False

### Работа с параметрами

`get_param(name, update=False)`

Возвращает значение параметра автопилота

Параметры:
- name (str): Имя параметра
- update (bool): Если True, принудительно обновит значение параметра из автопилота, иначе вернет кэшированное значение.

Тип результата:
float | None

Результат:
Значение параметра или None, если ошибка

`set_param(name, value)`

Устанавливает значение параметра автопилота

Параметры:
- name (str): Имя параметра
- value (float | int): Значение параметра

Тип результата:
bool

Результат:
True, если успешно, иначе False

### Состояние полета

Класс FlyState, предоставляет константы для состояний полета дрона в цикле: ON_LAND → ARMED → IN_SKY → ON_LAND.
```python
ON_LAND  # Коптер на земле, моторы выключены. Доступна команда: arm()
ARMED    # Коптер заармлен, моторы запущены. Доступна команда: takeoff()
IN_SKY   # Коптер в воздухе, выполняет полет. Доступны команды полета
```

`get_fly_state()`

Возвращает текущее состояние полета дрона

Тип результата:
FlyState

Результат:
Текущее состояние полета (ON_LAND, ARMED или IN_SKY)

### Работа с системой навигации

Класс NavSystem, предоставляет константы для видов навигации дрона.
```python
GPS # Глобальная система навигации ГНСС.
LPS # Локальная система навигации Локус (УЗ), ИК.
OPT # Оптическая система навигации.
```

Класс NavStatus, предоставляющий константы состояния системы навигации дрона.
```python
NO_DATA # Нет данных с модуля
CANNOT  # Невозможно оценить позицию
LOW     # Малое доверие к оценке
OK      # Успешная оценка
```

`get_nav_system(update=False)`

Возвращает текущую систему навигации дрона.

Параметры:
- update (bool): Если True, принудительно обновит значение параметра из автопилота, иначе вернет кэшированное значение.

Тип результата:
NavSystem

Результат:
Текущая система навигации (GPS, LPS или OPT).

`get_nav_status_lps()`

Возвращает статус локальной навигационной системы дрона

Тип результата:
NavStatus | None

`get_local_position_lps()`

Возвращает позицию по осям X, Y, Z в метрах

Тип результата:
tuple[float, float, float] | None

Результат:
Позиция по осям X, Y, Z в метрах или None, если ошибка

`get_local_velocity_lps()`

Возвращает скорость по осям X, Y, Z в м/с

Тип результата:
tuple[float, float, float] | None

Результат:
Скорость по осям X, Y, Z в м/с или None, если ошибка

`get_local_yaw_lps()`

Возвращает текущий угол рыскания

Тип результата:
float | None

Результат:
Угол рыскания в градусах (-180.0; +180.0) или None, если ошибка

`get_optical_data()`

Возвращает данные оптического потока.

Тип результата:
tuple[int, int, float] | None

Результат:
данные оптического потока или None, если ошибка.

Результат:
Статус системы навигации дрона или None, если ошибка

`get_nav_status_gps()`

Возвращает статус навигационной системы дрона (только для GPS)

Тип результата:
NavStatus | None

Результат:
Статус системы навигации дрона или None, если ошибка

`get_global_position_gps()`

Возвращает текущие глобальные координаты дрона по данным GPS (только для GPS)

Тип результата:
tuple[float, float, float] | None

Результат:
Кортеж (широта, долгота, высота) в градусах и метрах, либо None, если модуль навигации не установлен

`get_global_velocity_gps()`

Возвращает скорость дрона в системе координат GPS (только для GPS)

Тип результата:
tuple[float, float, float] | None

Результат:
Кортеж (северная скорость, восточная скорость, вертикальная скорость) в м/с или None, если модуль навигации не установлен

`get_satellites_count()`

Возвращает количество спутников GPS и ГЛОНАСС, видимых дрону (только для GPS)

Тип результата:
tuple[int, int] | None

Результат:
Кортеж (число GPS-спутников, число ГЛОНАСС-спутников), либо None, если модуль навигации не установлен

### Временные функции

`time()`

Возвращает время работы беспилотника в секундах с момента начала GPS-эпохи.

Тип результата:
float | None

Результат:
Время в секундах с начала эпохи GPS или None, если ошибка.

`uptime()`

Возвращает время в секундах, прошедшее с момента идентификации в системе навигации

Тип результата:
int | None

Результат:
Время в секундах или None, если ошибка

`flight_time()`

Возвращает время с начала полёта дрона в секундах

Тип результата:
float | None

Результат:
Время полёта в секундах или None, если ошибка

### Обработка событий

Для реализации не блокирующего фунционала управления можно самостоятельно подписываться на события и ожидать их получения от автопилота. Список событий описан в классе Event и содержит следующие поля:
```python
ALL                # Все события
NULL               # Пустое событие
COPTER_LANDED      # Событие посадки дрона на землю.
LOW_VOLTAGE1       # Низкий заряд АКБ, но заряда хватит, чтобы вернуться домой.
LOW_VOLTAGE2       # Низкий заряд АКБ, начата экстренная посадка
POINT_REACHED      # Событие достижения целевой точки.
POINT_DECELERATION # Событие замедления дрона перед целевой точкой.
TAKEOFF_COMPLETE   # Событие завершения взлета.
ENGINES_STARTED    # Событие запуска моторов.
SHOCK              # Сильный удар, возможна потеря управления
LOW_CHARGE         # Критически низкий заряд АКБ
```

`subscribe(callback, event)`

Подписывается на событие

Параметры:
- callback (callable): Функция обратного вызова при получении события
- event (Event): Событие для подписки

`unsubscribe(callback, event)`

Отписывается от события

Параметры:
- callback (callable): Функция обратного вызова
- event (Event): Событие для отписки

## Управление RC-каналами

Для управления RC каналами требуется выставить параметры АП:
- Copter_man_rcMode0=6.0
- Copter_man_rcMode1=3.0
- Copter_man_rcMode2=3.0
- Copter_flyWithoutRc=1.0
- SensorMux_rc=2.0

*Отправка RC каналов*

`send_rc_channels(channel_1=0, channel_2=0, channel_3=0, channel_4=0, channel_5=1, channel_6=0, channel_7=1, channel_8=0)`

Требуется постоянная отправка RC каналов для поддержания связи

Параметры:
- channel_1 (float): Правый джойстик -1 влево 0 вправо 1
- channel_2 (float): Правый джойстик -1 вперед 0 назад 1
- channel_3 (float): Левый джойстик -1 вниз 0 вверх 1
- channel_4 (float): Левый джойстик 1 влево 0 вправо -1
- channel_5 (float): Режим управления
- channel_6-8 (float): Дополнительные каналы

Тип результата:
bool

Результат:
True, если успешно отправлена команда, иначе False

`rc_sdk1_to_sdk2(channel_1=0, channel_2=0, channel_3=0, channel_4=0, channel_5=2000)`

Конвертация команд из SDK1 в SDK2

Параметры:
- channel_1-4 (float): Значения каналов SDK1
- channel_5 (float): Значение канала режима SDK1

Тип результата:
tuple[float, float, float, float, float]

Результат:
Кортеж из 5 значений для каналов управления

`get_rc_channel()`

Возвращает значение RC-канала.

Тип результата:
int | None

Результат:
Значение RC-канала или None, если произошла ошибка.

`set_rc_trigger(callback)`

Устанавливает функцию обратного вызова для триггера RC-канала.

Параметры:
- callback (callable): Функция обратного вызова, которая будет вызвана при срабатывании триггера.

## Работа с камерой

Классы `Camera` и `ImageViewer` динамически импортируются в SDK в зависимости от драйвера камеры, указанного в файле конфигурации платы (`board_config.json`).

### Поддерживаемые драйверы камер

- **gstreamer**: Использует GStreamer для захвата видео из shared memory (`/tmp/`). Поддерживает несколько камер одновременно.
- **rtsp**: Использует RTSP-поток для захвата видео. Требует указания IP-адреса камеры.

### Класс Camera

Класс для захвата видеокадров и предоставления их через очередь.

#### Инициализация
```python
# Для драйвера gstreamer
camera = Camera(camera_type)

# Для драйвера rtsp
camera = Camera(camera_type, camera_ip="10.42.0.1:8554")
```
Параметры:
- camera_type (CameraType): Тип камеры для захвата (например, `CameraType.MAIN` или `CameraType.OPT`).
- camera_ip (str): IP-адрес и порт камеры (по умолчанию "10.42.0.1:8554"). Используется только для драйвера `rtsp`.

Примечание: `CameraType` генерируется динамически на основе секции `cameras` файла конфигурации платы `board_config.json` (ключи, отличные от `driver`).

#### Методы

`get_cv_frame(timeout=5.0)`

Возвращает следующий доступный кадр из очереди.

Параметры:
- timeout (float): Время ожидания в секундах.

Тип результата:
numpy.ndarray

Результат:
Кадр в формате BGR.

`stop()`

Останавливает GStreamer-пайплайн и завершает поток захвата.

### Класс ImageViewer

Примечание: Класс `ImageViewer` доступен только при использовании драйвера камеры `gstreamer`.

Класс для трансляции numpy-кадров по RTSP через GStreamer.

#### Инициализация
```python
viewer = ImageViewer()
```

#### Методы

`imshow(name, frame, fps=30)`

Отправляет кадр в соответствующий RTSP-поток.

Параметры:
- name (str): Идентификатор потока.
- frame (numpy.ndarray): Изображение в формате BGR для трансляции.
- fps (int): кадров в секунду при передаче видео (по умолчанию 30)

`close()`

Уничтожает все gstreamer пайплайны.

### Класс RecorderControl
Класс для управления записью видео и съемкой фото

#### Инициализация
```python
recorder = RecorderControl()
```

#### Конфигурации записи (RecordingConfig)

`RecordingConfig` описывает набор параметров кадра (`width`, `height`, `fps`)

Получить список доступных режимов записи:
```python
all_recording_configs = recorder.get_camera_recording_configs(CameraType.MAIN)
```

#### Методы

`get_camera_recording_configs(camera_type=CameraType.MAIN)`

Возвращает список `RecordingConfig` для выбранной камеры.

Параметры:
- camera_type (CameraType): Тип камеры (`CameraType.MAIN`, `CameraType.OPT` и т.д.).

Тип результата:
list[RecordingConfig]

`start_recording(camera_type, recording_config=None, output_dir="/mnt/media/videos/")`

Подготавливает и запускает запись видео для выбранной камеры.

Параметры:
- camera_type (CameraType): Тип камеры (`CameraType.MAIN`, `CameraType.OPT` и т.д.).
- recording_config (RecordingConfig | None): Конфигурация записи (ширина/высота/fps), обычно из `get_camera_recording_configs(...)`.  
  Если `None`, используется первая доступная конфигурация для выбранной камеры.
- output_dir (str | Path): Каталог сохранения видео (по умолчанию `/mnt/media/videos/` - Галерея).

Тип результата:
bool

Результат:
`True`, если запись успешно запущена, иначе `False`.

`stop_recording(camera_type=CameraType.MAIN)`

Останавливает запись и удаляет подготовленный record-path выбранной камеры.

Параметры:
- camera_type (CameraType): Тип камеры (`CameraType.MAIN`, `CameraType.OPT` и т.д.).

Тип результата:
bool

Результат:
`True`, если команда успешно выполнена.

`take_photo(file_name, camera_type, recording_config=None, output_dir="/mnt/media/photos/")`

Делает фотографию и сохраняет файл в указанную директорию.

Параметры:
- file_name (str): Имя файла с расширением (`.jpg`, `.jpeg`, `.png`).
- camera_type (CameraType): Тип камеры (`CameraType.MAIN`, `CameraType.OPT` и т.д.).
- recording_config (RecordingConfig | None): Конфигурация для подготовки камеры.  
  Если `None`, используется первая доступная конфигурация для выбранной камеры.
- output_dir (str | Path): Каталог сохранения фото (по умолчанию `/mnt/media/photos/`).

Тип результата:
bool

Результат:
`True`, если фото успешно сделано и сохранено.

Исключения:
- ValueError: пустое имя файла или неподдерживаемое расширение.
- ValueError: для выбранной камеры нет доступных конфигураций записи.
- RuntimeError: ошибка подготовки камеры или выполнения команды фото.

## Управление сервоприводом камеры

### Класс ServoCamera

Класс для управления сервоприводом камеры, позволяющий устанавливать угол поворота. Только для Мини 2.

Инициализация
```python
servo_camera = ServoCamera()
```
Примечание: Проверяет поддержку сервомотора камеры бортом при инициализации.

Методы

`set_angle(angle, priority=ServoPriority.LOW)`

Устанавливает угол поворота сервопривода камеры.

Параметры:
- angle (float): Угол в градусах, должен быть в диапазоне от -80 до 30.
- priority (ServoPriority): Приоритет команды сервопривода (HIGH, MEDIUM, LOW).

Тип результата:
bool

Результат:
True, если команда успешно отправлена, иначе False.

Исключения:
ValueError: Если угол выходит за пределы допустимого диапазона (-80 до 30 градусов).
