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`