Key collector component

The key_collector component collects key presses from components like Matrix keypad, Wiegand keypad or LVGL Button Matrix, Keyboard widgets. It allows you to process key sequences and treat them as one, for example to allow inputting of a PIN code or a passkey. The component outputs the result of the keypress sequence as a variable usable in automations, and can publish the result to a text_sensor.

Component

# Example configuration entry
key_collector:
  - id: pincode_reader
    source_id: mykeypad
    start_keys: "*"
    min_length: 4
    max_length: 4
    start_keys: "A"
    end_keys: "#"
    end_key_required: true
    back_keys: "*"
    clear_keys: "C"
    allowed_keys: "0123456789"
    timeout: 5s
    on_progress:
      - logger.log:
          format: "input progress: '%s', started by '%c'"
          args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ]
    on_result:
      - logger.log:
          format: "input result: '%s', started by '%c', ended by '%c'"
          args: [ 'x.c_str()', "(start == 0 ? '~' : start)", "(end == 0 ? '~' : end)" ]
    on_timeout:
      - logger.log:
          format: "input timeout: '%s', started by '%c'"
          args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ]

Configuration variables

id (Optional, ID): Set the ID of this entry for use in lambdas.
source_id (Optional, ID): The ID of the key input device.
min_length (Optional, integer): The minimum length of the desired key sequence. Below this limit, on_result automation will not trigger even if any of the end_keys was pressed.
max_length (Optional, integer): The maximum length of the desired key sequence. After this limit is reached, the collector will either ignore additional keys or trigger the on_result automation, depending on end_key_required.
start_keys (Optional, string): Keys used to start the key sequence; when set, no keys will be accepted until one of the start keys is pressed.
end_keys (Optional, string): Keys used to finish the key sequence and trigger the on_result automation.
end_key_required (Optional, boolean): Only trigger on_result automation when one of the end_keys was pressed, and not when max_length characters have been entered. Defaults to false.
back_keys (Optional, string): Keys used to delete the last pressed key. Like Backspace on a keyboard.
clear_keys (Optional, string): Keys used to cancel building the key sequence.
allowed_keys (Optional, string): Keys allowed to be used. If not specified, then any otherwise unused keys will be allowed.
timeout (Optional, Time): Timeout after which to cancel building the key sequence.
enable_on_boot (Optional, boolean): If enabled, this key collector will be enabled on boot. Defaults to true.

At least one of end_keys or max_length must be specified. The rest are optional. When the key sequence is cancelled, by timeout or one of clear_keys, a key from start_keys (if configured) must be entered again as well.

Triggers

on_progress (Optional, Automation): An automation to perform when keys are pressed. The current key sequence is placed in a vector<uint8_t> variable x and start holds the start key that activated this key sequence or else 0. Useful if you want to have a display showing the current value or number of key presses, or a speaker beeping when keys are being pressed.
on_result (Optional, Automation): An automation to perform when the key sequence has been finished (eg. max_length has been reached or one of the end_keys was pressed). The finalized key sequence is placed in a vector<uint8_t> variable x, start holds the start key that activated this key sequence or else 0, and end holds the end key that terminated this key sequence or else 0.
on_timeout (Optional, Automation): An automation to perform if the timeout happens. The current key sequence is placed in a vector<uint8_t> variable x and start holds the start key that activated this key sequence or else 0.

Actions

`key_collector.enable` Action

This action activates a key_collector. It will start accepting keys. If there is more than one key collector, you will need to provide the id of the one to enable.

on_...:
  then:
    - key_collector.enable:

`key_collector.disable` Action

This action deactivates a key_collector. It will stop accepting keys and will clear any already collected ones. If there is more than one key collector, you will need to provide the id of the one to disable.

on_...:
  then:
    - key_collector.disable:

Lambdas

clear(bool progress_update=true): Cancel building the key sequence. Set progress_update to false to skip triggering the on_progress automation.
send_key(uint8_t key): Send a key to the collector directly.

Text Sensor

The key_collector component supports a Text Sensor that publishes the collected key sequence when a successful result occurs.