From 9c5afcbec143bda469496434074f04ba635f7f61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=2E=20=C3=81rkosi=20R=C3=B3bert?= Date: Tue, 17 Jan 2023 05:18:42 +0100 Subject: [PATCH] Documentation for `key_collector` component (#2426) Co-authored-by: Samuel Sieb --- components/key_collector.rst | 94 ++++++++++++++++++++++++++++++++++++ components/matrix_keypad.rst | 7 +-- 2 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 components/key_collector.rst diff --git a/components/key_collector.rst b/components/key_collector.rst new file mode 100644 index 000000000..ff9db7e3d --- /dev/null +++ b/components/key_collector.rst @@ -0,0 +1,94 @@ +.. _key_collector: + +Key collector component +======================= + +.. seo:: + :description: Key collector component + +The ``key_collector`` component collects key presses from +components like :ref:`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 +--------- + +.. code-block:: yaml + + # 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*, :ref:`config-id`): Set the ID of this entry for use in lambdas. +- **source_id** (*Optional*, :ref:`config-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*, :ref:`config-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*, :ref:`Automation `): An automation to perform + when keys are pressed. The current sequence of pressed keys is placed in a ``vector`` 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*, :ref:`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`` 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*, :ref:`Automation `): An automation to perform + if the timeout happens. The current sequence of pressed keys is placed in a ``vector`` variable ``x`` + and ``start`` holds the start key that activated this sequence or else ``0``. + + +See Also +-------- + +- :doc:`/components/matrix_keypad` + +.. - :doc:`/components/wiegand` + +- :ghedit:`Edit` diff --git a/components/matrix_keypad.rst b/components/matrix_keypad.rst index f4466792d..3fd3e579f 100644 --- a/components/matrix_keypad.rst +++ b/components/matrix_keypad.rst @@ -1,3 +1,5 @@ +.. _matrix_keypad: + Matrix keypad ============= @@ -80,12 +82,11 @@ Either the ``row`` and ``col`` parameters, or the ``key`` parameter has to be pr .. note:: Automatic handling of multiple keys (e.g. PIN code entry) is possible with the - the ``key_collector`` component. + the :ref:`Key Collector ` component. See Also -------- -.. - :doc:`/components/key_collector` - +- :doc:`/components/key_collector` - :ref:`Binary Sensor ` - :ghedit:`Edit`