Ниже представлена структурированная документация по MQTT-топикам, составленная на основе предоставленного вами кода. Документация разделена на логические блоки для удобства использования (управление и телеметрия).

---

# 📡 Документация по MQTT интерфейсу (ESP32 + TMC2209 + Servo)

## 📌 Общая информация
- **Архитектура**: ESP32 (FreeRTOS задача `mqttTask`).
- **Период опроса телеметрии**: 500 мс.
- **Оптимизация трафика**: Публикация данных происходит **только при изменении значения** (реализован кэш последних отправленных значений).
- **Префиксы**: 
  - `.../control/...` — топики для **отправки команд** устройству (подписка устройства).
  - `.../feedback/...` — топики для **получения статуса/телеметрии** от устройства (публикация устройства).

---

## ⚙️ 1. Управление шаговым двигателем (Motor Control)

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

| Топик | Тип данных | Описание | Пример полезной нагрузки (Payload) |
| :--- | :---: | :--- | :--- |
| `motor/control/rpm` | Integer | Целевая скорость в об/мин (RPM). **Отрицательные значения** включают реверс. | `-150`, `0`, `300` |
| `motor/control/driver` | String | Аппаратное включение/выключение драйвера (пин `EN_PIN`). `on` = LOW (включен), любое другое = HIGH (выключен). | `on`, `off` |
| `motor/control/totalsteps/reset` | Any | Сброс счетчика шагов в ноль. После сброса устройство само опубликует `0` в топик обратной связи. | `1`, `reset`, `""` |

---

## 🛠️ 2. Управление драйвером TMC2209 (TMC Control)

Специфические команды для настройки микросхемы TMC2209.

| Топик | Тип данных | Описание | Пример полезной нагрузки |
| :--- | :---: | :--- | :--- |
| `motor/control/tmc/current_percent` | Integer (0-100) | Установка рабочего тока в процентах. Ток удержания (Hold) автоматически устанавливается как 50% от рабочего. | `75` |
| `motor/control/tmc/microsteps` | Integer | Установка режима микрошага. | `16`, `32`, `256` |
| `motor/control/tmc/stallguard` | Integer | Установка порога чувствительности StallGuard (защита от заклинивания/определение нагрузки). | `10`, `50` |
| `motor/control/tmc/enable` | String | Программное включение/выключение чипа TMC. | `on`, `off` |
| `motor/control/tmc/stealthchop` | String | Включение/выключение режима StealthChop (бесшумный режим). | `on`, `off` |
| `motor/control/tmc/coolstep` | String | Включение/выключение режима CoolStep (динамическое управление током). | `on`, `off` |

---

## 📊 3. Телеметрия шагового двигателя (Motor Feedback)

Устройство публикует эти данные **только при изменении значения**, проверка происходит каждые 500 мс.

| Топик | Тип данных | Описание |
| :--- | :---: | :--- |
| `motor/feedback/rpm` | Integer | Текущая фактическая скорость вращения (RPM). |
| `motor/feedback/totalsteps` | Integer (String) | Общее количество сделанных шагов (накапливаемое). |
| `motor/feedback/is_run` | String (`true`/`false`) | Флаг: двигатель в движении (`true`) или остановлен (`false`). |
| `motor/feedback/driver/status` | String (`on`/`off`) | Общий статус драйвера (результат `checkDriverStatus()`). |
| `motor/feedback/tmc/status` | String (`on`/`off`) | Статус программного включения TMC (результат `checkTmcSoftwareEnable()`). |

### Детальная телеметрия TMC2209
*(Публикуется только если `tmcIsInitialized() == true`)*

| Топик | Тип данных | Описание |
| :--- | :---: | :--- |
| `motor/feedback/tmc/current_percent` | Integer | Текущий установленный процент рабочего тока. |
| `motor/feedback/tmc/microsteps` | Integer | Текущее значение микрошага. |
| `motor/feedback/tmc/sg_result` | Integer | Текущее значение StallGuard (нагрузка на вал). |
| `motor/feedback/tmc/interstep_duration`| Integer | Длительность между шагами (мкс/такты). |
| `motor/feedback/tmc/status/over_temp` | String (`true`/`false`) | Предупреждение или отключение по перегреву. |
| `motor/feedback/tmc/status/short_to_ground`| String (`true`/`false`) | Короткое замыкание на землю (фаза A или B). |
| `motor/feedback/tmc/status/open_load` | String (`true`/`false`) | Обрыв нагрузки (отключен двигатель) на фазе A или B. |
| `motor/feedback/tmc/status/stealth_chop_active`| String (`true`/`false`) | Фактически активный режим StealthChop. |
| `motor/feedback/tmc/status/standstill` | String (`true`/`false`) | Двигатель находится в состоянии покоя. |
| `motor/feedback/tmc/status/current_scaling`| Integer | Внутренний масштабный коэффициент тока драйвера. |

---

## 🦾 4. Управление сервоприводами (Servo Control)

Поддержка нескольких каналов (сервоприводов). Топики используют динамический параметр `{channel}` (номер канала, от `0` до `MAX_SERVOS - 1`).

### Команды (Подписка устройства)
Базовый паттерн: `servo/control/{channel}/{command}`

| Топик (пример для канала 0) | Тип данных | Описание | Пример Payload |
| :--- | :---: | :--- | :--- |
| `servo/control/0/angle` | Integer (0-180) | Установить угол поворота сервопривода. | `90`, `180`, `0` |
| `servo/control/0/enable` | String | Включить (`on`, `1`, `true`) или выключить сервопривод. | `on`, `off`, `true` |

*Примечание: Код использует `sscanf(topic, "servo/control/%d/%s", &channel, command)`, поэтому команда может быть любой строкой, но обрабатываются только `angle` и `enable`.*

### Обратная связь (Публикация устройства)
Устройство публикует состояние конкретного канала только при его изменении.

| Топик (пример для канала 0) | Тип данных | Описание |
| :--- | :---: | :--- |
| `servo/0/feedback/status` | String (`on`/`off`) | Текущий статус включения сервопривода на канале 0. |
| `servo/0/feedback/angle` | Integer | Текущий установленный угол (в градусах) сервопривода на канале 0. |

*(Замените `0` на актуальный номер канала при использовании)*

---

## 💡 Важные особенности реализации

1. **Анти-спам (Кэширование)**: В коде реализована строгая проверка `if (current_value != last_pub_value)`. Это означает, что если двигатель стоит, а его параметры не меняются, топик `motor/feedback/rpm` **не будет** засорять сеть сообщениями каждые 500 мс. Сообщение придет только при изменении.
2. **Сброс шагов**: При получении команды на `motor/control/totalsteps/reset`, устройство не только сбрасывает внутренний счетчик, но и принудительно публикует `"0"` в `motor/feedback/totalsteps`, чтобы синхронизировать состояние с клиентом.
3. **Логика пина Enable**: Для `motor/control/driver` значение `"on"` подает `LOW` на `EN_PIN` (что стандартно для TMC2209 означает **включение** драйвера), а любое другое значение подает `HIGH` (выключение).
4. **Безопасность серво**: При отправке команды `angle`, код проверяет диапазон `0 <= angle <= 180`. Значения вне этого диапазона будут проигнорированы.

---

### Пример сценария использования (CLI / mosquitto)

```bash
# Включить драйвер
mosquitto_pub -t "motor/control/driver" -m "on"

# Запустить двигатель на 200 об/мин вперед
mosquitto_pub -t "motor/control/rpm" -m "200"

# Включить бесшумный режим
mosquitto_pub -t "motor/control/tmc/stealthchop" -m "on"

# Повернуть сервопривод на канале 1 на 90 градусов и включить его
mosquitto_pub -t "servo/control/1/enable" -m "on"
mosquitto_pub -t "servo/control/1/angle" -m "90"

# Подписаться на всю телеметрию двигателя для отладки
mosquitto_sub -t "motor/feedback/#" -v
```

Если вам нужно добавить эту документацию в ваш репозиторий, я могу оформить её в виде готового файла `README.md` или `MQTT_API.md` с дополнительными разделами (например, схемой подключения или настройкой `config.h`).