Grow 指纹阅读器

fingerprint_grow 组件允许您在 ESPHome 中使用 R307、R503、R503-RGB、ZFM-20 等指纹传感器。

R307/ZFM-20 光学指纹阅读器 (数据手册, Adafruit)。图片由 Adafruit 提供。

R503 电容式指纹阅读器，带双色 Aura LED (数据手册, Adafruit)。图片由 Adafruit 提供。

组件/集线器

阅读器可以由 NodeMCU 的 3.3V 输出供电。由于与阅读器的通信是通过 UART 完成的（默认波特率为 57600），您需要在配置中设置一个 UART 总线，并将 rx_pin 连接到阅读器的 TX，将 tx_pin 连接到阅读器的 RX。

如果您的阅读器型号支持，建议将 3.3VT（触摸感应电源）和 3.3V 连接到 3.3V；将 WAKEUP（手指检测信号）连接到一个空闲的 GPIO 引脚，并使用 sensing_pin 选项定义它，以便在阅读器上没有手指时轮询功能能够快速返回。

# 示例配置条目
fingerprint_grow:
  sensing_pin: GPIOXX
  sensor_power_pin:
      number: GPIOXX
      inverted: true
  idle_period_to_sleep: 5s

  on_finger_scan_start:
    ...
  on_finger_scan_matched:
    ...
  on_finger_scan_unmatched:
    ...
  on_finger_scan_misplaced:
    ...
  on_finger_scan_invalid:
    ...
  on_enrollment_scan:
    ...
  on_enrollment_done:
    ...
  on_enrollment_failed:
    ...

配置变量

配置由三部分组成：核心组件、可选的独立传感器和可选的注册二进制传感器。

基本配置：

• uart_id (可选, ID): 手动指定 UART 集线器的 ID。
• id (可选, ID): 手动指定用于代码生成的 ID。
• sensing_pin (可选, 引脚方案): 连接到阅读器手指检测信号（WAKEUP）输出的引脚。
• sensor_power_pin (可选, 引脚方案): 负责开启和关闭传感器电源的输出引脚。
• password (可选, int): 用于身份验证的密码。默认为 0x00。
• new_password (可选, int): 设置用于身份验证的新密码。有关更多信息，请参阅设置新密码。
• idle_period_to_sleep (可选, 时间): 传感器进入睡眠（断电）前等待的空闲时间。默认为 5s。有关更多信息，请参阅睡眠模式。
• on_finger_scan_start (可选, 自动化): 当手指触摸传感器时执行的操作。请参阅 on_finger_scan_start 触发器。
• on_finger_scan_matched (可选, 自动化): 当扫描到已注册的指纹时执行的操作。请参阅 on_finger_scan_matched 触发器。
• on_finger_scan_unmatched (可选, 自动化): 当扫描到未知指纹时执行的操作。请参阅 on_finger_scan_unmatched 触发器。
• on_finger_scan_misplaced (可选, 自动化): 当手指没有完全接触传感器时执行的操作。请参阅 on_finger_scan_misplaced 触发器。
• on_finger_scan_invalid (可选, 自动化): 当指纹扫描失败时执行的操作。请参阅 on_finger_scan_invalid 触发器。
• on_enrollment_scan (可选, 自动化): 当注册过程中扫描指纹时执行的操作。请参阅 on_enrollment_scan 触发器。
• on_enrollment_done (可选, 自动化): 当指纹注册成功时执行的操作。请参阅 on_enrollment_done 触发器。
• on_enrollment_failed (可选, 自动化): 当指纹注册失败时执行的操作。请参阅 on_enrollment_failed 触发器。

二进制传感器

配置变量

• 二进制传感器的所有选项。

传感器

配置变量

• fingerprint_count: 存储在阅读器上的已注册指纹数量。 传感器的所有选项。

• last_finger_id: 由 on_finger_scan_matched 触发器设置的最后一个匹配的已注册指纹。 传感器的所有选项。

• last_confidence: 由 on_finger_scan_matched 触发器设置的最后一个匹配的置信度。 传感器的所有选项。

• status: 阅读器内部状态寄存器的整数表示。 传感器的所有选项。

• capacity: 阅读器的指纹存储容量。 传感器的所有选项。

• security_level: 阅读器当前配置的安全级别的整数表示。更高的安全级别会降低错误接受率（FAR），但会增加错误拒绝率（FRR）。范围是 1（最低）到 5（最高）。 传感器的所有选项。

睡眠模式

传感器的空闲功耗约为 20mA。如果您计划让设备持续运行，建议实现睡眠模式，该模式会在最后一次通信后的几秒钟内让传感器进入睡眠（断电）状态（可通过 idle_period_to_sleep 配置）。它只能与触摸感应功能一起实现，因为它使用触摸反馈来唤醒传感器。 要实现此功能，您需要一个额外的空闲 GPIO 引脚来控制传感器的电源开关，以及两个外部元件：一个 10kOhms 电阻和一个 PNP 晶体管（如 BC327）。

这是 R503 的接线示例，下面是相应的配置：

uart:
  rx_pin: GPIOXX
  tx_pin: GPIOXX
  baud_rate: 57600

fingerprint_grow:
  sensing_pin: GPIOXX
  sensor_power_pin:
      number: GPIOXX
      inverted: true
  idle_period_to_sleep: 5s

设置新密码

WARNING

忘记密码将导致您的指纹阅读器无法使用！

您可以使用 new_password: 配置选项为指纹阅读器设置新密码。密码定义为 32 位无符号整数。

fingerprint_grow:
  password: 0x275FE3D2      # 现有密码，如果是默认值 0x00 可以省略
  new_password: 0x72AB96CD  # 新密码

new_password: 配置选项的目的是编译后刷入 ESP 设备并运行一次，然后将其删除，并在 password: 配置选项中定义新密码，再次编译并刷入。

fingerprint_grow:
  password: 0x72AB96CD      # 使用新密码更新现有密码

触发器

on_finger_scan_start 触发器

使用此配置选项，您可以在检测到手指触摸传感器时触发自动化。非常有用，可以通过 AuraLed 向用户指示传感器已检测到手指触摸并将执行扫描。此触发器仅在您的指纹传感器配置了 sensing_pin 选项时才会激活。

on_finger_scan_start:
  - fingerprint_grow.aura_led_control:
      state: ALWAYS_ON
      color: GREEN
      speed: 0
      count: 0

on_finger_scan_invalid 触发器

使用此配置选项，您可以在扫描失败时编写复杂的自动化，例如当手指没有正确放置在阅读器上时。这与 on_finger_scan_unmatched 不同，后者是在扫描到未知指纹时触发。此选项在定义了 sensing_pin 选项时效果最佳。

on_finger_scan_invalid:
  - text_sensor.template.publish:
      id: fingerprint_state
      state: "Invalid finger"

on_finger_scan_matched 触发器

使用此配置选项，您可以在指纹扫描与已注册指纹匹配时编写复杂的自动化。 要使用变量，请使用 lambda 模板，匹配的槽位号和置信度可以在该 lambda 中通过名为 finger_id 和 confidence 的变量访问。

on_finger_scan_matched:
  - text_sensor.template.publish:
      id: fingerprint_state
      state: !lambda 'return "Authorized finger " + to_string(finger_id) + ", confidence " + to_string(confidence);'
  # 仅当置信度大于 50 时，根据 finger_id 推送 tag_scanned 事件
  - if:
      condition:
        lambda: 'return confidence > 50;'
      then:
        - homeassistant.tag_scanned: !lambda |-
            switch (finger_id) {
              case 0:
                return "person_a";
              case 1:
                return "person_b";
              ...
              default:
                return "person_unknown";
            }

on_finger_scan_unmatched 触发器

使用此配置选项，您可以在扫描到未知指纹时编写复杂的自动化。

on_finger_scan_unmatched:
  - text_sensor.template.publish:
      id: fingerprint_state
      state: "Unauthorized finger"

on_finger_scan_misplaced 触发器

使用此配置选项，您可以为手指接触传感器但未完全覆盖的情况创建自动化，使您能够执行成功的扫描。 此触发器仅在您的指纹传感器配置了 sensing_pin 选项时才会激活。它作为一个有用的指示器，提醒用户他们在传感器上的触摸不足。

on_finger_scan_misplaced:
  - text_sensor.template.publish:
      id: fingerprint_state
      state: "Misplaced finger"

on_enrollment_scan 触发器

使用此配置选项，您可以在注册过程中扫描指纹时编写复杂的自动化。 要使用变量，请使用 lambda 模板，扫描次数和要注册到的槽位号可以在该 lambda 中通过名为 scan_num 和 finger_id 的变量访问。

on_enrollment_scan:
  - text_sensor.template.publish:
      id: fingerprint_state
      state: !lambda 'return "Enrolling into slot " + to_string(finger_id) + ", scanned " + to_string(scan_num) + " time(s)";'

on_enrollment_done 触发器

使用此配置选项，您可以在指纹成功注册时编写复杂的自动化。 要使用变量，请使用 lambda 模板，注册到的槽位号可以在该 lambda 中通过名为 finger_id 的变量访问。

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

on_enrollment_failed 触发器

使用此配置选项，您可以在指纹注册失败时编写复杂的自动化。 要使用变量，请使用 lambda 模板，注册失败的槽位号可以在该 lambda 中通过名为 finger_id 的变量访问。

on_enrollment_failed:
  - text_sensor.template.publish:
      id: fingerprint_state
      state: !lambda 'return "Failed to enroll into slot " + to_string(finger_id);'
  # 重试注册到同一槽位
  - delay: 3s
  - text_sensor.template.publish:
      id: fingerprint_state
      state: !lambda 'return "Retrying enrollment into slot " + to_string(finger_id) + " in 3 seconds...";'
  - delay: 3s
  - fingerprint_grow.enroll: !lambda 'return finger_id;'

动作

fingerprint_grow.enroll 动作

在指定的槽位号上启动指纹注册过程。

on_...:
  then:
    - fingerprint_grow.enroll:
        finger_id: 0
        num_scans: 2
    # 简写形式
    - fingerprint_grow.enroll: 0
    # 更新模板文本传感器以提供视觉反馈
    - text_sensor.template.publish:
        id: fingerprint_state
        state: "Place a finger on the reader"

配置变量

• finger_id (必需, int, 可模板化): 要将新指纹注册到的槽位号。受阅读器上可用指纹容量的限制。
• num_scans (可选, int, 可模板化): 扫描要注册的手指的次数。受阅读器上可用字符缓冲区数量的限制。默认为 2。

fingerprint_grow.cancel_enroll 动作

取消当前的指纹注册过程。触发 on_enrollment_failed 触发器。

on_...:
  then:
    - fingerprint_grow.cancel_enroll:

fingerprint_grow.delete 动作

从指定的槽位号删除已注册的指纹。

on_...:
  then:
    - fingerprint_grow.delete:
        finger_id: 0
    # 简写形式
    - fingerprint_grow.delete: 0

配置变量

• finger_id (必需, int, 可模板化): 要删除的已注册指纹的槽位号。

fingerprint_grow.delete_all 动作

删除所有已注册的指纹。

on_...:
  then:
    - fingerprint_grow.delete_all:

fingerprint_grow.led_control 动作

打开或关闭阅读器上的 LED。仅适用于特定型号。如果您使用的是 R503 或 R503-RGB，请改用 fingerprint_grow.aura_led_control 动作。

on_...:
  then:
    - fingerprint_grow.led_control:
        state: ON
    # 简写形式
    - fingerprint_grow.led_control: ON

配置变量

• state (必需, boolean, 可模板化): 要设置的 LED 状态。

fingerprint_grow.aura_led_control 动作

控制阅读器上的 Aura LED。仅适用于特定型号。注意：R503 有两种不同 LED 颜色选项的变体。

on_...:
  then:
    - fingerprint_grow.aura_led_control:
        state: BREATHING
        speed: 100
        color: BLUE
        count: 2
# 所有阅读器触发器的 Aura LED 配置示例
fingerprint_grow:
  on_finger_scan_start:
    - fingerprint_grow.aura_led_control:
        state: ALWAYS_ON
        color: GREEN
        speed: 0
        count: 0
  on_finger_scan_matched:
    - fingerprint_grow.aura_led_control:
        state: BREATHING
        speed: 200
        color: BLUE
        count: 1
  on_finger_scan_unmatched:
    - fingerprint_grow.aura_led_control:
        state: FLASHING
        speed: 25
        color: RED
        count: 2
  on_finger_scan_misplaced:
    - fingerprint_grow.aura_led_control:
        state: FLASHING
        speed: 25
        color: PURPLE
        count: 2
  on_enrollment_scan:
    - fingerprint_grow.aura_led_control:
        state: FLASHING
        speed: 25
        color: BLUE
        count: 2
    - fingerprint_grow.aura_led_control:
        state: ALWAYS_ON
        speed: 0
        color: PURPLE
        count: 0
  on_enrollment_done:
    - fingerprint_grow.aura_led_control:
        state: BREATHING
        speed: 100
        color: BLUE
        count: 2
  on_enrollment_failed:
    - fingerprint_grow.aura_led_control:
        state: FLASHING
        speed: 25
        color: RED
        count: 4
on...:
  then:
    - fingerprint_grow.enroll: ...
    - fingerprint_grow.aura_led_control:
        state: ALWAYS_ON
        speed: 0
        color: PURPLE
        count: 0

配置变量

• state (必需, string, 可模板化): 要设置的 LED 状态。可选值为 BREATHING、FLASHING、ALWAYS_ON、ALWAYS_OFF、GRADUAL_ON 和 GRADUAL_OFF。
• speed (必需, int, 可模板化): 每个周期持续的时间，以 10ms 为单位的因子。仅与 BREATHING、FLASHING、GRADUAL_ON 和 GRADUAL_OFF 状态相关。总持续时间由 10ms speed 定义。范围为 0 到 255。
• color (必需, string, 可模板化): 要激活的 LED 颜色。对于 R503，可选值为 RED、BLUE 和 PURPLE。对于 R503-RGB，可选值为 RED、BLUE、PURPLE、GREEN、YELLOW、CYAN 和 WHITE。
• count (必需, int, 可模板化): 重复图案的次数。仅与 BREATHING 和 FLASHING 状态相关。0 表示无限，或 1 到 255。

测试设置

使用以下代码，您可以快速设置一个节点，并在 Home Assistant 的开发者工具中使用动作。 例如，要调用 fingerprint_grow.enroll，选择动作 esphome.test_node_enroll，并在动作数据中输入

{ "finger_id": 0, "num_scans": 2 }

示例代码

uart:
  rx_pin: GPIOXX
  tx_pin: GPIOXX
  baud_rate: 57600

fingerprint_grow:
  sensing_pin: GPIOXX
  on_finger_scan_invalid:
    - homeassistant.event:
        event: esphome.test_node_finger_scan_invalid
  on_finger_scan_matched:
    - homeassistant.event:
        event: esphome.test_node_finger_scan_matched
        data:
          finger_id: !lambda 'return finger_id;'
          confidence: !lambda 'return confidence;'
  on_finger_scan_unmatched:
    - homeassistant.event:
        event: esphome.test_node_finger_scan_unmatched
  on_finger_scan_misplaced:
    - homeassistant.event:
        event: esphome.frontdoor_finger_scan_misplaced
  on_enrollment_scan:
    - homeassistant.event:
        event: esphome.test_node_enrollment_scan
        data:
          finger_id: !lambda 'return finger_id;'
          scan_num: !lambda 'return scan_num;'
  on_enrollment_done:
    - homeassistant.event:
        event: esphome.test_node_enrollment_done
        data:
          finger_id: !lambda 'return finger_id;'
  on_enrollment_failed:
    - homeassistant.event:
        event: esphome.test_node_enrollment_failed
        data:
          finger_id: !lambda 'return finger_id;'

api:
  actions:
  - action: enroll
    variables:
      finger_id: int
      num_scans: int
    then:
      - fingerprint_grow.enroll:
          finger_id: !lambda 'return finger_id;'
          num_scans: !lambda 'return num_scans;'
  - action: cancel_enroll
    then:
      - fingerprint_grow.cancel_enroll:
  - action: delete
    variables:
      finger_id: int
    then:
      - fingerprint_grow.delete:
          finger_id: !lambda 'return finger_id;'
  - action: delete_all
    then:
      - fingerprint_grow.delete_all:

另请参阅

• Adafruit 教程
• Adafruit 指纹传感器库，作者 Adafruit
• API Reference: fingerprint_grow.h