CYGNAL Application Note
CP2101 Customization Guide
Relevant Devices
This application note applies to the following devices:
CP2101
1. Introduction
This document is intended for developers creating products based on the CP2101 USB to UART
Bridge Controller. It provides information about obtaining a Vendor ID (VID) and Product ID
(PID) for a CP2101 product. It also describes the steps necessary for customizing the device
driver installation and for customizing the device descriptors contained in the CP2101 EEPROM.
2. Obtaining a VID and PID
Each device on a single USB bus must have a unique VID, PID and Serial Number combination.
Vendor IDs are owned by the vendor company and are assigned by the USB Implementers Forum
(USB-IF) only. Details about obtaining a unique VID can be found at
http://www.usb.org/developers/vendor .
To obtain the right to license the USB-IF logo you must register your product's VID and PID with
USB-IF and submit your product to the USB-IF Compliance Program. USB-IF Compliance Program details can be found at http://www.usb.org/developers/compliance . Once your product has
been certified it can be added to the USB-IF Integrators List, and the "Certified USB" logo can be
used on your product.
If you do not wish to license the USB-IF logo the default Cygnal VID can be used. We recommend obtaining a unique PID for your product. To obtain a unique PID contact Cygnal Integrated
Products and one will be assigned to your product. Having a unique PID will reduce the chances
that another device with the same VID, PID and Serial Number will be encountered on the same
USB bus.
CYGNAL Integrated Products, Inc.
4301 Westbank Drive
Suite B-100
Austin, TX 78746
www.cygnal.com
AN044 -1.0 SEP03
Copyright © 2003 Cygnal Integrated Products, Inc.
(All rights reserved)
AN044 - CP2101 Customization Guide
3. Customizing Driver Installations
The driver installation is customizable by modifying certain sections of the hardware installation
files (.INF). The strings contained in the .INF files will affect what is displayed in the "Found
New Hardware" dialogs, the "Found New Hardware Wizard" dialogs, Device Manager and the
registry. The changes to the VID and PID should match the VID and PID contained in the
EEPROM of your product (see Section 5 and Section 6).
Note: Any changes to the .INF files of the Windows installation will require new WHQL tests.
3.1. Windows 2000/XP
Modifying VID and PID
To customize the Windows 2000/XP driver installation open the .INF files named cyg_w2k.inf
and cyg_bus.inf. To modify the VID and PID locate the following section in cyg_w2k.inf:
;--------------------------------------------------------------------------; Device-by-device entries
;--------------------------------------------------------------------------[Cygnal]
%Cygnal.Comm.Desc% = Cygnal.Install, USB\VID_10C4&PID_EA60&MI_00&OS_NT
and the following section in cyg_bus.inf:
;--------------------------------------------------------------------------; The devices
;--------------------------------------------------------------------------[Cygnal]
%Cygnal.CdcBus.Desc% = CygnalWdm.Install, USB\VID_10C4&PID_EA60
and change the 4 hexadecimal digits after "VID_" and "PID_" to the desired values.
Modifying Strings
The only .INF strings that are visible during installation and in Device Manager after installation
are Cygnal.Comm.Desc in cyg_w2k.inf and Cygnal.CdcBus.Desc in cyg_bus.inf. The Product
String contained in the CP2101 EEPROM is also displayed during installation and modification
of this string is described in Section 5 and Section 6. The remaining .INF strings can be found
after driver installation by searching the Windows registry. To modify the strings locate the following section in cyg_w2k.inf:
2
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
;--------------------------------------------------------------------------; STRINGS
;--------------------------------------------------------------------------[Strings]
;<<localize the following>>
;BEGIN ENG - US English Strings
Provider = "Cygnal Integrated Products, Inc."
Cygnal = "Cygnal Integrated Products, Inc."
DiskString = "CP2101 USB to UART Bridge Controller Drivers"
Cygnal.Comm.Desc = "CP2101 USB to UART Bridge Controller"
Cygnal.Service.Name = "CP2101 USB to UART Bridge Controller Drivers"
Cygnal.Service.Desc = "CP2101 USB to UART Bridge Controller Drivers"
CustomerDataPath = "CP2101 USB to UART Bridge Controller"
DriverSet = "CP2101 USB to UART Bridge Controller Driver Set"
and the following section in cyg_bus.inf:
;**************************************************************************
; Localizable Strings
;**************************************************************************
[strings]
;BEGIN ENG - US English Strings
Provider = "Cygnal Integrated Products, Inc."
Cygnal = "Cygnal Integrated Products, Inc."
DiskString = "Cygnal USB Composite Device Installation disk"
Cygnal.CdcBus.Desc = "Cygnal USB Composite Device"
Cygnal.Service.Desc = "Cygnal USB Composite Device driver (WDM)"
CustomerDataPath = "CP2101 USB to UART Bridge Controller"
DriverSet = "CP2101 USB to UART Bridge Controller Software"
and change the values in quotes to the desired strings.
3.2. Windows 98/Me
Modifying VID and PID
To customize the Windows 98/Me driver installation open the .INF files named cyg_wdm.inf and
cyg_bus.inf. To modify the VID and PID locate the following section in cyg_w2k.inf:
;--------------------------------------------------------------------------; Device-by-device entries
;--------------------------------------------------------------------------[Cygnal]
%Cygnal.Comm.Desc% = Cygnal.Install, USB\VID_10C4&PID_EA60&MI_00&OS_9X
and the following section in cyg_bus.inf:
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
3
AN044 - CP2101 Customization Guide
;--------------------------------------------------------------------------; The devices
;--------------------------------------------------------------------------[Cygnal]
%Cygnal.CdcBus.Desc% = CygnalWdm.Install, USB\VID_10C4&PID_EA60
and change the 4 hexadecimal digits after "VID_" and "PID_" to the desired values.
Modifying Strings
The only .INF strings that are visible during installation and in Device Manager after installation
are Cygnal.Comm.Desc in cyg_wmf.inf and Cygnal.CdcBus.Desc in cyg_bus.inf. The Product
String contained in CP2101 EEPROM is also displayed during installation and modification of
this string is described in sections 5 and 6 of this document. The remaining .INF strings can be
found after driver installation by searching the Windows registry. To modify the strings locate the
following section in cyg_wmf.inf:
;--------------------------------------------------------------------------; STRINGS
;--------------------------------------------------------------------------[Strings]
;BEGIN ENG - US English Strings
Provider = "Cygnal Integrated Products, Inc."
Cygnal = "Cygnal Integrated Products, Inc."
DiskString = "CP2101 USB to UART Bridge Controller Drivers"
Cygnal.Comm.Desc = "CP2101 USB to UART Bridge Controller"
UpperDescription = "CP2101 USB to UART Bridge Controller"
CustomerDataPath = "CP2101 USB to UART Bridge Controller"
DriverSet = "CP2101 USB to UART Bridge Controller Driver Set"
and the following section in cyg_bus.inf:
;**************************************************************************
; Localizable Strings
;**************************************************************************
[strings]
;BEGIN ENG - US English Strings
Provider = "Cygnal Integrated Products, Inc."
Cygnal = "Cygnal Integrated Products, Inc."
DiskString = "Cygnal USB Composite Device Installation disk"
Cygnal.CdcBus.Desc = "Cygnal USB Composite Device"
Cygnal.Service.Desc = "Cygnal USB Composite Device driver (WDM)"
CustomerDataPath = "CP2101 USB to UART Bridge Controller"
DriverSet = "CP2101 USB to UART Bridge Controller Software"
and change the values in quotes to the desired strings.
4
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
3.3. Macintosh OS9
If the VID or PID is changed from the default factory settings, please contact Cygnal Integrated
Products to obtain drivers for Mac OS9 that incorporate the new values. Mac OS9 requires that
the drivers be compiled with the values that will be used by the production CP2101 device.
3.4. Macintosh OSX
TBD
4. Installing Drivers
The CD-ROM included with the CP2101EK Evaluation Kit contains the Virtual COM Port Drivers for the CP2101. The following files are included on the CD-ROM:
•
•
•
•
CP2101 datasheet (CP2101.pdf)
Driver installation utility (CP2101_Drivers.exe)
Version information document (Readme.txt)
CP2101 Evaluation Kit User’s Guide (CP2101_UG.pdf)
4.1. Extract all Virtual COM Port Drivers
Initial software setup requires running CP2101_Drivers.exe to extract all of the device drivers
(Windows and Macintosh). After following the prompts, the utility will copy the driver files to a
specified directory or the default directory, “C:\Cygnal\CP2101”. Each set of drivers will be
extracted to an appropriately named directory, for example WIN, MAC9, and MAC10.
4.2. Install Windows Virtual COM Port Driver
To install the Windows virtual COM port driver, run Setup.exe located in the WIN directory created in Section 4.1. Driver files are installed into the “C:\Program Files\CUSB USB to RS-232
Bridge Controller” directory. COM port properties for the device can be selected in the device
manager (COM port number, baud rate etc.).
4.3. Install Macintosh Virtual COM Port Driver
To install the Macintosh OSX virtual COM port driver, extract the cardinal-osx-V1_00crelease.zip file located in the MAC10 directory created in Section 4.1. Next, run the extracted file
CygnalUSBToRS232Installer.
To install the Macintosh OS9 virtual COM port driver, extract the cardinal-os9-V3_00a-free.sit
file located in the MAC9 directory created in Section 4.1. Next, run the extracted file Installer.
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
5
AN044 - CP2101 Customization Guide
5. Customizing Device Descriptors
The CP2101 descriptors can be changed using the example utility CP2101SetIDs.exe in conjunction with the Windows Host API functions implemented by CP2101.DLL. The Host API functions give read/write access to the descriptors contained in EEPROM of a connected device.
Another option is implementing a custom application using the Host API and CP2101.DLL suited
to the individual needs of a particular production environment.
The descriptors can also be set in the factory at production time for large orders. Please contact
Cygnal Integrated Products for details.
5.1. Customizing Device Descriptors using CP2101SetIDs.exe
CP2101SetIDs.exe is an example program that uses the CP2101 Host API Functions implemented
by CP2101.DLL, see Figure 1. CP2101SetIDs.exe demonstrates the general method of accessing
and changing the descriptors contained in the connected device's EEPROM.
To use
CP2101SetIDs.exe or to follow the same general method of accessing the descriptors it is necessary
to have the devices connected and have the unmodified device drivers that shipped with the original
CP2101 kit installed. The customized device driver installation files that contain the new VID and
PID values (see Section 3) should also be installed. The default driver must be installed so that the
CP2101 device with the default factory settings will appear in the device list. The customized drivers will be needed after the device IDs have been changed and the CP2101 device is reset.
Before running CP2101SetIDs.exe, copy CP2101.DLL into \windows, \winnt, or \system32 directories, the directory containing the executable or any directory in the "Path" environment variable.
Figure 1. CP2101SetIDs.exe Example Application
6
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
When CP2101SetIDs.exe is launched the program searches the Windows registry for any CP2101
devices attached to the PC. The full path information for all of the devices found is inserted into
the "Select Device" drop-down list, and the first device is selected automatically.
CP2101SetIDs.exe then queries information from the selected device using the CP2101 Host API
functions and fills in the values for each of the seven selectable fields of the application. When a
new device is selected from the list, the fields will be updated with the information from the most
recently selected device.
To change one or more of the values, click on the checkbox to the left of the field and enter the
new value. Once the new values have been entered, click on the "Program Device" button.
The values entered are subject to the following limitations:
1.
2.
3.
4.
5.
6.
Vid - 4 hexadecimal digits.
Pid - 4 hexadecimal digits.
Max. Power - 2 hexadecimal digits (the value is in 2 mA units).
Serial Number - any sequence of up to 123 characters.
Product String - any sequence of up to 123 characters.
Release Version - each field is a decimal number value 0-99.
Note:
- Avoid connecting more than one device containing the same VID, PID and serial number
combination.
- When the serial number of a CP2101 device is changed and the device is reset by calling the
Host API function CP2101_Reset(), the device will re-enumerate and the device driver will be
installed.
5.2. Building CP2101.EXE
Open CP2101SetIDs.dsw in Visual Studio 6.0. Select "Release" or "Debug" and build the project.
5.3. Creating Custom Applications using CP2101.DLL
Custom applications can use the CP2101 Host API implemented in CP2101.DLL. To use functions implemented in CP2101.DLL, link CP2101.LIB with your Visual C++ 6.0 application.
Include CP2101.h in any file that calls functions implemented in CP2101.DLL.
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
7
AN044 - CP2101 Customization Guide
6. CP2101 Host API Functions
The CP2101 Host API is provided as a means to facilitate production of customized CP2101
devices. The API allows access to the CP2101 device for retrieving and setting the VID, PID, product string, serial number, self-power attribute, maximum power consumption, and device version.
The CP2101 Host API is provided in the form of a Windows Dynamic Link Library (DLL),
CP2101.DLL. The host interface DLL communicates with the bridge controller device via the
provided device driver and the operating system's USB stack. Following is a list of the available
host API functions:
CP2101_GetNumDevices()
- Returns the number of CP2101 devices connected.
CP2101_GetProductString()
- Returns a descriptor from the registry for a CP2101USB device.
CP2101_Open()
- Opens a CP2101 device as a USB device and returns a handle.
CP2101_Close()
- Closes a CP2101 device handle.
CP2101_SetVid()
- Sets the 2-byte vendor ID of a CP2101 device.
CP2101_SetPid()
- Sets the 2-byte product ID of a CP2101 device.
CP2101_SetProductString()
- Sets the product description string of a CP2101 device.
CP2101_SetSerialNumber()
- Sets the serial number string of a CP2101 device.
CP2101_SetSelfPower()
- Sets the self-power attribute of a CP2101 device.
CP2101_SetMaxPower()
- Sets the maximum power consumption of a CP2101 device.
CP2101_SetDeviceVersion()
- Sets version number of the CP2101 device.
CP2101_GetDeviceProductString() -Returns the product description string of a CP2101 device.
CP2101_GetDeviceSerialNumber() - Returns the serial number string of a CP2101 device.
CP2101_GetDeviceVid()
- Returns the vendor ID of a CP2101 device.
CP2101_GetDevicePid()
- Returns the product ID of a CP2101 device.
CP2101_GetSelfPower()
- Returns the self-power attribute of a CP2101 device.
CP2101_GetMaxPower()
- Returns max. power consumption value of a CP2101 device.
CP2101_GetDeviceVersion()
- Returns the version number of a CP2101 device.
CP2101_Reset()
- Resets a CP2101 device.
In general, the user initiates communication with the target CP2101 device by making a call to
CP2101_GetNumDevices(). This call will return the number of CP2101 target devices. This
number is used as a range when calling CP2101_GetProductString() to build a list of devices connected to the host machine.
To access a device a handle to the device must first be opened by a call to CP2101_Open() using
an index determined from the call to CP2101_GetNumDevices(). The handle will be used for all
subsequent accesses. When I/O operations are complete, the device handle is closed by a call to
CP2101_Close().
The remaining functions are provided to allow access to customizable values contained in the
CP2101 device EEPROM.
Each of these functions are described in the following sections. Type definitions and constants
are defined in Appendix A.
8
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
6.1. CP2101_GetNumDevices
Description
This function returns the number of CP2101 devices connected to the host.
Prototype
CP2101_STATUS CP2101_GetNumDevices( LPDWORD NumDevices )
Parameters
1. NumDevices - Address of a DWORD that will contain the number of devices.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_DEVICE_NOT_FOUND,
CP2101_INVALID_PARAMETER
6.2. CP2101_GetProductString
Description
This function returns a null terminated serial number (S/N) string, product description string or
full path string for the device specified by an index passed in the DeviceNum parameter. The
index of the first device is 0 and the index of the last device is the value (NumDevices) returned
by CP2101_GetNumDevices() - 1.
Prototype
CP2101_STATUS CP2101_GetProductString( DWORD DeviceNum, LPVOID DeviceString,
DWORD Options )
Parameters
1. DeviceNum - Index of the device for which the product description string, serial number
or full path is desired.
2. DeviceString - Variable of type CP2101_DEVICE_STRING returning the NULL terminated serial number, device description or full path string.
3. Options - flag that determines if DeviceString contains the product description, serial
number or full path string.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_DEVICE_NOT_FOUND,
CP2101_INVALID_PARAMETER
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
9
AN044 - CP2101 Customization Guide
6.3. CP2101_Open
Description
Opens and returns a handle to a device using a device number determined by the number returned
from CP2101_GetNumDevices().
Prototype
CP2101_STATUS CP2101_Open( DWORD DeviceNum, HANDLE* Handle )
Parameters
1. DeviceNum - Device index. 0 for the first device, 1 for the 2nd, etc..
2. Handle - Pointer to a variable where the handle to the device will be stored. This handle
will be used for all subsequent accesses to the device.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_DEVICE_NOT_FOUND,
CP2101_INVALID_PARAMETER
6.4. CP2101_Close
Description
Closes an open device handle.
Prototype
CP2101_STATUS CP2101_Close( HANDLE Handle )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_HANDLE
6.5. CP2101_SetVid
Description
Sets the 2-byte Vendor ID field, idVendor, of the Device Descriptor contained in EEPROM of a
CP2101 device.
Prototype
CP2101_STATUS CP2101_SetVid( HANDLE Handle, WORD Vid )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Vid - 2-byte Vendor ID value.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
10
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
6.6. CP2101_SetPid
Description
Sets the 2-byte Product ID field, idProduct, of the Device Descriptor contained in EEPROM of a
CP2101 device.
Prototype
CP2101_STATUS CP2101_SetPid( HANDLE Handle, WORD Pid )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Pid - 2-byte Product ID value.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.7. CP2101_SetProductString
Description
Sets the Product Description String of the String Descriptor contained in EEPROM of a CP2101
device. If the string is not already in Unicode format the function will convert the string to Unicode before committing it to EEPROM. The character size limit (in characters, not bytes) NOT
including a NULL terminator is CP2101_MAX_DEVICE_STRLEN.
Prototype
CP2101_STATUS CP2101_SetProductString( HANDLE Handle, LPVOID Product, BYTE
Length, BOOL ConvertToUnicode=TRUE )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Product - Buffer containing the Product String value.
3. Length - Length of the string in characters (not bytes) not including a NULL terminator.
4. ConvertToUnicode - Boolean flag that tells the function if the string needs to be converted
to Unicode. The flag is set to TRUE by default, i.e. the string is in ASCII format and
needs to be converted to Unicode.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
11
AN044 - CP2101 Customization Guide
6.8. CP2101_SetSerialNumber
Description
Sets the Serial Number String of the String Descriptor contained in EEPROM of a CP2101
device. If the string is not already in Unicode format the function will convert the string to Unicode before committing it to EEPROM. The character size limit (in characters, not bytes) NOT
including a NULL terminator is CP2101_MAX_DEVICE_STRLEN.
Prototype
CP2101_STATUS CP2101_SetSerialNumber( HANDLE Handle, LPVOID SerialNumber, BYTE
Length, BOOL ConvertToUnicode=TRUE )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. SerialNumber - Buffer containing the Serial Number String value.
3. Length - Length in characters (not bytes) not including a NULL terminator.
4. ConvertToUnicode - Boolean flag that tells the function if the string needs to be converted
to Unicode. The flag is set to TRUE by default, i.e. the string is in ASCII format and
needs to be converted to Unicode.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.9. CP2101_SetSelfPower
Description
Sets or clears the Self-powered bit of the Power Attributes field, bmAttributes, of the Configuration Descriptor contained in EEPROM of a CP2101 device.
Prototype
CP2101_STATUS CP2101_SetSelfPower( HANDLE Handle, BOOL SelfPower )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. SelfPower - Boolean flag where TRUE means set Self-powered bit, and FALSE means
clear Self-powered bit.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
12
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
6.10. CP2101_SetMaxPower
Description
Sets the Max Power field, MaxPower, of the Configuration Descriptor contained in EEPROM of a
CP2101 device.
Prototype
CP2101_STATUS CP2101_SetMaxPower( HANDLE Handle, BYTE MaxPower )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. MaxPower - 1-byte value representing the Maximum power consumption of the CP2101
USB device expressed in 2mA units.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.11. CP2101_SetDeviceVersion
Description
Sets the Device Release Version field, bcdDevice, of the Device Descriptor contained in
EEPROM of a CP2101 device.
Prototype
CP2101_STATUS CP2101_SetDeviceVersion( HANDLE Handle, WORD Version )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Version - 2-byte Device Release Version number in Binary-Coded Decimal (BCD) format
with the upper 2 nibbles containing the 2 decimal digits of the major version and the lower
2 nibbles containing the 2 decimal digits of the minor version.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.12. CP2101_GetDeviceProductString
Description
Returns the Product Description String of the String Descriptor contained in EEPROM of a
CP2101 device. If the ConvertToASCII parameter is set the string will be converted to ASCII
format before being returned to the caller. The character size limit (in characters, not bytes) NOT
including a NULL terminator is CP2101_MAX_DEVICE_STRLEN.
Prototype
CP2101_STATUS CP2101_GetDeviceProductString( HANDLE Handle, LPVOID Product,
LPBYTE Length, BOOL ConvertToASCII=TRUE )
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
13
AN044 - CP2101 Customization Guide
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Product - Pointer to a buffer returning the Product String value.
3. Length - Pointer to a BYTE value returning the length of the string in characters (not
bytes) not including a NULL terminator.
4. ConvertToASCII - Boolean flag that tells the function if the string needs to be converted
to ASCII before it is returned to the caller. The flag is set to TRUE by default, i.e. the
caller is expecting the string in ASCII format.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.13. CP2101_GetDeviceSerialNumber
Description
Gets the Serial Number String of the String Descriptor contained in EEPROM of a CP2101
device. If the ConvertToASCII parameter is set the string will be converted to ASCII format
before being returned to the caller. The character size limit (in characters, not bytes) NOT including a NULL terminator is CP2101_MAX_DEVICE_STRLEN.
Prototype
CP2101_STATUS CP2101_GetDeviceSerialNumber( HANDLE Handle, LPVOID SerialNumber, LPBYTE Length, BOOL ConvertToASCII=TRUE )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. SerialNumber - Pointer to a buffer returning the Serial Number String value.
3. Length - Pointer to a BYTE value returning the length of the string in characters (not
bytes) not including a NULL terminator.
4. ConvertToASCII - Boolean flag that tells the function if the string needs to be converted
to ASCII before it is returned to the caller. The flag is set to TRUE by default, i.e. the
caller is expecting the string in ASCII format.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.14. CP2101_GetDeviceVid
Description
Returns the 2-byte Vendor ID field, idVendor, of the Device Descriptor contained in EEPROM of
a CP2101 device.
Prototype
CP2101_STATUS CP2101_GetDeviceVid( HANDLE Handle, LPWORD Vid )
14
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Vid - Pointer to a 2-byte value that returns the Vendor ID of the CP2101 device.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.15. CP2101_GetDevicePid
Description
Returns the 2-byte Product ID field, idProduct, of the Device Descriptor contained in EEPROM
of a CP2101 device.
Prototype
CP2101_STATUS CP2101_GetDevicePid( HANDLE Handle, LPWORD Pid )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Pid - Pointer to a 2-byte value that returns the Product ID of the CP2101 device.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.16. CP2101_GetSelfPower
Description
Returns the state of the Self-powered bit of the Power Attributes field, bmAttributes, of the Configuration Descriptor contained in EEPROM of a CP2101 device.
Prototype
CP2101_STATUS CP2101_GetSelfPower( HANDLE Handle, LPBOOL SelfPower )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. SelfPower - Pointer to a boolean flag where TRUE means Self-powered bit is set, and
FALSE means Self-powered bit is cleared.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
15
AN044 - CP2101 Customization Guide
6.17. CP2101_GetMaxPower
Description
Returns the 1-byte Max Power field, MaxPower, of the Configuration Descriptor contained in
EEPROM of a CP2101 device.
Prototype
CP2101_STATUS CP2101_GetMaxPower( HANDLE Handle, LPBYTE MaxPower )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. MaxPower - Pointer to a 1-byte value returning the Maximum power consumption of the
CP2101 USB device expressed in 2mA units.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
6.18. CP2101_GetDeviceVersion
Description
Returns the 2-byte Device Release Version field, bcdDevice, of the Device Descriptor contained
in EEPROM of a CP2101 device.
Prototype
CP2101_STATUS CP2101_GetDeviceVersion( HANDLE Handle, LPWORD Version )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
2. Version - Pointer to a 2-byte value returning the Device Release Version number in
Binary-Coded Decimal (BCD) format with the upper 2 nibbles containing the 2 decimal
digits of the major version and the lower 2 nibbles containing the 2 decimal digits of the
minor version.
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_PARAMETER,
CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
16
AN044 - 1.0 SEP03
© 2003 Cygnal Integrated Products, Inc.
AN044 - CP2101 Customization Guide
6.19. CP2101_Reset
Description
Initiates a reset of the USB interface.
NOTE: There is a delay of ~1 second before the reset is initiated by the device firmware to give
the application time to call CP2101_Close() to close the device handle. No further operations
should be performed with the device until it resets, re-enumerates in Windows and a new handle
is opened.
Prototype
CP2101_STATUS CP2101_Reset( HANDLE Handle )
Parameters
1. Handle - Handle to the device to close as returned by CP2101_Open().
Return Value
CP2101_STATUS = CP2101_SUCCESS, CP2101_INVALID_HANDLE, CP2101_DEVICE_IO_FAILED
Appendix A
Type Definitions from C++ Header File CP2101.h
// GetProductString() function flags
#define
CP2101_RETURN_SERIAL_NUMBER
#define
CP2101_RETURN_DESCRIPTION
#define
CP2101_RETURN_FULL_PATH
0x00
0x01
0x02
// Return codes
#define
CP2101_SUCCESS
#define
CP2101_DEVICE_NOT_FOUND
#define
CP2101_INVALID_HANDLE
#define
CP2101_INVALID_PARAMETER
#define
CP2101_DEVICE_IO_FAILED
0x00
0xFF
0x01
0x02
0x03
// Buffer size limits
#define
CP2101_MAX_DEVICE_STRLEN
123
// Type definitions
typedef
int
CP2101_STATUS;
typedef
char
CP2101_DEVICE_STRING[CP2101_MAX_DEVICE_STRLEN];
© 2003 Cygnal Integrated Products, Inc.
AN044 - 1.0 SEP03
17