HLK-FM22x 人脸识别模块

hlk_fm22x 组件允许你在 ESPHome 中使用 HLK-FM225 和 HLK-FM223 人脸识别模块。

HLK-FM225 人脸识别模块（数据手册、AliExpress）。图片来自 AliExpress。

组件/Hub

该模块可由 5V 输出供电。由于与读卡器的通信使用 UART（默认波特率为 115200）进行，你需要在配置中拥有一个UART 总线，并将 rx_pin 连接到读卡器的 TX，将 tx_pin 连接到读卡器的 RX。

# Example configuration entry
hlk_fm22x:
  on_face_scan_matched:
    ...
  on_face_scan_unmatched:
    ...
  on_face_scan_invalid:
    ...
  on_face_info:
    ...
  on_enrollment_done:
    ...
  on_enrollment_failed:
    ...

配置变量

该配置由三部分构成：核心组件、可选的各个传感器、可选的注册二进制传感器以及可选的版本文本传感器。

基本配置：

uart_id（可选，ID）：手动指定 UART hub 的 ID。
id（可选，ID）：手动指定用于代码生成的 ID。
on_face_scan_matched（可选，Automation）：当扫描到已注册的人脸并识别成功时执行的操作。参见on_face_scan_matched。
on_face_scan_unmatched（可选，Automation）：当扫描到未知人脸时执行的操作。参见on_face_scan_unmatched。
on_face_scan_invalid（可选，Automation）：当人脸扫描失败时执行的操作。参见on_face_scan_invalid。
on_face_info（可选，Automation）：当人脸信息可用时执行的操作。参见on_face_info。
on_enrollment_done（可选，Automation）：当人脸注册步骤成功时执行的操作。参见on_enrollment_done。
on_enrollment_failed（可选，Automation）：当人脸注册步骤失败时执行的操作。参见on_enrollment_failed。

二进制传感器

配置变量：

来自 Binary Sensor 的所有选项。

传感器

face_count：模块中存储的已注册人脸数量。
来自 Sensor 的所有选项。
last_face_id：通过on_face_scan_matched设置的最近一次匹配的已注册人脸。
来自 Sensor 的所有选项。
status：模块内部状态寄存器的整数值表示。
来自 Sensor 的所有选项。

文本传感器

version：模块的固件版本。
来自 Text Sensor 的所有选项。
last_face_name：通过on_face_scan_matched设置的最近一次匹配的已注册人脸。
来自 Text Sensor 的所有选项。

`on_face_scan_matched` 触发器

通过此配置选项，你可以在每次人脸扫描与已注册人脸匹配时编写复杂的自动化。要使用变量，请使用lambda模板，匹配的人脸 ID 可在该 lambda 中通过名为 face_id 的变量访问，人脸名称通过名为 name 的变量访问。

on_face_scan_matched:
  - text_sensor.template.publish:
      id: face_state
      state: !lambda 'return "Authorized face " + name + " (" + to_string(face_id) + ")";'
  # Pushing a tag_scanned event based on face_id
  - homeassistant.tag_scanned: !lambda |-
      switch (face_id) {
        case 0:
          return "person_a";
        case 1:
          return "person_b";
        ...
        default:
          return "person_unknown";
      }

`on_face_scan_unmatched` 触发器

通过此配置选项，你可以在每次扫描到未知人脸时编写复杂的自动化。

on_face_scan_unmatched:
  - text_sensor.template.publish:
      id: face_state
      state: "Unauthorized face"

`on_face_scan_invalid` 触发器

通过此配置选项，你可以在每次扫描失败时编写复杂的自动化，例如当没有人脸可见时。这与 on_face_scan_unmatched 不同，后者是在扫描到未知人脸时触发。要使用变量，请使用lambda模板，错误编号可在该 lambda 中通过名为 error 的变量访问。

on_face_scan_invalid:
  - text_sensor.template.publish:
      id: face_state
      state: !lambda 'return "Invalid face. Error number: " + to_string(error);'

`on_face_info` 触发器

通过此配置选项，你可以在每次人脸信息可用时编写复杂的自动化。模块在注册和扫描过程中会发送人脸信息，这对于调试尤其有用。要使用变量，请使用lambda模板，状态值可在该 lambda 中通过名为 status 的变量访问。值为零表示正常，数据手册中包含各种错误状态码（例如 6 表示人脸距离太远）。还有额外的值用于确定人脸在画面中的位置（left、top、right、bottom）以及旋转角度（yaw、pitch、roll）。

on_face_info:
  - text_sensor.template.publish:
      id: face_info
      state: !lambda |-
        switch (status) {
          case 0:
            return "Normal";
          case 1:
            return "No face detected";
          case 2:
            return "Face too high";
          case 3:
            return "Face too low";
          ...
          default:
            return "Unknown status " + to_string(status);
        }

`on_enrollment_done` 触发器

通过此配置选项，你可以在每次人脸注册步骤成功时编写复杂的自动化。要使用变量，请使用lambda模板，注册到其中的槽位号可在该 lambda 中通过名为 face_id 的变量访问。请注意，只有在人脸已在全方向注册后，该值才有效（否则将为 -1）。方向值是一个位掩码，表示迄今已捕获的方向。值为 0x1f 表示所有方向均已捕获，人脸 ID 应有效。

on_enrollment_done:
  - text_sensor.template.publish:
      id: face_state
      state: !lambda 'return "Enrolled into slot " + to_string(face_id);'

`on_enrollment_failed` 触发器

通过此配置选项，你可以在每次人脸注册失败时编写复杂的自动化。要使用变量，请使用lambda模板，错误编号可在该 lambda 中通过名为 error 的变量访问。

on_enrollment_failed:
  - text_sensor.template.publish:
      id: face_state
      state: !lambda 'return "Failed to enroll face. Error: " + to_string(error);'

`hlk_fm22x.enroll` 操作

使用名称和方向启动人脸注册过程。要成功注册一张人脸，你需要连续成功地从各个方向扫描人脸。某一方向的失败将要求从头重新注册该人脸。

on_...:
  then:
    - hlk_fm22x.enroll:
        name: "My name"
        direction: 1
    # Update the template text sensor for visual feedback
    - text_sensor.template.publish:
        id: face_state
        state: "Look directly at the camera"

配置选项：

name（必选，string，templatable）：与人脸关联的名称。最多 32 个 ASCII 字符。
direction（必选，int，templatable）：要扫描人脸的方向。1 表示中心，2 表示右侧，4 表示左侧，8 表示下方，16 表示上方。

`hlk_fm22x.scan` 操作

扫描并尝试与已注册人脸匹配。将触发其中一个 on_face_scan 触发器。

on_...:
  then:
    - hlk_fm22x.scan:

`hlk_fm22x.delete` 操作

从指定槽位号移除已注册的人脸。

on_...:
  then:
    - hlk_fm22x.delete:
        face_id: 0
    # Shorthand
    - hlk_fm22x.delete: 0

配置选项：

face_id（必选，int，templatable）：要删除的已注册人脸的槽位号。

`hlk_fm22x.delete_all` 操作

移除所有已注册的人脸。

on_...:
  then:
    - hlk_fm22x.delete_all:

`hlk_fm22x.reset` 操作

重置模块。如果模块没有正确响应，在注册或扫描失败后使用此操作可能很有用。如果该命令失败，会将模块标记为失败。

on_...:
  then:
    - hlk_fm22x.reset:

所有操作

id（可选，ID）：如果拥有多个组件，手动指定 HLK-FM22x 读卡器的 ID。

测试设置

使用以下代码，你可以快速搭建一个节点，并在 Home Assistant 的开发者工具中使用其操作。例如，调用 hlk_fm22x.enroll 时，选择操作 esphome.test_node_enroll，并在操作数据中输入：

{ "name": "My name", "direction": 1 }

示例代码

uart:
  rx_pin: GPIOXX
  tx_pin: GPIOXX
  baud_rate: 115200

hlk_fm22x:
  on_face_scan_invalid:
    - homeassistant.event:
        event: esphome.test_node_face_scan_invalid
        data:
          error: !lambda 'return error;'
  on_face_scan_matched:
    - homeassistant.event:
        event: esphome.test_node_face_scan_matched
        data:
          face_id: !lambda 'return face_id;'
          name: !lambda 'return name;'
  on_face_scan_unmatched:
    - homeassistant.event:
        event: esphome.test_node_face_scan_unmatched
  on_face_info:
    - homeassistant.event:
        event: esphome.test_node_face_info
        data:
          status: !lambda 'return status;'
          left: !lambda 'return left;'
          top: !lambda 'return top;'
          right: !lambda 'return right;'
          bottom: !lambda 'return bottom;'
          yaw: !lambda 'return yaw;'
          pitch: !lambda 'return pitch;'
          roll: !lambda 'return roll;'
  on_enrollment_done:
    - homeassistant.event:
        event: esphome.test_node_enrollment_done
        data:
          face_id: !lambda 'return face_id;'
          direction: !lambda 'return direction;'
  on_enrollment_failed:
    - homeassistant.event:
        event: esphome.test_node_enrollment_failed
        data:
          error: !lambda 'return error;'

api:
  actions:
  - action: enroll
    variables:
      name: string
      direction: int
    then:
      - hlk_fm22x.enroll:
          name: !lambda 'return name;'
          direction: !lambda 'return direction;'
  - action: scan
    then:
      - hlk_fm22x.scan:
  - action: delete
    variables:
      face_id: int
    then:
      - hlk_fm22x.delete:
          face_id: !lambda 'return face_id;'
  - action: delete_all
    then:
      - hlk_fm22x.delete_all:
  - action: reset
    then:
      - hlk_fm22x.reset:

参见

API 参考：hlk_fm22x.h

HLK-FM22x 人脸识别模块

组件/Hub

配置变量

二进制传感器

传感器

文本传感器

on_face_scan_matched 触发器

on_face_scan_unmatched 触发器

on_face_scan_invalid 触发器

on_face_info 触发器

on_enrollment_done 触发器

on_enrollment_failed 触发器

hlk_fm22x.enroll 操作

hlk_fm22x.scan 操作

hlk_fm22x.delete 操作

hlk_fm22x.delete_all 操作

hlk_fm22x.reset 操作