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>
This commit is contained in:
Michiel van Turnhout 2019-10-19 16:04:41 -04:00 committed by Otto Winter
parent d8113d7fc3
commit 92af64ec18
6 changed files with 193 additions and 0 deletions

3
.vscode/settings.json vendored Normal file
View File

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

Binary file not shown.

After

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

189
components/sx1509.rst Normal file
View File

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

BIN
images/sx1509.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

View File

@ -309,6 +309,7 @@ Misc Components
PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg
MCP230XX I/O Expander, components/mcp230xx, mcp230xx.svg MCP230XX I/O Expander, components/mcp230xx, mcp230xx.svg
SX1509 I/O Expander, components/sx1509, sx1509.jpg
SIM800L, components/sim800l, sim800l.jpg SIM800L, components/sim800l, sim800l.jpg
DFPlayer, components/dfplayer_mini, dfplayer.svg DFPlayer, components/dfplayer_mini, dfplayer.svg
Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg