New: adding vl53l0x sensor
This commit is contained in:
@@ -1,129 +1,138 @@
|
||||
Ниже представлена структурированная документация по MQTT-топикам, составленная на основе предоставленного вами кода. Документация разделена на логические блоки для удобства использования (управление и телеметрия).
|
||||
Вот обновленная и расширенная документация по MQTT-интерфейсу, включающая новую функциональность работы с датчиками расстояния **VL53L0X**, а также оптимизации, появившиеся в коде.
|
||||
|
||||
---
|
||||
|
||||
# 📡 Документация по MQTT интерфейсу (ESP32 + TMC2209 + Servo)
|
||||
# 📡 Документация по MQTT интерфейсу (ESP32 + TMC2209 + Servo + VL53L0X)
|
||||
|
||||
## 📌 Общая информация
|
||||
- **Архитектура**: ESP32 (FreeRTOS задача `mqttTask`).
|
||||
- **Период опроса телеметрии**: 500 мс.
|
||||
- **Оптимизация трафика**: Публикация данных происходит **только при изменении значения** (реализован кэш последних отправленных значений).
|
||||
- **Оптимизация трафика**:
|
||||
1. Публикация данных происходит **только при изменении значения** (строгое кэширование).
|
||||
2. Используется статический буфер (`intToString`/`uintToString`) вместо динамического класса `String` для экономии памяти и предотвращения фрагментации кучи.
|
||||
- **Префиксы**:
|
||||
- `.../control/...` — топики для **отправки команд** устройству (подписка устройства).
|
||||
- `.../feedback/...` — топики для **получения статуса/телеметрии** от устройства (публикация устройства).
|
||||
- `.../control/...` — топики для **отправки команд** устройству (подписка).
|
||||
- `.../feedback/...` — топики для **получения статуса/телеметрии** от устройства (публикация).
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 1. Управление шаговым двигателем (Motor Control)
|
||||
|
||||
Устройство подписывается на эти топики для получения команд.
|
||||
|
||||
| Топик | Тип данных | Описание | Пример полезной нагрузки (Payload) |
|
||||
| Топик | Тип данных | Описание | Пример 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`, `""` |
|
||||
| `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"` в feedback. | `1`, `reset` |
|
||||
|
||||
### Телеметрия двигателя (Motor Feedback)
|
||||
*(Публикуется только при изменении)*
|
||||
- `motor/feedback/rpm` (Integer): Текущая скорость.
|
||||
- `motor/feedback/totalsteps` (Integer): Общее количество шагов.
|
||||
- `motor/feedback/is_run` (String: `true`/`false`): Двигатель движется.
|
||||
- `motor/feedback/driver/status` (String: `on`/`off`): Общий статус драйвера.
|
||||
- `motor/feedback/tmc/status` (String: `on`/`off`): Статус программного включения TMC.
|
||||
|
||||
#### Детальная телеметрия TMC2209 (`motor/feedback/tmc/...`)
|
||||
- `current_percent` (Integer): Текущий % рабочего тока.
|
||||
- `microsteps` (Integer): Текущий режим микрошага.
|
||||
- `sg_result` (Integer): Текущее значение StallGuard (нагрузка).
|
||||
- `interstep_duration` (Integer): Длительность между шагами.
|
||||
- `status/over_temp` (String: `true`/`false`): Перегрев.
|
||||
- `status/short_to_ground` (String: `true`/`false`): КЗ на землю.
|
||||
- `status/open_load` (String: `true`/`false`): Обрыв нагрузки.
|
||||
- `status/stealth_chop_active` (String: `true`/`false`): Активен ли StealthChop.
|
||||
- `status/standstill` (String: `true`/`false`): Двигатель в покое.
|
||||
- `status/current_scaling` (Integer): Внутренний масштабный коэффициент тока.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 2. Управление драйвером TMC2209 (TMC Control)
|
||||
## 🦾 2. Управление сервоприводами (Servo 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}`
|
||||
Поддержка нескольких каналов (`{channel}` от `0` до `MAX_SERVOS - 1`).
|
||||
|
||||
### Команды
|
||||
| Топик (пример для канала 0) | Тип данных | Описание | Пример Payload |
|
||||
| :--- | :---: | :--- | :--- |
|
||||
| `servo/control/0/angle` | Integer (0-180) | Установить угол поворота сервопривода. | `90`, `180`, `0` |
|
||||
| `servo/control/0/enable` | String | Включить (`on`, `1`, `true`) или выключить сервопривод. | `on`, `off`, `true` |
|
||||
| `servo/control/0/angle` | Integer (0-180) | Установить угол поворота. | `90` |
|
||||
| `servo/control/0/enable` | String | Включить (`on`, `1`, `true`) или выключить. | `on` |
|
||||
|
||||
*Примечание: Код использует `sscanf(topic, "servo/control/%d/%s", &channel, command)`, поэтому команда может быть любой строкой, но обрабатываются только `angle` и `enable`.*
|
||||
### Обратная связь
|
||||
- `servo/0/feedback/status` (String: `on`/`off`): Статус питания сервопривода.
|
||||
- `servo/0/feedback/angle` (Integer): Текущий установленный угол.
|
||||
|
||||
### Обратная связь (Публикация устройства)
|
||||
Устройство публикует состояние конкретного канала только при его изменении.
|
||||
---
|
||||
|
||||
## 📏 3. Управление датчиками VL53L0X (Sensor Control) **(НОВОЕ)**
|
||||
|
||||
Поддержка до 8 каналов (`VL53L0X_MAX_CHANNELS = 8`). Топики используют параметр `{channel}` (0–7).
|
||||
|
||||
| Топик | Тип данных | Описание | Пример Payload |
|
||||
| :--- | :---: | :--- | :--- |
|
||||
| `sensor/control/mode` | Integer | Установка глобального режима измерения (0 до `MODE_COUNT - 1`). | `0`, `1` |
|
||||
| `sensor/control/mode_name` | String | *Заглушка/Логирование.* Принимает имя режима для отладки. | `LongRange` |
|
||||
| `sensor/control/calibrate/start/{ch}`| Integer | Начало калибровки: указать близкое расстояние в мм. | `50` |
|
||||
| `sensor/control/calibrate/finish/{ch}`| Integer | Завершение калибровки: указать дальнее расстояние в мм. | `500` |
|
||||
| `sensor/control/clear_cal/{ch}` | Any | Сбросить калибровку для указанного канала. | `1` |
|
||||
| `sensor/control/enable/{ch}` | String | Включить (`on`, `1`, `true`) или выключить конкретный канал. | `on` |
|
||||
| `sensor/control/publish_all` | Any | **Принудительный сброс кэша.** Заставляет устройство немедленно опубликовать текущие значения всех датчиков, даже если они не изменились. | `1` |
|
||||
|
||||
---
|
||||
|
||||
## 📊 4. Телеметрия датчиков VL53L0X (Sensor Feedback) **(НОВОЕ)**
|
||||
|
||||
### Глобальная информация о режиме
|
||||
Публикуется только при смене режима измерения:
|
||||
- `sensor/feedback/mode` (String): Человекочитаемое имя текущего режима (например, "Default", "LongRange").
|
||||
- `sensor/feedback/mode_id` (Integer): Числовой ID текущего режима.
|
||||
- `sensor/feedback/max_range` (Integer): Максимальная дальность для текущего режима (в мм).
|
||||
|
||||
### Постатусная информация по каналам (`{channel}` = 0..7)
|
||||
*(Публикуется только при изменении состояния или значения)*
|
||||
|
||||
| Топик (пример для канала 0) | Тип данных | Описание |
|
||||
| :--- | :---: | :--- |
|
||||
| `servo/0/feedback/status` | String (`on`/`off`) | Текущий статус включения сервопривода на канале 0. |
|
||||
| `servo/0/feedback/angle` | Integer | Текущий установленный угол (в градусах) сервопривода на канале 0. |
|
||||
| `sensor/feedback/0/status` | String (`on`/`off`) | Включен ли логически данный канал. |
|
||||
| `sensor/feedback/0/calibrated` | String (`true`/`false`)| Была ли проведена калибровка для этого канала. |
|
||||
| `sensor/feedback/0/distance` | Integer или String | **Калиброванное** расстояние в мм. Если значение `65535` (ошибка/вне диапазона), публикуется строка `"out_of_range"`. |
|
||||
| `sensor/feedback/0/raw` | Integer | **Сырое** (некалиброванное) значение расстояния в мм. |
|
||||
|
||||
*(Замените `0` на актуальный номер канала при использовании)*
|
||||
*Примечание: Топики `distance` и `raw` публикуются только если канал активен (`vl53l0xIsChannelActive`).*
|
||||
|
||||
---
|
||||
|
||||
## 💡 Важные особенности реализации
|
||||
## 💡 Важные особенности реализации (Обновлено)
|
||||
|
||||
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`. Значения вне этого диапазона будут проигнорированы.
|
||||
1. **Безопасная работа со строками**: В новом коде добавлены функции `intToString` и `uintToString`, использующие статические буферы. Это полностью устраняет риск фрагментации памяти (heap fragmentation) при частой публикации телеметрии, который был присущ использованию класса `String`.
|
||||
2. **Принудительная публикация**: Топик `sensor/control/publish_all` сбрасывает кэш значений `distance` и `raw` на `65535`. При следующем цикле (через 500 мс) система "увидит" изменение и гарантированно отправит актуальные данные. Это полезно при подключении нового клиента, которому нужно получить текущее состояние без перезагрузки устройства.
|
||||
3. **Обработка ошибок дальности**: Если датчик возвращает `65535` (стандартный код ошибки "вне диапазона" или сбоя измерения для VL53L0X), в топик `distance` публикуется понятная строка `"out_of_range"`, а не число, что упрощает обработку на стороне клиента.
|
||||
4. **Изоляция каналов**: Цикл телеметрии VL53L0X предварительно проверяет `vl53l0xIsChannelPresent(ch)`, поэтому несуществующие или отключенные на аппаратном уровне каналы не создают лишнего трафика.
|
||||
|
||||
---
|
||||
|
||||
### Пример сценария использования (CLI / mosquitto)
|
||||
### 🛠️ Примеры использования (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/rpm" -m "100"
|
||||
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"
|
||||
# --- Сервопривод (канал 0) ---
|
||||
mosquitto_pub -t "servo/control/0/enable" -m "on"
|
||||
mosquitto_pub -t "servo/control/0/angle" -m "90"
|
||||
|
||||
# Подписаться на всю телеметрию двигателя для отладки
|
||||
mosquitto_sub -t "motor/feedback/#" -v
|
||||
# --- Датчики VL53L0X ---
|
||||
# Включить канал 1
|
||||
mosquitto_pub -t "sensor/control/enable/1" -m "on"
|
||||
|
||||
# Начать калибровку канала 1 (близкая точка 50 мм)
|
||||
mosquitto_pub -t "sensor/control/calibrate/start/1" -m "50"
|
||||
# ... передвинуть объект ...
|
||||
# Завершить калибровку канала 1 (дальняя точка 400 мм)
|
||||
mosquitto_pub -t "sensor/control/calibrate/finish/1" -m "400"
|
||||
|
||||
# Принудительно запросить публикацию всех текущих показаний датчиков
|
||||
mosquitto_pub -t "sensor/control/publish_all" -m "1"
|
||||
|
||||
# Подписаться на все события датчиков для отладки
|
||||
mosquitto_sub -t "sensor/feedback/#" -v
|
||||
```
|
||||
|
||||
Если вам нужно добавить эту документацию в ваш репозиторий, я могу оформить её в виде готового файла `README.md` или `MQTT_API.md` с дополнительными разделами (например, схемой подключения или настройкой `config.h`).
|
||||
Reference in New Issue
Block a user