esphome-docs/components/sx1509.rst

SX1509 16 channel I/O Expander with LED driver and keypad engine
================================================================

.. seo::
    :description: Instructions for setting up SX1509 16 channel I/O expander in ESPHome.
    :image: sx1509.jpg

The SX1509 component allows you to expand your I/O capabilities:
(`datasheet <https://www.semtech.com/uploads/documents/sx1509_evk_users_guide.pdf>`__,
`SparkFun`_) in ESPHome. It uses :ref:`I²C Bus <i2c>` for communication.

Once configured, you can use any of the 16 pins as pins for your projects.
Within ESPHome they emulate a real internal GPIO pin
and can therefore be used with many of ESPHome's components such as the GPIO
binary sensor or GPIO switch.
The SX1509 can do much more than just simple digital pin control. It can produce PWM signals.
And, with a built-in keypad engine, it can interface with up to 64 buttons set up in an 8x8 matrix.

Any option accepting a :ref:`Pin Schema <config-pin_schema>` can theoretically be used, but some more
complicated components that use the pin schema will not work. For example the I²C or SPI pins.

.. figure:: images/sx1509-full.jpg
    :align: center
    :width: 80.0%

    SX1509 16 channel I/O Expander.

.. _SparkFun: https://learn.sparkfun.com/tutorials/sx1509-io-expander-breakout-hookup-guide/all

.. code-block:: yaml

    # Example configuration entry for the SX1509 device
    sx1509:
      - id: sx1509_hub1
        address: 0x3E
        # If you need a keypad
        keypad:
          key_rows: 3
          key_columns: 4
          sleep_time: 256
          scan_time: 2
          debounce_time: 1

Configuration variables:
------------------------

- **id** (**Required**, :ref:`config-id`): The id to use for this SX1509 component.
- **address** (*Optional*, int): The I²C address of the driver.
  Defaults to ``0x3E``.

The SX1509 integrates a fully programmable keypad scanning engine to implement keypad applications.
up to 8x8 matrix (i.e. 64 keys).

- **keypad** (*Optional*): Add this to enable the keypad.

  - **key_rows** (**Required**, int): The number of keypad rows to use. This enables any number of the first 7 pins.
    So a value of 3 enables pins 0,1,2 to be used as the rows for the keypad matrix. This value must be between 1 and 8.
  - **key_columns** (**Required**, int): The number of keypad columns to use. This enables any number of the last 7 pins.
    So a value of 4 enables pins 8,9,10,11 to be used as the columns for the keypad matrix. This value must be between 1 and 8.
  - **sleep_time** (*Optional*, int): No key press within this time will set keypad engine to sleep.
  - **scan_time** (*Optional*, int): Scan time per row (must be set above debounce time).
  - **debounce_time** (*Optional*, int): The debounce time is common to all IOs.

.. figure:: images/sx1509-keypad.jpg
    :align: center
    :width: 80.0%

    SX1509 pins for keypad setup (image from the datasheet).

Attention should be paid to the capabilities of the I/O pins.

+-----+------------------+--------------+
|  #  |  pin function    |    Keypad    |
|     |                  |              +
+=====+==================+=====+========+
| I/O | input output PWM | Row | Column |
+-----+------------------+-----+--------+
| 0   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 1   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 2   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 3   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 4   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 5   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 6   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 7   |    ✓             |  ✓  |        |
+-----+------------------+-----+--------+
| 8   |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+
| 9   |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+
| 10  |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+
| 11  |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+
| 12  |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+
| 13  |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+
| 14  |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+
| 15  |    ✓             |     |   ✓    |
+-----+------------------+-----+--------+

Binary Sensor
=============

To use the individual keys on the keypad you need to add individual binary_sensor entries in the config.

.. code-block:: yaml

    # individual binary_sensor for keypad keys
    binary_sensor:
      - platform: sx1509
        sx1509_id: sx1509_hub1
        name: "keypadkey_0"
        row: 0
        col: 0
      - platform: sx1509
        sx1509_id: sx1509_hub1
        name: "keypadkey_1"
        row: 0
        col: 1

Configuration variables:
------------------------

- **row** (**Required**, int): The row number for this key on the keypad.
- **col** (**Required**, int): The column number for this key on the keypad.


Pin configuration variables:
----------------------------

With the following configuration items you may use the individual pins of the SX1509 as the pins for binary_sensor, switch, or output.
The outputs can in turn be used to add PWM-enabled lights like the monochromatic light.

.. code-block:: yaml

    # individual binary_sensor inputs
    binary_sensor:
      - platform: gpio
        name: "SX1509 Pin #0"
        pin:
          sx1509: sx1509_hub1
          # Use pin number 0 on the SX1509
          number: 0
          mode:
            input: true
            pullup: true
          inverted: true

    # Individual binary outputs
    switch:
      - platform: gpio
        name: "SX1509 Pin #1"
        pin:
          sx1509: sx1509_hub1
          # Use pin number 1 on the SX1509
          number: 1
          # use as output for switch
          mode:
            output: true
          inverted: false

    # Individual outputs
    output:
      - platform: sx1509
        sx1509_id: sx1509_hub1
        id: 'sx1509_output'
        # Use pin number 2 on the SX1509
        pin: 2

    # lights can then use the configured output
    light:
      - platform: monochromatic
        id: light0
        name: "light0"
        output: sx1509_output


- **sx1509** (**Required**, :ref:`config-id`): The id of the SX1509 component of the pin.
- **number** (**Required**, integer): The pin number.
- **inverted** (*Optional*, boolean): If all read and written values
  should be treated as inverted. Defaults to ``false``.
- **mode** (*Optional*, string): A pin mode to set for the pin at. One of ``INPUT``,
  ``INPUT_PULLUP`` or ``OUTPUT``.


And naturally you may use all automation functions with these SX1509 binary_sensors, switches and output (lights).

See Also
--------

- :ref:`i2c`
- :doc:`switch/gpio`
- :doc:`binary_sensor/gpio`
- :doc:`/components/light/monochromatic`
- :apiref:`sx1509/sx1509.h`
- :ghedit:`Edit`