esphome-docs/components/matrix_keypad.rst

95 lines
2.9 KiB
ReStructuredText

.. _matrix_keypad:
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: GPIOXX
- pin: GPIOXX
- pin: GPIOXX
- pin: GPIOXX
columns:
- pin: GPIOXX
- pin: GPIOXX
- pin: GPIOXX
- pin: GPIOXX
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. These pins need to be output capable.
- **columns** (**Required**, list): A list of :ref:`pins <config-pin_schema>` where the vertical
matrix lines are connected, in order from left to right. These pins need to be input capable
with pullups enabled. If there is no internal pullup, then an external one is required.
- **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``.
- **has_pulldowns** (*Optional*, boolean): For pads where the column lines have external pulldowns. Defaults to ``false``.
Binary Sensor
-------------
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: matrix_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 :ref:`Key Collector <key_collector>` component.
See Also
--------
- :doc:`/components/key_collector`
- :ref:`Binary Sensor <config-binary_sensor>`
- :ghedit:`Edit`