# `Espex.Wizard.Input`
[🔗](https://github.com/bbangert/espex/blob/main/lib/espex/wizard/input.ex#L1)

A wizard input: the user picks a Home Assistant entity, and the client
sends its entity id to the device.

  * `id` — a string you choose, unique in the document. Its key on the
    wire is `Espex.Wizard.fnv1_hash(id)`, which
    `Espex.Wizard.Document.new/1` fills in as `key`.
  * `description` — optional text shown with it, up to 255 bytes
  * `multiple` — the user may pick several entities (default `false`)
  * `max_length` — only with `multiple: true`: the longest list, in
    bytes joined by `,`, the device accepts. 255-4095; 255 when `nil`.
  * `entity_filters` — `Espex.Wizard.EntityFilter` structs limiting
    what the user may pick; any entity when empty
  * `links` — Home Assistant state subscriptions that follow the
    picked entity (see "Linked inputs" below); none by default

espex hands the chosen ids to `c:Espex.Wizard.input_set/2` by `key`.

## Linked inputs

An input with `links` also subscribes to the picked entity's state,
like ESPHome's `homeassistant` sensors linked to a wizard input. Each
link is an `Espex.HomeAssistantStates.Subscription` without an
`entity_id` (or a keyword list of its fields); the picked entity id
fills it in:

    %Input{
      id: "outdoor_temperature",
      entity_filters: [%EntityFilter{domain: ["sensor"]}],
      links: [[], [attribute: "unit_of_measurement"]]
    }

When the client sets the input, the filled-in entries join the
subscription table, replacing the ones from the input's previous
value. Clients that subscribed to Home Assistant states, the one that
set the input included, are sent the new entries, and the states
arrive at `c:Espex.HomeAssistantStates.handle_state/3`.

  * A `multiple: true` input cannot have links.
  * Setting the value the input already has sends nothing. ESPHome
    firmware sends the entries again, which makes Home Assistant track
    the entity twice.
  * Changing the value from A to B and back to A sends A's entries
    again, so the device gets A's current state. Home Assistant then
    tracks A twice on that connection, as with firmware. Every new
    value adds a tracked entity on each subscribed connection until it
    reconnects, as the protocol has no unsubscribe.
  * Links live in memory and belong to the device, not to the client
    that set them: they stay after it disconnects, until a client sets
    the input again or `Espex.update_adapters/2` sets a new `:wizard`
    module. Clients send every input again when they connect, before
    subscribing to states, so nothing is stored.

# `t`
*since 0.12.0* 

```elixir
@type t() :: %Espex.Wizard.Input{
  description: String.t() | nil,
  entity_filters: [Espex.Wizard.EntityFilter.t()],
  id: String.t(),
  key: non_neg_integer() | nil,
  links: [Espex.HomeAssistantStates.Subscription.t() | keyword()],
  max_length: 255..4095 | nil,
  multiple: boolean()
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*