Ниже представлена структурированная документация по 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 на актуальный номер канала при использовании)

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

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

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

# Включить драйвер
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).

README.md Unescape Escape