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, 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_instance (int | None) –

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

    Deprecated since version 1.2.0.

  • 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 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

async flush()

Flush write buffers.

Return type:

None

async get_modem_pins()

Get modem control bits.

Return type:

ModemPins

get_write_buffer_size()

Get the number of bytes currently in the write buffer.

Return type:

int