CEUSBKWrapper - Userspace USB Driver for Windows CE
===================================================

Contents
========

1. Introduction
2. Supported Features and Platforms
3. Build and Installation
4. Driver Configuration
5. Userspace Applications
6. Cross-Platform Support


1. Introduction
===============

CEUSBKWrapper allows userspace applications on Windows CE to interact with USB
devices. CEUSBKWrapper consists of two components:

* ceusbkwrapperdrv.dll: A Windows CE USB driver, exposing USB functionality to
  userspace.
* ceusbkwrapper.dll: A userspace library, which interacts with the driver and 
  exposes an API to applications. 

The driver component of CEUSBKWrapper is loaded for particular USB devices by 
USBD. These devices are then accessible from userspace applications. USB devices
must be associated with the driver component (via LoadClients registry entries 
for USBD) before userspace applications can interact with them.

CEUSBKWrapper is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free 
Software Foundation; either version 2.1 of the License, or (at your option) 
any later version.
 
CEUSBKWrapper is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 
details.

Please see LICENSE.txt for further licensing information.


2. Supported Features and Platforms
===================================

The following features are currently supported by CEUSBKWrapper:

* Notification of device connection and disconnection events.
* Retrieval of device and configuration descriptors.
* Control transfers, issued to the Default Control Pipe.
* Bulk transfers.
* Endpoint management (testing for and clearing of halt conditions).

Currently, CEUSBKWrapper requires Windows CE 6.0 or later. This is routinely
tested on the Freescale i.MX51 EVK board, using Freescale's April 2011 Windows
CE 6.0 Board Support Package. Prototype support has also been added for Windows
CE 5.0, but this is not routinely tested.


3. Build and Installation
=========================

These instructions are written for Windows CE 6.0. To build and deploy
CEUSBKWrapper, you must be capable of generating Windows CE OEM images for your
device. USB Host Support (SYSGEN_USB) must be enabled to allow CEUSBKWrapper
to function. 

Note that the driver component of CEUSBKWrapper is designed to be loaded by 
USBD. If USBD is not being used in your image, then the driver component may
require modification.

CEUSBKWrapper is provided as three Platform Builder subprojects, to be 
incorporated into an OS design:

* ceusbkwrapperdrv (drv\ceusbkwrapperdrv.pbpxml): The driver component.

* ceusbkwrapper (lib\ceusbkwrapper.pbpxml): The userspace library component.

* ceusbkwrappertest (test\ceusbkwrappertest.pbpxml): The optional CEUSBKWrapper 
  test utility.

At a minimum, both the ceusbkwrapperdrv and ceusbkwrapper subprojects must be 
incorporated into the OS design. The ceusbkwrappertest project is optional, and
is intended for testing and debugging purposes.

To incorporate each project, open the OS design and, in Solution Explorer, find
the Subprojects node. Right click this, and select "Add Existing Subproject...".
In the Open dialog that appears, navigate to and open the .pbpxml file for the 
subproject. This should then appear under the Subprojects node in Solution 
Explorer.

Once all required subprojects have been added, right-click Solution Explorer 
and select "Set Subproject Build Order". Ensure that the projects are built in 
the following order:

1. ceusbkwrapperdrv
2. ceusbkwrapper
3. ceusbkwrappertest (if using)

Finally, build the subprojects using the "Rebuild All Subprojects" option from 
the Build menu. Depending on your Visual Studio Platform Builder configuration, 
this should also cause a new run-time image to be generated. If it does not,  
use the "Make Run-Time Image" option from the Build menu to regenerate the 
run-time image.


4. Driver Configuration
=======================

The driver component of CEUSBKWrapper has a number of configuration registry 
settings, specified in drv\ceusbkwrapperdrv.reg. These control the USB devices 
to which CEUSBKWrapper shall attach, and USB interfaces for which CEUSBKWrapper 
shall automatically attempt to load alternative drivers. Consult this file for
detailed information on these configuration settings, and to view the default
configuration used.


5. Userspace Applications
=========================

Applications wishing to interact with CEUSBKWrapper should use the API defined
in lib\ceusbkwrapper.h. Please consult this file for API documentation. 
Applications will need to link against, or dynamically load, ceusbkwrapper.dll. 
Applications should not interact directly with the driver component.


6. Cross-Platform Support
=========================

Applications can also interact with CEUSBKWrappper through libusbx for Windows
CE. libusbx provides a single cross-platform API allowing access to USB devices. 
Please refer to the following web page for more information on libusbx:

http://libusbx.org/