Key collector component

The key_collector component collects key presses from components like Matrix keypad or wiegand. 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.

Component

# Example configuration entry
key_collector:
  - id: pincode_reader
    source_id: mykeypad
    min_length: 4
    max_length: 4
    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 minimal length of the desired key sequence. Below this, 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 which the sequence will trigger the on_result automation witout having to press any of the end_keys

  • end_keys (Optional, string): Keys used to enter the sequence.

  • end_key_required (Optional, boolean): Only trigger on_result automation when one of the end_keys was pressed. 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 entirely clear the sequence, all the pressed keys.

  • 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 sequence and delete all the keys.

At least one of end_keys or max_length have to be specified. The rest are optional. If both end_keys and max_length are specified, then once max_length keys are collected, no more will be accepted until an end key is pressed.

Automations:

  • on_progress (Optional, Automation): An automation to perform when keys are pressed. The current sequence of pressed keys is placed in a vector<uint8_t> variable x and start holds the start key that activated this 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 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 sequence or else 0, and end holds the end key that terminated this sequence or else 0.

  • on_timeout (Optional, Automation): An automation to perform if the timeout happens. The current sequence of pressed keys is placed in a vector<uint8_t> variable x and start holds the start key that activated this sequence or else 0.

See Also