# `NervesMCP.Connection`
[🔗](https://github.com/nerves-project/nerves_mcp/blob/v0.1.0/lib/nerves_mcp/connection.ex#L5)

Talks to the device behind a running server, whichever transport it uses.

Every function takes the id the server was started with, see
`NervesMCP.start_server/2`.

Requests to one device run one at a time. A request made while another is in
flight waits its turn, and its timeout starts counting when it is sent to the
device.

# `id`

```elixir
@type id() :: term()
```

# `result`

```elixir
@type result() :: {:ok, String.t()} | {:error, String.t()}
```

# `attach_console`

```elixir
@spec attach_console(id(), pid()) :: :ok
```

Sends everything the device prints outside of requests to `pid` as `{:console_data, binary}`.

# `await_firmware_uuid`

```elixir
@spec await_firmware_uuid(id(), non_neg_integer()) :: result()
```

Waits for the device to answer with a firmware UUID, for up to `timeout` ms.

Useful after a reboot or a firmware update. An SSH connection is re-established
between attempts, since a session to a rebooted device can hang for a while.

# `detach_console`

```elixir
@spec detach_console(id()) :: :ok
```

# `eval`

```elixir
@spec eval(id(), String.t(), timeout()) :: result()
```

Evaluates Elixir code on the device and returns the inspected result.

Code that raises, throws or exits gives `{:error, formatted_exception}`.

# `eval_output`

```elixir
@spec eval_output(id(), String.t(), timeout()) :: result()
```

Evaluates Elixir code on the device, capturing what it prints as well.

# `firmware_uuid`

```elixir
@spec firmware_uuid(id(), timeout()) :: result()
```

Reads the UUID of the firmware the device is running.

Fails when the device does not answer, does not run Nerves, or has no UUID.

# `probe`

```elixir
@spec probe(id(), timeout()) ::
  {:ok, String.t()} | {:eval_error, String.t()} | :noise | :down | :busy
```

Probes what is on the other end. Returns:

  * `{:ok, result}` - Elixir ran and gave this for the firmware UUID
  * `{:eval_error, message}` - Elixir ran, but reading the UUID failed
  * `:noise` - bytes came back but no Elixir result
  * `:down` - not connected, or nothing came back
  * `:busy` - other requests are in flight

# `reconnect`

```elixir
@spec reconnect(id()) :: :ok | {:error, String.t()}
```

Drops and re-establishes the connection. Only SSH needs this; UART is a no-op.

# `send_raw`

```elixir
@spec send_raw(id(), iodata()) :: :ok
```

Writes bytes to the device as they are.

# `shell_eval`

```elixir
@spec shell_eval(id(), String.t(), timeout()) :: result()
```

Runs a shell command on a device that offers a shell rather than IEx.

# `shell_eval_output`

```elixir
@spec shell_eval_output(id(), String.t(), timeout()) :: result()
```

Runs a shell command, capturing stdout, stderr and the exit code.

# `type`

```elixir
@spec type(id()) :: :ssh | :uart | nil
```

The transport a server uses: `:ssh`, `:uart`, or `nil` when it is not running.

# `validate`

```elixir
@spec validate(keyword()) :: :ok | {:error, String.t()}
```

Checks a `:connection` option before a server is started with it.

# `whereis`

```elixir
@spec whereis(id()) :: pid() | nil
```

The connection process for a server, if it is running.

---

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