diff --git a/components/images/DFR0627.jpg b/components/images/DFR0627.jpg new file mode 100644 index 000000000..5a112ccc9 Binary files /dev/null and b/components/images/DFR0627.jpg differ diff --git a/components/weikai.rst b/components/weikai.rst new file mode 100644 index 000000000..eec22c4e6 --- /dev/null +++ b/components/weikai.rst @@ -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 `__ +- `WK2132-ISSG `__ +- `WK2124-ISSG `__ +- `WK2204-IQNG `__ +- `WK2212-IQNG `__ + +It can also be used with evaluation board equipped with these chips, such as: + +- `WK2168 Chip Development Board `__ +- `WK2132 Chip Development Board `__ +- `DFROBOT Gravity: I²C to Dual UART Module `__ + +.. 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 ` 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 ` 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 ` if you want + to use multiple SPI buses. +- **cs_pin** (**Required**, :ref:`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 ` 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` diff --git a/images/wk2168.jpg b/images/wk2168.jpg new file mode 100644 index 000000000..284699c93 Binary files /dev/null and b/images/wk2168.jpg differ diff --git a/index.rst b/index.rst index 8b4c89b40..2c6f87d22 100644 --- a/index.rst +++ b/index.rst @@ -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