UART 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.

# 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, Pin): The pin to send data to from the ESP’s perspective.

  • rx_pin (Optional, 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, ID): Manually specify the ID for this UART hub if you need multiple UART hubs.

  • debug (Optional, mapping): Options for debugging communication on the UART hub, see Debugging.

ESP32 options:

  • invert (Optional, boolean): Invert the logic levels of the RX and TX pins. Options: true or false. Defaults to false.

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 logger component, 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

This Action sends a defined UART signal to the given UART bus.

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'

Debugging

If you need insight in the communication that is being sent and/or received over a UART bus, then you can make use of the debugging feature.

# Example configuration entry
uart:
  baud_rate: 115200
  debug:
    direction: BOTH
    dummy_receiver: false
    after:
      bytes: 60
    sequence:
      - lambda: UARTDebug::log_hex(direction, bytes, ':');
  • direction (Optional, enum): The direction of communication to debug, one of: “RX” (receive, incoming), “TX” (send, outgoing) or “BOTH”. Defaults to “BOTH”.

  • dummy_receiver (Optional, boolean): Whether or not to enable the dummy receiver feature. The debugger will only accumulate bytes that are actually read or sent by a UART device component. This feature is useful when you want to debug all incoming communication, while no UART device component is configured for the UART bus (yet). This is especially useful for developers. Normally you’d want to leave this option disabled. Defaults to false.

  • after (Optional, mapping): The debugger accumulates bytes of communication. This option defines when to trigger publishing the accumulated bytes. The possible options are:

    • bytes (Optional, int): Trigger after accumulating the specified number of bytes. Defaults to 256.

    • timeout (Optional, Time): Trigger after no communication has been seen during the specified timeout, while one or more bytes have been accumulated. Defaults to 100ms.

    • delimiter (Optional, string or list of bytes): Trigger after the specified sequence of bytes is detected in the communication.

  • sequence (Required, Action): Action(s) to perform for publishing debugging data. The actions can make use of the following variables:

    • direction: uart::UART_DIRECTION_RX or uart::UART_DIRECTION_TX

    • bytes: std::vector<uint8_t> containing the accumulated bytes

Helper functions for logging

Helper functions are provided to make logging of debug data in various formats easy:

  • UARTDebug::log_hex(direction, bytes, char separator) Log the bytes as hex values, separated by the provided separator character.

  • UARTDebug::log_string(direction, bytes) Log the bytes as string values, escaping unprintable characters.

  • UARTDebug::log_int(direction, bytes, char separator) Log the bytes as integer values, separated by the provided separator character.

  • UARTDebug::log_binary(direction, bytes, char separator) Log the bytes as <binary> (<hex>) values, separated by the provided separator character.

Logger buffer size

Beware that the logger component uses a limited buffer size of 512 bytes by default. If the UART debugger log lines become too long, then you will notice that they end up truncated in the log output.

In that case, either make sure that the debugger outputs less data per log line (e.g. by setting the after.bytes option to a lower value) or increase the logger buffer size using the logger tx_buffer_size option.

See Also