SX1509 device documentation (#315)

* add sx1509 docs

* add table

* sx1509 docs

* added to index

* fixed table

* text fixes

* Formatting

* Use standardized section header keys

* Spelling

* Properly size index file

* Use short name for index page (table view)

* fixed review issues

* Add API Reference


Co-authored-by: Otto Winter <otto@otto-winter.com>

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "restructuredtext.confPath": "${workspaceFolder}"
+}

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 <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 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 <config-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`

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