usb-0.6.0.8: Communicate with USB devices

MaintainerBas van Dijk <v.dijk.bas@gmail.com>

System.USB.Descriptors

Contents

Description

USB devices report their attributes using descriptors. A descriptor is a data structure with a defined format. Using descriptors allows concise storage of the attributes of individual configurations because each configuration may reuse descriptors or portions of descriptors from other configurations that have the same characteristics. In this manner, the descriptors resemble individual data records in a relational database.

Where appropriate, descriptors contain references to string descriptors (StrIx) that provide textual information describing a descriptor in human-readable form. Note that the inclusion of string descriptors is optional.

Synopsis

Device descriptor

data DeviceDesc Source

A structure representing the standard USB device descriptor.

This descriptor is documented in section 9.6.1 of the USB 2.0 specification.

This structure can be retrieved by deviceDesc.

Constructors

DeviceDesc 

Fields

deviceUSBSpecReleaseNumber :: !ReleaseNumber

USB specification release number.

deviceClass :: !Word8

USB-IF class code for the device.

deviceSubClass :: !Word8

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

deviceProtocol :: !Word8

USB-IF protocol code for the device, qualified by the deviceClass and deviceSubClass values.

deviceMaxPacketSize0 :: !Word8

Maximum packet size for endpoint 0.

deviceVendorId :: !VendorId

USB-IF vendor ID.

deviceProductId :: !ProductId

USB-IF product ID.

deviceReleaseNumber :: !ReleaseNumber

Device release number.

deviceManufacturerStrIx :: !(Maybe StrIx)

Optional index of string descriptor describing manufacturer.

deviceProductStrIx :: !(Maybe StrIx)

Optional index of string descriptor describing product.

deviceSerialNumberStrIx :: !(Maybe StrIx)

Optional index of string descriptor containing device serial number.

deviceNumConfigs :: !Word8

Number of possible configurations.

deviceConfigs :: ![ConfigDesc]

List of configurations supported by the device.

For a database of USB vendors and products see the usb-id-database package at: http://hackage.haskell.org/package/usb-id-database

Configuration descriptor

data ConfigDesc Source

A structure representing the standard USB configuration descriptor.

This descriptor is documented in section 9.6.3 of the USB 2.0 specification.

This structure can be retrieved by deviceConfigs.

Constructors

ConfigDesc 

Fields

configValue :: !ConfigValue

Identifier value for the configuration.

configStrIx :: !(Maybe StrIx)

Optional index of string descriptor describing the configuration.

configAttribs :: !ConfigAttribs

Configuration characteristics.

configMaxPower :: !Word8

Maximum power consumption of the USB device from the bus in the configuration when the device is fully operational. Expressed in 2 mA units (i.e., 50 = 100 mA).

configNumInterfaces :: !Word8

Number of interfaces supported by the configuration.

configInterfaces :: ![Interface]

List of interfaces supported by the configuration. Note that the length of this list should equal configNumInterfaces.

configExtra :: !ByteString

Extra descriptors. If libusb encounters unknown configuration descriptors, it will store them here, should you wish to parse them.

type Interface = [InterfaceDesc]Source

An interface is represented as a list of alternate interface settings.

Configuration attributes

type ConfigAttribs = DeviceStatusSource

The USB 2.0 specification specifies that the configuration attributes only describe the device status.

data DeviceStatus Source

Constructors

DeviceStatus 

Fields

remoteWakeup :: !Bool

The Remote Wakeup field indicates whether the device is currently enabled to request remote wakeup. The default mode for devices that support remote wakeup is disabled.

selfPowered :: !Bool

The Self Powered field indicates whether the device is currently self-powered

Interface descriptor

data InterfaceDesc Source

A structure representing the standard USB interface descriptor.

This descriptor is documented in section 9.6.5 of the USB 2.0 specification.

This structure can be retrieved using configInterfaces.

Constructors

InterfaceDesc 

Fields

interfaceNumber :: !InterfaceNumber

Number of the interface.

interfaceAltSetting :: !InterfaceAltSetting

Value used to select the alternate setting for the interface.

interfaceClass :: !Word8

USB-IF class code for the interface.

interfaceSubClass :: !Word8

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

interfaceProtocol :: !Word8

USB-IF protocol code for the interface, qualified by the interfaceClass and interfaceSubClass values.

interfaceStrIx :: !(Maybe StrIx)

Optional index of string descriptor describing the interface.

interfaceEndpoints :: ![EndpointDesc]

List of endpoints supported by the interface.

interfaceExtra :: !ByteString

Extra descriptors. If libusb encounters unknown interface descriptors, it will store them here, should you wish to parse them.

Endpoint descriptor

data EndpointDesc Source

A structure representing the standard USB endpoint descriptor.

This descriptor is documented in section 9.6.3 of the USB 2.0 specification.

This structure can be retrieved by using interfaceEndpoints.

Constructors

EndpointDesc 

Fields

endpointAddress :: !EndpointAddress

The address of the endpoint described by the descriptor.

endpointAttribs :: !EndpointAttribs

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

endpointMaxPacketSize :: !MaxPacketSize

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

endpointInterval :: !Word8

Interval for polling endpoint for data transfers. Expressed in frames or microframes depending on the device operating speed (i.e., either 1 millisecond or 125 μs units).

endpointRefresh :: !Word8

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

endpointSynchAddress :: !Word8

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

endpointExtra :: !ByteString

Extra descriptors. If libusb encounters unknown endpoint descriptors, it will store them here, should you wish to parse them.

Endpoint address

data TransferDirection Source

The direction of data transfer relative to the host.

Constructors

Out

Out transfer direction (host -> device) used for writing.

In

In transfer direction (device -> host) used for reading.

Endpoint attributes

type EndpointAttribs = TransferTypeSource

The USB 2.0 specification specifies that the endpoint attributes only describe the endpoint transfer type.

data TransferType Source

Describes what types of transfers are allowed on the endpoint.

Constructors

Control

Control transfers are typically used for command and status operations.

Isochronous !Synchronization !Usage

Isochronous transfers occur continuously and periodically.

Bulk

Bulk transfers can be used for large bursty data.

Interrupt

Interrupt transfers are typically non-periodic, small device "initiated" communication requiring bounded latency.

Isochronous transfer attributes

Endpoint max packet size

String descriptors

getLanguages :: DeviceHandle -> IO [LangId]Source

Retrieve a list of supported languages.

This function may throw USBExceptions.

type LangId = (PrimaryLangId, SubLangId)Source

The language ID consists of the primary language identifier and the sublanguage identififier as described in:

http://www.usb.org/developers/docs/USB_LANGIDs.pdf

For a mapping between IDs and languages see the usb-id-database package at:

http://hackage.haskell.org/package/usb-id-database

To see which LangIds are supported by a device see getLanguages.

type StrIx = Word8Source

Type of indici of string descriptors.

Can be retrieved by all the *StrIx functions.

getStrDescSource

Arguments

:: DeviceHandle 
-> StrIx 
-> LangId 
-> Int

Maximum number of characters in the requested string. An IOException will be thrown when the requested string is larger than this number.

-> IO String 

Retrieve a string descriptor from a device.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor. The string returned is Unicode, as detailed in the USB specifications.

This function may throw USBExceptions.

getStrDescFirstLangSource

Arguments

:: DeviceHandle 
-> StrIx 
-> Int

Maximum number of characters in the requested string. An IOException will be thrown when the requested string is larger than this number.

-> IO String 

Retrieve a string descriptor from a device using the first supported language.

This is a convenience function which formulates the appropriate control message to retrieve the descriptor. The string returned is Unicode, as detailed in the USB specifications.

This function may throw USBExceptions.