When using this library to develop your USB HID device, there are no device drivers to create since the API uses existing Windows HID class drivers.  Used primarily for keyboards, mice, and joysticks, the HID class is also well-suited for special-purpose applications including access and control of custom-developed devices.  UsbHidApi encapsulates API calls that give you easy access to your device.  These API calls can be used in any development environment that accepts DLLs (e.g., Microsoft Visual C++ or Visual Basic). 

1. System Requirements

UsbHidApi requires a Windows laptop or desktop PC with the following minimum capabilities:
 
1. 1 MB RAM
2. USB port
3. Windows XP or higher
   
 

2. USB Compatibility

There are a number of defined USB device classes as listed in the table below:

Device Class	Typical Use
Audio	Sound card
Communications	Modem, network
Human Interface	Keyboard, mouse
Still Image Capture	Still camera
Printer	Printer
Mass Storage	Disk drive, flash drive
Hub	USB hub
Video	Camera
Wireless	Bluetooth

There are standard device drivers available for each class.  If a device does not fall into one of these classes or the device has special requirements, a custom driver must be provided.  The UsbHidApi library uses the HID class and therefore does not require a custom driver.  While the HID class is typically used for devices such as keyboards, mice, and joysticks, the class is well-suited for custom-developed devices as well.

The maximum defined transfer rate for the HID class is 64K bytes/sec.  For more information, please refer to the following resource:

   http://www.usb.org/developers/hidpage

 
3. Features

UsbHidApi library features include the following:
 
1.  Easy to use API calls - Open( ), Read( ), and Write( ), etc.
2.  No custom drivers (uses USB HID drivers already included in Windows)
3.  Develop PC host applications quickly
4.  Write applications for USB HID devices
5.  Two available demonstration applications: Generic and U4x1
6.  Free demo source code included:  Visual C++ and Visual Basic
7.  VC++ demo source available for either generic demo app or U4x1 demo app.
8.  VB demo source available for generic demo app only.
9.  Can be used with ANSI-C compilers such as LabView and LabWindows/CVI
10.  Use implicit- or explicit-linking
11.  Includes static (.lib) and dynamic (.dll)  libraries
12. Compatible with UsbMicro U4x1 devices

 
4. Ordering

UsbHidApi is available at the following source:

    Kadtronix
    web: http://www.kadtronix.com
    email: sales@kadtronix.com
 

5. Demonstrations

There are two available applications which demonstrate how to use the UsbHidApi: generic and U4x1.  The generic demo  is applicable to any USB HID device and includes demonstration source code for use with the following development environments: 


1. Visual C++ 2008
   
2. Visual C++ 6.0
3. Visual Basic 6.0
   

 
1. Generic Demonstration

To run the Visual C++ generic demo, perform the following Windows command:
 
Start -> All Programs -> USB HID DEMO -> Usb Hid Demo


When executed, the following dialog screen image will appear on your monitor display:
 

Screenshot from Generic demo app - UsbHidDemo
 

 

The Visual C++ 2008 generic demo project source code is located on your PC as follows:
 
Start -> All Programs -> USB HID DEMO -> VC2008

 
The Visual C++ 6 generic demo project source code is located on your PC as follows:
 

Start -> All Programs -> USB HID DEMO -> VC6

To run the Visual Basic generic demo, first open the following folder:

 
Start -> All Programs -> USB HID DEMO -> VB6


 
2. U4x1  Demonstration

To run the Visual C++ U4x1 demo, perform the following Windows command:
 
Start -> All Programs -> USB U4x1 DEMO -> Usb U4x1 Demo


The U4x1 demo is provided only for Visual C++ and was developed primarily for showing how to access a UsbMicro U4x1 device.  When executed, the following dialog screen image will appear on your monitor display:
 

Screenshot from U4x1 demo app - UsbU4x1Demo
 

 

The Visual C++ U4x1 demo project source code is located on your PC as follows:

  Start -> All Programs -> USB U4x1 DEMO -> VC++
 
(There is no available Visual Basic version of this project.)

A trial version of the UsbHidApi is available for free download.  The trial version is unregistered software that is fully operational, but displays periodic pop-up messages.  Visit the Kadtronix website for download details.
 

1. Installation

Before installing the UsbHidApi, you may need to uninstall any earlier version.  To start the installation process, locate and run the self-extracting setup file (setup.exe) on the install media.

Your device hardware may be plugged into any available USB port using a compatible cable.  Since drivers pre-exist under Windows, you may plug in the device at any time, before or after installing the UsbHidApi.
 

2. Linking

Your application may link the UsbHidApi DLL statically (.lib) or dynamically (.dll).  Dynamic linking differs from static linking in that it allows your application  module to include only the information needed at run time to locate the executable code for a DLL function.  In static linking, the linker gets all of the referenced functions from the static link library and places it with your code into your executable.  Using dynamic linking instead of static linking offers several advantages.  DLLs save memory, reduce swapping, save disk space, upgrade easier, provide after-market support, provide a mechanism to extend the MFC library classes, support multilanguage programs, and ease the creation of international versions.

The Generic demo uses static linking while the U4x1demo uses dynamic linking.  You may reference the appropriate demo for further details.

UsbHidApi.h

(This file is included in the distribution within the "VC++" sub-folder.)
 

In addition, functions have been exported for compatibility with certain ANSI C compilers such as LabView and LabWindows/CVI.  For these situations, a special header file has been created named UsbHidApi_2.h and is located in the "ANSI C" folder.  This is a specially modified version of the original header (UsbHidApi.h) and is intended only for use with ANSI C applications.  To use, copy the file to your project space and add the following statement to your C source file:

  #include "UsbHidApi_2.h"

 This statement serves to include or add the file to your application.  Also add the following library file to your list of build objects
 (located in the "VC++" folder):   

UsbHidApi.lib

 For additional information, see the following online resources:   

FAQ: Using Dynamic Link Libraries with LabWindows/CVI
Integrating external code using Import Shared Lib. Wizard
Writing win32 DLLs and Calling them from LabView

(Note: Kadtronix can only provide limited support for LabView and LabWindows applications. Demo applications for LabView or LabWindows/CVI are not available.)
 

/*------ Report Descriptor Group ---------------------*/
/* This is a basic report descriptor. All data in the */
/* reports are vendor defined and therefore the host  */
/* doesn't care  what we transfer                    */
BYTE code abromReportDescriptor[SIZEOF_REPORT_DESCRIPTOR] =
{
   0x06, 0xA0, 0xFF, // Usage Page (FFA0H = vendor defined)
   0x09, 0x01, // Usage (vendor defined)
   0xA1, 0x01, // Start Collection (Application)

   // INPUT DEFINITION
   0x09, 0x01, // Usage (vendor defined)
   0x15, 0x00, // Logical Minimum (0)
   0x25, 0xff, // Logical Maximum (255)
   0x75, 0x08, // Report Size ( 8 BITS)
   0x95, EP1_MAX_REPORT_SIZE, // Report Count (16 Bytes)
   0x81, 0x00, // Input (Data, Variable, Absolute)

  // OUTPUT DEFINITION
  0x09, 0x02, // Usage (vendor defined)
  0x75, 0x08, // Report Size (8 BITS)
  0x95, EP0_MAX_REPORT_SIZE, // Report Count (16 Bytes)
  0x91, 0x00, // 0utput (Data, Variable, Absolute)
  0xC0 // End Collection
};

For more information, please refer to the following resource:

   http://www.usb.org/developers/hidpage
 

The library defines a device structure called mdeviceList.  Used primarily by the GetList( ) function, this structure defines an entry in a device list.  The mdeviceList structure definition is listed below.
 

typedef struct
{
    char         DeviceName[50];   // Device name
    char         Manufacturer[50]; // Manufacturer
    char         SerialNumber[20]; // Serial number
    unsigned int VendorID;         // Vendor ID
    unsigned int ProductID;        // Product ID
    int          InputReportLen;   // Size of input report
    int          OutputReportLen;  // Size of output report
    int          Interface;        // Interface
    int          Collection;       // Collection
} mdeviceList;

The UsbHidApi library provides a number of functions for use by your application.  Examples of their use can be found in the demonstrations.
 

1. GetList( )

This function searches the system for attached USB HID devices and builds a list of these devices and their availability.  The caller must supply a pointer to a buffer that will hold the list of structure entries.  Must also supply an integer representing maximum no. of entries the buffer can hold.  Returns total number stored.

int CUsbHidApi::GetList(
   unsigned int VendorID,
   unsigned int ProductID,
   char         *Manufacturer,
   char         *SerialNum,
   char         *DeviceName,
   mdeviceList  *pList,
   int          nMaxDevices);

Parameter descriptions:

   VendorID     // Vendor ID to search  (0xffff if unused)
   ProductID    // Product ID to search (0xffff if unused)
   Manufacturer // Manufacturer            (NULL if unused)
   SerialNum    // Serial number to search (NULL if unused)
   DeviceName   // Device name to search   (NULL if unused)
   pList        // Caller's array for storing device(s)
   nMaxDevices  // Size of the caller's array list (no.entries)
 

2. Open( )

This function opens a link to a specified USB HID device.  The caller supplies parameters describing the device, typically a vendor ID and product ID.  Additional optional parameters can be provided to further describe the device if desired.  (See also SetInterface and SetCollection.)  If a successful open occurs, the function returns TRUE.  Otherwise, the function returns FALSE.  If the bAsync flag is TRUE, subsequent read requests will be non-blocking.  A device must be opened before any other actions can be taken on it.

int CUsbHidApi::Open(
   unsigned int VendorID,
   unsigned int ProductID,
   char         *Manufacturer,
   char         *SerialNum,
   char         *DeviceName,
   int          bAsync)

Parameter descriptions:

   VendorID     // Vendor ID to search     (0xffff if unused)
   ProductID    // Product ID to search    (0xffff if unused)
   Manufacturer // Manufacturer            (NULL if unused)
   SerialNum    // Serial number to search (NULL if unused)
   DeviceName   // Device name to search   (NULL if unused)
   bAsync       // Set TRUE for non-blocking read requests.
 

3. Read( )

This function reads an input report from an open device.  (The device must be open prior to calling this routine.)  The type of read performed is based on the method used for opening the device (blocking or non-blocking).  If no data is currently available, the function returns 0.  On successful completion, the function returns an integer representing the number of bytes read (usually the input report length defined by the device).  The function returns -1 if disconnect is detected.  (Note:  The caller must supply a pointer to a read buffer that is large enough to accommodate the report length.  This number can be obtained using GetReportLengths.)

int CUsbHidApi::Read(void *Buf)

Parameter description:

   Buf            // Pointer to the caller's storage buffer
 

4. Write( )

This function writes an output report to an open device.  (The device must be open prior to calling this routine.)  The function writes the caller's data to the device.  The number of bytes is determined by the output report length (refer to GetReportLengths).  The caller must guarantee the correct byte-count and buffer storage.  (Note:  The first byte location is usually a report ID [possibly 0].  The caller must ensure this value is prepended to the buffer.)

int CUsbHidApi::Write(void *Buf)

Parameter description:

   Buf            // Pointer to the caller's storage buffer
 

5. GetReportLengths( )

This function retrieves the lengths of input- and output-reports for an open device.  (The device must be open prior to calling this routine.)  The caller must supply integer pointers for storing the report lengths.

void CUsbHidApi::GetReportLengths (
   int *input_len,
   int *output_len)

Parameter descriptions:

   input_len   // Pointer for storing input report length
   output_len  // Pointer for storing output report length
 

6. SetInterface( )

This function sets an optional device interface ID (e.g., 0) for search purposes and is used in instances only where the device has multiple interfaces.  If used, must be called prior to calling the Open() function.

void CUsbHidApi::SetInterface (int iface)

Parameter description:

   iface       // Interface (-1 if unused)
 

7. GetInterface( )

This function eturns the interface ID that was set using SetInterface().

int CUsbHidApi::GetInterface (void)
 

8. SetCollection( )

This function sets an optional collection ID (e.g., 0) for search purposes.  It is used to locate a device to be opened.  Use this function when a the device has multiple collections.  Must be called prior to calling the Open() method.

void CUsbHidApi::SetCollection (int col)

Parameter description:

   col        // Collection (-1 if unused)
 

9. GetCollection( )

This function returns the optional collection ID that was set using SetCollection().

int CUsbHidApi::GetCollection (void)
 

10. CloseRead( )

This function closes the read pipe.  (The device must be open prior to calling this routine.)

void CUsbHidApi::CloseRead(void)
 

11. CloseWrite( )

This function closes the write pipe.  (The device must be open prior to calling this routine.)

void CUsbHidApi::CloseWrite(void)
 

12. GetLibVersion( )

This function retrieves the current library version.  A string pointer must be supplied by the caller for storing the version string.  (The buffer should be at least 10 characters in length.)   It returns 0 on success, -1 otherwise.

int CUsbHidApi::GetLibVersion(LPSTR buf)

Parameter description:

   buf       // Pointer to buffer for storing the version string

1. U401
2. U421
3. U451

Refer to the following resources for additional information:  

http://www.kadtronix.com/digio.htm
http://www.usbmicro.com
http://www.circuitgizmos.com

The following tables present pin-out information: