SenseCAP指示器—Home Assistant（家庭助理）应用程序开发

Get One Now 🖱️

欢迎来到Seeed SenseCAP指示器和Home Assistant开发教程。本指南将引导您完成使用Home Assistant Yellow将SenseCAP指示器与Home Assistant集成的步骤。

Home Assistant Yellow 预装在定制外壳中，带有树莓派计算模块4 (CM4)和无风扇、静音操作的定制散热器。CM4是一个没有无线的版本，有2gb RAM和16gb eMMC存储空间。预装的Home Assistant。

为了让您的SenseCAP指示器与Home Assistant一起工作，您需要遵循两个主要步骤:

1. 安装Home Assistant
2. 配置家庭助理投影

前提

在开始之前，请务必阅读SenseCAP指示板的用户指南，了解SenseCAP的软硬件信息。

安装 Home Assistant

Home Assistant是一个强大的开源家庭自动化平台，专注于隐私和本地控制。它提供了一个可定制和灵活的框架，以管理和自动化所有家庭设备从一个单一的，统一的平台。

使用Home Assistant Yellow，您可以按照这里提供的说明进行操作。此外，要在任何类型的树莓派或本地服务器上运行，您可以逐步遵循这个说明。

安装完成后，进入这个页面意味着你可以进入下一步。

:::小贴士:不知道如何安装Home Assistant? 一旦您安装了Home Assistant，请查看File Editor了解详细信息。 :::

Step 1: 安装Mosquitto Broker和File Editor

下一步是安装Mosquitto代理和File Editor。Mosquitto是一个开源消息代理，它实现了MQTT协议，而File Editor则允许你修改configuration. py 。不访问终端的Yaml `文件。

在Home Assistant Yellow中，您可以使用附加功能安装Mosquitto Broker和File Editor。

:::注意需要附加功能 Home Assistant Yellow自带Home Assistant操作系统，可以轻松安装插件。然而，Home Assistant Container不支持插件，这意味着除了Home Assistant之外，您还需要安装MQTT代理应用程序。具体请参见安装方法。 :::

:::小贴士

为了方便起见, 在侧边栏显示 'File editorr:

:::

现在我们有两个附加组件。

Step 2: 添加MQTT集成和配置

在安装MQTT代理之后，您需要将MQTT集成和配置添加到Home Assistant。这将允许Home Assistant助理与SenseCAP指示板通信。

:::提示 如果没有发现MQTT，重新启动Home Assistant以查看发现的新MQTT。 :::

Step 3: 修改"configuration.yaml" ，添加指示器实体

你可以使用Home Assistant Yellow中的文件编辑器插件来修改 configuration.yaml文件。

点击复制 Configuration.yaml ，配置集成

# Example configuration.yaml entry
mqtt:
  sensor:
    - unique_id: indicator_temperature
      name: "Indicator Temperature"
      state_topic: "indicator/sensor"
      suggested_display_precision: 1
      unit_of_measurement: "°C"
      value_template: "{{ value_json.temp }}"
    - unique_id: indicator_humidity
      name: "Indicator Humidity"
      state_topic: "indicator/sensor"
      unit_of_measurement: "%"
      value_template: "{{ value_json.humidity }}"
    - unique_id: indicator_co2
      name: "Indicator CO2"
      state_topic: "indicator/sensor"
      unit_of_measurement: "ppm"
      value_template: "{{ value_json.co2 }}"
    - unique_id: indicator_tvoc
      name: "Indicator tVOC"
      state_topic: "indicator/sensor"
      unit_of_measurement: ""
      value_template: "{{ value_json.tvoc }}"
  switch:
    - unique_id: indicator_switch1
      name: "Indicator Switch1"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch1 }}"
      payload_on: '{"switch1":1}'
      payload_off: '{"switch1":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch2
      name: "Indicator Switch2"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch2 }}"
      payload_on: '{"switch2":1}'
      payload_off: '{"switch2":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch3
      name: "Indicator Switch3"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch3 }}"
      payload_on: '{"switch3":1}'
      payload_off: '{"switch3":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch4
      name: "Indicator Switch4"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch4 }}"
      payload_on: '{"switch4":1}'
      payload_off: '{"switch4":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch6
      name: "Indicator Switch6"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch6 }}"
      payload_on: '{"switch6":1}'
      payload_off: '{"switch6":0}'
      state_on: 1
      state_off: 0
    - unique_id: indicator_switch7
      name: "Indicator Switch7"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      value_template: "{{ value_json.switch7 }}"
      payload_on: '{"switch7":1}'
      payload_off: '{"switch7":0}'
      state_on: 1
      state_off: 0
  number:
    - unique_id: indicator_switch5
      name: "Indicator Switch5"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      command_template: '{"switch5": {{ value }} }'
      value_template: "{{ value_json.switch5 }}"
    - unique_id: indicator_switch8
      name: "Indicator Switch8"
      state_topic: "indicator/switch/state"
      command_topic: "indicator/switch/set"
      command_template: '{"switch8": {{ value }} }'
      value_template: "{{ value_json.switch8 }}"

:::注意：如果您的本地服务器不支持Add-ons，例如Home Assistant容器，您需要通过终端修改configuration.yaml。 :::

下一步是修改configuration.yaml文件，以添加指示器实体。这个文件被Home Assistant用来跟踪设置中的各种实体。

将代码添加到configuration.yaml中，就像这样：

保存文件，并转到开发者工具以更新YAML配置。

Step 4: 编辑仪表板

最后一步是编辑Home Assistant仪表板。您需要将以下内容添加到仪表板的原始配置编辑器中：

点击复制仪表板YAML以更改UI

注意：这不是用于configuration.yaml。

views:
  - title: Indicator device
    icon: ''
    badges: []
    cards:
      - graph: line
        type: sensor
        detail: 1
        icon: mdi:molecule-co2
        unit: ppm
        entity: sensor.indicator_co2
      - graph: line
        type: sensor
        entity: sensor.indicator_temperature
        detail: 1
        icon: mdi:coolant-temperature
      - graph: line
        type: sensor
        detail: 1
        entity: sensor.indicator_humidity
      - graph: line
        type: sensor
        entity: sensor.indicator_tvoc
        detail: 1
        icon: mdi:air-filter
      - type: entities
        entities:
          - entity: switch.indicator_switch1
          - entity: switch.indicator_switch2
          - entity: switch.indicator_switch3
          - entity: switch.indicator_switch4
          - entity: number.indicator_switch5
          - entity: switch.indicator_switch6
          - entity: switch.indicator_switch7
          - entity: number.indicator_switch8
        title: Indicator control
        show_header_toggle: false
        state_color: true

创建一个用于SenseCAP指示器的仪表板（不一定要创建，任何仪表板都可以）。

切换侧边栏：设置->仪表板。

设置您喜欢的标题和图标，然后创建它。

按下 TAKE CONTROL 按钮

替换YAML内容如上所示：

现在您已完成Home Assistant配置。

为MQTT添加用户

项目配置

本节的目的是建立Home Assistant（HA）和指示器之间的默认通信。

Step 1：配置IP地址

通常，默认的Home Assistant服务器地址是homeassistant.local，如果您有多个Home Assistant服务器，或者如果没有默认的DNS解析，或者如果有多个IP服务器地址，您将需要相应地配置IP地址。

在ha_config.h中，更改CONFIG_BROKER_URL值，例如：

// #define CONFIG_BROKER_URL    "mqtt://homeassistant.local" // Default
#define CONFIG_BROKER_URL    "mqtt://192.168.1.100" // To yours

Step 2: 配置用户名和密码

如果您有用户名和密码，您需要对它们进行配置。这可以在indicator_ha.c文件中的mqtt_start函数中完成，具体是在mqtt_cfg配置中。如果您没有用户名和密码，可以将它们注释掉。

以下是如何配置用户名和密码的示例：

    esp_mqtt_client_config_t mqtt_cfg = {
        .broker.address.uri = CONFIG_BROKER_URL,
        .credentials.username = "MQTT_Indicator_1", // Your Home Assistant user
        .credentials.authentication.password = "kjdf", // user's password
    };

完成这些步骤并构建后，您应该能够看到Home Assistant和指示器一起正常工作。

构建并烧写本地固件

完成上述步骤后，您可以开始构建并烧写项目。

Download the Project

git clone https://github.com/Seeed-Solution/SenseCAP_Indicator_ESP32

1. 克隆git存储库。
2. 导航到examples\indicator_ha文件夹。
   • 运行idf.py -p PORT build flash monitor来构建、烧写并监视项目。
   • 要退出串行监视器，请键入Ctrl-]。

$ git clone https://github.com/Seeed-Solution/SenseCAP_Indicator_ESP32
$ cd SenseCAP_Indicator_ESP32/examples/indicator_ha
$ idf.py -p PORT build flash monitor

:::警告：需要 PSRAM 八位 120M 功能

该项目默认使用八位 120M 配置 PSRAM。请查看此处以启用PSRAM 八位 120M功能。 :::

要完整配置和使用ESP-IDF构建项目的步骤，请参考入门指南。

由于Home Assistant演示主要基于indicator_basis演示，因此您可以在滑动到其他面板时体验Home Assistant的功能。

附加信息

修改配置

在ha_config.h文件中，有几个用于MQTT通信的标签。这些标签用于识别系统中的不同组件，并可以根据您的需要进行修改。

例如，对于sensor5，标签定义如下：

#define CONFIG_SENSOR5_VALUE_KEY     "temp"
#define CONFIG_SENSOR5_UI_UNIT       "°C"
#define CONFIG_SENSOR5_UI_NAME       "Temp"
#define CONFIG_SENSOR5_TOPIC_DATA    CONFIG_TOPIC_SENSOR_DATA

CONFIG_SENSOR5_VALUE_KEY标签用于解析JSON和构造JSON数据。此标记确定将用于从传入的MQTT消息中提取传感器数据的密钥。

SenseCAP指示器UI

CONFIG_SENSOR5_UI_UNIT和CONFIG_SENSOR5_UI_NAME标签用于设置SenseCAP指示器上的显示。CONFIG_SENSOR5_UI_UNIT标签确定要显示的测量单位，而CONFIG_SENSOR5_UI_NAME标签确定要显示的传感器名称。

如果你想改变SenseCAP指示器上显示的标题或测量单位，你可以简单地修改CONFIG_SENSOR5_UI_UNIT和CONFIG_SENSOR5_UI_NAME标签。同样的原理也适用于其他传感器和开关。

CONFIG_BROKER_URL

CONFIG_BROKER_URL应该与Home Assistant的MQTT代理地址相关。这对于SenseCAP指示器和Home Assistant之间的通信至关重要。

ha_config.h 和Configuration.yaml之间的关系

ha_config.h文件是C编程语言的头文件。它包含在几个源文件之间共享的定义。在这种情况下，它包含与MQTT配置相关的定义。

"configuration.yaml"文件，另一方面，是Home Assistant使用的一个文件，用于跟踪您设置中的各种实体。

当你修改configuration. py 文件时。要添加指示器实体，你需要将ha_config.h文件中的定义添加到Home Assistant设置中。

indicator_ha.c 功能

indicator_ha.c文件包含了集成家庭助手的主要功能。它包括用于初始化MQTT客户机、订阅主题和处理传入消息的函数。

你可以在这里找到indicator_ha.c文件。

该文件包含Home Assistant集成的主要功能。它包括用于初始化MQTT客户机、订阅主题和处理传入消息的函数。下面是关键函数的简要概述以及它们是如何工作的:

1. mqtt_event_handler():该函数是MQTT事件的主要事件处理程序。每当MQTT客户机中发生事件时，例如到达新消息、建立连接或发生断开连接时，都会调用它。根据事件的类型，它执行不同的操作。例如，如果新消息到达，它会调用mqtt_message_arrived()函数来处理该消息。

2. mqtt_message_arrived():当新的MQTT消息到达时，调用此函数。它解析消息并根据消息的内容执行适当的操作。例如，它可能根据接收到的消息更新传感器或开关的状态。

3. mqtt_subscribe():此函数用于订阅MQTT主题。当您订阅一个主题时，您告诉MQTT代理您希望接收发布到该主题的消息。在SenseCAP指示器的上下文中，该函数用于订阅指示器的传感器和开关将其状态发布到的主题。

4. mqtt_publish():此函数用于将消息发布到MQTT主题。当您将消息发布到主题时，它将被发送到MQTT代理，然后由MQTT代理将其转发到订阅了该主题的所有客户机。在SenseCAP指示器的上下文中，此函数用于发布指示器的传感器和开关的状态。

5. mqtt_app_start():此函数用于启动MQTT客户端。它设置MQTT客户机配置，创建MQTT客户机，设置MQTT事件处理程序，最后将MQTT客户机连接到MQTT代理。

6. indicator_ha_init():这是集成Home Assistant的主要初始化函数。它通过调用mqtt_app_start()初始化MQTT客户端，然后通过调用mqtt_subscribe()订阅必要的MQTT主题。

这些函数协同工作，实现SenseCAP指示器与Home Assistant之间通过MQTT进行通信。indicator_ha_init()函数启动MQTT客户端并订阅必要的主题。然后，每当MQTT事件发生时，都会调用mqtt_event_handler()函数来处理事件。如果新消息到达，它会调用mqtt_message_arrived()来处理该消息。每当传感器或开关的状态发生变化时，都会调用mqtt_publish()将新状态发布到相应的MQTT主题。

来源

1. Demo SDK: SenseCAP指示器的Demo SDK可以在GitHub上找到。
2. indicator_ha.c文件:该文件包含集成家庭助手的主要功能。你可以在这里查看它。
3. 用户指南:提供SenseCAP指示板的软硬件详细信息。你可以在这里阅读它。
4. Home Assistant安装指南:如果你刚接触Home Assistant，本指南将帮助你安装和设置它。你可以在这里找到它。
5. ESP-IDF入门指南:该指南提供了配置和使用ESP-IDF来构建项目的完整步骤。你可以在这里访问它。
6. Home Assistant（家庭助理）的概念和术语

技术支持

需要帮助你的SenseCAP指示器吗?我们是来帮助你的!

如果您在学习本教程过程中遇到任何问题或问题，请随时联系我们的技术支持。我们永远在这里提供帮助!

访问我们的查看官方Discord频道提出您的问题或GitHub讨论分享您想要的一切!