Documentation for matrix_keypad component (#2425)

Co-authored-by: Samuel Sieb <samuel@sieb.net>
Co-authored-by: Samuel Sieb <samuel-github@sieb.net>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/matrix_keypad.rst

@@ -0,0 +1,91 @@
+Matrix keypad
+=============
+
+.. seo::
+    :description: Matrix key input panel
+
+The ``matrix_keypad`` component allows you to integrate pads which
+have the keys connected at the intersection points of the rows and columns 
+of a matrix. 
+
+.. figure:: ../images/matrix_keypad.jpg
+    :align: center
+
+
+Component
+---------
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    matrix_keypad:
+      id: mykeypad
+      rows:
+        - pin: 21
+        - pin: 19
+        - pin: 18
+        - pin: 5
+      columns:
+        - pin: 17
+        - pin: 16
+        - pin: 4
+        - pin: 15
+      keys: "123A456B789C*0#D"
+      has_diodes: false
+
+
+Configuration variables:
+
+- **id** (*Optional*, :ref:`config-id`): Set the ID of this device for use in lambdas.
+- **rows** (**Required**, list): A list of :ref:`pins <config-pin_schema>` where the horrizontal
+  matrix lines are connected, in order from top to bottom.
+- **columns** (**Required**, list): A list of :ref:`pins <config-pin_schema>` where the vertical
+  matrix lines are connected, in order from left to right.
+- **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right, 
+  row by row. Required for ``key_collector`` and ``binary_sensor`` (if using key selection).
+- **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are 
+  connected with diodes. Defaults to ``false``.
+
+
+Binary Sensors
+--------------
+
+Individual keys can be added independently to ESPHome as ``binary_sensor``:
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    binary_sensor:
+      - platform: matrix_keypad
+        keypad_id: mykeypad
+        id: key4
+        row: 1
+        col: 0
+      - platform: keypad
+        id: keyA
+        key: A
+
+Configuration variables:
+
+- **keypad_id** (*Optional*, :ref:`config-id`): The ID of the keypad to process keypresses from.
+- **id** (*Optional*, :ref:`config-id`): Set the ID of this key for use in lambdas.
+- **row** (*Optional*, integer): The row of the key.
+- **col** (*Optional*, integer): The column of the key.
+- **key** (*Optional*, string): The key from ``keys`` configuration entry above.
+- All other options from :ref:`Binary Sensor <config-binary_sensor>`.
+
+Either the ``row`` and ``col`` parameters, or the ``key`` parameter has to be provided.
+
+
+.. note::
+
+    Automatic handling of multiple keys (e.g. PIN code entry) is possible with the 
+    the ``key_collector`` component.
+
+See Also
+--------
+
+.. - :doc:`/components/key_collector`
+
+- :ref:`Binary Sensor <config-binary_sensor>`
+- :ghedit:`Edit`

index.rst

@@ -671,6 +671,7 @@ Misc Components
     Status LED, components/status_led, led-on.svg
     Display Menu Core, components/display_menu/index, folder-open.svg
     LCD Menu, components/display_menu/lcd_menu, lcd_menu.png
+    Matrix Keypad, components/matrix_keypad, matrix_keypad.jpg
     HTTP Request, components/http_request, connection.svg
     mDNS, components/mdns, radio-tower.svg