ozone-tech_owl_prime/arduino_code/Test/README.md

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

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