# `Hassock`
[🔗](https://github.com/bbangert/hassock/blob/v0.3.0/lib/hassock.ex#L1)

Home Assistant WebSocket client for Elixir.

Two layers, opt-in:

  * `Hassock.Connection` — the WebSocket itself. Always required.
  * `Hassock.Cache` — optional ETS-backed full entity cache, kept in sync
    via HA's `subscribe_entities` command.

Both follow the controlling-process pattern (à la `:gen_tcp`,
`Circuits.UART`): the process that calls `start_link/1` is the default
recipient of async messages. Use `controlling_process/2` to hand off.

## Bare connection

    {:ok, conn} =
      Hassock.connect(
        config: %Hassock.Config{url: "http://homeassistant.local:8123", token: "..."}
      )

    receive do
      {:hassock, ^conn, :connected} -> :ok
    end

    {:ok, sub} = Hassock.subscribe_entities(conn, ["light.kitchen"])
    # handle {:hassock, ^conn, {:event, {:entities, _}}} in your handle_info/2

## With entity cache

    {:ok, conn} = Hassock.connect(config: config)
    {:ok, cache} = Hassock.Cache.start_link(connection: conn)

    receive do
      {:hassock_cache, ^cache, :ready} -> :ok
    end

    Hassock.cached_state(cache, "light.kitchen")

# `cached_domain`

All cached entities under a domain prefix (e.g. `"light"`).

# `cached_state`

Look up a cached entity by id (requires a `Hassock.Cache`).

# `cached_states`

All cached entities.

# `call_service`

Call a Home Assistant service. See `Hassock.Connection.call_service/3`.

# `command`

Send any HA WebSocket command and wait for its result. See `Hassock.Connection.command/4`.

# `connect`

Open a WebSocket connection. See `Hassock.Connection.start_link/1`.

# `connected?`

True if the connection is authenticated and the socket is open.

# `controlling_process`

Transfer connection ownership.

# `get_services`

Fetch all available service domains and their services.

# `get_states`

One-shot fetch of all entity states.

# `status`

Connection status and next retry time. See `Hassock.Connection.status/1`.

# `subscribe_entities`

Subscribe to entity state updates. Pass `nil` for all entities.

# `subscribe_events`

Subscribe to a non-entity HA event type.

# `unsubscribe_events`

Cancel a subscription.

# `unwatch`

Stop receiving the connection's lifecycle messages. See `Hassock.Connection.unwatch/1`.

# `watch`

Also receive the connection's lifecycle messages. See `Hassock.Connection.watch/1`.

---

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