EEPW论坛

M5Paper 是基于 ESP32 的低功耗电子墨水屏开发板，搭载 960×540 分辨率的 IT8951E 控制器墨水屏，非常适合作为 Home Assistant 智能消息可视化终端，用于展示天气、通知、设备状态等信息。

1、硬件驱动兼容性

结合 M5Paper 官方文档与 ESPHome 官方文档，确认各硬件模块的支持情况如下：

• 触摸模块（GT911）：原生支持（gt911 Touch Screen Controller - ESPHome - Smart Home Made Simple）

• RTC 时钟模块（BM8563）：原生支持（BM8563 Time Source - ESPHome - Smart Home Made Simple）

• 温湿度模块（SHT30）：原生支持（SHT3X-D Temperature+Humidity Sensor - ESPHome - Smart Home Made Simple）

• 墨水屏控制器（IT8951E）：ESPHome 无原生驱动，需手动适配

2、IT8951E墨水屏驱动适配

在GitHub上找了一圈，好消息是GitHub 已有相关仓库（razqqm/m5paper_esphome），坏消息是已停更2年了，不兼容最新版ESPHOME，无法直接使用。

于是，我基于 M5Stack 官方驱动库（m5stack/M5GFX）中的 IT8951 驱动源码，对旧版驱动进行修改重构：

• 下载旧版仓库代码，保留 m5paper 、 it8951e 核心驱动文件夹，删除无用文件；

• 参照 M5GFX 官方 IT8951 驱动，修改适配最新版 ESPHome。

此处不展开介绍了，完整修改后的驱动代码可直接查看我的个人仓库（https://github.com/pysn2012/m5paper_esphome）。

3、编写ESPHOME配置文件

编写基础ESPHome配置文件，用于测试墨水屏的基础显示功能，配置分为以下几个部分：

① 基础配置：

# ESPHome 核心配置
esphome:
  name: ${device_name}
  friendly_name: ${friendly_name}
  min_version: 2025.5.0               # 要求的最低 ESPHome 版本
  name_add_mac_suffix: true           # 在设备名后附加 MAC 地址
  on_boot:
    - priority: -100                  # 低优先级
      then:
        - it8951e.clear:
            id: m5paper_display       # 清屏
        - delay: 100ms                # 等待 100 毫秒确保清屏完成
        - component.update: m5paper_display  # 手动触发屏幕刷新

esp32:
  board: m5stack_paper
  flash_size: 16MB
  framework:
    type: esp-idf
    advanced:
      minimum_chip_revision: '3.1'

② 添加外部自定义组件（IT8951E）：

# 外部自定义组件（本地路径）
external_components:
  - source:
      type: local
      path: components/

③ 使用开源的思源黑体，支持简体中文，配置2种字号：

font:
  - file:
      type: gfonts                  # 字体来源：谷歌字体
      family: "Noto Sans SC"        # 字体家族：思源黑体（简体中文）
      weight: 400                   # 字重：常规（Regular，400）
      italic: false                 # 非斜体
    id: cn_font                     # 字体唯一ID
    size: 36                        # 字号：36
    glyphs: ${allowed_characters}   # 只加载指定字符
    ignore_missing_glyphs: true     # 忽略字体中缺失的字符，不报错
  - file:
      type: gfonts
      family: "Noto Sans SC"
      weight: 400
      italic: false
    id: big_font
    size: 72
    glyphs: ${allowed_characters}
    ignore_missing_glyphs: true

④ 调用外部IT8951E组件，配置引脚、刷新逻辑及显示内容：

# SPI 总线
spi:
  clk_pin: GPIO14                 # SPI 时钟引脚
  mosi_pin: GPIO12                # MOSI
  miso_pin: GPIO13                # MISO

# 显示屏：M5Paper ePaper（基于 IT8951 驱动芯片）
display:
  - platform: it8951e
    id: m5paper_display
    model: M5EPD
    cs_pin: GPIO15                # 片选引脚
    reset_pin: GPIO23             # 复位引脚
    busy_pin: GPIO27              # 忙信号引脚
    rotation: 0                   # 屏幕旋转角度，0是横向
    reversed: False               # 不反转颜色
    update_interval: never        # 不自动刷新，仅手动更新
    # 在屏幕上绘制内容
    lambda: |-
      // 屏幕边缘画边框
      it.rectangle(10, 10, it.get_width() - 20, it.get_height() - 20);
      // 标题：顶部居中 —— 你好M5Paper
      it.print(it.get_width()/2, 30, id(cn_font), TextAlign::TOP_CENTER, "你好EEPW");
      it.print(it.get_width()/2, 100, id(big_font), TextAlign::TOP_CENTER, "M5paper 屏幕测试");

4、云端编译固件

由于国内网络环境限制，本地编译可能会遇到依赖包下载失败的问题，推荐使用 GitHub Actions workflows 进行云端编译，高效且稳定。

① 启用工作流：进入仓库页面，点击上方「Actions」选项卡，启用工作流功能；

② 编写workflows配置文件：

# 工作流名称
name: screen_test

# 触发条件
on:
  workflow_dispatch:  # 手动触发（推荐）

jobs:
  compile-esphome:
    runs-on: ubuntu-latest
    steps:
      # 步骤1：拉取仓库代码
      - name: 拉取仓库代码
        uses: actions/checkout@v4

      # 步骤2：配置 Python 环境
      - name: 配置 Python 环境
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      # 步骤3：安装 ESPHome
      - name: 安装 ESPHome
        run: |
          python -m pip install --upgrade pip
          pip install esphome

      # 步骤4：动态生成 secrets.yaml
      - name: Generate secrets.yaml
        run: |
          cat > secrets.yaml <<EOF
          wifi_ssid: "${{ secrets.WIFI_SSID }}"
          wifi_password: "${{ secrets.WIFI_PASSWORD }}"
          EOF

      # 步骤5：编译m5paper_esphome固件
      - name: 编译固件
        run: esphome compile screen_test.yaml

      # 步骤6：动态查找编译产物
      - name: 动态查找 firmware.bin
        id: find_fw
        run: |
          SEARCH_ROOT=".esphome/build"   # 与编译目录对应
          FIRMWARE=$(find "$SEARCH_ROOT" -name "firmware.bin" | head -n 1)
          OTA=$(find "$SEARCH_ROOT" -name "firmware.ota.bin" | head -n 1)
          FACTORY=$(find "$SEARCH_ROOT" -name "firmware.factory.bin" | head -n 1)

          if [[ -z "$FIRMWARE" ]]; then
            echo "::error::未找到 firmware.bin，请检查编译是否成功"
            exit 1
          fi

          echo "FIRMWARE=$FIRMWARE" >> $GITHUB_OUTPUT
          echo "OTA=$OTA" >> $GITHUB_OUTPUT
          echo "FACTORY=$FACTORY" >> $GITHUB_OUTPUT

      # 步骤7：上传固件
      - name: 上传固件到 Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: m5paper_esphome-${{ github.sha }}
          path: |
            ${{ steps.find_fw.outputs.FIRMWARE }}
            ${{ steps.find_fw.outputs.OTA }}
            ${{ steps.find_fw.outputs.FACTORY }}
            screen_test.yaml
          retention-days: 30

③ 配置 WIFI 加密参数：进入仓库「Settings > Actions」，添加两个仓库密钥（WIFI_SSID、WIFI_PASSWORD），编译时将自动注入 WIFI 信息；

④ 触发编译：选择「Build」工作流，点击「Run workflow」手动触发编译；

⑤ 下载固件：编译完成后，在工作流运行结果的「Artifacts」板块，下载生成的固件压缩包。

⑥ 固件选择：下载的压缩包包含3个bin文件，选择「firmware.factory.bin」（完整固件）用于烧录。

5、烧录固件

测试阶段推荐使用ESPConnect在线工具烧录，支持查看串口日志，便于调试：

① 用 USB 数据线将 M5Paper 开发板连接至电脑；

② 访问ESPConnect在线工具：https://thelastoutpostworkshop.github.io/ESPConnect/

③ 点击「连接」，在设备列表中选择对应的设备；

④ 左侧选择「闪存工具」，上传编译好的固件，勾选「写入前擦除整个闪存」；

⑤ 点击「烧录固件」，等待烧录完成。

烧录完成后，可打开串口监视器查看设备运行日志。

6、墨水屏效果

烧录成功后，屏幕即可正常显示内容。本项目使用开源思源黑体，完美支持中文显示，展示效果清晰。

Home Assistant上也会自动发现一个设备，不过目前这个设备没有实体。