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!

One-off transfers

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

Generic Status

Typeable * Status

type Rep Status

Control transfers

data ControlSetup

Setup for control transfers.

Constructors

ControlSetup

Fields

controlSetupRequestType :: !RequestType

The type of request.

controlSetupRecipient :: !Recipient

The recipient of the request.

controlSetupRequest :: !Request

The numeric request.

controlSetupValue :: !Value

The value.

controlSetupIndex :: !Index

The index.

Instances

Eq ControlSetup

Data ControlSetup

Read ControlSetup

Show ControlSetup

Generic ControlSetup

Typeable * ControlSetup

type Rep ControlSetup

data RequestType

The type of control requests.

Constructors

Standard

Standard requests are common to all USB device's.

Class

Class requests are common to classes of drivers. For example, all device's conforming to the HID class will have a common set of class specific requests. These will differ to a device conforming to the communications class and differ again to that of a device conforming to the mass storage class.

Vendor

These are requests which the USB device designer (you?) can assign. These are normally different from device to device, but this is all up to your implementation and imagination.

Instances

Enum RequestType

Eq RequestType

Data RequestType

Read RequestType

Show RequestType

Generic RequestType

Typeable * RequestType

type Rep RequestType

data Recipient

A common request can be directed to different recipients and based on the recipient perform different functions. A GetStatus Standard request for example, can be directed at the device, interface or endpoint. When directed to a device it returns flags indicating the status of remote wakeup and if the device is self powered. However if the same request is directed at the interface it always returns zero, or should it be directed at an endpoint will return the halt flag for the endpoint.

Constructors

ToDevice

Directed to the device.

ToInterface

Directed to the interface.

ToEndpoint

Directed to the endpoint.

ToOther

Directed to something other than the device, interface or endpoint.

Instances

Enum Recipient

Eq Recipient

Data Recipient

Read Recipient

Show Recipient

Generic Recipient

Typeable * Recipient

type Rep Recipient

type Request = Word8

The actual request code.

type Value = Word16

A potential additional parameter for the request.

(Host-endian)

type Index = Word16

A potential additional parameter for the request. Usually used as an index or offset.

(Host-endian)

control :: DeviceHandle -> ControlSetup -> 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 -> ControlSetup -> 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 -> ControlSetup -> 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 -> ControlSetup -> 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 -> ControlSetup -> 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

Arguments

:: DeviceHandle

-> EndpointAddress

Make sure transferDirection is set to In.

-> 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.
• NoDeviceException if the device has been disconnected.
• Another USBException.

writeBulk

Arguments

:: DeviceHandle

-> EndpointAddress

Make sure transferDirection is set to Out.

-> 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.
• NoDeviceException if the device has been disconnected.
• Another USBException.

Interrupt transfers

readInterrupt

Arguments

:: DeviceHandle

-> EndpointAddress

Make sure transferDirection is set to In.

-> 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.
• NoDeviceException if the device has been disconnected.
• Another USBException.

writeInterrupt

Arguments

:: DeviceHandle

-> EndpointAddress

Make sure transferDirection is set to Out.

-> 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.
• 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

Make sure transferDirection is set to In.

-> Vector Size

Sizes of isochronous packets to read.

-> Timeout

-> IO (Vector 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.
• NoDeviceException if the device has been disconnected.
• Another USBException.

writeIsochronous

Arguments

:: DeviceHandle

-> EndpointAddress

Make sure transferDirection is set to Out.

-> Vector ByteString

Isochronous packets to write.

-> Timeout

-> IO (Vector 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.
• NoDeviceException if the device has been disconnected.
• Another USBException.