← Калибровка датчиков | Содержание | Далее: Интеграция с Home Assistant →

11. Руководство по интеграции MQTT

Version: 1.2.0
Date: 2025-12-24

Полное руководство по подключению ACRouter через MQTT, включая структуру топиков и интеграцию с Home Assistant.

Содержание

• Обзор
• Возможности
• Быстрый старт
• Структура топиков
• Консольные команды
• Конфигурация
• Тестирование топиков
• Устранение неполадок

Обзор

ACRouter поддерживает протокол MQTT для:

• Мониторинг в реальном времени — метрики мощности, напряжение, токи, состояние роутера
• Удалённое управление — переключение режимов, управление диммером, аварийная остановка
• Конфигурация — удалённая настройка параметров
• Интеграция с Home Assistant — автоматическое обнаружение для бесшовной интеграции с умным домом

The MQTT client is based on ESP-IDF's esp-mqtt library with automatic reconnection, Last Will & Testament (LWT), and QoS support.

Возможности

Быстрый старт

1. Включение MQTT через последовательную консоль

# Set broker URL (replace with your broker IP)
mqtt-broker mqtt://192.168.1.10:1883

# Enable MQTT
mqtt-enable

# Check status
mqtt-status

2. Проверка подключения

======================================================
  MQTT Status
======================================================
State:         Connected
Enabled:       Yes
Broker:        mqtt://192.168.1.10:1883
Device ID:     039C7C
Device Name:   (default)
HA Discovery:  Enabled
Pub Interval:  5000 ms
------------------------------------------------------
Uptime:        125 sec
Published:     250 messages
Received:      3 messages
======================================================

3. Подписка на топики

Пример с использованием клиентских утилит Mosquitto:

# Subscribe to all ACRouter topics
mosquitto_sub -h 192.168.1.10 -t "acrouter/#" -v

Структура топиков

Все топики следуют шаблону: acrouter/{device_id}/category/name

{device_id} генерируется автоматически из последних 6 символов MAC-адреса (например, 039C7C) или может быть задан вручную.

Топики статуса (Retained)

Топики метрик (не Retained)

Публикуются каждые 5 секунд (настраивается).

Топики конфигурации (Retained)

Топики команд (только запись)

Отправляйте команды, публикуя сообщения в эти топики:

Системные топики (Retained)

Агрегированные JSON-топики

Для повышения эффективности метрики также публикуются в виде агрегированного JSON:

Топик: json/metrics

{
  "voltage": 230.5,
  "power_grid": -150.2,
  "power_solar": 1250.0,
  "power_load": 1100.0,
  "current_grid": 0.65,
  "current_solar": 5.43,
  "current_load": 4.78,
  "direction": "supplying"
}

Консольные команды

Управление подключением

Конфигурация

Примеры

# Configure broker with authentication
mqtt-broker mqtt://192.168.1.10:1883
mqtt-user myuser
mqtt-pass mypassword
mqtt-enable

# Set custom device name for Home Assistant
mqtt-device-name "Solar Router Kitchen"

# Reduce publish frequency to 10 seconds
mqtt-interval 10000

# Disable Home Assistant auto-discovery
mqtt-ha-discovery 0

Конфигурация

Ключи хранилища NVS

Все настройки MQTT сохраняются в NVS (энергонезависимое хранилище):

Значения по умолчанию

Тестирование топиков

Для тестирования топиков можно использовать любой MQTT-клиент. В примерах ниже используются утилиты Mosquitto (mosquitto_sub / mosquitto_pub).

Подписка на все топики

mosquitto_sub -h 192.168.1.10 -t "acrouter/#" -v

Подписка на конкретные топики

# Status only
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/status/#" -v

# Metrics only
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/metrics/#" -v

# JSON aggregated
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/json/#" -v

Отправка команд

# Change mode to AUTO
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/mode" -m "auto"

# Set dimmer to 50% (in MANUAL mode)
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/dimmer" -m "50"

# Emergency stop
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/emergency_stop" -m "1"

# Reboot device
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/reboot" -m "1"

# Force refresh all data
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/refresh" -m "1"

Обновление конфигурации через MQTT

# Set control gain
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/config/control_gain/set" -m "200"

# Set balance threshold
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/config/balance_threshold/set" -m "25"

Устранение неполадок

Проблемы с подключением

Симптом: esp-tls: select() timeout

Решения:

1. Проверьте, что брокер запущен и доступен
2. Убедитесь, что файрвол разрешает порт 1883
3. Проверьте формат URL брокера: mqtt://IP:PORT
4. Протестируйте подключение к брокеру с другого клиента

"Client has started" Error

Симптом: Повторяющиеся ошибки mqtt_client: Client has started

Решение: Это был баг в ранних версиях. Обновите прошивку до последней версии, где esp_mqtt_client_start() вызывается только один раз.

WiFi не подключён

Symptom: MQTT doesn't connect on boot

Пояснение: Теперь MQTT ожидает подключения WiFi перед попыткой соединения. Сначала проверьте состояние WiFi:

wifi-status

Сообщения не принимаются

Симптом: Команды отправлены, но не обрабатываются

Решения:

1. Проверьте правильность написания топика (учитывается регистр)
2. Убедитесь, что ID устройства совпадает: mqtt-status
3. Проверьте, что сообщение получено: в логе устройства отображается MQTT: Command: mode = auto

Home Assistant не обнаруживает устройство

Symptom: Device doesn't appear in Home Assistant

Решения:

1. Убедитесь, что HA Discovery включено: mqtt-ha-discovery 1
2. Проверьте, что интеграция MQTT в HA настроена
3. Выполните повторную публикацию: mqtt-publish или перезагрузите устройство
4. Проверьте логи HA на наличие сообщений обнаружения

Смотрите также

• 12_HOME_ASSISTANT.md — подробности интеграции с Home Assistant
• 07_COMMANDS_EN.md — полный справочник команд
• 05_API_REFERENCE_EN.md — документация REST API

Последнее обновление: 2025-12-24

← Калибровка датчиков | Содержание | Далее: Интеграция с Home Assistant →