Grow 指纹读取器

fingerprint_grow 组件允许你将 R307、R503、R503-RGB、ZFM-20 等指纹传感器与 ESPHome 一起使用。

R307/ZFM-20 光学指纹读取器（数据手册，Adafruit）。图片来源：Adafruit。

R503 电容式指纹读取器，带双色光环 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 选项定义它，以便轮询功能在读取器上没有手指时能快速返回。

# Example configuration entry
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:
    ...

配置变量

配置由三个部分组成：中心组件、可选的各个传感器以及可选的注册（enrolling）二进制传感器。

基础配置：

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

二进制传感器

配置变量

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

传感器

配置变量

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

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

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

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

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

• security_level: 读取器当前配置的安全级别的整数表示。较高的安全级别以增加错误拒绝率（FRR）为代价来降低错误接受率（FAR）。范围为 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      # Existing password, can be omitted if it's the default of 0x00
  new_password: 0x72AB96CD  # New password

new_password: 配置选项意在编译、刷写到 ESP 设备上并运行一次，之后它会被移除，并在 password: 配置选项中定义新密码，以便再次编译并刷写。

fingerprint_grow:
  password: 0x72AB96CD      # Update the existing password with the new one

触发器

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);'
  # Pushing a tag_scanned event based on finger_id only if confidence is greater than 50
  - 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);'
  # Retry enrollment into the same slot
  - 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
    # Shorthand
    - fingerprint_grow.enroll: 0
    # Update the template text sensor for visual feedback
    - text_sensor.template.publish:
        id: fingerprint_state
        state: "Place a finger on the reader"

配置变量

• finger_id (Required, int, templatable): 要将新指纹注册到的插槽号。限于读取器上可用的指纹容量。
• num_scans (Optional, int, templatable): 扫描要注册的手指的次数。限于读取器上可用的字符缓冲区数量。默认为 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
    # Shorthand
    - fingerprint_grow.delete: 0

配置变量

• finger_id (Required, int, templatable): 要删除的已注册指纹的插槽号。

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
    # Shorthand
    - fingerprint_grow.led_control: ON

配置变量

• state (Required, boolean, templatable): 要设置的 LED 状态。

fingerprint_grow.aura_led_control 操作

控制读取器上的 Aura LED。仅在特定型号上可用。注意：R503 有 2 个颜色选项不同的型号。

on_...:
  then:
    - fingerprint_grow.aura_led_control:
        state: BREATHING
        speed: 100
        color: BLUE
        count: 2
# Sample Aura LED config for all reader triggers
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 (Required, string, templatable): 要设置的 LED 状态。为 BREATHING、FLASHING、ALWAYS_ON、ALWAYS_OFF、GRADUAL_ON 和 GRADUAL_OFF 之一。
• speed (Required, int, templatable): 每个循环的持续时间，为 10ms 的倍数。仅与 BREATHING、FLASHING、GRADUAL_ON 和 GRADUAL_OFF 状态相关。总持续时间由 10ms * speed 定义。范围为 0 到 255。
• color (Required, string, templatable): 要激活的 LED 颜色。对于 R503，为 RED、BLUE 和 PURPLE 之一。对于 R503-RGB，为 RED、BLUE、PURPLE、GREEN、YELLOW、CYAN 和 WHITE 之一。
• count (Required, int, templatable): 图案重复的次数。仅与 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 参考：fingerprint_grow.h