Behaviour for serial proxy adapters.

Implement this module to expose one or more serial ports to ESPHome clients through the Native API's serial proxy feature. Home Assistant can then talk to the port over the network as though it were local — useful for Zigbee coordinators, CLI debug ports, and similar "tunnel a UART through the device" use cases.

Espex itself owns no port state. It calls your callbacks from the per-connection handler process when a client configures, writes to, or closes an instance.

Callbacks

The three optional callbacks are each reported to the client as :not_supported when omitted — your adapter can safely ignore them if the hardware can't do modem-pin control or drain-flush.

Data flow

After a successful open/3, data arriving on the port must be sent to the subscriber pid (the per-connection handler) as:

{:espex_serial_data, handle, binary}

handle is the opaque term you returned from open/3 — typically a pid, reference, or small tuple. The handler uses it to correlate the data back to an instance id.

The client can later change port parameters by issuing another configure request; the connection handler will close/1 the existing handle and call open/3 again with the new options. Your adapter doesn't need to handle reconfigure-in-place.

open_opts reference

open/3 receives a keyword list shaped like open_opts/0:

The defaults follow common "9600-8-N-1" convention and match what ESPHome uses when fields are omitted from a SerialProxyConfigureRequest. Use configure_request_to_open_opts/1 if you're building your own message-routing test harness; the connection handler calls it for you in normal operation.

SerialProxy.Info for advertisements

list_instances/0 returns a list of Espex.SerialProxy.Info structs, one per port. Each needs:

• instance — stable non_neg_integer() id; the client refers to ports by this id in all subsequent requests
• name — display name shown in the Home Assistant UI
• port_type — :ttl, :rs232, or :rs485

The list is snapshotted at connection-accept time and cached by the client; see the "Architecture" guide for why changes require a reconnect.

Example: a port wrapping Circuits.UART

The following sketch wires a single port (/dev/ttyUSB0) to a Zigbee-style advertisement. It assumes a real Circuits.UART-like library is available; adapt to whichever serial library you use.

defmodule MyApp.SerialAdapter do
  @behaviour Espex.SerialProxy

  @impl true
  def list_instances do
    [Espex.SerialProxy.Info.new(instance: 0, name: "zigbee", port_type: :ttl)]
  end

  @impl true
  def open(0, opts, subscriber) do
    {:ok, pid} = MyApp.SerialPort.start_link(
      device: "/dev/ttyUSB0",
      subscriber: subscriber,
      speed: opts[:speed],
      data_bits: opts[:data_bits],
      stop_bits: opts[:stop_bits],
      parity: opts[:parity],
      flow_control: opts[:flow_control]
    )
    {:ok, pid}
  end

  def open(_unknown, _opts, _subscriber), do: {:error, :no_such_instance}

  @impl true
  def write(pid, data), do: MyApp.SerialPort.write(pid, data)

  @impl true
  def close(pid) do
    _ = MyApp.SerialPort.stop(pid)
    :ok
  end

  @impl true
  def set_modem_pins(pid, rts, dtr), do: MyApp.SerialPort.set_pins(pid, rts: rts, dtr: dtr)

  @impl true
  def get_modem_pins(pid), do: MyApp.SerialPort.get_pins(pid)

  @impl true
  def request(pid, :flush), do: MyApp.SerialPort.flush(pid)
  def request(_pid, _), do: {:ok, :not_supported}
end

And inside the wrapper GenServer (MyApp.SerialPort), any time your read loop gets a chunk from the OS, forward it to the subscriber:

send(state.subscriber, {:espex_serial_data, self(), chunk})

request/2 semantics

The optional request/2 callback handles the three operations the ESPHome wire protocol exposes:

• :subscribe / :unsubscribe — espex already wires data delivery at open/3 time via the subscriber pid. Most adapters can return {:ok, :not_supported} or {:ok, :ok} here. Implement them only if your adapter keeps a separate stream-enabled flag you want the client to toggle explicitly.
• :flush — block until all queued TX data has been drained. Return {:ok, :ok} if you confirmed the drain, {:ok, :assumed_success} if the platform can't report completion, {:ok, :timeout} if you gave up waiting, or {:error, reason} on failure.

When you don't define request/2 at all, espex responds with :not_supported to every request type automatically.

Wiring

Pass your adapter module to Espex.start_link/1:

Espex.start_link(
  device_config: [name: "serial-gateway"],
  serial_proxy: MyApp.SerialAdapter
)