mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-12-26 17:27:47 +01:00
119 lines
5.0 KiB
ReStructuredText
119 lines
5.0 KiB
ReStructuredText
.. _uart:
|
|
|
|
UART Bus
|
|
========
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up a UART serial bus on ESPs
|
|
:image: uart.png
|
|
:keywords: UART, serial bus
|
|
|
|
UART is a common serial protocol for a lot of devices. For example, when uploading a binary to your ESP
|
|
you have probably used UART to access the chip. UART (or for Arduino often also called Serial) usually
|
|
consists of 2 pins:
|
|
|
|
- **TX**: This line is used to send data to the device at the other end.
|
|
- **RX**: This line is used to receive data from the device at the other end.
|
|
|
|
Please note that the naming of these two pins depends on the chosen perspective and can be ambiguous. For example,
|
|
while the ESP might send (``TX``) on pin A and receive (``RX``) data on pin B, from the other device's
|
|
perspective these two pins are switched (i.e. *it* sends on pin B and receives on pin A). So you might
|
|
need to try with the two pins switched if it doesn't work immediately.
|
|
|
|
Additionally, each UART bus can operate at different speeds (baud rates), so ESPHome needs to know what speed to
|
|
receive/send data at using the ``baud_rate`` option. The most common baud rates are 9600 and 115200.
|
|
|
|
In some cases only **TX** or **RX** exists as the device at the other end only accepts data or sends data.
|
|
|
|
.. note::
|
|
|
|
On the ESP32, this component uses the hardware UART units and is thus very accurate. On the ESP8266 however,
|
|
ESPHome has to use a software implementation as there are no other hardware UART units available other than the
|
|
ones used for logging. Therefore the UART data on the ESP8266 can have occasional data glitches especially with
|
|
higher baud rates..
|
|
|
|
.. note::
|
|
|
|
From ESPHome 2021.8 the ``ESP8266SoftwareSerial`` UART ``write_byte`` function had the parity bit fixed to be correct
|
|
for the data being sent. This could cause unexpected issues if you are using the Software Serial and have devices that
|
|
explicity check the parity. Most likely you will need to flip the ``parity`` flag in YAML.
|
|
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
uart:
|
|
tx_pin: 1
|
|
rx_pin: 3
|
|
baud_rate: 9600
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **baud_rate** (**Required**, int): The baud rate of the UART bus.
|
|
- **tx_pin** (*Optional*, :ref:`config-pin`): The pin to send data to from the ESP's perspective.
|
|
- **rx_pin** (*Optional*, :ref:`config-pin`): The pin to receive data on from the ESP's perspective.
|
|
- **rx_buffer_size** (*Optional*, int): The size of the buffer used for receiving UART messages. Increase if you use an integration that needs to read big payloads from UART. Defaults to ``256``.
|
|
- **data_bits** (*Optional*, int): The number of data bits used on the UART bus. Options: 5 to 8. Defaults to 8.
|
|
- **parity** (*Optional*): The parity used on the UART bus. Options: ``NONE``, ``EVEN``, ``ODD``. Defaults to ``NONE``.
|
|
- **stop_bits** (*Optional*, int): The number of stop bits to send. Options: 1, 2. Defaults to 1.
|
|
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this UART hub if you need multiple UART hubs.
|
|
|
|
ESP32 options:
|
|
|
|
- **invert** (*Optional*, boolean): Invert the logic levels of the RX and TX pins. Options: ``true`` or ``false``. Defaults to ``false``.
|
|
|
|
.. _uart-hardware_uarts:
|
|
|
|
Hardware UARTs
|
|
--------------
|
|
|
|
Whenever possible, ESPHome will use the hardware UART unit on the processor for fast and accurate communication.
|
|
When the hardware UARTs are all occupied, ESPHome will fall back to a software implementation that may not
|
|
be accurate at higher baud rates.
|
|
|
|
``UART0`` is (by default) used by the :doc:`logger component </components/logger>`, using ``tx_pin: GPIO1`` and
|
|
``rx_pin: GPIO3``. If you configure a UART that overlaps with these pins, you can share the hardware with the
|
|
logger and leave others available. If you have configured the logger to use a different hardware UART, the pins
|
|
used for hardware sharing change accordingly.
|
|
|
|
The ESP32 has three UARTs. Any pair of GPIO pins can be used, as long as they support the proper output/input modes.
|
|
|
|
The ESP8266 has two UARTs; the second of which is TX-only. Only a limited set of pins can be used. ``UART0`` may
|
|
use either ``tx_pin: GPIO1`` and ``rx_pin: GPIO3``, or ``tx_pin: GPIO15`` and ``rx_pin: GPIO13``. ``UART1`` must
|
|
use ``tx_pin: GPIO2``. Any other combination of pins will result in use of a software UART.
|
|
|
|
.. _uart-write_action:
|
|
|
|
``uart.write`` Action
|
|
---------------------
|
|
|
|
This :ref:`Action <config-action>` sends a defined UART signal to the given UART bus.
|
|
|
|
.. code-block:: yaml
|
|
|
|
on_...:
|
|
- uart.write: 'Hello World'
|
|
|
|
# For escape characters, you must use double quotes!
|
|
- uart.write: "Hello World\r\n"
|
|
|
|
# Raw data
|
|
- uart.write: [0x00, 0x20, 0x42]
|
|
|
|
# Templated, return type is std::vector<uint8_t>
|
|
- uart.write: !lambda
|
|
return {0x00, 0x20, 0x42};
|
|
|
|
# in case you need to specify the uart id
|
|
- uart.write:
|
|
id: my_second_uart
|
|
data: 'other data'
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :doc:`/components/logger`
|
|
- :apiref:`uart/uart.h`
|
|
- :ghedit:`Edit`
|