Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-03-12 13:39:50 +01:00
Code Issues Projects Releases Wiki Activity

Add WeiKai component documentation (#3113)

Browse Source 
Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu>
This commit is contained in:
Jean Louis-Guerin 2024-04-24 03:21:48 +02:00 committed by GitHub
parent ab42cc0fef
commit 0559ef14fb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 341 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
components/images/DFR0627.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 110 KiB

340
components/weikai.rst Normal file
View File

@ -0,0 +1,340 @@
WeiKai SPI/I²C UART/IO Expander
===============================
.. seo::
:description: Instructions for setting up WeiKai SPI/I²C to UART Expanders in ESPHome.
:image: wk2168.jpg
:keywords: UART, SPI, I²C, WK2132, WK2168, WK2204, WK2212, wk2124
**WeiKai Microelectronics** provides a family of UART & GPIO expansion chips
that interfaces to a micro-controller through SPI or I²C bus.
The ESPHome ``WeiKai`` component supports the following WeiKai chips:
- `WK2168-IQPG <https://jlcpcb.com/partdetail/WEIKAI-WK2168IQPG/C401041>`__
- `WK2132-ISSG <https://jlcpcb.com/partdetail/WeiKai-WK2132ISSG/C401039>`__
- `WK2124-ISSG <https://jlcpcb.com/partdetail/WeiKai-WK2124ISSG/C86332>`__
- `WK2204-IQNG <https://jlcpcb.com/partdetail/WeiKai-WK2204IQNG/C401040>`__
- `WK2212-IQNG <https://jlcpcb.com/partdetail/WeiKai-WK2212IQNG/C2987671>`__
It can also be used with evaluation board equipped with these chips, such as:
- `WK2168 Chip Development Board <https://fr.aliexpress.com/item/1005002198759633.html>`__
- `WK2132 Chip Development Board <https://www.aliexpress.com/item/1005002018579265.html>`__
- `DFROBOT Gravity: I²C to Dual UART Module <https://www.dfrobot.com/product-2001.html>`__
.. figure:: images/DFR0627.jpg
:align: center
The features provided by the different WeiKai chips are described in the following table:
.. list-table:: WeiKai chip's features
:header-rows: 1
:width: 450px
:align: center
* - Chip
- Bus
- UART
- GPIO
* - WK2132-ISSG
- S/I
- 2
-
* - WK2212-IQNG
- S/I
- 2
- 8
* - WK2124-ISSG
- S
- 4
-
* - WK2204-IQNG
- S/I
- 4
-
* - WK2168-IQPG
- S/I
- 4
- 8
As you can see most of the components can interface either through an I²C bus or a SPI bus,
they provide either 2 or 4 serial channels, and some provide 8 input/output pins.
Each UART channel has two independent 256-byte FIFO hardware buffers to transmit and
receive and support data transmission rates up to 1 Mbps.
The baud rate and parity format of each UART channel can be configured independently.
However, the data bit length is fixed at 8.
Utilizing the UART channels enables you to connect your UART devices, with each channel functioning
as a virtual UART bus for the connected component.
The I/O pins of the WeiKai chips can be use as any of the other GPIO pins.
Any option accepting a :ref:`Pin Schema <config-pin_schema>` can theoretically
be used, but some more complicated components that do communication through
this I/O expander might not work.
Connecting via an SPI bus
-------------------------
The ``wk2132_spi``, ``wk2212_spi``, ``wk2204_spi``, ``wk2168_spi`` components allows
you to connect the WeiKai chip with ESPHome via a :ref:`SPI <spi>` bus.
You can connect several of these modules to a single SPI controller circuit effectively expanding
the number of hardware serial ports available. Each WeiKai chip needs to be selected
with a individual CS.
Here is an example of configuration entry for a wk2168_spi component. For the other components
in the list just replace the name of the component and make sure you do not use more channels that the chip
can support (an error message will be generated otherwise). Note that for the ``WK2124-ISSG`` chip
you need to use ``wk2204_spi`` as the two chips are similar.
.. code-block:: yaml
wk2168_spi:
- id: wk2168_bridge_spi
cs_pin: 5
uart:
- id: spi_uart_0
channel: 0
baud_rate: 128200
parity: even
- id: spi_uart_1
channel: 1
baud_rate: 19200
- id: spi_uart_2
channel: 2
baud_rate: 9600
- id: spi_uart_3
channel: 3
baud_rate: 19200
Configuration variables:
************************
- **id** (**Required**, :ref:`config-id`): The id to use for this WeiKai component.
- **spi_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the :ref:`SPI Component <spi>` if you want
to use multiple SPI buses.
- **cs_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The pin on the ESP that the chip select line
of the chip is connected to.
- **data_rate** (*Optional*): Set the data rate of the controller. One of ``80MHz``, ``40MHz``, ``20MHz``, ``10MHz``,
``5MHz``, ``4MHz``, ``2MHz``, ``1MHz`` (default), ``200kHz``, ``75kHz`` or ``1kHz``. A numeric value in Hz can
alternatively be specified.
- **crystal** (*Optional*): The frequency in Hz of the crystal connected to the chip.
The default value is 14745600 Hz.
- **uart** (**Required**): The UART channels.
- **id** (**Required**, :ref:`config-id`): The id to use for this UART channel.
- **channel** (**Required**): Unique channel number of this virtual UART.
Options: ``0`` to ``1`` or ``0`` to ``3`` depending on the model.
- **baud_rate** (**Required**): The baud rate of the UART channel.
- **parity** (*Optional*): The parity used on the UART channel. Options: ``NONE``, ``EVEN``,
``ODD``. Defaults to ``NONE``.
- **stop_bits** (*Optional*): The number of stop bits to send. Options: ``1``, ``2``.
Defaults to ``1``.
Connecting via an I²C bus
-------------------------
The ``wk2132_i2c`` ``wk2212_i2c`` ``wk2204_i2c`` ``wk2168_i2c`` components allows you
to connect the WeiKai chip with ESPHome via an :ref:`I²C <i2c>` bus.
Up to four WeiKai chips can be connected to an I²C controller board, effectively expanding the
available hardware serial ports. The base addresses of these boards are defined by the
positions of two switches, A0 and A1, on the board.
.. list-table:: WeiKai address selection
:header-rows: 1
:width: 350px
:align: center
* - I²C address
- A1
- A0
* - 0x10 - 0x17
- 0
- 0
* - 0x30 - 0x37
- 0
- 1
* - 0x50 - 0x57
- 1
- 0
* - 0x70 - 0x77
- 1
- 1
.. important::
Note that the address is given as a **range** a not a number as you usually find on other I²C component.
Indeed due to a peculiar way of addressing the different internal registers each component actually occupy
8 consecutive addresses. For example if the component base address is 0x10, it will occupy the addresses ranging from
0x10 to 0x17 on the I²C bus.
This is important to know if you want to connect other devices on the same I²C bus.
Here is an example of configuration entry for a ``wk2168_i2c`` component. For the other components
just replace the name of the component and do not use more channels that the chip can
support (an error message will be generated in this case).
.. code-block:: yaml
wk2168_i2c:
- address: 0x70
id: wk2168_bridge_i2c
uart:
- id: i2c_uart_0
channel: 0
baud_rate: 9600
parity: even
- id: i2c_uart_1
channel: 1
baud_rate: 19200
- id: i2c_uart_2
channel: 2
baud_rate: 9600
- id: i2c_uart_3
channel: 3
baud_rate: 19200
Configuration variables:
************************
- **id** (**Required**, :ref:`config-id`): The id to use for this WeiKai component.
- **address** (*Optional*): The I²C address of this component. Defaults to ``0x10``.
- **i2c_id** (*Optional*): The I²C Bus ID. Defaults to the default i²c bus.
- **crystal** (*Optional*): The frequency in Hz of the crystal connected to the chip.
The default value is 14745600 Hz.
- **uart** (*Required*): The UART channels.
- **id** (**Required**, :ref:`config-id`): The id to use for this UART channel.
- **channel** (**Required**): Unique channel number of this virtual UART.
Options: ``0`` to ``1`` or ``0`` to ``3`` depending on the model.
- **baud_rate** (**Required**): The baud rate of the UART channel.
- **parity** (*Optional*): The parity used on the UART channel. Options: ``NONE``, ``EVEN``,
``ODD``. Defaults to ``NONE``.
- **stop_bits** (*Optional*): The number of stop bits to send. Options: ``1``, ``2``.
Defaults to ``1``.
Using the GPIO pins
-------------------
For the ``WK2212``, and ``WK2168`` it is possible to use the chip I/O pins as any of the other GPIO pins.
For example for a wk2168_spi chip:
.. code-block:: yaml
# individual binary_sensor inputs
binary_sensor:
- platform: gpio
name: "pin_0"
pin:
wk2168_spi: wk2168_bridge_spi
number: 0
mode:
input: true
- platform: gpio
name: "pin_1"
pin:
wk2168_spi: wk2168_bridge_spi
number: 1
mode:
input: true
inverted: true
# Individual binary outputs
switch:
- platform: gpio
name: "pin_2"
pin:
wk2168_spi: wk2168_bridge_spi
number: 2
mode:
output: true
- platform: gpio
name: "pin_3"
pin:
wk2168_spi: wk2168_bridge_spi
number: 3
mode:
output: true
inverted: true
Pin configuration variables:
****************************
- **wkxxxx_xxx** (**Required**, :ref:`config-id`): The id of the ``wkxxxx_xxx`` component for the pin. For
example ``wk2212_i2c: wk2168_bridge_spi``
- **number** (**Required**): The pin number (``0`` to ``7``)
- **inverted** (*Optional*): If all read and written values should be treated as inverted. Defaults to ``false``.
- **mode** (*Optional*): A pin mode to set for the pin at. One of ``INPUT`` or ``OUTPUT``. Default to ``INPUT``
Performance considerations:
---------------------------
Bus speed
*********
Please be aware that the communication between the WeiKai chips and the processor occurs on an external bus,
with a relatively low operating frequency. Therefore tasks such as checking the status of the chip's
registers or transferring bytes from the internal FIFOs to the processor may take time.
To improve this situation, it is strongly recommended to increase the default bus frequency.
- With a SPI bus this can be done on the WeiKai component by specifying ``data_rate``. For example:
.. code-block:: yaml
wk2168_spi:
- id: wk2168_bridge_spi
spi_id: spi_bus_id
cs_pin: 5
data_rate: 4MHz
- With an I²C bus this needs to be done on the ``i2c`` declaration and therefore this frequency will
apply to all components connected to this bus.
.. code-block:: yaml
i2c:
sda: 21
scl: 22
scan: true
id: bus_i2c
frequency: 800kHz
Maximum Baud rate
*****************
The maximum baud_rate is proportional to the crystal frequency. The following table
gives the maximum baud_rate at usual system clock:
.. list-table:: maximum baud rate
:header-rows: 1
:width: 300px
:align: center
* - Clock
- Max Bd
* - 14,745,600 Hz
- 921,600 Bd
* - 11,059,200 Hz
- 691,200 Bd
* - 7,372,800 Hz
- 460,800 Bd
* - 3,686,400 Hz
- 230,400 Bd
* - 1,843,200 Hz
- 115,200 Bd
If you try to use a baud rate superior to the maximum baud_rate an error will be displayed in the
log file and the baud rate will automatically be decreased.
See Also
--------
- :ref:`i2c`
- :ref:`spi`
- :doc:`switch/gpio`
- :doc:`binary_sensor/gpio`
- :apiref:`weika/weika.h`
- :ghedit:`Edit`

BIN
images/wk2168.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

1
index.rst
View File

@ -226,6 +226,7 @@ I/O Expanders/Multiplexers
SN74HC595, components/sn74hc595, sn74hc595.jpg
SX1509, components/sx1509, sx1509.jpg
TCA9548A I²C Multiplexer, components/tca9548a, tca9548a.jpg
WeiKai SPI/I²C UART/IO Expander, components/weikai, wk2168.jpg
XL9535, components/xl9535, xl9535.svg
Sensor Components