Behaviour for Bluetooth Low Energy active-proxy adapters.

Implement this module to expose outbound BLE connections — connect, GATT read/write, notifications, pairing — to ESPHome clients through the Native API. Together with Espex.BluetoothScanner (passive advertisement sniffing), this lets a Nerves device act as a drop-in BLE proxy for Home Assistant, indistinguishable from an ESPHome C++-firmware proxy on the wire.

This behaviour is independent of Espex.BluetoothScanner — you can configure either, both, or neither in Espex.start_link/1. Scanner- only mode is useful for devices that only sniff advertisements; proxy-only mode is rare (clients typically want both).

Callbacks

Espex advertises each optional callback in the device's bluetooth_proxy_feature_flags only when the adapter exports it. When a client invokes a missing optional callback, espex synthesises the protocol's "not supported" response shape (success: false with an error code) without calling the adapter.

Address-keyed model

Every callback takes address :: non_neg_integer() — the 48-bit peripheral MAC packed into a uint64 (most-significant 16 bits zero). Espex never returns an opaque handle; the client refers to a peripheral by address from connect through disconnect. If your adapter tracks internal handles, key them by address yourself.

Owner-locked connections

Espex enforces that an address can be claimed by at most one connection at a time. The first client to issue CONNECT for an address becomes its owner; concurrent connects from other clients receive a BUSY error (error: -3) without invoking the adapter. All GATT requests on an owned address are gated on ownership; a non-owning client gets a GATT error envelope.

Ownership is released when:

• The owning client sends DISCONNECT for the address.
• The owning connection's TCP socket closes (espex calls disconnect/1 for every owned address during cleanup).

Adapters should not implement their own per-client ownership tracking — espex handles it cross-connection. From your adapter's perspective, connect/3 is called at most once per address until the matching disconnect/1 fires.

Data flow: subscriber messages

All adapter callbacks are cast-style: they return :ok to acknowledge the request and deliver results asynchronously to the subscriber pid (the per-connection handler). The subscriber pid for an address is the one passed to connect/3.

Lifecycle messages:

{:espex_ble_connection, address, {:ok, mtu :: non_neg_integer()}}
{:espex_ble_connection, address, {:error, error_code :: integer()}}
{:espex_ble_pair, address, paired? :: boolean(), error_code :: integer()}
{:espex_ble_unpair, address, success? :: boolean(), error_code :: integer()}
{:espex_ble_clear_cache, address, success? :: boolean(), error_code :: integer()}
{:espex_ble_connection_params, address, error_code :: integer()}

GATT messages:

{:espex_ble_gatt_service, address, %Espex.BluetoothProxy.Service{}}
{:espex_ble_gatt_services_done, address}
{:espex_ble_gatt_read, address, handle, {:ok, data :: binary()}}
{:espex_ble_gatt_read, address, handle, {:error, error_code :: integer()}}
{:espex_ble_gatt_write, address, handle, {:ok, _}}
{:espex_ble_gatt_write, address, handle, {:error, error_code :: integer()}}
{:espex_ble_gatt_notify, address, handle, {:ok, _}}
{:espex_ble_gatt_notify, address, handle, {:error, error_code :: integer()}}
{:espex_ble_gatt_notify_data, address, handle, data :: binary()}

Espex translates each tuple into the corresponding wire proto and forwards it to the client.

Streamed GATT services

gatt_get_services/1 is a streaming operation: send one {:espex_ble_gatt_service, address, service} message per service, then {:espex_ble_gatt_services_done, address} to terminate the stream. Espex emits one BluetoothGATTGetServicesResponse per service plus a final BluetoothGATTGetServicesDoneResponse. Don't batch — one service per message keeps the contract simple.

connect/3 options

The opts keyword list carries the client's connection preferences:

:cache_mode reflects the CONNECT_V3_WITH_CACHE / CONNECT_V3_WITHOUT_CACHE / plain CONNECT request types from the wire — adapters should honor it when caching is supported, or ignore it otherwise.

connections_free/0

Espex calls connections_free/0 whenever a client subscribes to BluetoothConnectionsFreeResponse or after every successful connect/disconnect. Return {free, limit} where:

• limit — total active-connection slots your adapter supports
• free — slots currently available (i.e. limit - in_use)

Espex fills the allocated list from its own ownership set, so you don't need to track per-client occupancy.

set_connection_params/2

Optional. The params map carries:

• :min_interval, :max_interval — connection interval bounds (units of 1.25 ms)
• :latency — slave latency (allowed peripheral skips)
• :timeout — supervision timeout (units of 10 ms)

The adapter applies the parameters and reports the outcome via {:espex_ble_connection_params, address, error_code} where error_code == 0 means success.

Example: a BlueHeron-shaped adapter

This sketch wraps a hypothetical BlueHeron-style stack. The actual GATT machinery is elided; focus on the espex-facing shape.

defmodule MyApp.BLEProxy do
  @behaviour Espex.BluetoothProxy

  use GenServer

  alias Espex.BluetoothProxy.{Service, Characteristic, Descriptor}

  @max_connections 3

  def start_link(opts), do: GenServer.start_link(__MODULE__, opts, name: __MODULE__)

  @impl true
  def connect(address, opts, subscriber) do
    GenServer.cast(__MODULE__, {:connect, address, opts, subscriber})
    :ok
  end

  @impl true
  def disconnect(address) do
    GenServer.cast(__MODULE__, {:disconnect, address})
    :ok
  end

  @impl true
  def gatt_get_services(address) do
    GenServer.cast(__MODULE__, {:gatt_get_services, address})
    :ok
  end

  @impl true
  def gatt_read(address, handle) do
    GenServer.cast(__MODULE__, {:gatt_read, address, handle})
    :ok
  end

  @impl true
  def gatt_write(address, handle, data, response?) do
    GenServer.cast(__MODULE__, {:gatt_write, address, handle, data, response?})
    :ok
  end

  @impl true
  def gatt_read_descriptor(address, handle) do
    GenServer.cast(__MODULE__, {:gatt_read_descriptor, address, handle})
    :ok
  end

  @impl true
  def gatt_write_descriptor(address, handle, data) do
    GenServer.cast(__MODULE__, {:gatt_write_descriptor, address, handle, data})
    :ok
  end

  @impl true
  def gatt_notify(address, handle, enable?) do
    GenServer.cast(__MODULE__, {:gatt_notify, address, handle, enable?})
    :ok
  end

  @impl true
  def connections_free do
    {free, _used} = GenServer.call(__MODULE__, :connection_slots)
    {free, @max_connections}
  end

  @impl true
  def pair(address), do: GenServer.cast(__MODULE__, {:pair, address})

  @impl true
  def unpair(address), do: GenServer.cast(__MODULE__, {:unpair, address})

  @impl true
  def clear_cache(address), do: GenServer.cast(__MODULE__, {:clear_cache, address})

  @impl true
  def set_connection_params(address, params) do
    GenServer.cast(__MODULE__, {:set_connection_params, address, params})
  end

  # Inside handle_cast, your stack would call into BlueHeron and
  # forward results back to the subscriber:
  #
  #   send(subscriber, {:espex_ble_connection, address, {:ok, 247}})
  #   send(subscriber, {:espex_ble_gatt_service, address,
  #     %Service{uuid: <<0x18, 0x0F, ...>>, handle: 1, characteristics: [...]}})
  #   send(subscriber, {:espex_ble_gatt_services_done, address})
end

Wiring

Espex.start_link(
  device_config: [name: "ble-proxy"],
  bluetooth_scanner: MyApp.BLEScanner,
  bluetooth_proxy: MyApp.BLEProxy
)

Configure both adapters together for a full Home Assistant BLE proxy.