View Source usb (usb v0.2.0)

Erlang interface for interacting with USB devices.

Link to this section Summary

Types

Reference to a USB device attached to the host system.
A map representing the standard USB device descriptor. This descriptor is documented in section 9.6.1 of the USB 3.0 specification.
A referenced to an open USB device. This handle is used to perform I/O and other operations. When finished with a device handle, you should call close_device/1.

Indicates the speed at which the device is operating.

Functions

Claim an interface on a given device handle. You must claim the interface you wish to use before you can perform I/O on any of its endpoints.

Clear the halt/stall condition for an endpoint.

Close a device handle.
Stop listening for hotplug events.
Get the number of the bus that a device is connected to.
Get a USB configuration descriptor based on its index.
Get the address of the device on the bus it is connected to.
Get the USB device descriptor for a given device.
Returns a list of USB devices currently attached to the system.
Get the negotiated connection speed for a device.
Get the number of the port that a device is connected to.
Get the list of all port numbers from root for the specified device.

start listening for hotplug events. The owner process will start receiving the following hotplug events

Open a device and obtain a device handle. A handle allows you to perform I/O on the device in question.

Release an interface previously claimed with claim_interface/2.

Link to this section Types

-type alt_setting() ::
    #{interface_number := non_neg_integer(),
      setting_number := non_neg_integer(),
      class_code := non_neg_integer(),
      sub_class_code := non_neg_integer(),
      protocol_code := non_neg_integer(),
      description_string_index := non_neg_integer(),
      endpoints := [endpoint()],
      extra := binary()}.
-type config_descriptor() ::
    #{configuration_number := byte(),
      num_interfaces := byte(),
      description_string_index := byte(),
      attributes := byte(),
      max_power := byte(),
      interfaces := [interface_descriptor()],
      extra := binary()}.
-opaque device()
Reference to a USB device attached to the host system.
-type device_descriptor() ::
    #{usb_version := 0..65535,
      class_code := byte(),
      sub_class_code := byte(),
      protocol_code := byte(),
      max_packet_size0 := byte(),
      vendor_id := 0..65535,
      product_id := 0..65535,
      device_version := 0..65535,
      manufacturer_string_index := byte(),
      product_string_index := byte(),
      serial_number_string_index := byte(),
      num_configurations := byte()}.
A map representing the standard USB device descriptor. This descriptor is documented in section 9.6.1 of the USB 3.0 specification.
Link to this opaque

device_handle/0

View Source (opaque)
-opaque device_handle()
A referenced to an open USB device. This handle is used to perform I/O and other operations. When finished with a device handle, you should call close_device/1.
-type device_speed() :: unknown | low | full | high | super | super_plus.

Indicates the speed at which the device is operating.

unknown
The OS doesn't report or know the device speed.
low
The device is operating at low speed (1.5MBit/s).
full
The device is operating at full speed (12MBit/s).
high
The device is operating at high speed (480MBit/s).
super
The device is operating at super speed (5000MBit/s).
super_plus
The device is operating at super speed plus (10000MBit/s).
-type endpoint() ::
    #{address := non_neg_integer(),
      attributes := non_neg_integer(),
      max_packet_size := non_neg_integer(),
      interval := non_neg_integer(),
      refresh := non_neg_integer(),
      synch_address := non_neg_integer(),
      extra := binary()}.
Link to this opaque

hotplug_monitor/0

View Source (opaque)
-opaque hotplug_monitor()
Link to this type

interface_descriptor/0

View Source
-type interface_descriptor() :: #{alt_settings := [alt_setting()]}.
Link to this type

monitor_hotplug_flag/0

View Source
-type monitor_hotplug_flag() :: enumerate.

Link to this section Functions

Link to this function

attach_kernel_driver(DeviceHandle, InterfaceNumber)

View Source
-spec attach_kernel_driver(device_handle(), integer()) -> ok | {error, term()}.
Link to this function

claim_interface(DeviceHandle, InterfaceNumber)

View Source
-spec claim_interface(device_handle(), non_neg_integer()) -> ok | {error, term()}.

Claim an interface on a given device handle. You must claim the interface you wish to use before you can perform I/O on any of its endpoints.

It is legal to attempt to claim an already-claimed interface, in which case this function just returns ok without doing anything.

Claiming of interfaces is a purely logical operation; it does not cause any requests to be sent over the bus. Interface claiming is used to instruct the underlying operating system that your application wishes to take ownership of the interface.
Link to this function

clear_halt(DeviceHandle, Endpoint)

View Source
-spec clear_halt(device_handle(), byte()) -> ok | {error, term()}.

Clear the halt/stall condition for an endpoint.

Endpoints with halt status are unable to receive or transmit data until the halt condition is stalled.

You should cancel all pending transfers before attempting to clear the halt condition.
Link to this function

close_device(DeviceHandle)

View Source
-spec close_device(device_handle()) -> ok | {error, term()}.
Close a device handle.
Link to this function

demonitor_hotplug(HotplugEvents)

View Source
-spec demonitor_hotplug(hotplug_monitor()) -> ok | {error, term()}.
Stop listening for hotplug events.
Link to this function

detach_kernel_driver(DeviceHandle, InterfaceNumber)

View Source
-spec detach_kernel_driver(device_handle(), integer()) -> ok | {error, term()}.
-spec get_bus_number(device()) -> {ok, 0..255} | {error, term()}.
Get the number of the bus that a device is connected to.
Link to this function

get_config_descriptor(Device, ConfigIndex)

View Source
-spec get_config_descriptor(device(), byte()) -> {ok, config_descriptor()} | {error, term()}.
Get a USB configuration descriptor based on its index.
Link to this function

get_device_address(Device)

View Source
-spec get_device_address(device()) -> {ok, 0..255} | {error, term()}.
Get the address of the device on the bus it is connected to.
Link to this function

get_device_descriptor(Device)

View Source
-spec get_device_descriptor(device()) -> {ok, device_descriptor()} | {error, term()}.
Get the USB device descriptor for a given device.
-spec get_device_list() -> {ok, [device()]} | {error, term()}.
Returns a list of USB devices currently attached to the system.
Link to this function

get_device_speed(Device)

View Source
-spec get_device_speed(device()) -> {ok, device_speed()} | {error, term()}.
Get the negotiated connection speed for a device.
-spec get_port_number(device()) -> {ok, 0..255} | {error, term()}.
Get the number of the port that a device is connected to.
Link to this function

get_port_numbers(Device)

View Source
-spec get_port_numbers(device()) -> {ok, [0..255]} | {error, term()}.
Get the list of all port numbers from root for the specified device.
-spec monitor_hotplug() -> {ok, hotplug_monitor()} | {error, term()}.

Equivalent to monitor_hotplug([]).

start listening for hotplug events.
-spec monitor_hotplug([monitor_hotplug_flag()]) -> {ok, hotplug_monitor()} | {error, term()}.

start listening for hotplug events. The owner process will start receiving the following hotplug events:

{usb, device_arrived, Device} and {usb, device_left, Device}.

If the enumerate flag is provided, the owner process will received device_arrived events for all devices already plugged into the host.
-spec open_device(device()) -> {ok, device_handle()} | {error, term()}.
Open a device and obtain a device handle. A handle allows you to perform I/O on the device in question.
Link to this function

read_bulk(DeviceHandle, Endpoint, DataLen, Timeout)

View Source
-spec read_bulk(device_handle(), byte(), integer(), timeout()) ->
             {ok, binary()} | {error, timeout, binary()} | {error, term()}.
Link to this function

read_control(DeviceHandle, RequestType, Request, Value, Index, ReadLen, Timeout)

View Source
-spec read_control(device_handle(),
             byte(),
             byte(),
             non_neg_integer(),
             non_neg_integer(),
             non_neg_integer(),
             timeout()) ->
                {ok, binary()} | {error, term()}.
Link to this function

read_interrupt(DeviceHandle, Endpoint, DataLen, Timeout)

View Source
-spec read_interrupt(device_handle(), byte(), integer(), timeout()) ->
                  {ok, binary()} | {error, timeout, binary()} | {error, term()}.
Link to this function

release_interface(DeviceHandle, InterfaceNumber)

View Source
-spec release_interface(device_handle(), non_neg_integer()) -> ok | {error, term()}.

Release an interface previously claimed with claim_interface/2.

You should release all claimed interfaces before closing a device handle.
Link to this function

set_configuration(DeviceHandle, Configuration)

View Source
-spec set_configuration(device_handle(), integer()) -> ok | {error, term()}.
Link to this function

write_bulk(DeviceHandle, Endpoint, Data, Timeout)

View Source
-spec write_bulk(device_handle(), byte(), binary(), timeout()) ->
              {ok, integer()} | {error, timeout, non_neg_integer()} | {error, term()}.
Link to this function

write_control(DeviceHandle, RequestType, Request, Value, Index, Data, Timeout)

View Source
-spec write_control(device_handle(),
              byte(),
              byte(),
              non_neg_integer(),
              non_neg_integer(),
              binary(),
              timeout()) ->
                 {ok, integer()} | {error, term()}.
Link to this function

write_interrupt(DeviceHandle, Endpoint, Data, Timeout)

View Source
-spec write_interrupt(device_handle(), byte(), binary(), timeout()) ->
                   {ok, integer()} | {error, timeout, non_neg_integer()} | {error, term()}.