minor edit

arduino_code/Test/README.md

@@ -1,36 +1,96 @@
-# MQTT Топики для управления двигателем и обратной связи
+# Документация MQTT-интерфейса управления шаговым двигателем (TMC2209)
 
-## Подписка (от клиента к устройству)
+Данный документ описывает структуру MQTT-топиков для удаленного управления шаговым двигателем и получения телеметрии с драйвера TMC2209. 
 
-### Основное управление
-- `motor/control/rpm` - Установка целевой скорости в об/мин (положительное значение - вперед, отрицательное - назад)
-- `motor/control/totalsteps/reset` - Сброс счетчика шагов
+**Особенности реализации:**
+* **Интервал опроса:** Чтение и публикация статусов происходят каждые **500 мс**.
+* **State-Change Publishing:** Для экономии трафика и снижения нагрузки на брокер, устройство публикует данные в топики телеметрии **только при изменении значения**.
+* **Сброс кэша:** При успешном переподключении к MQTT-брокеру внутренний кэш значений сбрасывается, что гарантирует отправку актуального состояния всех параметров сразу после установки связи.
 
-### Управление TMC (настройки двигателя)
-- `motor/control/tmc/current_percent` - Установка текущего тока в процентах (0-100)
-- `motor/control/tmc/microsteps` - Установка микрокроков (1, 2, 4, 8, 16, 32, 64, 128, 256)
-- `motor/control/tmc/stallguard` - Включение/выключение StallGuard (0-255)
-- `motor/control/tmc/enable` - Включение/выключение двигателя ("on"/"off")
-- `motor/control/tmc/stealthchop` - Включение/выключение бесшумного режима. ("on"/"off")
-- `motor/control/tmc/coolstep` - Включение/выключение режима динамического снижение тока при малой нагрузке("on"/"off")
+---
 
-## Публикация (от устройства к клиенту)
+## 1. Топики управления (Subscribe)
+Устройство подписано на эти топики для получения команд от пользователя или вышестоящей системы (Home Assistant, Node-RED и т.д.).
 
-### Базовая телеметрия
-- `motor/feedback/rpm` - Текущая скорость в об/мин
-- `motor/feedback/totalsteps` - Общее количество шагов
-- `motor/feedback/is_run` - Статус работы двигателя ("true"/"false")
+| Топик | Тип данных | Описание | Пример Payload |
+| :--- | :--- | :--- | :--- |
+| `motor/control/rpm` | `int` | Установка целевой скорости вращения (об/мин). Отрицательные значения включают **реверс**. | `150` (вперед)<br>`-50` (назад) |
+| `motor/control/driver` | `string` | Аппаратное управление пином `EN` драйвера. | `on` (включить)<br>*Любое другое* (выключить) |
+| `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` |
 
-### TMC Телеметрия
-- `motor/feedback/tmc/current_percent` - Текущий ток в процентах
-- `motor/feedback/tmc/microsteps` - Текущие микрокроки
-- `motor/feedback/tmc/sg_result` - Результат StallGuard
-- `motor/feedback/tmc/interstep_duration` - Длительность интервала шага (в наносекундах)
+---
 
-### Статусы TMC
-- `motor/feedback/tmc/status/over_temp` - Предупреждение о перегреве
-- `motor/feedback/tmc/status/short_to_ground` - Короткое замыкание на землю
-- `motor/feedback/tmc/status/open_load` - Предупреждение о коротком замыкании
-- `motor/feedback/tmc/status/stealth_chop_active` - Активен ли бесшумный режим.
-- `motor/feedback/tmc/status/standstill` - Стоп-состояние
-- `motor/feedback/tmc/status/current_scaling` - Масштабирование тока
+## 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. Примеры сценариев использования
+
+### Запуск двигателя с нужными параметрами
+```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 "turnon"
+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` при движении обычно означает столкновение или заклинивание механизма.

arduino_code/Test/src/motor.cpp

@@ -236,6 +236,19 @@ bool tmcIsCommunicating() {
     return res;
 }
 
+// Функция проверки состояния EN_PIN
+bool checkDriverStatus() {
+    bool en_state = (digitalRead(EN_PIN) == LOW);
+    return en_state;
+}
+
+// Функция проверки программного состояния TMC
+bool checkTmcSoftwareEnable() {
+    TMC2209::Settings s = tmcGetSettings();
+    bool tmc_state = s.software_enabled;
+    return tmc_state;
+}
+
 uint16_t tmcGetMicrostepsSetting() { return current_microsteps; }
 uint8_t tmcGetRunCurrentPercent() { return current_run_percent; }
 

arduino_code/Test/src/motor.h

@@ -36,5 +36,7 @@ TMC2209::Settings tmcGetSettings();
 uint16_t tmcGetStallGuardResult();
 uint32_t tmcGetInterstepDuration();
 uint16_t tmcGetMicrostepCounter();
+bool checkDriverStatus();
+bool checkTmcSoftwareEnable();
 
 #endif

arduino_code/Test/src/mqtt_handler.cpp

@@ -25,6 +25,8 @@ static int last_pub_short_gnd = -1;
 static int last_pub_open_load = -1;
 static int last_pub_stealth_active = -1;
 static int last_pub_standstill = -1;
+static int last_pub_driver_status = -1;
+static int last_pub_tmc_software_enable = -1;
 static uint8_t last_pub_current_scaling = 255;
 
 static void setup_wifi() {
@@ -71,7 +73,7 @@ static void callback(char* topic, byte* payload, unsigned int length) {
     }
     else if (strcmp(topic, "motor/control/driver") == 0) {
         // TMC2209: LOW = Enabled, HIGH = Disabled
-        bool enable = (strcmp(msg, "turnon") == 0);
+        bool enable = (strcmp(msg, "on") == 0);
         digitalWrite(EN_PIN, enable ? LOW : HIGH);
     }
     else if (strcmp(topic, "motor/control/totalsteps/reset") == 0) {
@@ -188,6 +190,17 @@ static void publishTelemetry() {
                 client.publish("motor/feedback/tmc/status/current_scaling", String(status.current_scaling).c_str());
                 last_pub_current_scaling = status.current_scaling;
             }
+
+            int cds = checkDriverStatus() ? 1 : 0;
+            if (cds != last_pub_driver_status) {
+                client.publish("motor/feedback/driver/status", cds ? "on" : "off");
+                last_pub_driver_status = cds;
+            }
+            int tse = checkTmcSoftwareEnable() ? 1 : 0;
+            if (tse != last_pub_tmc_software_enable) {
+                client.publish("motor/feedback/tmc/status", tse ? "on" : "off");
+                last_pub_tmc_software_enable = tse;
+            }
         }
         last_feedback_time = now;
     }