# Module USB

    module USB: sig .. end

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 `USB.Error` or `Transport` is raised, it prints a message describing the error and exits with code 2.

General errors

    type error =

`|` | `Error_io` | `(*` | Error on IOs | `*)`
`|` | `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. | `*)`
`|` | `Error_access` | `(*` | Access denied to a peripheral | `*)`
`|` | `Error_no_device` | `(*` | No such device (it may have been disconnected) | `*)`
`|` | `Error_not_found` | `(*` | Entity not found | `*)`
`|` | `Error_busy` | `(*` | Resource busy | `*)`
`|` | `Error_timeout` | `(*` | Operation timed out | `*)`
`|` | `Error_overflow` | `(*` | Overflow | `*)`
`|` | `Error_pipe` | `(*` | Pipe error | `*)`
`|` | `Error_interrupted` | `(*` | System call interrupted (perhaps due to signal) | `*)`
`|` | `Error_no_mem` | `(*` | Insufficient memory | `*)`
`|` | `Error_not_supported` | `(*` | Operation not supported or unimplemented on this platform | `*)`
`|` | `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 =

`|` | `In`
`|` | `Out`

A USB endpoint direction

    type endpoint = int

A USB endpoint number

Miscellanies

    val init : unit Stdlib.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 : [ `error | `quiet | `verbose | `warning ] -> 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 `USB.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 = {

`` | `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. | `*)`
`` | `dd_device_class : `Class.t`;` | `(*` | USB-IF class code for the device. | `*)`
`` | `dd_device_sub_class : `int`;` | `(*` | USB-IF subclass code for the device, qualified by the `dd_device_class` value. | `*)`
`` | `dd_device_protocol : `int`;` | `(*` | USB-IF protocol code for the device, qualified by the `dd_device_class` and `dd_device_subclass` values. | `*)`
`` | `dd_max_packet_size : `int`;` | `(*` | Maximum packet size for endpoint 0. | `*)`
`` | `dd_vendor_id : `int`;` | `(*` | USB-IF vendor ID. | `*)`
`` | `dd_product_id : `int`;` | `(*` | USB-IF product ID. | `*)`
`` | `dd_device : `int`;` | `(*` | Device release number in binary-coded decimal. | `*)`
`` | `dd_index_manufacturer : `int`;` | `(*` | Index of string descriptor describing manufacturer. | `*)`
`` | `dd_index_product : `int`;` | `(*` | Index of string descriptor describing product. | `*)`
`` | `dd_index_serial_number : `int`;` | `(*` | Index of string descriptor containing device serial number. | `*)`
`` | `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 = {

`` | `ed_endpoint_address : `int`;` | `(*` | The address of the endpoint described by this descriptor. | `*)`
`` | `ed_attributes : `int`;` | `(*` | Attributes which apply to the endpoint when it is configured using the `cd_configuration_value`. | `*)`
`` | `ed_max_packet_size : `int`;` | `(*` | Maximum packet size this endpoint is capable of sending/receiving. | `*)`
`` | `ed_interval : `int`;` | `(*` | Interval for polling endpoint for data transfers. | `*)`
`` | `ed_refresh : `int`;` | `(*` | For audio devices only: the rate at which synchronization feedback is provided. | `*)`
`` | `ed_synch_address : `int`;` | `(*` | For audio devices only: the address if the synch endpoint. | `*)`

`}`

    type interface_descriptor = {

`` | `id_interface : `int`;` | `(*` | Number of this interface. | `*)`
`` | `id_alternate_setting : `int`;` | `(*` | Value used to select this alternate setting for this interface. | `*)`
`` | `id_interface_class : `Class.t`;` | `(*` | USB-IF class code for this interface. | `*)`
`` | `id_interface_sub_class : `int`;` | `(*` | USB-IF subclass code for this interface, qualified by the `id_interface_class` value. | `*)`
`` | `id_interface_protocol : `int`;` | `(*` | USB-IF protocol code for this interface, qualified by the `id_interface_class` and `id_interface_sub_class` values. | `*)`
`` | `id_index_interface : `int`;` | `(*` | Index of string descriptor describing this interface. | `*)`
`` | `id_endpoints : `endpoint_descriptor array`;` | `(*` | Array of endpoint descriptors. | `*)`

`}`

    type config_descriptor = {

`` | `cd_configuration_value : `int`;` | `(*` | Identifier value for this configuration | `*)`
`` | `cd_index_configuration : `int`;` | `(*` | Index of string descriptor describing this configuration. | `*)`
`` | `cd_attributes : `int`;` | `(*` | A bitmask, representing configuration characteristics. | `*)`
`` | `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. | `*)`
`` | `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 =

`|` | `Transfer_error` | `(*` | Transfer failed | `*)`
`|` | `Transfer_timed_out` | `(*` | Transfer timed out | `*)`
`|` | `Transfer_cancelled` | `(*` | Transfer was cancelled | `*)`
`|` | `Transfer_stall` | `(*` | For bulk/interrupt endpoints: halt condition detected (endpoint stalled). For control endpoints: control request not supported. | `*)`
`|` | `Transfer_no_device` | `(*` | Device was disconnected | `*)`
`|` | `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 =

`|` | `Iso_ok of `int`` | `(*` | The packet has been transfered successfully | `*)`
`|` | `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 =

`|` | `Device`
`|` | `Interface`
`|` | `Endpoint`
`|` | `Other`

    type request_type =

`|` | `Standard`
`|` | `Class`
`|` | `Vendor`
`|` | `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.

`recipient` : defaults to `Device`
`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.

`recipient` : defaults to `Device`
`request_type` : defaults to `Standard`

    module Request: sig .. end

Standard requests