home-assistant

Интеграции Meshtastic для Home Assistant

:::warning Note

Из-за известной проблемы с устройствами nRF52 и JSON устройства nRF52 в настоящее время не поддерживаются для использования с Home Assistant.

:::

Интеграция Meshtastic в Home Assistant поднимает контроль и мониторинг вашей mesh-сети на новый уровень. На этой странице мы проведем вас через процесс создания сущностей датчиков Meshtastic MQTT в Home Assistant. Независимо от того, хотите ли вы следить за уровнем заряда батареи, окружающими условиями или даже получать уведомления от вашей mesh-сети, эти интеграции предоставят вам необходимые инструменты.

:::info

Рекомендуется скачать MQTT Explorer для анализа JSON-потоков, проходящих через брокер. Его можно скачать здесь http://mqtt-explorer.com/.

:::

Создание сущностей датчиков Meshtastic MQTT

• Убедитесь, что ваша mesh-единица подключена к вашему MQTT-брокеру и использует JSON как вывод.

• Откройте configuration.yaml и добавьте следующую строку:

mqtt: !include mqtt.yaml

• Создайте новый текстовый файл с именем mqtt.yaml в корневой директории home assistant (в той же папке, что и configuration.yaml).

• Скопируйте следующий код в файл mqtt.yaml.

Пример телеметрии узла по умолчанию

sensor:

# Node #1 

  - name: "Node 1 Battery Voltage"
    unique_id: "node_1_battery_voltage"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and
            value_json.payload.voltage is defined and
            value_json.payload.temperature is not defined %}
        {{ (value_json.payload.voltage | float) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    unit_of_measurement: "Volts"
    # Telemetry packets come in two flavors: The default node telemetry, and the I2C sensor data.
    # Both packets contain "voltage" so we check for temperature to ignore the sensor packet here.

  - name: "Node 1 Battery Percent"
    unique_id: "node_1_battery_percent"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.battery_level is defined %}
        {{ (value_json.payload.battery_level | float) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    device_class: "battery"
    unit_of_measurement: "%"

  - name: "Node 1 ChUtil"
    unique_id: "node_1_chutil"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.channel_utilization is defined %}
        {{ (value_json.payload.channel_utilization | float) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    unit_of_measurement: "%"

  - name: "Node 1 AirUtilTX"
    unique_id: "node_1_airutiltx"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.air_util_tx is defined %}
        {{ (value_json.payload.air_util_tx | float) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    unit_of_measurement: "%"

Сущности модуля телеметрии

• Если у вас установлены датчики окружающей среды, создайте для них сущности, включив некоторые или все из следующих блоков:

  - name: "Node 1 Temperature"
    unique_id: "node_1_temperature"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.temperature is defined %}
        {{ (((value_json.payload.temperature | float) * 1.8) +32) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    device_class: "temperature"
    unit_of_measurement: "°F"
# With device_class: "temperature" set, make sure to use the configured unit for temperature in your HA instance.
# If you don't, then non-temperature messages will change the value of this sensor by reinterpreting the current state with the wrong unit, unless you account for it.
# For Celsius use:    {{ (value_json.payload.temperature | float) | round(1) }} 
# For Fahrenheit use: {{ (((value_json.payload.temperature | float) * 1.8) +32) | round(2) }}

  - name: "Node 1 Humidity"
    unique_id: "node_1_humidity"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.relative_humidity is defined %}
        {{ (value_json.payload.relative_humidity | float) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    device_class: "humidity"
    unit_of_measurement: "%"

  - name: "Node 1 Pressure"
    unique_id: "node_1_pressure"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.barometric_pressure is defined %}
        {{ (value_json.payload.barometric_pressure | float) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    device_class: "pressure"
    unit_of_measurement: "hPa"
# With device_class: "pressure" set, make sure to use the configured unit for pressure in your HA instance.
# For psi use:    {{ ((value_json.payload.barometric_pressure | float) / 68.9475729) | round(2) }} 

  - name: "Node 1 Gas Resistance"
    unique_id: "node_1_gas_resistance"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    state_class: measurement
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.gas_resistance is defined %}
        {{ (value_json.payload.gas_resistance | float) | round(2) }}
      {% else %}
        {{ this.state }}
      {% endif %}
    unit_of_measurement: "MOhms"

Сущности сообщений

• Для дополнительной функциональности вы можете создать сущность для сообщений, полученных от узла:

  - name: "Node 1 Messages"
    unique_id: "node_1_messages"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    value_template: >-
      {% if value_json.from == 4038675309 and value_json.payload.text is defined %}
        {{ value_json.payload.text }}
      {% else %}
        {{ this.state }}
      {% endif %}

Карты и Device Tracker

Чтобы ваши узлы отображались на картах в Home Assistant, вам потребуется настроить сущность device_tracker. К счастью, Home Assistant позволяет создавать их ad-hoc, просто вызывая сервис device_tracker.see из скрипта или автоматизации.

Для этого создайте новую автоматизацию и используйте меню с тремя точками, чтобы переключиться в режим "Edit in YAML", и настройте её следующим образом:

alias: Update Node 1 location
description: Update Meshtastic node when corresponding MQTT messages are seen.
trigger:
  - platform: mqtt
    topic: msh/US/2/json/LongFast/!67ea9400
    payload: "on"
    value_template: |-
      {% if value_json.from == 4038675309 and
            value_json.payload.latitude_i is defined and 
            value_json.payload.longitude_i is defined %}on{% endif %}
condition: []
action:
  - service: device_tracker.see
    metadata: {}
    data:
      dev_id: node_1
      gps:
        - "{{ (trigger.payload | from_json).payload.latitude_i | int * 1e-7 }}"
        - "{{ (trigger.payload | from_json).payload.longitude_i | int * 1e-7 }}"
      battery: "{{ states('sensor.node_1_battery_percent')|float(0) }}"
mode: single

Поле dev_id в вызове сервиса определяет, как будет называться сущность device_tracker, например device_tracker.node_1 для приведенного выше. Убедитесь, что у вас разные имена в этом поле для разных узлов, иначе они все отобразятся под одним трекером! Meshtastic представляет широту и долготу в целых числах, поэтому их нужно умножить на 1e-7, чтобы получить реальное местоположение.

Трекеры устройств также поддерживают несколько дополнительных полей, но наиболее релевантным для использования Meshtastic является уровень заряда батареи, который можно получить из ранее созданных датчиков, как показано.

Дополнительные сущности

Сущности Home Assistant можно создавать для любого типа данных, публикуемых в MQTT. Например: altitude, latitude_i, longitude_i, time, current и neighbors. Используйте приведенные выше шаблоны в качестве руководства для создания дополнительных сущностей по желанию.

Настройка с вашим топиком и ID узлов

• В каждой сущности замените msh/US/2/json/LongFast/!67ea9400 на топик, на который публикует ваш узел. В этом примере !67ea9400 относится к узлу, на котором включен mqtt в mesh и который публикует в брокер.

• В каждой сущности замените 4038675309 на номер узла радиостанции, которую вы хотите мониторить. В этом примере 4038675309 — это узел в mesh с датчиками окружающей среды и телеметрией, который я хочу наблюдать. Номера узлов можно найти, мониторя вывод в MQTT Explorer, прослушивая с аддоном MQTT или используя Python CLI с meshtastic --info.

Дополнительные узлы

Скопируйте и вставьте эти сущности, затем измените name, unique_id, from и states, чтобы создать сущности из параметров любых дополнительных узлов:

  - name: "Node 2 Messages"
    unique_id: "node_2_messages"
    state_topic: "msh/US/2/json/LongFast/!67ea9400"
    value_template: >-
      {% if value_json.from == 695318008 and value_json.payload.text is defined %}
        {{ value_json.payload.text }}
      {% else %}
        {{ this.state }}
      {% endif %}

Проверка конфигурации и перезагрузка YAML

• В Home Assistant запустите CHECK CONFIGURATION в разделе инструментов разработчика, а затем перезагрузите всю конфигурацию yaml.

:::danger warning

Всегда проверяйте конфигурацию перед перезагрузкой YAML или перезапуском Home Assistant, чтобы выявить ошибки.

:::

Создание карточек дашборда

Карточка сущностей для телеметрии

Создайте новую карточку сущностей и выберите сущности, которые вы создали.

Карточка журнала для сообщений

Карточка журнала полезна для ведения записи входящих сообщений из mesh-сети. Ниже приведен пример настройки карточки журнала.

Запуск автоматизаций HA

Возможно настроить запуск автоматизаций Home Assistant на основе сообщений или событий в вашей mesh-сети.

Уведомления

В этом примере ожидается сообщение, содержащее @Tropho, после чего отправляется всплывающее уведомление на его раскладушку с сообщением. Опционально можно настроить отправку ВСЕХ сообщений из mesh-сети в виде уведомлений HA на ваш телефон.

Добавьте следующий код в ваш файл automations.yaml. Обязательно измените topic, regex_search и service в соответствии с вашей конфигурацией.

- alias: Meshtastic - New notification
  description: any message with an @Tropho will send to mobile device
  trigger:
    - platform: mqtt
      topic: msh/US/2/json/LongFast/!67ea9400
      value_template: |
        {% if value_json.type == "text" %}on{% endif %}
      payload: "on"
      id: text
      trigger: mqtt
  condition:
    - condition: template
      value_template: "{{ trigger.payload_json.payload.text | regex_search('@Tropho') }}"
    # or send ALL messages from the mesh to HA notifications (except for range tests)
    # value_template: "{{ trigger.payload_json.payload.text is defined and "seq " not in trigger.payload_json.payload.text}}"
      enabled: true
  action:
    - service: notify.mobile_app_trophos_galaxy_z_flip5
      data:
      # show the message as coming from "Meshtastic": 
        message: "Meshtastic: {{ trigger.payload_json.payload.text }}"
      # or show the device id instead:  
      # message: "{{ trigger.payload_json.from }}: {{ trigger.payload_json.payload.text }}"
    - delay:
        hours: 0
        minutes: 0
        seconds: 30
        milliseconds: 0
  mode: single

Такая же автоматизация очень полезна для запуска других действий в Home Assistant. Например, вы можете включить вентилятор, когда температура достигнет определенного значения, или проиграть звук на динамике при получении нового сообщения.

Создание сущности для отправки сообщений

Возможно создать поле ввода текста для отправки сообщений в вашу mesh-сеть из Home Assistant.

Сущность помощника ввода текста

Сначала создайте сущность помощника ввода текста. Предпочтительный способ настройки поля ввода текста — через интерфейс HA в разделе Настройки > Устройства и службы > Помощники. Нажмите кнопку добавления, затем выберите опцию Текст. Создайте помощник ввода текста с максимальной длиной 190 символов для надежности. См. пример ниже:

Создание автоматизации для отправки сообщений

Эта автоматизация будет проверять поле отправки на изменения. После ввода сообщения нажмите Enter или кликните вне поля, и автоматизация отправит текстовую строку в формате JSON на брокер MQTT.

Для работы убедитесь, что ваш узел имеет настроенный канал Meshtastic с названием "mqtt" и включенным downlink. PSK не имеет значения. Этот канал позволяет узлу прослушивать сообщения на тему msh/US/2/json/mqtt/.

Теперь убедитесь, что вы публикуете в ту же тему "mqtt" и обновите ID устройства и поле from в примере ниже. Можно добавить поле channel для передачи на другой индекс канала, отличный от основного, или поле to с номером узла для отправки DM.

yaml - alias: Meshtastic - Send Automation description: "" trigger: - platform: state entity_id: - input_text.meshtastic_send_box condition: [] action: - delay: hours: 0 minutes: 0 seconds: 1 milliseconds: 0 - service: mqtt.publish data: qos: 0 retain: false topic: msh/US/2/json/mqtt/!67ea9400 payload: >- {"from":1743426560,"type":"sendtext","payload":"{{ states('input_text.meshtastic_send_box') }}"} - delay: hours: 0 minutes: 0 seconds: 1 milliseconds: 0 - service: input_text.set_value data: value: " " target: entity_id: input_text.meshtastic_send_box - delay: hours: 0 minutes: 0 seconds: 2 milliseconds: 0 mode: single

Добавьте эту карточку на дашборд, перейдя в Редактировать дашборд -> + ДОБАВИТЬ КАРТОЧКУ. Затем выполните поиск ПО СУЩНОСТИ для Meshtastic Send Box и отметьте галочкой рядом с записью. Нажмите ПРОДОЛЖИТЬ, затем ДОБАВИТЬ НА ДАШБОРД.