-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Communicate with USB devices -- -- This library enables you to communicate with USB devices from -- userspace. It is implemented as a high-level wrapper around -- bindings-libusb which is a low-level binding to the C library: -- libusb-1.*. @package usb @version 0.3 module System.USB.Exceptions -- | Type of USB exceptions. data USBException -- | Input/output exception. IOException :: USBException -- | Invalid parameter. InvalidParamException :: USBException -- | Access denied (insufficient permissions). AccessException :: USBException -- | No such device (it may have been disconnected). NoDeviceException :: USBException -- | Entity not found. NotFoundException :: USBException -- | Resource busy. BusyException :: USBException -- | Operation timed out. TimeoutException :: USBException -- | Overflow. OverflowException :: USBException -- | Pipe exception. PipeException :: USBException -- | System call interrupted (perhaps due to signal). InterruptedException :: USBException -- | Insufficient memory. NoMemException :: USBException -- | Operation not supported or unimplemented on this platform. NotSupportedException :: USBException -- | Other exception. OtherException :: USBException -- | 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. module System.USB.Descriptors -- | 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. data DeviceDesc -- | USB specification release number in binary-coded decimal. deviceUSBSpecReleaseNumber :: DeviceDesc -> BCD4 -- | USB-IF class code for the device. deviceClass :: DeviceDesc -> Word8 -- | USB-IF subclass code for the device, qualified by the -- deviceClass value. deviceSubClass :: DeviceDesc -> Word8 -- | USB-IF protocol code for the device, qualified by the -- deviceClass and deviceSubClass values. deviceProtocol :: DeviceDesc -> Word8 -- | Maximum packet size for endpoint 0. deviceMaxPacketSize0 :: DeviceDesc -> Word8 -- | USB-IF vendor ID. deviceVendorId :: DeviceDesc -> VendorId -- | USB-IF product ID. deviceProductId :: DeviceDesc -> ProductId -- | Device release number in binary-coded decimal. deviceReleaseNumber :: DeviceDesc -> BCD4 -- | Index of string descriptor describing manufacturer. deviceManufacturerStrIx :: DeviceDesc -> StrIx -- | Index of string descriptor describing product. deviceProductStrIx :: DeviceDesc -> StrIx -- | Index of string descriptor containing device serial number. deviceSerialNumberStrIx :: DeviceDesc -> StrIx -- | Number of possible configurations. deviceNumConfigs :: DeviceDesc -> Word8 -- | List of configurations supported by the device. deviceConfigs :: DeviceDesc -> [ConfigDesc] -- | A decoded 16 bits Binary Coded Decimal using 4 bits for each digit. type BCD4 = (Int, Int, Int, Int) type VendorId = Word16 type ProductId = Word16 -- | 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. data ConfigDesc -- | Identifier value for the configuration. configValue :: ConfigDesc -> ConfigValue -- | Index of string descriptor describing the configuration. configStrIx :: ConfigDesc -> StrIx -- | Configuration characteristics. configAttribs :: ConfigDesc -> ConfigAttribs -- | 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). configMaxPower :: ConfigDesc -> Word8 -- | Number of interfaces supported by the configuration. configNumInterfaces :: ConfigDesc -> Word8 -- | List of interfaces supported by the configuration. Note that the -- length of this list should equal configNumInterfaces. configInterfaces :: ConfigDesc -> [Interface] -- | Extra descriptors. If libusb encounters unknown configuration -- descriptors, it will store them here, should you wish to parse them. configExtra :: ConfigDesc -> ByteString -- | An interface is represented as a list of alternate interface settings. type Interface = [InterfaceDesc] type ConfigAttribs = DeviceStatus data DeviceStatus DeviceStatus :: Bool -> Bool -> DeviceStatus -- | 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. remoteWakeup :: DeviceStatus -> Bool -- | The Self Powered field indicates whether the device is currently -- self-powered selfPowered :: DeviceStatus -> Bool -- | 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. data InterfaceDesc -- | Number of the interface. interfaceNumber :: InterfaceDesc -> InterfaceNumber -- | Value used to select the alternate setting for the interface. interfaceAltSetting :: InterfaceDesc -> InterfaceAltSetting -- | USB-IF class code for the interface. interfaceClass :: InterfaceDesc -> Word8 -- | USB-IF subclass code for the interface, qualified by the -- interfaceClass value. interfaceSubClass :: InterfaceDesc -> Word8 -- | USB-IF protocol code for the interface, qualified by the -- interfaceClass and interfaceSubClass values. interfaceProtocol :: InterfaceDesc -> Word8 -- | Index of string descriptor describing the interface. interfaceStrIx :: InterfaceDesc -> StrIx -- | List of endpoints supported by the interface. interfaceEndpoints :: InterfaceDesc -> [EndpointDesc] -- | Extra descriptors. If libusb encounters unknown interface descriptors, -- it will store them here, should you wish to parse them. interfaceExtra :: InterfaceDesc -> ByteString -- | 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. data EndpointDesc -- | The address of the endpoint described by the descriptor. endpointAddress :: EndpointDesc -> EndpointAddress -- | Attributes which apply to the endpoint when it is configured using the -- configValue. endpointAttribs :: EndpointDesc -> EndpointAttribs -- | Maximum packet size the endpoint is capable of sending/receiving. endpointMaxPacketSize :: EndpointDesc -> MaxPacketSize -- | 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). endpointInterval :: EndpointDesc -> Word8 -- | For audio devices only: the rate at which synchronization -- feedback is provided. endpointRefresh :: EndpointDesc -> Word8 -- | For audio devices only: the address if the synch endpoint. endpointSynchAddress :: EndpointDesc -> Word8 -- | Extra descriptors. If libusb encounters unknown endpoint descriptors, -- it will store them here, should you wish to parse them. endpointExtra :: EndpointDesc -> ByteString -- | The address of an endpoint. data EndpointAddress EndpointAddress :: Int -> TransferDirection -> EndpointAddress -- | Must be >= 0 and <= 15 endpointNumber :: EndpointAddress -> Int transferDirection :: EndpointAddress -> TransferDirection -- | The direction of data transfer relative to the host. data TransferDirection -- | Out transfer direction (host -> device) used for writing. Out :: TransferDirection -- | In transfer direction (device -> host) used for reading. In :: TransferDirection type EndpointAttribs = TransferType data TransferType Control :: TransferType Isochronous :: Synchronization -> Usage -> TransferType Bulk :: TransferType Interrupt :: TransferType data Synchronization NoSynchronization :: Synchronization Asynchronous :: Synchronization Adaptive :: Synchronization Synchronous :: Synchronization data Usage Data :: Usage Feedback :: Usage Implicit :: Usage data MaxPacketSize MaxPacketSize :: Size -> TransactionOpportunities -> MaxPacketSize maxPacketSize :: MaxPacketSize -> Size transactionOpportunities :: MaxPacketSize -> TransactionOpportunities -- | Number of additional transactions. data TransactionOpportunities Zero :: TransactionOpportunities One :: TransactionOpportunities Two :: TransactionOpportunities -- | Retrieve a list of supported languages. -- -- This function may throw USBExceptions. getLanguages :: DeviceHandle -> IO [LangId] -- | 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 LangId = (PrimaryLangId, SubLangId) type PrimaryLangId = Word16 type SubLangId = Word16 -- | Type of indici of string descriptors. -- -- Can be retrieved by all the *StrIx functions. type StrIx = Word8 -- | 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. getStrDesc :: DeviceHandle -> StrIx -> LangId -> Size -> 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. getStrDescFirstLang :: DeviceHandle -> StrIx -> Size -> IO String -- | The module provides functionality for opening, closing and configuring -- a USB devices. module System.USB.DeviceHandling -- | Abstract type representing a handle on a USB device, usually -- originating from openDevice. -- -- A device handle is used to perform I/O and other operations. When -- finished with a device handle, you should close it by applying -- closeDevice to it. data DeviceHandle -- | Open a device and obtain a device handle. -- -- A handle allows you to perform I/O on the device in question. -- -- This is a non-blocking function; no requests are sent over the bus. -- -- It is advised to use withDeviceHandle because it automatically -- closes the device when the computation terminates. -- -- Exceptions: -- -- openDevice :: Device -> IO DeviceHandle -- | Close a device handle. -- -- Should be called on all open handles before your application exits. -- -- This is a non-blocking function; no requests are sent over the bus. closeDevice :: DeviceHandle -> IO () -- | withDeviceHandle dev act opens the Device dev -- and passes the resulting handle to the computation act. The -- handle will be closed on exit from withDeviceHandle whether -- by normal termination or by raising an exception. withDeviceHandle :: Device -> (DeviceHandle -> IO a) -> IO a -- | Retrieve the Device from the DeviceHandle. getDevice :: DeviceHandle -> Device -- | Identifier for configurations. -- -- Can be retrieved by getConfig or by configValue. type ConfigValue = Word8 -- | Determine the bConfigurationValue of the currently active -- configuration. -- -- You could formulate your own control request to obtain this -- information, but this function has the advantage that it may be able -- to retrieve the information from operating system caches (no I/O -- involved). -- -- If the OS does not cache this information, then this function will -- block while a control transfer is submitted to retrieve the -- information. -- -- This function will return a value of 0 if the device is in -- unconfigured state. -- -- Exceptions: -- -- getConfig :: DeviceHandle -> IO ConfigValue -- | Set the active configuration for a device. -- -- The operating system may or may not have already set an active -- configuration on the device. It is up to your application to ensure -- the correct configuration is selected before you attempt to claim -- interfaces and perform other operations. -- -- If you call this function on a device already configured with the -- selected configuration, then this function will act as a lightweight -- device reset: it will issue a SET_CONFIGURATION request using the -- current configuration, causing most USB-related device state to be -- reset (altsetting reset to zero, endpoint halts cleared, toggles -- reset). -- -- You cannot change/reset configuration if your application has claimed -- interfaces - you should free them with releaseInterface first. -- You cannot change/reset configuration if other applications or drivers -- have claimed interfaces. -- -- A configuration value of -1 will put the device in unconfigured state. -- The USB specifications state that a configuration value of 0 does -- this, however buggy devices exist which actually have a configuration -- 0. -- -- You should always use this function rather than formulating your own -- SET_CONFIGURATION control request. This is because the underlying -- operating system needs to know when such changes happen. -- -- This is a blocking function. -- -- Exceptions: -- -- setConfig :: DeviceHandle -> ConfigValue -> IO () -- | Identifier for interfaces. -- -- Can be retrieved by interfaceNumber. type InterfaceNumber = Word8 -- | 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 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. -- -- This is a non-blocking function. -- -- Exceptions: -- -- claimInterface :: DeviceHandle -> InterfaceNumber -> IO () -- | Release an interface previously claimed with claimInterface. -- -- 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. -- -- Exceptions: -- -- releaseInterface :: DeviceHandle -> InterfaceNumber -> IO () -- | withClaimedInterface claims the interface on the given device -- handle then executes the given computation. On exit from -- withClaimedInterface, the interface is released whether by -- normal termination or by raising an exception. withClaimedInterface :: DeviceHandle -> InterfaceNumber -> IO a -> IO a -- | Identifier for interface alternate settings. -- -- Can be retrieved by interfaceAltSetting. type InterfaceAltSetting = Word8 -- | Activate an alternate setting for an interface. -- -- The interface must have been previously claimed with -- claimInterface or withInterfaceHandle. -- -- You should always use this function rather than formulating your own -- SET_INTERFACE control request. This is because the underlying -- operating system needs to know when such changes happen. -- -- This is a blocking function. -- -- Exceptions: -- -- setInterfaceAltSetting :: DeviceHandle -> InterfaceNumber -> InterfaceAltSetting -> IO () -- | 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. -- -- This is a blocking function. -- -- Exceptions: -- -- clearHalt :: DeviceHandle -> EndpointAddress -> IO () -- | Perform a USB port reset to reinitialize a device. -- -- The system will attempt to restore the previous configuration and -- alternate settings after the reset has completed. -- -- If the reset fails, the descriptors change, or the previous state -- cannot be restored, the device will appear to be disconnected and -- reconnected. This means that the device handle is no longer valid (you -- should close it) and rediscover the device. A NotFoundException -- is raised to indicate that this is the case. -- -- This is a blocking function which usually incurs a noticeable delay. -- -- Exceptions: -- -- resetDevice :: DeviceHandle -> IO () -- | 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. -- -- Exceptions: -- -- kernelDriverActive :: DeviceHandle -> InterfaceNumber -> IO Bool -- | Detach a kernel driver from an interface. -- -- If successful, you will then be able to claim the interface and -- perform I/O. -- -- Exceptions: -- -- detachKernelDriver :: DeviceHandle -> InterfaceNumber -> IO () -- | Re-attach an interface's kernel driver, which was previously detached -- using detachKernelDriver. -- -- Exceptions: -- -- attachKernelDriver :: DeviceHandle -> InterfaceNumber -> IO () -- | If a kernel driver is active on the specified interface the driver is -- detached and the given action is executed. If the action terminates, -- whether by normal termination or by raising an exception, the kernel -- driver is attached again. If a kernel driver is not active on the -- specified interface the action is just executed. -- -- Exceptions: -- -- withDetachedKernelDriver :: DeviceHandle -> InterfaceNumber -> IO a -> IO a -- | This module provides functionality for enumerating the USB devices -- currently attached to the system. module System.USB.Enumeration -- | Abstract type representing a USB device detected on the system, -- usually originating from getDevices. -- -- Certain operations can be performed on a device, but in order to do -- any I/O you will have to first obtain a DeviceHandle using -- openDevice. Alternatively you can use the usb-safe -- package which provides type-safe device handling. See: -- -- http://hackage.haskell.org/package/usb-safe -- -- Just because you have a reference to a device does not mean it is -- necessarily usable. The device may have been unplugged, you may not -- have permission to operate such device, or another program or driver -- may be using the device. -- -- To get additional information about a device you can retrieve its -- descriptor using deviceDesc. data Device -- | Returns a list of USB devices currently attached to the system. -- -- This is your entry point into finding a USB device to operate. -- -- Exceptions: -- -- getDevices :: Ctx -> IO [Device] -- | Get the number of the bus that a device is connected to. busNumber :: Device -> Word8 -- | Get the address of the device on the bus it is connected to. deviceAddress :: Device -> Word8 -- | Get the USB device descriptor for a given device. deviceDesc :: Device -> DeviceDesc -- | This module provides functionality for initializing this usb -- library. module System.USB.Initialization -- | Abstract type representing a USB session. -- -- The concept of individual sessions allows your program to use multiple -- threads that can independently use this library without interfering -- with eachother. -- -- Sessions are created and initialized by newCtx and are -- automatically closed when garbage collected. -- -- The only functions that receive a Ctx are setDebug and -- getDevices. data Ctx -- | Create and initialize a new USB context. -- -- This function may throw USBExceptions. newCtx :: IO Ctx -- | Set message verbosity. -- -- The default level is PrintNothing, which means no messages are -- ever printed. If you choose to increase the message verbosity level, -- ensure that your application does not close the stdout/stderr file -- descriptors. -- -- You are advised to set level PrintWarnings. libusb is -- conservative with its message logging and most of the time, will only -- log messages that explain error conditions and other oddities. This -- will help you debug your software. -- -- If the LIBUSB_DEBUG environment variable was set when libusb was -- initialized, this function does nothing: the message verbosity is -- fixed to the value in the environment variable. -- -- If libusb was compiled without any message logging, this function does -- nothing: you'll never get any messages. -- -- If libusb was compiled with verbose debug message logging, this -- function does nothing: you'll always get messages from all levels. setDebug :: Ctx -> Verbosity -> IO () -- | Message verbosity data Verbosity -- | No messages are ever printed by the library PrintNothing :: Verbosity -- | Error messages are printed to stderr PrintErrors :: Verbosity -- | Warning and error messages are printed to stderr PrintWarnings :: Verbosity -- | Informational messages are printed to stdout, warning and error -- messages are printed to stderr PrintInfo :: Verbosity -- | Experimental enumerators for endpoints. module System.USB.IO.Synchronous.Enumerator enumReadBulk :: (ReadableChunk s el, MonadCatchIO m) => DeviceHandle -> EndpointAddress -> Timeout -> Size -> EnumeratorGM s el m a enumReadInterrupt :: (ReadableChunk s el, MonadCatchIO m) => DeviceHandle -> EndpointAddress -> Timeout -> Size -> EnumeratorGM s el m a module System.USB.IO.Synchronous -- | Handy type synonym for read transfers. -- -- A ReadAction is a function which takes a Timeout and a -- Size which defines how many bytes to read. The function returns -- an IO action which, when executed, performs the actual read and -- returns the ByteString that was read paired with an indication -- if the transfer timed out. type ReadAction = Timeout -> Size -> IO (ByteString, Bool) -- | Handy type synonym for write transfers. -- -- A WriteAction is a function which takes a Timeout and -- the ByteString to write. The function returns an IO -- action which, when exectued, returns the number of bytes that were -- actually written paired with an indication if the transfer timed out. type WriteAction = Timeout -> ByteString -> IO (Size, Bool) -- | A timeout in millseconds. A timeout defines how long a transfer should -- wait before giving up due to no response being received. For no -- timeout, use value 0. type Timeout = Int -- | Number of bytes transferred. type Size = Int data RequestType Standard :: RequestType Class :: RequestType Vendor :: RequestType data Recipient ToDevice :: Recipient ToInterface :: Recipient ToEndpoint :: Recipient ToOther :: Recipient -- | Perform a USB control request that does not transfer data. -- -- The value and index values should be given in -- host-endian byte order. -- -- Exceptions: -- -- control :: DeviceHandle -> RequestType -> Recipient -> Word8 -> Word16 -> Word16 -> Timeout -> IO () -- | Perform a USB control read. -- -- The value and index values should be given in -- host-endian byte order. -- -- Exceptions: -- -- readControl :: DeviceHandle -> RequestType -> Recipient -> Word8 -> Word16 -> Word16 -> ReadAction -- | Perform a USB control write. -- -- The value and index values should be given in -- host-endian byte order. -- -- Exceptions: -- -- writeControl :: DeviceHandle -> RequestType -> Recipient -> Word8 -> Word16 -> Word16 -> WriteAction -- | See: USB 2.0 Spec. section 9.4.9 setHalt :: DeviceHandle -> EndpointAddress -> Timeout -> IO () -- | See: USB 2.0 Spec. section 9.4.1 clearRemoteWakeup :: DeviceHandle -> Timeout -> IO () -- | See: USB 2.0 Spec. section 9.4.9 setRemoteWakeup :: DeviceHandle -> Timeout -> IO () -- | See: USB 2.0 Spec. section 9.4.9 TODO: What about vendor-specific test -- modes? setStandardTestMode :: DeviceHandle -> TestMode -> Timeout -> IO () -- | See: USB 2.0 Spec. table 9-7 data TestMode Test_J :: TestMode Test_K :: TestMode Test_SE0_NAK :: TestMode Test_Packet :: TestMode Test_Force_Enable :: TestMode -- | See: USB 2.0 Spec. section 9.4.4 getInterfaceAltSetting :: DeviceHandle -> InterfaceNumber -> Timeout -> IO InterfaceAltSetting -- | See: USB 2.0 Spec. section 9.4.5 getDeviceStatus :: DeviceHandle -> Timeout -> IO DeviceStatus -- | See: USB 2.0 Spec. section 9.4.5 getEndpointStatus :: DeviceHandle -> EndpointAddress -> Timeout -> IO Bool -- | See: USB 2.0 Spec. section 9.4.6 setDeviceAddress :: DeviceHandle -> Word16 -> Timeout -> IO () -- | See: USB 2.0 Spec. section 9.4.11 synchFrame :: DeviceHandle -> EndpointAddress -> Timeout -> IO Int -- | Perform a USB bulk read. -- -- Exceptions: -- -- readBulk :: DeviceHandle -> EndpointAddress -> ReadAction -- | Perform a USB bulk write. -- -- Exceptions: -- -- writeBulk :: DeviceHandle -> EndpointAddress -> WriteAction -- | Perform a USB interrupt read. -- -- Exceptions: -- -- readInterrupt :: DeviceHandle -> EndpointAddress -> ReadAction -- | Perform a USB interrupt write. -- -- Exceptions: -- -- writeInterrupt :: DeviceHandle -> EndpointAddress -> WriteAction -- | This library allows you to communicate with USB devices from -- userspace. It is implemented as a high-level wrapper around -- bindings-libusb which is a low-level binding to the C -- library: libusb-1.*. -- -- This documentation assumes knowledge of how to operate USB devices -- from a software standpoint (descriptors, configurations, interfaces, -- endpoints, control/bulk/interrupt/isochronous transfers, etc). Full -- information can be found in the USB 2.0 Specification. -- -- For an example how to use this library see the ls-usb package -- at: -- -- http://hackage.haskell.org/package/ls-usb -- -- Also see the usb-safe package which wraps this packages and -- provides some strong safety guarantees for working with USB devices. -- -- http://hackage.haskell.org/package/usb-safe -- -- Besides this API documentation the following sources might be -- interesting: -- -- module System.USB