Документация MQTT-интерфейса управления шаговым двигателем (TMC2209)
Данный документ описывает структуру MQTT-топиков для удаленного управления шаговым двигателем и получения телеметрии с драйвера TMC2209.
Особенности реализации:
- Интервал опроса: Чтение и публикация статусов происходят каждые 500 мс.
- State-Change Publishing: Для экономии трафика и снижения нагрузки на брокер, устройство публикует данные в топики телеметрии только при изменении значения.
- Сброс кэша: При успешном переподключении к MQTT-брокеру внутренний кэш значений сбрасывается, что гарантирует отправку актуального состояния всех параметров сразу после установки связи.
1. Топики управления (Subscribe)
Устройство подписано на эти топики для получения команд от пользователя или вышестоящей системы (Home Assistant, Node-RED и т.д.).
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
motor/control/rpm |
int |
Установка целевой скорости вращения (об/мин). Отрицательные значения включают реверс. | 150 (вперед)-50 (назад) |
motor/control/driver |
string |
Аппаратное управление пином EN драйвера. |
on (включить)Любое другое (выключить) |
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 |
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 |
2.4. Общие статусы системы
| Топик | Тип данных | Описание | Пример Payload |
|---|---|---|---|
motor/feedback/driver/status |
string |
Общий результат аппаратной проверки драйвера (checkDriverStatus()). |
on / off |
motor/feedback/tmc/status |
string |
Результат проверки программного флага включения TMC (checkTmcSoftwareEnable()). |
on / off |
3. Примеры сценариев использования
Запуск двигателя с нужными параметрами
# Устанавливаем ток 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 "turnon"
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 при движении обычно означает столкновение или заклинивание механизма.