使用 Home Assistant 和 ePaper 构建空气质量面板

家里安装了Home Assistant，我用它来监控多个传感器，例如门开、运动、温度和湿度传感器，同时控制家中的许多灯光。在其中一个房间，我将其用作工作间，并存放油漆和溶剂等物品，这里还配备了一个空气质量传感器，用于测量不同的环境参数。

虽然我可以在电脑或手机上的Home Assistant仪表板上查看这些数据，但我认为如果有一个专用的、始终可见的面板，让我能随时一目了然地查看房间状况，会更加方便实用。

对于这类应用，我认为电子纸(ePaper)或电子纸显示屏(EPD)将是理想的选择，适合我所设想的面板。这种显示技术非常适合展示不频繁变化的信息，功耗极低，由于其双稳态特性，即使在无电情况下也能保持图像清晰可见，并且在明亮环境中仍能提供出色的可读性。

该面板还利用了Home Assistant的一个非常实用的功能：它提供了多种机制，使其他板卡和设备能够与所监测的传感器信息进行交互。通过这一功能，面板可以向空气质量传感器请求数据，并在电子纸屏幕上显示出来。

在接下来的部分中，我将向您展示如何使用此Home Assistant功能，并基于使用Arduino中的Seeed_GFX进行编程的Seeed Studio EE05板构建一个信息面板。

空气质量监测

家庭、学校或工作场所的室内环境条件，会直接影响在这些地方度过数小时的人们的健康、福祉和舒适度。

空气质量检测仪有多种类型，其质量与精度不同，可测量与空气质量相关的各种参数。

就我而言，安装的仪器并非专业级设备，无法提供高精度的测量结果。相反，它虽然价格低廉，但仍然可以作为评估房间空气质量的通用参考。

尽管这些数值不应被理解为专业测量结果，但它们为环境的整体状况提供了有用的参考。通过这种方式，该传感器有助于检测变化，判断何时适合通风，并做出更优决策，以维持一个更健康、更舒适的室内空间。

连接到 Home Assistant

我安装的空气质量传感器兼容Tuya(在某些国家也称为Smart Life)，并通过Tuya集成与Home Assistant连接，使用我的家庭WiFi网络。这样，传感器会将测量数据发送至Tuya平台，Home Assistant便可将其作为系统中的实体进行集成。

在 Home Assistant 中，该传感器有五个主要关联实体，分别对应设备测量或计算出的值。它们的名称或标识符如下：

这些实体的数值可以从Home Assistant仪表板中查看，每个实体都以独立卡片的形式显示。这是我的自定义仪表板视图，用于展示该房间(我的工作室)的空气质量数据和照明状态。

这是查看 Home Assistant 实体值的常规方式，但如果我们想在外部设备(例如带电子纸屏幕的面板)上显示它们，该怎么做呢?

这些机制各有其特点、优势和不足。对于本项目，我们将采用第一种：REST API，因为它不仅使用简单，而且功能极为强大。

REST API

REST API 是一种用于 Web 应用程序开发的技术，它允许访问网站以交换信息。该技术使用 HTTP 协议及其部分方法(如 GET 或 POST)来请求或发送信息。

要访问 REST API，我们必须使用一个特定的 URL 或地址，称为端点。通过查看 Home Assistant 的文档，我们可以找到相应的端点：

其中 IP_ADDRESS 是用于访问 Home Assistant 安装主仪表板的相同 IP 地址。

可以通过 GET、POST 和 DELETE 等方法向此端点发送 HTTP 请求，例如读取传感器值、设置实体的值或删除实体。

在所有情况下，发送和接收的信息均以 JSON 格式存在。此外，为限制对 Home Assistant 的访问，每个 HTTP 请求都必须包含一个 Authorization: Bearer TOKEN 头部，其中的令牌是一个唯一标识符，用于识别我们作为授权用户的身份。

提出请求

现在让我们更详细地了解如何向 Home Assistant 发送 GET 请求，以及它返回响应所使用的格式。

如果我们向该 URL 发送一个 GET 请求：

Home Assistant 将返回一个包含名为 的实体状态信息的 JSON 对象。

可以通过命令行使用 curl 轻松测试此功能。例如，如果实体是传感器测量的温度值 sensor.calidad_de_aire_temperature，那么在 Windows 上请求其值的 curl 命令格式如下：

其中 --token-- 是从管理面板生成的长期访问令牌，如前所述。

这是由 Home Assistant 返回的响应：

更易读的格式中，响应如下所示：

在这个JSON对象中包含大量信息。对于本项目，我们只关注state字段，该字段包含测量参数的值，也就是我们将显示在电子纸屏幕上的内容。

电子报面板

既然我们已经了解了如何从 Home Assistant 中获取实体值，接下来就让我们动手构建 ePaper 显示面板。首先，我们将查看项目中使用的组件，然后介绍使所有功能协同工作的软件。

电子纸显示屏

在这个项目中，我选择了Seeed Studio提供的4.26英寸单色电子纸显示屏。主要原因之一是其出色的800×480像素分辨率，能够以极高的清晰度和对比度显示信息。此外，它功耗低、刷新速度快，非常适合作为信息面板、电子阅读器及其他便携设备的显示选择。

EE05 板

为了控制4.26英寸的显示屏，我将使用另一款来自Seeed Studio的EE05控制器板。EE05是一款ePaper显示驱动板，其功能与EE04类似，但外形更为紧凑。它基于性能强大的XIAO ESP32-S3 Plus模块，集成了WiFi和蓝牙连接功能、电池接口、充电管理电路以及用于兼容ePaper显示屏的24针接口。

除了控制显示屏外，这块电路板还将负责连接到Home Assistant，并获取空气质量传感器测量的数据。借助XIAO ESP32-S3 Plus的Wi-Fi连接能力和处理能力，EE05会向Home Assistant发送必要的请求，获取五个对应实体的状态，然后将这些数据显示在连接的电子纸屏幕上。

组装面板

以下是面板的两张图片。第一张显示的是组装前的状态，第二张显示的是在测试第一个外壳原型时的情况。

软件

面板程序使用Arduino开发，并采用Seeed Studio创建的Seeed_GFX库，该库专为支持其ePaper显示屏和控制器板(如EE05)而优化。

完整的代码已添加到文章中。现在，让我们更详细地分析其各个部分：

包含

最初，我们有 #include 指令，用于加载不同的库：WiFi 用于连接 Wi-Fi，TFT_eSPI(Seeed_GFX)用于控制 ePaper 显示屏，HTTPClient 用于向服务器发送请求，ArduinoJson 用于处理服务器响应，以及 image，该文件包含作为面板背景的图像定义。

背景图片

面板背景图像以16级灰度的BMP格式创建，如下图所示。

然后，我使用 SenseCraft HMI 色彩抖动工具将此 BMP 文件转换为头文件。通过该工具，我首先应用 Floyd-Steinberg 抖动算法将颜色数量减少到每像素 1 位(1 bpp)，接着生成了包含图像定义的头文件。

这是生成的头文件的一部分：

驱动

尽管在 #include 指令中并未明确列出，但 Seeed_GFX 库要求我们创建一个 driver.h 文件，其中包含所使用的 ePaper 显示屏和控制器板的定义。为此，我使用了 Seeed Studio 提供的在线工具：

然后我将生成的代码复制到一个名为 driver.h 的新文件中：

声明

在此部分，创建并关联了电子报对象与显示界面。然后定义了若干常量：用于WiFi网络的用户名和密码、面板刷新时间(即连接Home Assistant更新数据的频率)以及用于身份验证所需的令牌。

功能

接下来，代码定义了几个函数。

程序中最重要的功能可能是 getHAState()，因为它负责调用 Home Assistant 的 REST API，以获取特定实体的状态。

该函数接收实体名称作为参数，例如 sensor.calidad_de_aire_temperature，并利用该信息构建相应的端点URL。然后检查板是否已连接到WiFi网络，并向Home Assistant发送HTTP GET请求。

要使请求被接受，需通过 Authorization 头部包含访问令牌。如果 Home Assistant 响应正确，该函数会接收到一个 JSON 对象，解析它并查找名为 state 的字段，其中包含实体的当前值。

最后，它会将该值以字符串形式返回。如果发生错误，例如缺少WiFi连接、HTTP请求错误或解析JSON时出现问题，函数将返回“--”。

准备

在代码的这一部分，开始执行 setup() 函数。在此处进行了一些初始准备工作：初始化串行控制台以进行调试，使板子连接到 Wi-Fi 网络，并准备 ePaper 显示屏。

已配置多个显示参数，背景图像已加载到驱动程序内存中，但尚未显示。

阅读价值观并展示它们

在最后一个阶段，通过之前定义的 getHAState() 函数，向 REST API 发送五个请求，以获取与空气质量传感器相关的五个实体的值。

然后，这些值会被加载到屏幕上。epaper.update() 方法会执行完整刷新，同时显示背景图像和实体值。

准备睡觉了……

屏幕刷新完成后，EE05的ESP32-S3会进入低功耗模式，持续时间由RefreshTime值(以分钟为单位)决定。由于ePaper具有双稳态特性，信息在下次更新前保持不变，同时功耗极低。

10秒的延迟在程序运行时非常有用，因为它能让你在IDE进入低功耗模式之前重新获得对电路板的控制权。

然后它就睡着了。

就这样。loop() 函数什么也不做。

结论

在这个项目中，我们构建了一个简单却非常实用的面板，可一目了然地查看集成到Home Assistant中的空气质量传感器所测量的数据。通过这些数据，可以快速了解房间的整体状况，并及时判断是否需要通风或改善室内环境。

在本文中，我们首先探讨了传感器所测量的参数以及这些值如何在 Home Assistant 中以独立实体的形式呈现。接着，我们回顾了一些从外部设备获取这些信息的方法，重点介绍了使用 REST API 的方式，即向相应的端点发送 HTTP GET 请求，并通过授权令牌安全地访问数据。

我们还分析了本项目所选用硬件的标准。ePaper显示屏非常适合此类信息面板，因为它具有出色的可读性、低功耗，并且即使在无电源的情况下也能保持图像清晰可见。目前，EE05板起着核心作用：它不仅作为4.26英寸ePaper显示屏的控制器，还通过集成的XIAO ESP32-S3 Plus模块，提供了Wi-Fi连接、处理能力、电池管理功能，以及紧凑的外形设计，特别适合开发此类应用。

最后，我们详细回顾了使用Arduino和Seeed_GFX开发的软件，从WiFi连接到向Home Assistant发送查询，再到处理JSON响应、提取状态字段、屏幕更新以及低功耗模式的应用。

最终成果是一个专用、自主且易于检查的面板，它结合了Home Assistant的功能、电子纸显示屏的优势以及EE05板的实用性。除了满足特定需求外，该项目还展示了一种简单的方法，用于创建物理界面，以可视化智能家居信息，而无需始终依赖电脑或手机。

本文编译自hackster.io