SDK: Управление манипулятором Medu с помощью Python

SDK требует наличия Python 3.12. Ниже — краткие инструкции по проверке и установке на популярных платформах, а также рекомендация по использованию виртуального окружения.

Проверка версии

Копироватьpython3.12 --version
# или, если система использует "python"
python --version

Ожидаемый вывод: Python 3.12.x. Если команда не найдена или версия ниже — нужно установить/обновить.

Установка

• Ubuntu / Debian (пример):

  Копироватьsudo apt update
  sudo apt install -y python3.12 python3.12-venv python3.12-distutils

• Fedora / CentOS / RHEL: используйте пакетный менеджер дистрибутива или сборку из исходников; можно также установить через pyenv.
• macOS (Homebrew):

  Копироватьbrew update
  brew install python@3.12

• Windows: скачайте официальный инсталлятор Python 3.12 с python.org и выполните установку, включив опцию "Add Python to PATH". После установки проверьте в PowerShell:

  Копироватьpython --version

• Переиспользование нескольких версий — pyenv (рекомендуется разработчикам):

  Копировать# установка pyenv (пример)
  curl https://pyenv.run | bash
  
  # затем
  
  pyenv install 3.12.0
  pyenv global 3.12.0

Виртуальное окружение (обязательно для проекта)

Рекомендуется запускать SDK внутри виртуального окружения, созданного той же версией Python 3.12.

Копировать# создать venv
python3.12 -m venv .venv

# Linux / macOS

source .venv/bin/activate

# Windows (PowerShell)

.venv\Scripts\Activate.ps1

# обновить pip/setuptools

python -m pip install --upgrade pip setuptools wheel

Установка SDK

После активации виртуального окружения установите SDK из предоставленного организаторами архива:

# Установка из wheel файла
pip install dist/*.whl

# Или установка из tar.gz архива
pip install dist/pm_python_sdk-0.6.11.tar.gz

Проверьте версию установленного SDK:

pip show pm-python-sdk

Важно: Установите необходимые зависимости:

pip install pydantic==2.11.7 paho-mqtt==2.1.0

Важно: Архив с SDK (папка dist) будет предоставлен организаторами. Скопируйте его в директорию проекта перед установкой. Убедитесь, что установлены все зависимости с указанными версиями

7. Стриминг

Поддерживается управление в трех режимах: TWIST (скорости), POSE (целевая поза), JOINT_JOG (положение суставов).

Перед началом каждого стриминга необходимо включить соответствующий режим:

Копироватьfrom sdk.utils.enums import ServoControlType

# Режимы
manipulator.set_servo_control_type(ServoControlType.TWIST)
manipulator.set_servo_control_type(ServoControlType.POSE)
manipulator.set_servo_control_type(ServoControlType.JOINT_JOG)

# Либо короткий вариант
manipulator.set_servo_twist_mode()  # Для скорости
manipulator.set_servo_pose_mode()   # Для позы
manipulator.set_servo_joint_jog_mode()  # Для суставов

Стриминг скоростей

Копировать# Включаем режим TWIST
manipulator.set_servo_twist_mode()

linear_vel = {"x": 0.02, "y": 0, "z": 0}
angular_vel = {"rx": 0, "ry": 0, "rz": 0.01}
manipulator.stream_cartesian_velocities(linear_vel, angular_vel)

Параметры (stream_cartesian_velocities):

• position: позиция (объект с x, y, z).
• velocities: скорость (объект с rx, ry, rz).
• header: информация о штампе времени и системе координат (по умолчанию now и base_link).

Стриминг позы

Копировать# Включаем режим POSE
manipulator.set_servo_pose_mode()

position = MoveCoordinatesParamsPosition(0.27, 0.0, 0.15)
orientation = MoveCoordinatesParamsOrientation(0, 0, 0, 1)
manipulator.stream_coordinates(position, orientation)

Параметры (stream_coordinates):

• position: позиция (объект с x, y, z).
• orientation: ориентация (объект с x, y, z, w).
• header: информация о штампе времени и системе координат (по умолчанию now и base_link).

Стриминг суставов

Копировать# Включаем режим JOINT_JOG
manipulator.set_servo_joint_jog_mode()

manipulator.stream_joint_angles(
    povorot_osnovaniya=0.5, privod_plecha=1.0, privod_strely=0.8,
    v_osnovaniya=0.2, v_plecha=0.1, v_strely=0.15
)

Параметры (stream_joint_angles):

• povorot_osnovaniya, privod_plecha, privod_strely: позиции (углы) для каждого сустава.
• v_osnovaniya, v_plecha, v_strely: скорости для каждого сустава.
• header: информация о штампе времени и системе координат (опционально).

8. Программы

SDK позволяет запускать готовые программы, JSON-сценарии и выполнять Python-код прямо на манипуляторе.

Копировать# Запуск готовой программы
manipulator.run_program('edum/default')

# Запуск JSON-программы
program_json = {
  'Root':[{'Move':{'content':[{'Point':{'positions':[0.3,-0.3,-0.4],'time':0.5}}],'type':'Simple'}}]
}
manipulator.run_program_json('program_1', program_json)

# Запуск Python-кода на роботе
manipulator.run_python_program("print('Hello!')")

Параметры (run_program):

• name: название программы (строка).

Параметры (run_program_json):

• name: название программы (строка).
• json: JSON-программа — объект с корневым ключом Root и массивом команд.

Параметры (run_python_program):

• code: строка с Python-кодом для выполнения на манипуляторе.

9. Остановка движениями

Остановка всего движения с таймаутом.

Копироватьmanipulator.stop_movement(timeout_seconds=5.0)

10. Состояния и данные

Методы для получения состояния манипулятора и подписок:

• manipulator.get_joint_state() — текущие углы суставов.
• manipulator.get_home_position() — домашняя позиция.
• manipulator.get_cartesian_coordinates() — текущие координаты X, Y, Z.

11. Конвейерная лента (MGbot)

Управление конвейерной лентой и связанными устройствами.

Копировать# Установить скорость мотора (0..100)
manipulator.mgbot_conveyer.set_speed_motors(10)

# Повернуть сервопривод
manipulator.mgbot_conveyer.set_servo_angle(45)

# Установить цвет светодиода (0..255)
manipulator.mgbot_conveyer.set_led_color(255, 0, 0)

# Показать текст на дисплее
manipulator.mgbot_conveyer.display_text('Hello')

# Звуковой сигнал (1..15)
manipulator.mgbot_conveyer.set_buzz_tone(10)

# Чтение датчиков
sensor_data = manipulator.mgbot_conveyer.get_sensors_data(True)
# Возвращаемые поля: "DistanceSensor", "ColorSensor", "Prox"

Параметры:

• set_speed_motors(speed): задает скорость мотора в диапазоне 0..100.
• set_servo_angle(angle): поворачивает сервопривод (градусы).
• set_led_color(r, g, b): задает цвет светодиодов (каждый канал 0..255).
• display_text(text): показывает текст на дисплее конвейера (utf-8).
• set_buzz_tone(level): подает звуковой сигнал в диапазоне 1..15.
• get_sensors_data(enabled): получить данные с датчиков. True — данные возвращаются в виде JSON.

Возвращаемые данные (sensor_data):

• DistanceSensor — значение расстояния / показания дистанционного датчика.
• ColorSensor — объект с полями R, G, B, Prox (например {"R":97,"G":114,"B":108,"Prox":50}).
• Prox — значение приближения к ColorSensor.

12. Управление GPIO

GPIO (General Purpose Input/Output) позволяет управлять цифровыми входами и выходами манипулятора. Это полезно для взаимодействия с внешними устройствами, датчиками, светодиодами и другими периферийными компонентами.

Основные методы

Копировать# Синхронная запись в GPIO
manipulator.write_gpio_bit(name, value, timeout_seconds=60.0, throw_error=True)

# Чтение значения GPIO
manipulator.get_gpio_bit(name, timeout_seconds=60.0, throw_error=True)

Параметры

• name: имя GPIO-пина (строка)
• value: значение для записи (0 или 1)
• timeout_seconds: таймаут выполнения команды (по умолчанию 60.0)
• throw_error: выбрасывать исключение при ошибке (по умолчанию True)

Пример использования

Копировать# Определение имени GPIO-пина
gpio_name = "/dev/gpiochip4/e1_pin"

# Функция для управления светодиодом
def set_led(on: bool):
    try:
        manipulator.write_gpio_bit(gpio_name, 1 if on else 0, timeout_seconds=0.5, throw_error=False)
    except Exception as e:
        print(f"Ошибка управления GPIO: {e}")

# Использование
set_led(True)   # Включить светодиод
set_led(False)  # Выключить светодиод

Типичные сценарии использования

• Управление внешними светодиодами или индикаторами
• Включение/выключение периферийных устройств
• Взаимодействие с простыми датчиками
• Создание световых сигналов о состоянии системы

13. Получение данных из I2C

Интерфейс I2C (Inter-Integrated Circuit) позволяет читать данные с различных датчиков и устройств, подключенных к манипулятору. Это полезно для получения показаний сенсоров, коммутаторов и других периферийных компонентов.

Основной метод

Копировать# Получение значения I2C устройства
value = manipulator.get_i2c_value(name, timeout_seconds=60.0, throw_error=True)

Параметры

• name: имя I2C устройства (строка)
• timeout_seconds: таймаут выполнения команды (по умолчанию 60.0)
• throw_error: выбрасывать исключение при ошибке (по умолчанию True)

Доступные I2C устройства

Коммутатор:

• commutator/sel_serv — выбор сервопривода
• commutator/en_serv — включение сервопривода
• commutator/en_fan — включение вентилятора
• commutator/pwm1 — значение ШИМ 1
• commutator/pwm2 — значение ШИМ 2
• commutator/fd_key — статус кнопки freedrive
• commutator/adc_temp — температура с АЦП

Примеры использования

Чтение значения с I2C устройства

Копировать
# Получение значения с коммутатора
fd_key_value = manipulator.get_i2c_value("commutator/fd_key")
if fd_key_value is not None:
    print(f"Статус freedrive: {'ВКЛ' if fd_key_value < 1000 else 'ВЫКЛ'} (значение: {fd_key_value})")
else:
    print("Не удалось получить значение")

# Завершение работы
manipulator.disconnect()

Типичные сценарии использования

• Определение статуса кнопки freedrive
• Мониторинг температуры для контроля перегрева
• Диагностика состояния периферийных устройств

14. Воспроизведение аудио

Манипулятор поддерживает воспроизведение аудиофайлов. Это может быть полезно для звуковых уведомлений, предупреждений или интерактивных сценариев.

Основные методы

Копировать# Синхронное воспроизведение аудио
manipulator.play_audio(file_name, timeout_seconds=60.0, throw_error=True)

Параметры

• file_name: имя аудиофайла (строка). Файл должен находиться в доступной директории манипулятора.
• timeout_seconds: таймаут выполнения команды (по умолчанию 60.0)
• throw_error: выбрасывать исключение при ошибке (по умолчанию True)

Примеры использования

Синхронное воспроизведение

Копировать# Простое воспроизведение аудиофайла
try:
    manipulator.play_audio('start.wav')
    print("Аудиофайл воспроизведен успешно")
except Exception as e:
    print(f"Ошибка воспроизведения аудио: {e}")

Типичные сценарии использования

• Звуковые уведомления о начале/завершении операции
• Предупреждающие сигналы при ошибках
• Интерактивные сценарии с обратной связью
• Озвучивание состояния системы

Примечания

• Поддерживаются распространенные аудиоформаты (WAV, MP3)
• Файлы должны быть предварительно загружены на манипулятор
• Воспроизведение выполняется через встроенную аудиосистему манипулятора

Примеры использования команд

В составе SDK предоставлены примеры, демонстрирующие использование основных команд управления манипулятором и дополнительными модулями. Они позволяют ознакомиться с базовыми возможностями, а также служат отправной точкой для разработки собственных сценариев.

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

Заключение

Если возникли проблемы — используйте диагностические инструменты SDK и обращайтесь в техническую поддержку ПРОМОБОТ с подробными логами.