package usb

  1. Overview
  2. Docs
package usb
Legend:
Library
Module
Module type
Parameter
Class
Class type

Module for USB communication

val handle_error : ('a -> 'b) -> 'a -> 'b

handle_error f x applies f to x and returns the result. If the exception Error or Transport is raised, it prints a message describing the error and exits with code 2.

General errors
type error =
  1. | Error_io
    (*

    Error on IOs

    *)
  2. | Error_invalid_param
    (*

    Invalid parameter. If this error is raised, then there is a bug in ocaml-usb. Please fill a bug report in this case.

    *)
  3. | Error_access
    (*

    Access denied to a peripheral

    *)
  4. | Error_no_device
    (*

    No such device (it may have been disconnected)

    *)
  5. | Error_not_found
    (*

    Entity not found

    *)
  6. | Error_busy
    (*

    Resource busy

    *)
  7. | Error_timeout
    (*

    Operation timed out

    *)
  8. | Error_overflow
    (*

    Overflow

    *)
  9. | Error_pipe
    (*

    Pipe error

    *)
  10. | Error_interrupted
    (*

    System call interrupted (perhaps due to signal)

    *)
  11. | Error_no_mem
    (*

    Insufficient memory

    *)
  12. | Error_not_supported
    (*

    Operation not supported or unimplemented on this platform

    *)
  13. | Error_other
    (*

    Other error

    *)

Any function of this module may raise one of the following errors:

exception Error of error * string

Error(error, func_name) is raised when libusb returns an error. func_name is a the name of the function which failed.

val error_message : error -> string

error_message error returns a human readable description of the error

Types
type direction =
  1. | In
  2. | Out

A USB endpoint direction

type endpoint = int

A USB endpoint number

Miscellanies
val init : unit Lazy.t

When forced, init initialises libusb. This is automatically done so you do not need to do it manually. By the way you can do it to catch initialisation errors.

val set_debug : [ `quiet | `error | `warning | `verbose ] -> unit

set_debug level set the debug level.

Device informations
type device

Representation of a device description

val get_device_list : unit -> device list

Returns a list of USB devices currently attached to the system.

val get_bus_number : device -> int

Get the number of the bus that a device is connected to.

val get_device_address : device -> int

Get the address of the device on the bus it is connected to.

val get_max_packet_size : device:device -> direction:direction -> endpoint:endpoint -> int

get_max_packet_size ~device ~direction ~endpoint Convenience function to retrieve the wMaxPacketSize value for a particular endpoint in the active device configuration.

Device use
type handle

A handle allows you to perform I/O on the device in question.

type interface = int

An interface number on a device

val open_device : device -> handle

Open a device and obtain a device handle.

A handle allows you to perform I/O on the device in question.

val close : handle -> unit

Close a previously opened device handle

val open_device_with : vendor_id:int -> product_id:int -> handle

open_device_with ~vendor_id ~product_id

Convenience function for finding a device with a particular idVendor/idProduct combination.

  • raises Failure

    if the device is not found.

val get_device : handle -> device

Get the underlying device for a handle

val kernel_driver_active : handle -> interface -> bool

Determine if a kernel driver is active on an interface.

If a kernel driver is active, you cannot claim the interface, and libusb will be unable to perform I/O.

val detach_kernel_driver : handle -> interface -> unit

Detach a kernel driver from an interface.

If successful, you will then be able to claim the interface and perform I/O.

val attach_kernel_driver : handle -> interface -> unit

Re-attach an interface's kernel driver, which was previously detached using detach_kernel_driver.

val claim_interface : handle -> interface -> unit Lwt.t

claim_interface handle interface_number

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.

val release_interface : handle -> interface -> unit Lwt.t

Release an interface previously claimed with libusb_claim_interface().

You should release all claimed interfaces before closing a device handle.

This is a blocking function. A SET_INTERFACE control request will be sent to the device, resetting interface state to the first alternate setting.

type configuration = int

A device configuration

val get_configuration : handle -> configuration Lwt.t

get_configuration handle returns the current configuration of a device

val set_configuration : handle -> configuration -> unit Lwt.t

set_configuration handle conf change the current configuration of a device

val set_interface_alt_setting : handle -> interface -> int -> unit Lwt.t

set_interface_alt_setting handle interface alternate_setting activates an alternate setting for an interface.

val clear_halt : handle -> endpoint -> unit Lwt.t

clear_halt handle endpoint clears the halt/stall condition for an endpoint.

val reset_device : handle -> unit Lwt.t

reset_device handle reset the given device

USB descriptors
module Class : sig ... end

Device class codes

type device_descriptor = {
  1. dd_usb : int;
    (*

    USB specification release number in binary-coded decimal.

    A value of 0x0200 indicates USB 2.0, 0x0110 indicates USB 1.1, etc.

    *)
  2. dd_device_class : Class.t;
    (*

    USB-IF class code for the device.

    *)
  3. dd_device_sub_class : int;
    (*

    USB-IF subclass code for the device, qualified by the dd_device_class value.

    *)
  4. dd_device_protocol : int;
    (*

    USB-IF protocol code for the device, qualified by the dd_device_class and dd_device_subclass values.

    *)
  5. dd_max_packet_size : int;
    (*

    Maximum packet size for endpoint 0.

    *)
  6. dd_vendor_id : int;
    (*

    USB-IF vendor ID.

    *)
  7. dd_product_id : int;
    (*

    USB-IF product ID.

    *)
  8. dd_device : int;
    (*

    Device release number in binary-coded decimal.

    *)
  9. dd_index_manufacturer : int;
    (*

    Index of string descriptor describing manufacturer.

    *)
  10. dd_index_product : int;
    (*

    Index of string descriptor describing product.

    *)
  11. dd_index_serial_number : int;
    (*

    Index of string descriptor containing device serial number.

    *)
  12. dd_configurations : int;
    (*

    Number of possible configurations.

    *)
}
val get_device_descriptor : device -> device_descriptor

Get the USB device descriptor for a given device.

type endpoint_descriptor = {
  1. ed_endpoint_address : int;
    (*

    The address of the endpoint described by this descriptor.

    *)
  2. ed_attributes : int;
    (*

    Attributes which apply to the endpoint when it is configured using the cd_configuration_value.

    *)
  3. ed_max_packet_size : int;
    (*

    Maximum packet size this endpoint is capable of sending/receiving.

    *)
  4. ed_interval : int;
    (*

    Interval for polling endpoint for data transfers.

    *)
  5. ed_refresh : int;
    (*

    For audio devices only: the rate at which synchronization feedback is provided.

    *)
  6. ed_synch_address : int;
    (*

    For audio devices only: the address if the synch endpoint.

    *)
}
type interface_descriptor = {
  1. id_interface : int;
    (*

    Number of this interface.

    *)
  2. id_alternate_setting : int;
    (*

    Value used to select this alternate setting for this interface.

    *)
  3. id_interface_class : Class.t;
    (*

    USB-IF class code for this interface.

    *)
  4. id_interface_sub_class : int;
    (*

    USB-IF subclass code for this interface, qualified by the id_interface_class value.

    *)
  5. id_interface_protocol : int;
    (*

    USB-IF protocol code for this interface, qualified by the id_interface_class and id_interface_sub_class values.

    *)
  6. id_index_interface : int;
    (*

    Index of string descriptor describing this interface.

    *)
  7. id_endpoints : endpoint_descriptor array;
    (*

    Array of endpoint descriptors.

    *)
}
type config_descriptor = {
  1. cd_configuration_value : int;
    (*

    Identifier value for this configuration

    *)
  2. cd_index_configuration : int;
    (*

    Index of string descriptor describing this configuration.

    *)
  3. cd_attributes : int;
    (*

    A bitmask, representing configuration characteristics.

    *)
  4. cd_max_power : int;
    (*

    Maximum power consumption of the USB device from this bus in this configuration when the device is fully opreation.

    Expressed in units of 2 mA.

    *)
  5. cd_interfaces : interface_descriptor array array;
    (*

    Array of interfaces supported by this configuration.

    cd_interface.(iface).(altsetting) designate the interface descriptor for interface iface with alternate setting altsetting.

    *)
}
val get_active_config_descriptor : device -> config_descriptor

Get the USB configuration descriptor for the currently active configuration.

val get_config_descriptor : device -> int -> config_descriptor

Get a USB configuration descriptor based on its index.

val get_config_descriptor_by_value : device -> int -> config_descriptor

Get a USB configuration descriptor with a specific cd_configuration_value.

module DT : sig ... end

Descriptor types

val get_string_descriptor : handle -> ?timeout:float -> ?lang_id:int -> index:int -> string Lwt.t

Retrieve a string descriptor from a device.

IOs
Errors
type transfer_error =
  1. | Transfer_error
    (*

    Transfer failed

    *)
  2. | Transfer_timed_out
    (*

    Transfer timed out

    *)
  3. | Transfer_cancelled
    (*

    Transfer was cancelled

    *)
  4. | Transfer_stall
    (*

    For bulk/interrupt endpoints: halt condition detected (endpoint stalled). For control endpoints: control request not supported.

    *)
  5. | Transfer_no_device
    (*

    Device was disconnected

    *)
  6. | Transfer_overflow
    (*

    Device sent more data than requested

    *)

Transfers may fails with any of the following error:

exception Transfer of transfer_error * string

Transfer(error, func_name) Exception raised when a transfer fail.

val transfer_error_message : transfer_error -> string

transfer_error_message error

Bulk transfers
val bulk_recv : handle:handle -> endpoint:endpoint -> ?timeout:float -> string -> int -> int -> int Lwt.t

bulk_recv ~handle ~endpoint ?timeout buffer offset length

val bulk_send : handle:handle -> endpoint:endpoint -> ?timeout:float -> string -> int -> int -> int Lwt.t

bulk_send ~handle ~endpoint ?timeout buffer offset length

Interrupt transfers
val interrupt_recv : handle:handle -> endpoint:endpoint -> ?timeout:float -> string -> int -> int -> int Lwt.t

interrupt_recv ~handle ~endpoint ?timeout buffer offset length

val interrupt_send : handle:handle -> endpoint:endpoint -> ?timeout:float -> string -> int -> int -> int Lwt.t

interrupt_send ~handle ~endpoint ?timeout buffer offset length

Isochronous transfers
type iso_result =
  1. | Iso_ok of int
    (*

    The packet has been transfered successfully

    *)
  2. | Iso_error of transfer_error * string
    (*

    Iso_error(error, func_name) An error occured

    *)

Result of the transfer of one packet in an isochronous transfer:

val iso_recv : handle:handle -> endpoint:endpoint -> ?timeout:float -> string -> int -> int list -> iso_result list Lwt.t
val iso_send : handle:handle -> endpoint:endpoint -> ?timeout:float -> string -> int -> int list -> iso_result list Lwt.t
Control transfers
type recipient =
  1. | Device
  2. | Interface
  3. | Endpoint
  4. | Other
type request_type =
  1. | Standard
  2. | Class
  3. | Vendor
  4. | Reserved
type request = int
val control_send : handle:handle -> endpoint:endpoint -> ?timeout:float -> ?recipient:recipient -> ?request_type:request_type -> request:request -> value:int -> index:int -> string -> int -> int -> int Lwt.t

Sends a control packet.

  • parameter recipient

    defaults to Device

  • parameter request_type

    defaults to Standard

val control_recv : handle:handle -> endpoint:endpoint -> ?timeout:float -> ?recipient:recipient -> ?request_type:request_type -> request:request -> value:int -> index:int -> string -> int -> int -> int Lwt.t

Receives a control packet.

  • parameter recipient

    defaults to Device

  • parameter request_type

    defaults to Standard

module Request : sig ... end

Standard requests