esphome-docs/components/sx1509.rst
2021-11-29 07:57:01 +13:00

207 lines
7.1 KiB
ReStructuredText

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**, int): 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`