[key_collector] refrence SX1509 keypad engine

components/index.rst

@@ -1080,6 +1080,7 @@ Miscellaneous Components
     Exposure Notifications, components/exposure_notifications, exposure_notifications.png
     GPS, components/gps, crosshairs-gps.svg, dark-invert
     Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg, dark-invert
+    Key collector, components/key_collector, form-textbox-password.svg, dark-invert
     Modbus Controller, components/modbus_controller, modbus.png
     Sprinkler, components/sprinkler, sprinkler-variant.svg, dark-invert
     Status LED, components/status_led, led-on.svg, dark-invert

components/key_collector.rst

@@ -7,11 +7,11 @@ Key collector component
     :description: Key collector component
 
 The ``key_collector`` component collects key presses from components
-like :ref:`matrix_keypad`, :doc:`Wiegand keypad </components/wiegand>`
-or LVGL :ref:`Button Matrix <lvgl-widget-buttonmatrix>`, :ref:`Keyboard <lvgl-widget-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.
+like :ref:`matrix_keypad`, :doc:`Wiegand keypad </components/wiegand>`,
+:doc:`SX1509 keypad engine </components/sx1509>`,
+or LVGL :ref:`Button Matrix <lvgl-widget-buttonmatrix>` or :ref:`Keyboard <lvgl-widget-keyboard>` widgets;
+and outputs the collected sequence as a variable in automations,
+for example to allow it to be used as a PIN code or One-Time Password.
 
 Component
 ---------
@@ -47,26 +47,26 @@ Component
 
 Configuration variables:
 
-- **id** (*Optional*, :ref:`config-id`): Set the ID of this entry for use in lambdas.
+- **id** (*Optional*, :ref:`config-id`): Set the ID for use in lambdas and actions.
 - **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.
+- **min_length** (*Optional*, integer): The minimum length key sequence
+  that can be sent to ``on_result`` by pressing any ``end_keys``.
+- **max_length** (*Optional*, integer): The maximum length key sequence.
+  Triggers ``on_result`` automation once reached if ``end_key_required`` is ``false``;
+  if ``end_key_required`` is ``true``, further keys won't be added, and ``on_progress`` automation will be re-triggered.
+  At least one of ``max_length`` and ``end_keys`` must be specified.
+- **end_keys** (*Optional*, string): Keys used to *submit* the sequence.
+  At least one of ``max_length`` and ``end_keys`` must be specified.
+- **end_key_required** (*Optional*, boolean): Stops ``max_length`` triggering ``on_result``. Defaults to ``false``.
+- **back_keys** (*Optional*, string): Keys used to delete the last pressed key. Like :kbd:`Backspace` on a keyboard.
+- **clear_keys** (*Optional*, string): Keys used to clear the whole sequence.
+- **allowed_keys** (*Optional*, string): Keys allowed to be added to the key sequence.
+  Defaults to any otherwise unused keys.
+- **timeout** (*Optional*, :ref:`config-time`): Time after last pressed key to trigger ``on_timeout`` and clear the whole sequence.
+  All keys, including ``back_keys``, ``end_keys`` pressed when the sequence is below ``min_length``, and non-``allowed_keys`` reset the timeout.
+  Won't trigger if the whole sequence has alredy been cleared, for example by pressing any ``clear_keys``.
 - **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`` 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:
 ------------
 
@@ -88,7 +88,7 @@ Automations:
 -------------------------------
 
 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.
+If there is more than one key collector, you need to provide the ``id`` of the one to enable.
 
 .. code-block:: yaml
 
@@ -100,7 +100,7 @@ If there is more than one key collector, you will need to provide the ``id`` of
 --------------------------------
 
 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.
+If there is more than one key collector, you need to provide the ``id`` of the one to disable.
 
 .. code-block:: yaml
 
@@ -118,6 +118,8 @@ See Also
 
 - :doc:`/components/matrix_keypad`
 - :doc:`/components/wiegand`
+- :doc:`SX1509 keypad engine </components/sx1509>`
 - :ref:`LVGL Button Matrix widget <lvgl-widget-buttonmatrix>`
 - :ref:`LVGL Keyboard widget <lvgl-widget-keyboard>`
+- :apiref:`key_collector/key_collector.h`
 - :ghedit:`Edit`