System.USB.IO

This module provides functions for performing control, bulk and interrupt transfers.

When your system supports the GHC EventManager this module additionally exports functions for performing isochronous transfers. These are currently not available on Windows.

WARNING: You need to enable the threaded runtime (-threaded) when using the isochronous functions. They throw a runtime error otherwise!

Documentation

type ReadAction = Size -> Timeout -> IO (ByteString, Status)

Handy type synonym for read transfers.

A ReadAction is a function which takes a Size which defines how many bytes to read and a Timeout. The function returns an IO action which, when executed, performs the actual read and returns the ByteString that was read paired with a Status flag which indicates whether the transfer Completed or TimedOut.

type ReadExactAction = Size -> Timeout -> IO ByteString

Handy type synonym for read transfers that must exactly read the specified number of bytes. An incompleteReadException is thrown otherwise.

type WriteAction = ByteString -> Timeout -> IO (Size, Status)

Handy type synonym for write transfers.

A WriteAction is a function which takes a ByteString to write and a Timeout. The function returns an IO action which, when exectued, returns the number of bytes that were actually written paired with a Status flag which indicates whether the transfer Completed or TimedOut.

type WriteExactAction = ByteString -> Timeout -> IO ()

Handy type synonym for write transfers that must exactly write all the given bytes. An incompleteWriteException is thrown otherwise.

type Size = Int

Number of bytes transferred.

type Timeout = Int

A timeout in milliseconds. A timeout defines how long a transfer should wait before giving up due to no response being received. Use noTimeout for no timeout.

noTimeout :: Timeout

A timeout of 0 denotes no timeout so: noTimeout = 0.

data Status

Status of a terminated transfer.

Constructors

Completed

All bytes were transferred within the maximum allowed Timeout period.

TimedOut

Not all bytes were transferred within the maximum allowed Timeout period.

Instances

Eq Status

Data Status

Read Status

Show Status

Typeable Status

Control transfers

type ControlAction α = RequestType -> Recipient -> Request -> Value -> Index -> α

Handy type synonym that names the parameters of a control transfer.

data RequestType

Constructors

Standard

Class

Vendor

Instances

Enum RequestType

Eq RequestType

Data RequestType

Read RequestType

Show RequestType

Typeable RequestType

data Recipient

Constructors

ToDevice

ToInterface

ToEndpoint

ToOther

Instances

Enum Recipient

Eq Recipient

Data Recipient

Read Recipient

Show Recipient

Typeable Recipient

type Request = Word8

type Value = Word16

(Host-endian)

type Index = Word16

(Host-endian)

control :: DeviceHandle -> ControlAction (Timeout -> IO ())

Perform a USB control request that does not transfer data.

Exceptions:

• TimeoutException if the transfer timed out.
• PipeException if the control request was not supported by the device
• NoDeviceException if the device has been disconnected.
• Another USBException.

readControl :: DeviceHandle -> ControlAction ReadAction

Perform a USB control read.

Exceptions:

• PipeException if the control request was not supported by the device
• NoDeviceException if the device has been disconnected.
• Another USBException.

readControlExact :: DeviceHandle -> ControlAction ReadExactAction

A convenience function similar to readControl which checks if the specified number of bytes to read were actually read. Throws an incompleteReadException if this is not the case.

writeControl :: DeviceHandle -> ControlAction WriteAction

Perform a USB control write.

Exceptions:

• PipeException if the control request was not supported by the device
• NoDeviceException if the device has been disconnected.
• Another USBException.

writeControlExact :: DeviceHandle -> ControlAction WriteExactAction

A convenience function similar to writeControl which checks if the given bytes were actually fully written. Throws an incompleteWriteException if this is not the case.

Bulk transfers

readBulk :: DeviceHandle -> EndpointAddress -> ReadAction

Perform a USB bulk read.

Exceptions:

• PipeException if the endpoint halted.
• OverflowException if the device offered more data, see Packets and overflows in the libusb documentation: http://libusb.sourceforge.net/api-1.0/packetoverflow.html.
• NoDeviceException if the device has been disconnected.
• Another USBException.

writeBulk :: DeviceHandle -> EndpointAddress -> WriteAction

Perform a USB bulk write.

Exceptions:

• PipeException if the endpoint halted.
• OverflowException if the device offered more data, see Packets and overflows in the libusb documentation: http://libusb.sourceforge.net/api-1.0/packetoverflow.html.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Interrupt transfers

readInterrupt :: DeviceHandle -> EndpointAddress -> ReadAction

Perform a USB interrupt read.

Exceptions:

• PipeException if the endpoint halted.
• OverflowException if the device offered more data, see Packets and overflows in the libusb documentation: http://libusb.sourceforge.net/api-1.0/packetoverflow.html.
• NoDeviceException if the device has been disconnected.
• Another USBException.

writeInterrupt :: DeviceHandle -> EndpointAddress -> WriteAction

Perform a USB interrupt write.

Exceptions:

• PipeException if the endpoint halted.
• OverflowException if the device offered more data, see Packets and overflows in the libusb documentation: http://libusb.sourceforge.net/api-1.0/packetoverflow.html.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Isochronous transfers

WARNING: You need to enable the threaded runtime (-threaded) when using the isochronous functions. They throw a runtime error otherwise!

readIsochronous

Arguments

:: DeviceHandle

-> EndpointAddress

-> [Size]

Sizes of isochronous packets

-> Timeout

-> IO [ByteString]

Perform a USB isochronous read.

WARNING: You need to enable the threaded runtime (-threaded) for this function to work correctly. It throws a runtime error otherwise!

Exceptions:

• PipeException if the endpoint halted.
• OverflowException if the device offered more data, see Packets and overflows in the libusb documentation: http://libusb.sourceforge.net/api-1.0/packetoverflow.html.
• NoDeviceException if the device has been disconnected.
• Another USBException.

writeIsochronous :: DeviceHandle -> EndpointAddress -> [ByteString] -> Timeout -> IO [Size]

Perform a USB isochronous write.

WARNING: You need to enable the threaded runtime (-threaded) for this function to work correctly. It throws a runtime error otherwise!

Exceptions:

• PipeException if the endpoint halted.
• OverflowException if the device offered more data, see Packets and overflows in the libusb documentation: http://libusb.sourceforge.net/api-1.0/packetoverflow.html.
• NoDeviceException if the device has been disconnected.
• Another USBException.