usb-0.3.0.1: Communicate with USB devicesSource codeContentsIndex
System.USB.Descriptors
MaintainerBas van Dijk <v.dijk.bas@gmail.com>
Contents
Device descriptor
Querying device descriptors
Configuration descriptor
Querying configuration descriptors
Configuration attributes
Interface descriptor
Querying interface descriptors
Endpoint descriptor
Querying endpoint descriptors
Endpoint address
Endpoint attributes
Endpoint max packet size
String descriptors
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. The inclusion of string descriptors is optional. If a device does not support string descriptors, string reference fields must be reset to zero to indicate no string descriptor is available.

Synopsis
data DeviceDesc
deviceUSBSpecReleaseNumber :: DeviceDesc -> BCD4
deviceClass :: DeviceDesc -> Word8
deviceSubClass :: DeviceDesc -> Word8
deviceProtocol :: DeviceDesc -> Word8
deviceMaxPacketSize0 :: DeviceDesc -> Word8
deviceVendorId :: DeviceDesc -> VendorId
deviceProductId :: DeviceDesc -> ProductId
deviceReleaseNumber :: DeviceDesc -> BCD4
deviceManufacturerStrIx :: DeviceDesc -> StrIx
deviceProductStrIx :: DeviceDesc -> StrIx
deviceSerialNumberStrIx :: DeviceDesc -> StrIx
deviceNumConfigs :: DeviceDesc -> Word8
deviceConfigs :: DeviceDesc -> [ConfigDesc]
type BCD4 = (Int, Int, Int, Int)
type VendorId = Word16
type ProductId = Word16
data ConfigDesc
configValue :: ConfigDesc -> ConfigValue
configStrIx :: ConfigDesc -> StrIx
configAttribs :: ConfigDesc -> ConfigAttribs
configMaxPower :: ConfigDesc -> Word8
configNumInterfaces :: ConfigDesc -> Word8
configInterfaces :: ConfigDesc -> [Interface]
configExtra :: ConfigDesc -> ByteString
type Interface = [InterfaceDesc]
type ConfigAttribs = DeviceStatus
data DeviceStatus = DeviceStatus {
remoteWakeup :: Bool
selfPowered :: Bool
}
data InterfaceDesc
interfaceNumber :: InterfaceDesc -> InterfaceNumber
interfaceAltSetting :: InterfaceDesc -> InterfaceAltSetting
interfaceClass :: InterfaceDesc -> Word8
interfaceSubClass :: InterfaceDesc -> Word8
interfaceProtocol :: InterfaceDesc -> Word8
interfaceStrIx :: InterfaceDesc -> StrIx
interfaceEndpoints :: InterfaceDesc -> [EndpointDesc]
interfaceExtra :: InterfaceDesc -> ByteString
data EndpointDesc
endpointAddress :: EndpointDesc -> EndpointAddress
endpointAttribs :: EndpointDesc -> EndpointAttribs
endpointMaxPacketSize :: EndpointDesc -> MaxPacketSize
endpointInterval :: EndpointDesc -> Word8
endpointRefresh :: EndpointDesc -> Word8
endpointSynchAddress :: EndpointDesc -> Word8
endpointExtra :: EndpointDesc -> ByteString
data EndpointAddress = EndpointAddress {
endpointNumber :: Int
transferDirection :: TransferDirection
}
data TransferDirection
= Out
| In
type EndpointAttribs = TransferType
data TransferType
= Control
| Isochronous Synchronization Usage
| Bulk
| Interrupt
data Synchronization
= NoSynchronization
| Asynchronous
| Adaptive
| Synchronous
data Usage
= Data
| Feedback
| Implicit
data MaxPacketSize = MaxPacketSize {
maxPacketSize :: Size
transactionOpportunities :: TransactionOpportunities
}
data TransactionOpportunities
= Zero
| One
| Two
getLanguages :: DeviceHandle -> IO [LangId]
type LangId = (PrimaryLangId, SubLangId)
type PrimaryLangId = Word16
type SubLangId = Word16
type StrIx = Word8
getStrDesc :: DeviceHandle -> StrIx -> LangId -> Size -> IO String
getStrDescFirstLang :: DeviceHandle -> StrIx -> Size -> IO String
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.

show/hide Instances
Querying device descriptors
deviceUSBSpecReleaseNumber :: DeviceDesc -> BCD4Source
USB specification release number in binary-coded decimal.
deviceClass :: DeviceDesc -> Word8Source
USB-IF class code for the device.
deviceSubClass :: DeviceDesc -> Word8Source
USB-IF subclass code for the device, qualified by the deviceClass value.
deviceProtocol :: DeviceDesc -> Word8Source
USB-IF protocol code for the device, qualified by the deviceClass and deviceSubClass values.
deviceMaxPacketSize0 :: DeviceDesc -> Word8Source
Maximum packet size for endpoint 0.
deviceVendorId :: DeviceDesc -> VendorIdSource
USB-IF vendor ID.
deviceProductId :: DeviceDesc -> ProductIdSource
USB-IF product ID.
deviceReleaseNumber :: DeviceDesc -> BCD4Source
Device release number in binary-coded decimal.
deviceManufacturerStrIx :: DeviceDesc -> StrIxSource
Index of string descriptor describing manufacturer.
deviceProductStrIx :: DeviceDesc -> StrIxSource
Index of string descriptor describing product.
deviceSerialNumberStrIx :: DeviceDesc -> StrIxSource
Index of string descriptor containing device serial number.
deviceNumConfigs :: DeviceDesc -> Word8Source
Number of possible configurations.
deviceConfigs :: DeviceDesc -> [ConfigDesc]Source
List of configurations supported by the device.
type BCD4 = (Int, Int, Int, Int)Source
A decoded 16 bits Binary Coded Decimal using 4 bits for each digit.
For a database of USB vendors and products see the usb-id-database package at: http://hackage.haskell.org/package/usb-id-database
type VendorId = Word16Source
type ProductId = Word16Source
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.

show/hide Instances
Querying configuration descriptors
configValue :: ConfigDesc -> ConfigValueSource
Identifier value for the configuration.
configStrIx :: ConfigDesc -> StrIxSource
Index of string descriptor describing the configuration.
configAttribs :: ConfigDesc -> ConfigAttribsSource
Configuration characteristics.
configMaxPower :: ConfigDesc -> Word8Source
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 :: ConfigDesc -> Word8Source
Number of interfaces supported by the configuration.
configInterfaces :: ConfigDesc -> [Interface]Source
List of interfaces supported by the configuration. Note that the length of this list should equal configNumInterfaces.
configExtra :: ConfigDesc -> ByteStringSource
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
data DeviceStatus Source
Constructors
DeviceStatus
remoteWakeup :: BoolThe 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 :: BoolThe Self Powered field indicates whether the device is currently self-powered
show/hide Instances
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.

show/hide Instances
Querying interface descriptors
interfaceNumber :: InterfaceDesc -> InterfaceNumberSource
Number of the interface.
interfaceAltSetting :: InterfaceDesc -> InterfaceAltSettingSource
Value used to select the alternate setting for the interface.
interfaceClass :: InterfaceDesc -> Word8Source
USB-IF class code for the interface.
interfaceSubClass :: InterfaceDesc -> Word8Source
USB-IF subclass code for the interface, qualified by the interfaceClass value.
interfaceProtocol :: InterfaceDesc -> Word8Source
USB-IF protocol code for the interface, qualified by the interfaceClass and interfaceSubClass values.
interfaceStrIx :: InterfaceDesc -> StrIxSource
Index of string descriptor describing the interface.
interfaceEndpoints :: InterfaceDesc -> [EndpointDesc]Source
List of endpoints supported by the interface.
interfaceExtra :: InterfaceDesc -> ByteStringSource
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. All multiple-byte fields are represented in host-endian format.

show/hide Instances
Querying endpoint descriptors
endpointAddress :: EndpointDesc -> EndpointAddressSource
The address of the endpoint described by the descriptor.
endpointAttribs :: EndpointDesc -> EndpointAttribsSource
Attributes which apply to the endpoint when it is configured using the configValue.
endpointMaxPacketSize :: EndpointDesc -> MaxPacketSizeSource
Maximum packet size the endpoint is capable of sending/receiving.
endpointInterval :: EndpointDesc -> Word8Source
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 :: EndpointDesc -> Word8Source
For audio devices only: the rate at which synchronization feedback is provided.
endpointSynchAddress :: EndpointDesc -> Word8Source
For audio devices only: the address if the synch endpoint.
endpointExtra :: EndpointDesc -> ByteStringSource
Extra descriptors. If libusb encounters unknown endpoint descriptors, it will store them here, should you wish to parse them.
Endpoint address
data EndpointAddress Source
The address of an endpoint.
Constructors
EndpointAddress
endpointNumber :: IntMust be >= 0 and <= 15
transferDirection :: TransferDirection
show/hide Instances
data TransferDirection Source
The direction of data transfer relative to the host.
Constructors
OutOut transfer direction (host  device) used for writing.
InIn transfer direction (device  host) used for reading.
show/hide Instances
Endpoint attributes
type EndpointAttribs = TransferTypeSource
data TransferType Source
Constructors
Control
Isochronous Synchronization Usage
Bulk
Interrupt
show/hide Instances
data Synchronization Source
Constructors
NoSynchronization
Asynchronous
Adaptive
Synchronous
show/hide Instances
data Usage Source
Constructors
Data
Feedback
Implicit
show/hide Instances
Endpoint max packet size
data MaxPacketSize Source
Constructors
MaxPacketSize
maxPacketSize :: Size
transactionOpportunities :: TransactionOpportunities
show/hide Instances
data TransactionOpportunities Source
Number of additional transactions.
Constructors
Zero
One
Two
show/hide Instances
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 PrimaryLangId = Word16Source
type SubLangId = Word16Source
type StrIx = Word8Source

Type of indici of string descriptors.

Can be retrieved by all the *StrIx functions.

getStrDesc :: DeviceHandle -> StrIx -> LangId -> Size -> IO StringSource

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.

getStrDescFirstLang :: DeviceHandle -> StrIx -> Size -> IO StringSource

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.

Produced by Haddock version 2.6.0