ESPHome

ESPHome serial proxy transport.

The ESPHome serial proxy component exposes any ESPHome serial instance through the ESPHome API. This is used by serialx to create a fully functional remote serial port, similar to RFC2217 but with many quality of life, performance, and security improvements.

This platform requires the aioesphomeapi package to be installed, provided by the esphome dependency group:

pip install 'serialx[esphome]'

Note

The aioesphomeapi package does not provide a synchronous interface so the sync serial transport relies on spawning an asyncio event loop in a secondary thread in order to proxy the async methods. This interface is far from ideal. If you’d like to make use of this transport, please migrate your application to the async APIs for better compatibility.

class serialx.platforms.serial_esphome.ESPHomeSerial

Bases: BaseSerial

Synchronous serial interface over ESPHome serial proxy API.

Warning

ESPHome does not have a native synchronous API, using this interface is heavily discouraged. Please use the async API.

__init__(*args, connect_timeout=10.0, loop=None, api=None, port_name=None, port_instance=None, mode=SerialProxyModeName.RAW, port_manufacturer=None, port_product=None, port_serial_number=None, port_usb_vid=None, port_usb_pid=None, port_usb_bcd_device=None, port_usb_interface_num=None, port_udev_id=None, key=None, password=None, noise_psk=None, **kwargs)

Initialize ESPHome serial port.

Parameters:

  • connect_timeout (float) – Total timeout for connecting to the ESPHome device and subscribing to events.

  • loop (asyncio.AbstractEventLoop | None) – Event loop to offload async operations to, optional. This is mostly intended for internal use from the async transport. If an event loop is not provided, the default for the synchronous API, a new one will be created at runtime.

  • api (APIClient | None) – An instance of aioesphomeapi.APIClient to use. Authentication will be skipped and the API will not be disconnected once the serial object is closed.

  • port_name (str | None) – The name attribute of the ESPHome serial proxy to connect to.

  • port_manufacturer (str | None) – Manufacturer the device behind the port must report. A port is a socket, so without any of the matchers below the connection succeeds against whatever happens to be plugged in. Every matcher given must match, both when opening and for as long as the port stays open. All are also read from query parameters of the same name, integers with int(value, 0).

  • port_product (str | None) – Product the device behind the port must report.

  • port_serial_number (str | None) – Serial number the device behind the port must report.

  • port_usb_vid (int | None) – USB vendor ID the device behind the port must report. Any port_usb_* matcher also requires the port to report a non-zero USB vendor and product ID.

  • port_usb_pid (int | None) – USB product ID the device behind the port must report.

  • port_usb_bcd_device (int | None) – USB device release number the device behind the port must report.

  • port_usb_interface_num (int | None) – USB interface number the port must be bound to.

  • port_udev_id (str | None) – The /dev/serial/by-id/ link name udev would give the device behind the port, without the directory or any -portN suffix. See udev_serial_by_id_stem.

  • port_instance (int | None) –

    The numerical instance ID of the ESPHome serial proxy instance to connect to.

    Deprecated since version 1.2.0.

  • mode (SerialProxyModeName | str) – The mode the serial proxy should use, either raw (the default) or protocol to engage the port’s protocol-aware tap.

  • key (str | None) – The Noise PSK to use when creating an aioesphomeapi.APIClient instance.

  • password (str | None) – The API password to use when creating an aioesphomeapi.APIClient instance.

  • noise_psk (str | None) – An alias for key. Both cannot be passed at once.

  • *args (Any) – Passed through to BaseSerial.

  • **kwargs (Any) – Passed through to BaseSerial.

Return type:

None

property tap_mode: SerialProxyModeName | None

The mode the device confirmed for this port, or None before subscribing.

raw means the port has no tap, so a client must do the protocol’s work itself.

property is_open: bool

Return whether the serial port is open.

num_unread_bytes()

Return the number of bytes waiting to be read.

Return type:

int

num_unwritten_bytes()

Return the number of bytes waiting to be written.

Return type:

int

class serialx.platforms.serial_esphome.ESPHomeSerialTransport

Bases: BaseSerialTransport

Serial transport over ESPHome serial proxy API.

__init__(loop, protocol)

Initialize the ESPHome serial transport.

Parameters:

  • loop (AbstractEventLoop)

  • protocol (Protocol)

Return type:

None

write(data)

Write data to the serial proxy.

Parameters:

data (bytes | bytearray | memoryview)

Return type:

None

is_closing()

Return whether the transport is closing.

Return type:

bool

close()

Close the transport.

Return type:

None

abort()

Abort the transport immediately.

Return type:

None

get_write_buffer_size()

Get the number of bytes currently in the write buffer.

Return type:

int