Skip to content
ESPHome - Smart Home Made Simple

Serial Proxy

IMPORTANT

This component is EXPERIMENTAL. The API (both Python configuration and C++ interfaces) may change at any time without following the normal breaking changes policy. Use at your own risk. Once the API is considered stable, this warning will be removed.

The serial_proxy component exposes a physical UART serial port on your ESPHome device to API clients (such as Home Assistant) via the Native API. This allows an API client to send and receive data directly to and from a serial device connected to the ESP, effectively creating a network-attached serial port.

The component requires the Native API and UART components.

Multiple serial_proxy instances may be configured on a single device, each attached to a different UART.

# Example configuration entry
serial_proxy:
  - id: serial_proxy_1
    uart_id: serial_1
    name: My Serial Device
    port_type: TTL

Configuration variables

Section titled “Configuration variables”
  • id (Optional, ID): Manually specify the ID to use for code generation.
  • name (Required, string): A human-readable name for this serial port, used to identify it to API clients.
  • uart_id (Required, ID): The ID of the UART component this proxy is attached to.
  • port_type (Required, string): The electrical type of the serial port. One of:
    • TTL: Standard TTL logic-level UART (3.3V or 5V). Typically used for direct connections to most microcontrollers.
    • RS232: RS-232 standard serial port (typically ±12V levels via an appropriate line-driver IC). Typically used for PC-style serial connections, often with a DB9-type connector.
    • RS485: RS-485 differential serial bus. Typically used for industrial/multi-drop serial networks.
  • rts_pin (Optional, Pin): GPIO pin to use as the RTS (Request to Send) modem control output. The state of this pin may be controlled by the API client at runtime.
  • dtr_pin (Optional, Pin): GPIO pin to use as the DTR (Data Terminal Ready) modem control output. The state of this pin may be controlled by the API client at runtime.

How It Works

Section titled “How It Works”

When an API client connects, it can:

  • Send data to the serial device by writing bytes through the API.
  • Receive data from the serial device — data arriving on the UART is forwarded to connected API clients automatically each loop iteration (up to 256 bytes at a time).
  • Reconfigure the UART at runtime — the API client may change the baud rate, data bits, stop bits, and parity without reflashing firmware.
  • Control modem pins — if rts_pin or dtr_pin are configured, the API client can set their states at runtime.

Full Example

Section titled “Full Example”
# Two serial proxies on separate UARTs
uart:
  - id: device_uart
    tx_pin: GPIO4
    rx_pin: GPIO5
    baud_rate: 9600


  - id: rs485_uart
    tx_pin: GPIO16
    rx_pin: GPIO17
    baud_rate: 19200


api:


serial_proxy:
  - id: device_serial
    uart_id: device_uart
    name: TTL Device
    port_type: TTL


  - id: rs485_serial
    uart_id: rs485_uart
    name: RS-485 Bus
    port_type: RS485
    rts_pin: GPIO18

See Also

Section titled “See Also”