User Manual

Version 1.18

02/25/10

Copyright (C) 2010

All rights reserved

USB HID API Library

Develop custom USB HID applications using existing Windows drivers!

for software developers, engineers, and programmers

by K.A. Delahoussaye Delahoussaye Consulting

web: www.kadtronix.com email: info@kadtronix.com

Table of Contents 1. Introduction

1. 2. 3. 4. 5. 6. 7.

System Requirements USB Compatibility Features Ordering Demonstrations Installation Linking

2. Header Definition

3. Compiler Compatibility

4. Device Descriptors

5. Function Reference

1. 2. 3. 4.

GetList( ) Open( ) Read( ) Write( )

5. GetReportLengths() 6. SetInterface( ) 7. GetInterface( ) 8. SetCollection( ) 9. GetCollection( ) 10. CloseRead( ) 11. CloseWrite( ) 12. GetLibVersion

6. U4x1 Hardware

7. Legal 1. License 2. Warranty

1. Introduction

The USB HID API Library, herein referred to as "UsbHidApi", provides a set of applications programmer interface (API) functions for accessing a USB Human Interface Device (HID) class device. The routines are compiled within a standard Windows dynamic link library (DLL), callable by applications including C, C++ or Visual Basic. 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 MB RAM USB port Windows 98/2000/XP/Vista

2. USB Compatibility

There are a number of defined USB device classes as listed in the table below: Device Class Audio Communications Human Interface Still Image Capture Printer Mass Storage Hub Video Wireless Typical Use Sound card Modem, network Keyboard, mouse Still camera Printer Disk drive, flash drive USB hub Camera 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:

Easy to use API calls - Open( ), Read( ), and Write( ), etc. No custom drivers (uses USB HID drivers already included in Windows) Develop PC host applications quickly Write applications for USB HID devices Two available demonstration applications: Generic and U4x1 Free demo source code included: Visual C++ and Visual Basic VC++ demo source available for either generic demo app or U4x1 demo app. VB demo source available for generic demo app only. Can be used with ANSI-C compilers such as LabView and LabWindows/CVI Use implicit- or explicit-linking Includes static (.lib) and dynamic (.dll) libraries 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:

Visual C++ 2008 Visual C++ 6.0 Visual Basic 6.0

The U4x1 demo is applicable only to UsbMicro U4x1 devices and includes demonstration source code for use with the following development environments:

Visual C++ 2008 Visual C++ 6.0

Pre-built demo executables are included in the installation, allowing you to run the demo even in the absence of a development environment.

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.

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

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

2. Header Definition

The header definition file defines the UsbHidApi library class and lists all properties and features of the library including structure assignments, exported functions, and parameters. This file, listed below, may be included in your application for static linking: UsbHidApi.h (This file is included in the distribution within the "VC++" sub-folder.)

3. Compiler Compatibility

TheUsbHidApi library is compatible with Visual C++ 2008, Visual C++ 6.0, and Visual Basic 6.0 compilers. To meet the needs of developers who use other compilers, the API has been adapted for .NET (2003) and ANSI C use. For .NET, use the header file named: UsbHidApi_NET.h. (Refer to the "NET" folder of your installation for details.) 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.)

4. Device Descriptors

If you are designing USB firmware, then one of your key considerations will be definition of descriptors for the device. This is important for proper device enumeration by the host. There are several types of descriptors including configuration, device, and report. Developers will sometimes define a valid set of descriptors, but then fail to properly classify the device. The device is classified by its "usage" such as a keyboard, joystick, or mouse. These devices are typically allocated for exclusive use by the operating system. If you are developing a custom device (e.g., temperature controller, digital input/output board, etc.) using the HID class, then your report descriptor should indicate a "Vendor Defined" usage as indicated in the sample report descriptor below (courtesy of L. Zadra): /*------ 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

5. Function Reference

This section presents a description of functions provided by the UsbHidApi library. The library is encapsulated with a class called CUsbHidApi for C++ users. To allow for the greatest flexibility and compatibility, individual functions have been exported for use with Visual Basic and other languages. 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 char char unsigned int unsigned int int int int int } mdeviceList;

DeviceName[50]; Manufacturer[50]; SerialNumber[20]; VendorID; ProductID; InputReportLen; OutputReportLen; Interface; Collection;

// // // // // // // // //

Device name Manufacturer Serial number Vendor ID Product ID Size of input report Size of output report Interface Collection

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 ProductID Manufacturer SerialNum DeviceName pList nMaxDevices // // // // // // // Vendor ID to search (0xffff if unused) Product ID to search (0xffff if unused) Manufacturer (NULL if unused) Serial number to search (NULL if unused) Device name to search (NULL if unused) Caller's array for storing device(s) 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 int

*DeviceName, bAsync)

Parameter descriptions:
VendorID ProductID Manufacturer SerialNum DeviceName bAsync // // // // // // Vendor ID to search (0xffff if unused) Product ID to search (0xffff if unused) Manufacturer (NULL if unused) Serial number to search (NULL if unused) Device name to search (NULL if unused) 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 output_len // Pointer for storing input report length // 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

6. U4x1 Hardware

Developers who need a pre-built USB hardware may choose to use the UsbMicro U4x1. This module provides 16 digital signal lines, configurable in any combination of inputs and outputs. Available in two form-factors (U401 and U421), these devices are compatible with the UsbHidApi library. Demonstration software is available which demonstrates input and output operations specifically patterned for the U4x1 I/O. Kadtronix offers these devices pre-bundled with the USB Digital I/O Commander software.

Visit the following website for detailed hardware information:

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

The following tables present pin-out information:

Pin Number 7 9 15 16 17 18 19 20 21

U401 Interface Connector Pin Out USB Interface Signal +5V USB from PC GND PA.0 - Port A bit 0 PA.1 - Port A bit 1 PA.2 - Port A bit 2 PA.3 - Port A bit 3 PA.4 - Port A bit 4 [SPI SS (slave-mode only)] PA.5 - Port A bit 5 [SPI MOSI] PA.6 - Port A bit 6 [SPI MISO]

22 23 24 25 26 27 28 29 30

PA.7 - Port A bit 7 [SPI SCLK] PB.0 - Port B bit 0 PB.1 - Port B bit 1 PB.2 - Port B bit 2 PB.3 - Port B bit 3 PB.4 - Port B bit 4 PB.5 - Port B bit 5 PB.6 - Port B bit 6 PB.7 - Port B bit 7

Pin Number 14 9 1 2 3 4 24 23 22 21 5 20 6 19 7 18 8 17 7. Legal

U421 Interface Connector Pin Out USB Interface Signal +5V USB from PC GND PA.0 - Port A bit 0 PA.1 - Port A bit 1 PA.2 - Port A bit 2 PA.3 - Port A bit 3 PA.4 - Port A bit 4 [SPI SS (slave-mode only)] PA.5 - Port A bit 5 [SPI MOSI] PA.6 - Port A bit 6 [SPI MISO] PA.7 - Port A bit 7 [SPI SCLK] PB.0 - Port B bit 0 PB.1 - Port B bit 1 PB.2 - Port B bit 2 PB.3 - Port B bit 3 PB.4 - Port B bit 4 PB.5 - Port B bit 5 PB.6 - Port B bit 6 PB.7 - Port B bit 7

By purchasing this product, you agree to terms of licensing and warranty. Please read the following sections carefully. 1. License

Kadtronix and Delahoussaye Consulting (the seller) grant the registered user of the USB HID API library, herein referred to as "the application", the right to use one copy of the application software on a single computer. The user may not use the application on more than one computer at the same time unless expressly intended for this purpose (such as network applications). The application may NOT be distributed without our express written permission.

2. Warranty

THE SELLER DISCLAIMS ALL WARRANTIES RELATING TO THIS PRODUCT, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER THE SELLER. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS PRODUCT SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH PRODUCT EVEN IF THE SELLER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL THE SELLER'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE PRODUCT, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE PRODUCT BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE PRODUCT.