MAX7219 数字显示

max7219 显示平台允许你在 ESPHome 中使用 MAX7219 数字显示。请注意，此组件仅用于数字”矩阵”显示，对于 7 段显示，请参见 Max7219。

由于与 MAX7219 数字的通信是通过 SPI 进行的，因此你需要在配置中有一个 SPI 总线，并设置 mosi_pin（不需要 miso_pin）。将 VCC 连接到 3.3V（制造商推荐 4+ V，但 3.3V 似乎工作正常），DIN 连接到你的 mosi_pin， CS 连接到你的 cs_pin，最后 GND 连接到 GND。

你甚至可以级联多个 MAX7219，方法是将级联中前一个芯片的 DOUT 连接到下一个 DIN。超过约 3 个芯片时，3.3V 可能不够，所以你可能需要使用电平转换器。

# 示例配置条目
spi:
  clk_pin: D0
  mosi_pin: D1

display:
  - platform: max7219digit
    cs_pin: D2
    num_chips: 4
    intensity: 15
    lambda: |-
      it.print(0, 0, id(digit_font), "HELLO!");

配置变量

cs_pin (必需, Pin Schema): 你连接 CS 线的引脚。
num_chips (可选, int): 用于级联的芯片数量。默认为 4。
rotate_chip (可选): 旋转每个 8x8 芯片。有效值为 0、90、180 和 270。默认为 0。
scroll_enable (可选, boolean): 内容无法容纳时打开滚动模式。默认为 true。
scroll_mode (可选): 设置滚动模式。可选值为 CONTINUOUS 或 STOP。默认为 CONTINUOUS
- CONTINUOUS ：始终滚动且文本连续重复，你可能需要在末尾添加一些分隔符。
- STOP ：文本结束时等待 scroll_dwell 时间，然后滚动重置到开头。
scroll_speed (可选, Time): 设置滚动速度。默认为 250ms
scroll_delay (可选, Time): 设置滚动开始前的延迟时间。默认为 1s。
scroll_dwell (可选, Time): 设置在滚动结束时的等待时间，然后再从头开始。仅在 STOP 模式下使用。默认为 1s。
reverse_enable (可选, boolean): 对于某些显示器，显示顺序是反的（“DCBA”）。此选项会将显示顺序反转回（“ABCD”）。默认为 false。
intensity (可选, int): MAX7219 驱动输出的强度。范围从 0（最弱）到 15（最亮）。默认为 15。
lambda (可选, lambda): 用于在 MAX7219 上渲染内容的 lambda。更多信息请参见渲染 Lambda。
update_interval (可选, Time): 重新绘制屏幕的间隔。默认为 1s。
spi_id (可选, ID): 如果你想使用多个 SPI 总线，请手动指定 SPI 组件的 ID。
id (可选, ID): 手动指定用于代码生成的 ID。
num_chip_lines (可选, int): 在 Multiline 模式下使用时显示的行数。默认为 1。示例：https://github.com/esphome/esphome/pull/1622#issue-836179156
chip_lines_style (可选): Multiline 模式下的行如何连接？可选值为 zigzag 和 snake。默认为 snake
flip_x (可选, boolean): 翻转屏幕的水平轴。默认为 false。

操作

以下操作是下一部分中显示的 LAMBDA 函数的副本。

`max7219digit.invert_on` / `max7219digit.invert_off` 操作

操作 max7219digit.invert_on 将反转显示。因此背景像素为开启，文本像素为关闭。max7219digit.invert_off 将显示恢复为正常。背景像素仅在下次更新时设置，而在各种函数（如 print、line 等）中绘制的像素则直接受反转命令影响。

`max7219digit.turn_on` / `max7219digit.turn_off` 操作

可以通过操作 max7219digit.turn_on / max7219digit.turn_off “动态”地打开和关闭显示。

`max7219digit.reverse_on` / `max7219digit.reverse_off` 操作

通过这些操作，你可以将显示方向从从左到右反转为从右到左。

`max7219digit.intensity` 操作

可以通过此操作”动态”设置屏幕的亮度。

intensity (可选, int): MAX7219 驱动输出的强度。范围从 0（最弱）到 15（最亮）。默认为 15。

渲染 Lambda

MAX7219 数字基于功能齐全的显示渲染引擎，因为它每个 max7219 芯片都有 8 X 8 个单个像素的概念。在 lambda 中，你收到一个名为 it 的变量，与其他所有显示一样。一些”特殊” 命令已被添加到基本显示集中。

display:
  - platform: max7219digit
    cs_pin: D8
    num_chips: 4
    lambda: |-
      it.strftime(0, 0, id(digit_font), "%H:%M", id(hass_time).now());
      it.image(24, 0, id(my_image));
      it.line(1, 7, 21, 7);
font:
  - file: "pixelmix.ttf"
    id: digit_font
    size: 6

time:
  - platform: homeassistant
    id: hass_time

image:
  - platform: file
    file: "smile.png"
    id: my_image
    type: BINARY

这大致是用于显示图像中 MAX7219 的代码。

字体使用

因为 8x8 矩阵显示的可用高度只有 8 像素，所以建议使用 TrueType 字体来显示文本是不可取的。在渲染单个字符时很容易出现不美观的伪影。基于位图的 bdf 格式字体更合适。例如 5x7.bdf 或 5x8.bdf

滚动

默认情况下，MAX7219Digit 显示启用了滚动。参数可以在 YAML 文件中设置。它们也可以在 Lambda 中通过添加以下命令来更改：

it.scroll(<on/off>, <mode>, <speed>, <delay>, <dwell>);

on/off -> 打开或关闭滚动，使用 true 或 false
mode -> max7219digit::CONTINUOUS 为连续滚动，max7219digit::STOP = 在末尾停止并重置
speed -> 设置滚动速度（每个一点的步骤的 ms）
delay -> 滚动开始时的暂停时间
dwell -> 滚动结束时的暂停（仅在模式 1 中）

display:
  - platform: max7219digit
    # ...
    lambda: |-
      # ...
      it.scroll(true, max7219digit::CONTINUOUS, 100, 5000, 1500);
      // 或
      it.scroll(true, max7219digit::CONTINUOUS);
      // 或
      it.scroll(true);

如果文本适合屏幕，屏幕不会滚动。
printdigit("...") 和 printdigitf("...") 是显示文本的替代方式，不会滚动

屏幕反转

display:
  - platform: max7219digit
    # ...
    lambda: |-
      it.invert_on_off(true);
      // 在位置 0（左侧）打印 Hello
      it.print(0,0, id(digit_font), "Hello!");

函数 it.invert_on_off(true); 将反转显示。因此背景像素为开启，文本像素为关闭。it.invert_on_off(false); 将显示恢复为正常。如果不使用参数：it.invert_on_off(); 则反转将在开启和关闭之间切换。每次显示更新时都会发生这种情况。从而产生闪烁效果。背景像素仅在下次更新时设置，而在各种函数（如 print、line 等）中绘制的像素则直接受反转命令影响。

display:
  - platform: max7219digit
    # ...
    lambda: |-
      it.invert_on_off(true);
      // 在位置 0（左侧）打印 Hello
      it.print(0,0, id(digit_font), "Hello!");
      it.line(0, 0, 31, 7, COLOR_OFF);

此代码只影响屏幕上绘制的线。线将从左上到右下擦除像素。背景不受影响。

屏幕亮度

屏幕的亮度可以在 lambda 代码中通过以下命令”动态”设置：it.intensity(0 .. 15 )。

display:
  - platform: max7219digit
    # ...
    lambda: |-
      it.intensity(10);

屏幕开/关

可以通过 lambda 代码中的以下命令”动态”地打开和关闭显示：it.turn_on_off(true or false)。

display:
  - platform: max7219digit
    # ...
    lambda: |-
      it.turn_on_off(true);

为了快速显示，代码中嵌入了一些额外的命令和相关联的 8 像素字体。三种方法（printdigit、printdigitf 和 strftimedigit ）可用于显示字符。每个 8 X 8 网格用于显示单个字符。因此空间效率不高。命令格式为：it.printdigit("1234"); 或 it.printdigitf("%s","1234") ;

请参见格式化文本了解 printf 格式化规则的介绍，以及显示时间了解 strftime 时间格式化的介绍。