# Документация 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` (вперед)<br>`-50` (назад) |
| `motor/control/driver` | `string` | Аппаратное управление пином `EN` драйвера. | `on` (включить)<br>`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` (центр)<br>`0` (мин)<br>`180` (макс) |
| `servo/control/pulse` | `int (500-2500)` | Прямая установка ширины управляющего импульса в микросекундах. | `1500` (центр)<br>`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. Управление шаговым двигателем

#### Запуск двигателя с нужными параметрами
```bash
# Устанавливаем ток 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"
```

#### Аварийная остановка и сброс
```bash
# Остановка (скорость 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. Управление сервоприводом

#### Базовое позиционирование
```bash
# Установить серво в центральное положение (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-скрипт)
```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
```

#### Точное управление по ширине импульса
```bash
# Установка точного положения через ширину импульса (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"
```

#### Управление питанием серво
```bash
# Отключить серво (снять удержание, экономия энергии)
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. Комплексные сценарии

#### Одновременное управление обоими двигателями
```bash
# Запуск шагового двигателя на 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/#"
```

---