NervesMCP.Connection (NervesMCP v0.1.0)

Copy Markdown View Source

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.

Summary

Functions

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

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

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

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

Reads the UUID of the firmware the device is running.

Probes what is on the other end. Returns

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

Writes bytes to the device as they are.

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

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

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

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

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

Types

id()

@type id() :: term()

result()

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

Functions

attach_console(id, pid \\ self())

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

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

await_firmware_uuid(id, timeout \\ 60000)

@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(id)

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

eval(id, code, timeout \\ 15000)

@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(id, code, timeout \\ 15000)

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

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

firmware_uuid(id, timeout \\ 5000)

@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(id, timeout \\ 4000)

@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(id)

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

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

send_raw(id, data)

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

Writes bytes to the device as they are.

shell_eval(id, command, timeout \\ 15000)

@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(id, command, timeout \\ 15000)

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

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

type(id)

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

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

validate(connection)

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

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

whereis(id)

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

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