Документация MQTT-интерфейса управления двигателями (TMC2209 + Сервопривод)
Данный документ описывает структуру MQTT-топиков для удаленного управления шаговым двигателем с драйвером TMC2209 и сервоприводом, а также получения телеметрии с обоих устройств.
Общие особенности реализации:
- Интервал опроса: Чтение и публикация статусов происходят каждые 500 мс.
- State-Change Publishing: Для экономии трафика и снижения нагрузки на брокер, устройство публикует данные в топики телеметрии только при изменении значения.
- Сброс кэша: При успешном переподключении к MQTT-брокеру внутренний кэш значений сбрасывается, что гарантирует отправку актуального состояния всех параметров сразу после установки связи.
- Единый контроллер: Оба устройства управляются через один ESP32 с общей MQTT-инфраструктурой.
1. Топики управления (Subscribe)
Устройство подписано на эти топики для получения команд от пользователя или вышестоящей системы (Home Assistant, Node-RED и т.д.).
1.1. Управление шаговым двигателем
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
motor/control/rpm |
int |
Установка целевой скорости вращения (об/мин). Отрицательные значения включают реверс. | 150 (вперед)-50 (назад) |
motor/control/driver |
string |
Аппаратное управление пином EN драйвера. |
on (включить)off (выключить) |
motor/control/totalsteps/reset |
any |
Сброс счетчика шагов в ноль. После сброса устройство опубликует 0 в motor/feedback/totalsteps. |
1 / reset |
motor/control/tmc/current_percent |
int (0-100) |
Установка тока двигателя (Run Current) в процентах. Ток удержания (Hold) автоматически устанавливается как 50% от заданного. | 80 |
motor/control/tmc/microsteps |
int |
Настройка режима микрошага. | 256, 64, 16, 4 |
motor/control/tmc/stallguard |
int |
Установка порогового значения StallGuard (защита от пропуска шагов / датчик нагрузки). | 5 |
motor/control/tmc/enable |
string |
Программное включение/выключение чипа TMC2209. | on / off |
motor/control/tmc/stealthchop |
string |
Включение/выключение режима StealthChop (бесшумная работа на малых скоростях). | on / off |
motor/control/tmc/coolstep |
string |
Включение/выключение режима CoolStep (адаптивное снижение тока для уменьшения нагрева). | on / off |
1.2. Управление сервоприводом
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
servo/control/angle |
int (0-180) |
Установка угла поворота сервопривода в градусах. | 90 (центр)0 (мин)180 (макс) |
servo/control/pulse |
int (500-2500) |
Прямая установка ширины управляющего импульса в микросекундах. | 1500 (центр)500 (мин) |
servo/control/enable |
string |
Включение/выключение сервопривода. При off происходит detach (снятие сигнала). |
on / off |
servo/control/detach |
string |
Принудительное отсоединение сигнала (серво перестаёт держать позицию, экономия энергии). | 1 / true |
2. Топики телеметрии (Publish)
Устройство публикует в эти топики текущее состояние двигателей и драйверов.
2.1. Базовая телеметрия шагового двигателя
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
motor/feedback/rpm |
int |
Текущая фактическая скорость вращения (об/мин). Может быть отрицательной при реверсе. | 145 |
motor/feedback/totalsteps |
unsigned long |
Накопительный счетчик шагов. | 145000 |
motor/feedback/is_run |
bool (string) |
Флаг вращения двигателя. | true / false |
2.2. Телеметрия настроек TMC2209
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
motor/feedback/tmc/current_percent |
int |
Текущий установленный рабочий ток (Run Current) в %. | 80 |
motor/feedback/tmc/microsteps |
int |
Текущее значение делителя микрошага. | 16 |
motor/feedback/tmc/sg_result |
uint16_t |
Текущее считанное значение StallGuard (индикатор нагрузки на вал). | 12 |
motor/feedback/tmc/interstep_duration |
uint32_t |
Текущая длительность интервала между шагами (в тиках/микросекундах). | 4500 |
2.3. Статусы и флаги драйвера (DRV_STATUS)
Эти топики отражают аппаратные флаги, считываемые из регистра статуса TMC2209.
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
motor/feedback/tmc/status/over_temp |
bool (string) |
Перегрев драйвера (предупреждение или аварийное отключение). | true / false |
motor/feedback/tmc/status/short_to_ground |
bool (string) |
Короткое замыкание на землю (на фазах A или B). | true / false |
motor/feedback/tmc/status/open_load |
bool (string) |
Обрыв нагрузки (не подключена катушка двигателя). | true / false |
motor/feedback/tmc/status/stealth_chop_active |
bool (string) |
Находится ли драйвер в режиме StealthChop в данный момент. | true / false |
motor/feedback/tmc/status/standstill |
bool (string) |
Находится ли двигатель в состоянии покоя (Standstill). | true / false |
motor/feedback/tmc/status/current_scaling |
uint8_t |
Текущий коэффициент масштабирования тока (Current Scaling), применяемый драйвером. | 150 |
motor/feedback/driver/status |
string |
Общий результат аппаратной проверки драйвера. | on / off |
motor/feedback/tmc/status |
string |
Результат проверки программного флага включения TMC. | on / off |
2.4. Телеметрия сервопривода
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
servo/feedback/angle |
int |
Текущий установленный угол поворота (0-180). | 90 |
servo/feedback/status |
string |
Статус сервопривода (включен/выключен). | on / off |
3. Примеры сценариев использования
3.1. Управление шаговым двигателем
Запуск двигателя с нужными параметрами
# Устанавливаем ток 70% и микрошаг 16
mosquitto_pub -t "motor/control/tmc/current_percent" -m "70"
mosquitto_pub -t "motor/control/tmc/microsteps" -m "16"
# Включаем тихий режим
mosquitto_pub -t "motor/control/tmc/stealthchop" -m "on"
# Аппаратно включаем драйвер и задаем скорость 100 RPM
mosquitto_pub -t "motor/control/driver" -m "on"
mosquitto_pub -t "motor/control/rpm" -m "100"
Аварийная остановка и сброс
# Остановка (скорость 0)
mosquitto_pub -t "motor/control/rpm" -m "0"
# Программное отключение чипа TMC
mosquitto_pub -t "motor/control/tmc/enable" -m "off"
# Сброс счетчика шагов
mosquitto_pub -t "motor/control/totalsteps/reset" -m "1"
Мониторинг нагрузки (StallGuard)
Для отслеживания нагрузки на вал или момента срыва шагов, необходимо слушать топик motor/feedback/tmc/sg_result. Резкое падение значения sg_result при движении обычно означает столкновение или заклинивание механизма.
3.2. Управление сервоприводом
Базовое позиционирование
# Установить серво в центральное положение (90°)
mosquitto_pub -t "servo/control/angle" -m "90"
# Установить в крайнее положение (180°)
mosquitto_pub -t "servo/control/angle" -m "180"
# Вернуть в ноль
mosquitto_pub -t "servo/control/angle" -m "0"
Плавное движение (bash-скрипт)
#!/bin/bash
for angle in 0 45 90 135 180 135 90 45 0; do
mosquitto_pub -t "servo/control/angle" -m "$angle"
sleep 1
done
Точное управление по ширине импульса
# Установка точного положения через ширину импульса (1500 мкс = центр)
mosquitto_pub -t "servo/control/pulse" -m "1500"
# Минимальное положение
mosquitto_pub -t "servo/control/pulse" -m "500"
# Максимальное положение
mosquitto_pub -t "servo/control/pulse" -m "2500"
Управление питанием серво
# Отключить серво (снять удержание, экономия энергии)
mosquitto_pub -t "servo/control/enable" -m "off"
# Включить серво (восстановить удержание позиции)
mosquitto_pub -t "servo/control/enable" -m "on"
# Принудительное отсоединение сигнала
mosquitto_pub -t "servo/control/detach" -m "1"
3.3. Комплексные сценарии
Одновременное управление обоими двигателями
# Запуск шагового двигателя на 50 RPM
mosquitto_pub -t "motor/control/rpm" -m "50"
# Одновременное перемещение серво в положение 45°
mosquitto_pub -t "servo/control/angle" -m "45"
# Мониторинг телеметрии обоих устройств
mosquitto_sub -t "motor/feedback/#" -t "servo/feedback/#"