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

Methods

(==) :: Status -> Status -> Bool

(/=) :: Status -> Status -> Bool

Data Status

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Status -> c Status

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Status

toConstr :: Status -> Constr

dataTypeOf :: Status -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c Status)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Status)

gmapT :: (forall b. Data b => b -> b) -> Status -> Status

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Status -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Status -> r

gmapQ :: (forall d. Data d => d -> u) -> Status -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Status -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Status -> m Status

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Status -> m Status

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Status -> m Status

Read Status

Methods

readsPrec :: Int -> ReadS Status

readList :: ReadS [Status]

readPrec :: ReadPrec Status

readListPrec :: ReadPrec [Status]

Show Status

Methods

showsPrec :: Int -> Status -> ShowS

show :: Status -> String

showList :: [Status] -> ShowS

Generic Status

Associated Types

type Rep Status :: * -> *

Methods

from :: Status -> Rep Status x

to :: Rep Status x -> Status

type Rep Status

type Rep Status = D1 * (MetaData "Status" "System.USB.Base" "usb-1.3.0.6-BxALn33Tmsa87zdhZNpf2H" False) ((:+:) * (C1 * (MetaCons "Completed" PrefixI False) (U1 *)) (C1 * (MetaCons "TimedOut" PrefixI False) (U1 *)))

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

Methods

(==) :: ControlSetup -> ControlSetup -> Bool

(/=) :: ControlSetup -> ControlSetup -> Bool

Data ControlSetup

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ControlSetup -> c ControlSetup

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ControlSetup

toConstr :: ControlSetup -> Constr

dataTypeOf :: ControlSetup -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c ControlSetup)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ControlSetup)

gmapT :: (forall b. Data b => b -> b) -> ControlSetup -> ControlSetup

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ControlSetup -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ControlSetup -> r

gmapQ :: (forall d. Data d => d -> u) -> ControlSetup -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> ControlSetup -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> ControlSetup -> m ControlSetup

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ControlSetup -> m ControlSetup

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ControlSetup -> m ControlSetup

Read ControlSetup

Methods

readsPrec :: Int -> ReadS ControlSetup

readList :: ReadS [ControlSetup]

readPrec :: ReadPrec ControlSetup

readListPrec :: ReadPrec [ControlSetup]

Show ControlSetup

Methods

showsPrec :: Int -> ControlSetup -> ShowS

show :: ControlSetup -> String

showList :: [ControlSetup] -> ShowS

Generic ControlSetup

Associated Types

type Rep ControlSetup :: * -> *

Methods

from :: ControlSetup -> Rep ControlSetup x

to :: Rep ControlSetup x -> ControlSetup

type Rep ControlSetup

type Rep ControlSetup = D1 * (MetaData "ControlSetup" "System.USB.Base" "usb-1.3.0.6-BxALn33Tmsa87zdhZNpf2H" False) (C1 * (MetaCons "ControlSetup" PrefixI True) ((:*:) * ((:*:) * (S1 * (MetaSel (Just Symbol "controlSetupRequestType") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * RequestType)) (S1 * (MetaSel (Just Symbol "controlSetupRecipient") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * Recipient))) ((:*:) * (S1 * (MetaSel (Just Symbol "controlSetupRequest") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * Request)) ((:*:) * (S1 * (MetaSel (Just Symbol "controlSetupValue") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * Value)) (S1 * (MetaSel (Just Symbol "controlSetupIndex") NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 * Index))))))

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

Methods

succ :: RequestType -> RequestType

pred :: RequestType -> RequestType

toEnum :: Int -> RequestType

fromEnum :: RequestType -> Int

enumFrom :: RequestType -> [RequestType]

enumFromThen :: RequestType -> RequestType -> [RequestType]

enumFromTo :: RequestType -> RequestType -> [RequestType]

enumFromThenTo :: RequestType -> RequestType -> RequestType -> [RequestType]

Eq RequestType

Methods

(==) :: RequestType -> RequestType -> Bool

(/=) :: RequestType -> RequestType -> Bool

Data RequestType

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> RequestType -> c RequestType

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c RequestType

toConstr :: RequestType -> Constr

dataTypeOf :: RequestType -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c RequestType)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c RequestType)

gmapT :: (forall b. Data b => b -> b) -> RequestType -> RequestType

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> RequestType -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> RequestType -> r

gmapQ :: (forall d. Data d => d -> u) -> RequestType -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> RequestType -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> RequestType -> m RequestType

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> RequestType -> m RequestType

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> RequestType -> m RequestType

Read RequestType

Methods

readsPrec :: Int -> ReadS RequestType

readList :: ReadS [RequestType]

readPrec :: ReadPrec RequestType

readListPrec :: ReadPrec [RequestType]

Show RequestType

Methods

showsPrec :: Int -> RequestType -> ShowS

show :: RequestType -> String

showList :: [RequestType] -> ShowS

Generic RequestType

Associated Types

type Rep RequestType :: * -> *

Methods

from :: RequestType -> Rep RequestType x

to :: Rep RequestType x -> RequestType

type Rep RequestType

type Rep RequestType = D1 * (MetaData "RequestType" "System.USB.Base" "usb-1.3.0.6-BxALn33Tmsa87zdhZNpf2H" False) ((:+:) * (C1 * (MetaCons "Standard" PrefixI False) (U1 *)) ((:+:) * (C1 * (MetaCons "Class" PrefixI False) (U1 *)) (C1 * (MetaCons "Vendor" PrefixI False) (U1 *))))

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

Methods

succ :: Recipient -> Recipient

pred :: Recipient -> Recipient

toEnum :: Int -> Recipient

fromEnum :: Recipient -> Int

enumFrom :: Recipient -> [Recipient]

enumFromThen :: Recipient -> Recipient -> [Recipient]

enumFromTo :: Recipient -> Recipient -> [Recipient]

enumFromThenTo :: Recipient -> Recipient -> Recipient -> [Recipient]

Eq Recipient

Methods

(==) :: Recipient -> Recipient -> Bool

(/=) :: Recipient -> Recipient -> Bool

Data Recipient

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Recipient -> c Recipient

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Recipient

toConstr :: Recipient -> Constr

dataTypeOf :: Recipient -> DataType

dataCast1 :: Typeable (* -> *) t => (forall d. Data d => c (t d)) -> Maybe (c Recipient)

dataCast2 :: Typeable (* -> * -> *) t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Recipient)

gmapT :: (forall b. Data b => b -> b) -> Recipient -> Recipient

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Recipient -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Recipient -> r

gmapQ :: (forall d. Data d => d -> u) -> Recipient -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Recipient -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Recipient -> m Recipient

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Recipient -> m Recipient

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Recipient -> m Recipient

Read Recipient

Methods

readsPrec :: Int -> ReadS Recipient

readList :: ReadS [Recipient]

readPrec :: ReadPrec Recipient

readListPrec :: ReadPrec [Recipient]

Show Recipient

Methods

showsPrec :: Int -> Recipient -> ShowS

show :: Recipient -> String

showList :: [Recipient] -> ShowS

Generic Recipient

Associated Types

type Rep Recipient :: * -> *

Methods

from :: Recipient -> Rep Recipient x

to :: Rep Recipient x -> Recipient

type Rep Recipient

type Rep Recipient = D1 * (MetaData "Recipient" "System.USB.Base" "usb-1.3.0.6-BxALn33Tmsa87zdhZNpf2H" False) ((:+:) * ((:+:) * (C1 * (MetaCons "ToDevice" PrefixI False) (U1 *)) (C1 * (MetaCons "ToInterface" PrefixI False) (U1 *))) ((:+:) * (C1 * (MetaCons "ToEndpoint" PrefixI False) (U1 *)) (C1 * (MetaCons "ToOther" PrefixI False) (U1 *))))

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.