NetMD.Transport behaviour (NetMD v0.1.0)

Copy Markdown View Source

Behaviour for the USB plumbing underneath NetMD.Device.

NetMD devices speak vendor-specific control transfers on the default endpoint plus one bulk IN and one bulk OUT endpoint. Implemented by NetMD.Transport.Usb for real hardware and by a scripted mock in the test suite.

Summary

Types

handle()

Implementation-specific device handle.

info()

Identifying info returned from open/1.

location()

A device found by list/1, located on the bus.

Callbacks

bulk_in(handle, length, timeout)

Read from the bulk IN endpoint.

bulk_out(handle, data, timeout)

Write to the bulk OUT endpoint.

close(handle)

Release the device.

control_in(handle, request, value, index, length)

Vendor-interface control IN transfer.

control_out(handle, request, value, index, data)

Vendor-interface control OUT transfer.

list(keyword)

List the connected NetMD devices without opening any of them.

open(keyword)

Open a device, prepare it for I/O and return a handle plus info.

Types

handle()

@type handle() :: term()

Implementation-specific device handle.

info()

@type info() :: %{vendor_id: 0..65535, product_id: 0..65535}

Identifying info returned from open/1.

location()

@type location() :: %{
  vendor_id: 0..65535,
  product_id: 0..65535,
  bus: pos_integer() | nil,
  address: pos_integer() | nil
}

A device found by list/1, located on the bus.

Callbacks

bulk_in(handle, length, timeout)

@callback bulk_in(handle(), length :: non_neg_integer(), timeout()) ::
  {:ok, binary()} | {:error, term()}

Read from the bulk IN endpoint.

bulk_out(handle, data, timeout)

@callback bulk_out(handle(), data :: binary(), timeout()) :: :ok | {:error, term()}

Write to the bulk OUT endpoint.

close(handle)

@callback close(handle()) :: :ok

Release the device.

control_in(handle, request, value, index, length)

@callback control_in(
  handle(),
  request :: 0..255,
  value :: 0..65535,
  index :: 0..65535,
  length :: non_neg_integer()
) :: {:ok, binary()} | {:error, term()}

Vendor-interface control IN transfer.

control_out(handle, request, value, index, data)

@callback control_out(
  handle(),
  request :: 0..255,
  value :: 0..65535,
  index :: 0..65535,
  data :: binary()
) :: :ok | {:error, term()}

Vendor-interface control OUT transfer.

list(keyword)

(optional) 
@callback list(keyword()) :: [location()]

List the connected NetMD devices without opening any of them.

Enumeration is best-effort and does not fail: a device that cannot be read is simply left out. Optional; transports that model a single fixed device need not implement it.

open(keyword)

@callback open(keyword()) :: {:ok, handle(), info()} | {:error, term()}

Open a device, prepare it for I/O and return a handle plus info.