diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..d5d660bd6 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "restructuredtext.confPath": "${workspaceFolder}" +} \ No newline at end of file diff --git a/components/images/sx1509-full.jpg b/components/images/sx1509-full.jpg new file mode 100644 index 000000000..41b91bda3 Binary files /dev/null and b/components/images/sx1509-full.jpg differ diff --git a/components/images/sx1509-keypad.jpg b/components/images/sx1509-keypad.jpg new file mode 100644 index 000000000..edd1c5c51 Binary files /dev/null and b/components/images/sx1509-keypad.jpg differ diff --git a/components/sx1509.rst b/components/sx1509.rst new file mode 100644 index 000000000..59501b685 --- /dev/null +++ b/components/sx1509.rst @@ -0,0 +1,189 @@ +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 `__, +`Sparkfun`_) in ESPHome. It uses :ref:`I²C Bus ` 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 ` can theoretically be used, but some more +complicated components that use the pin schema will not work. For example the I2C 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 for the SX1509 device: +---------------------------------------------- + +- **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_row** (*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 | ✓ | | ✓ | ++-----+------------------+-----+--------+ + +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 for the SX1509 keypad keys: +--------------------------------------------------- + +- **row** (**Required**, int): The row number for this key on the keypad. +- **col** (**Required**, int): The column number for this key on the keypad. + +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_PULLUP + 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 + 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 + +- All other options from :ref:`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` diff --git a/images/sx1509.jpg b/images/sx1509.jpg new file mode 100644 index 000000000..586195e31 Binary files /dev/null and b/images/sx1509.jpg differ diff --git a/index.rst b/index.rst index 583616f9b..50ddc424b 100644 --- a/index.rst +++ b/index.rst @@ -309,6 +309,7 @@ Misc Components PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg MCP230XX I/O Expander, components/mcp230xx, mcp230xx.svg + SX1509 I/O Expander, components/sx1509, sx1509.jpg SIM800L, components/sim800l, sim800l.jpg DFPlayer, components/dfplayer_mini, dfplayer.svg Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg