Freescale Semiconductor Document Number: AN4314

Rev. 1, 07/2011
Application Note

Using USB2SER DLL in C#

Projects
by: Juan Cazares
IMM Software Engineer

1 Introduction Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
This application note explains how to use the USB2SER 2 Using DLLs in a C# Project . . . . . . . . . . . . . . . . . . . . . . . 2
2.1 Creating a new DLL folder. . . . . . . . . . . . . . . . . . . . 2
DLL in any C# (C sharp) project. This DLL is used to 2.2 Application programming interface . . . . . . . . . . . . . 5
communicate with the USB2SER, which allows the 3 Serial Production GUI User Guide. . . . . . . . . . . . . . . . . . 8
reading and modification of USB descriptors allocated in 3.1 Valid formats and values for USB descriptors’ fields 9
3.2 Discover USB devices . . . . . . . . . . . . . . . . . . . . . . . 9
nonvolatile memory. 3.3 Read USB descriptors . . . . . . . . . . . . . . . . . . . . . . 10
3.4 Customize USB descriptors. . . . . . . . . . . . . . . . . . 10
First, the application note explains how to include and 4 Conclusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
use the USB2SER DLL in a C# project. Second, it
explains in detail the application programming interface
(API) of the USB2SER DLL. Third, this document
explains how the serial production GUI is implemented
and how it uses the USB2SER DLL.

© Freescale Semiconductor, Inc., 2011. All rights reserved.

Using DLLs in a C# Project

2 Using DLLs in a C# Project

2.1 Creating a new DLL folder
The USB2SER_DLL.dll can be used in an existent project. This document explains how to create a new
project and then how to use the DLL.
Open C# studio and follow the next steps:
1. Choose the File pull-down menu.
2. Choose the New Project option.

3. On the New Project screen, choose Windows Forms Applications.

4. Change the name for the new application (for example, “SerialProductionGUI”) and click OK.

Using USB2SER DLL in C# Projects, Rev. 1

2 Freescale Semiconductor
 Using DLLs in a C# Project

The project is created and shows an empty form.

5. On the solution explorer, right click on References, then choose Add Reference.

Using USB2SER DLL in C# Projects, Rev. 1

Freescale Semiconductor 3
Using DLLs in a C# Project

6. Select the Browse tab and look for the USB2SER_DLL.dll file. Select it and click OK.
7. Repeat steps 6 and 7 for any other desired DLL files.
8. Open the Form1 code and add the class USB2SER_DLL with the “using” word.

Using USB2SER DLL in C# Projects, Rev. 1

4 Freescale Semiconductor
 Using DLLs in a C# Project

9. Now, by declaring a new USB2SER_API object the Form1 can use the methods provided by the
referenced class.
Download and open the SerialProduction1v3 project from www.freescale.com for more information about
the mentioned class.

2.2 Application programming interface

This section explains in detail all methods used by the USB2SER_DLL class.

2.2.1 USB2SER_DLL class

This class allows the configuration of the USB2SER’s nonvolatile memory, which is intended to store the
USB descriptors. This class provides methods to read and modify vendor ID, product ID, manufacturer
string, product string, serial number string, and maximum current consumption. These parameters are
protected by a password which should be validated first in order to allow access to the nonvolatile memory.
This class also provides a method for changing the password.
The USB2SER_DLL class uses a Freescale proprietary USB CDC class to communicate with USB2SER
devices. Please ensure that the USB2SER USB driver has been installed before attempting to use the
USB2SER_DLL DLL.

Using USB2SER DLL in C# Projects, Rev. 1

Freescale Semiconductor 5
 Using DLLs in a C# Project

2.2.2 USB2SER_DLL application programming interface

Public Variables: The USB2SER_DLL uses public variables as inputs and outputs for the methods. The
variables listed below are read-only variables used by the ReadUSBDescriptors method:
public bool VendorID
public bool ProductID
public bool StrManufacturer
public bool StrProduct
public bool StrSerial
public bool NumConsumption

The variables listed below are read/write variables and are used by the application. The BusPowered
variable configures whether the device is self- or bus-powered. The SerialAutoIncrement variable
configures whether the serial number string is incremented each time the nonvolatile memory is written or
whether it remains unchanged.
public bool BusPowered
public bool SerialAutoIncrement
public bool HexFormat

2.2.3 Methods
Table 1. USB2SER C# Methods

Syntax Description Parameters Return

OpenPort public bool Opens the serial port to communicate COM: string containing the TRUE: port closed
OpenPort(string with the USB2SER device and enters serial port to open successfully
COM); the device in loader mode. Only one FALSE: port can´t
port can be opened at the time. be closed
ClosePort public bool Closes the serial port opened by the Void TRUE: port closed
ClosePort(); OpenPort method. Closes the port but successfully
the device remains in loader mode. FALSE: port can´t
be closed
ClosePort public bool Closes the serial port opened by the Void TRUE: port closed
AndReset ClosePortAnd OpenPort method and forces the successfully
Reset(); USB2SER device to come out of loader FALSE: port can´t
mode by performing a software reset. be closed
Should be used when an error occurs
or just before closing the main
application.
Validate public bool Validates the password string, sends Password: string containing the TRUE: port closed
Password ValidatePassword the password validation command, and password to be validated by the successfully
_CMD _CMD (string waits for the answer. USB2SER. Must always be 16 FALSE: port can´t
Password); characters long. Only be closed
hexadecimal values are valid.
Change public bool Validates the password string, sends Password: string containing the TRUE: port closed
Password ChangePassword the command to change the current new password. Must always be successfully
_CMD _CMD(string password, and waits for the answer. 16 characters long. Only FALSE: port can´t
Password); hexadecimal values are valid. be closed
Change public bool Validates the vendor ID string, sends VendorID: string containing the TRUE: port closed
VendorID ChangeVendorID the command to change the current new vendor ID. Must always be successfully
_CMD _CMD(string vendor ID, and waits for the answer. 4 characters long. Only FALSE: port can´t
VendorID); hexadecimal values are valid. be closed

Using USB2SER DLL in C# Projects, Rev. 1

6 Freescale Semiconductor
 Using DLLs in a C# Project

Table 1. USB2SER C# Methods (continued)

Syntax Description Parameters Return

Change public bool Validates the product ID string, sends ProductID: string containing the TRUE: port closed
ProductID ChangeProductID the command to change the current new product ID. Must always be successfully
_CMD _CMD(string product ID, and waits for the answer. 4 characters long. Only FALSE: port can´t
ProductID); hexadecimal values are valid. be closed
Change public bool Validates the manufacturer string, strManufacturer: string TRUE: port closed
Manufacturer ChangeManufacturer sends the command to change the containing the new successfully
String_CMD String_CMD current manufacturer string, and waits manufacturer string. Must be FALSE: port can´t
(string for the answer. from 1–63 characters long. be closed
strManufacturer); Valid range is any printable
character from 32–126.
Change public bool Validates the product string, sends the strProduct: string containing TRUE: port closed
Product ChangeProduct command to change the current the new product string. Must be successfully
String_CMD String_CMD(string product string, and waits for the answer. from 1–63 characters long. FALSE: port can´t
strProduct); Valid range is any printable be closed
character from 32–126.
Change public bool Closes the serial port opened by the strSerialNum: string containing TRUE: port closed
Serial ChangeSerialNumber OpenPort method. Closes the port, but the new serial number string. successfully
Number String_CMD(string the device remains in loader mode. Must be from 1–63 characters FALSE: port can´t
String_CMD strSerialNum); long. Valid range is any be closed
printable character from
32–126.
Change public bool Validates the milliamperes string, Milliamperes: string containing TRUE: port closed
MaxCurrent ChangeMaxCurrent sends the command to change the the new current consumption successfully
Consumption Consumption_CMD maximum current consumption, and value. The valid range is even FALSE: port can´t
_CMD (string waits for the answer. values from 20–500 mA, if the be closed
Milliamperes); bus-powered option is
selected. For self-powered the
valid value must be 0.
ReadUSB public bool Sends the command to read the entire Void TRUE: port closed
Descriptors ReadUSBDescriptors nonvolatile memory where the USB de- successfully
_CMD _CMD(); scriptors are located. Stores the USB FALSE: port can´t
descriptors in the following public vari- be closed
ables:
Public string VendorID
Public string ProductID
Public string StrManufacturer
Public string StrProduct
Public string StrSerial
Public string NumConsumption
DiscoverUSB public string Validates the VID and PID parameters VID: string containing the Returns NULL if
Device DiscoverUSBDevice and polls all enumerated USB devices vendor ID to match. the desired VID
(string VID, looking for those that have the desired PID: string containing the and PID was not
string PID); VID and PID. product ID to match. found. Returns a
Both parameters must always string containing
be 4 characters long. Only the friendly port
hexadecimal values are valid name if the desired
VID and PID were
found.

Using USB2SER DLL in C# Projects, Rev. 1

Freescale Semiconductor 7
 Serial Production GUI User Guide

Table 1. USB2SER C# Methods (continued)

Syntax Description Parameters Return

Validate public bool Validates if the password is in strField: string to be validated TRUE: string is
Password ValidatePassword hexadecimal format and 16 characters valid
(string strField); long. FALSE: string is not
valid
Validate public bool Validates if the product ID is in strField: string to be validated TRUE: port closed
VendorID ValidateVendorID hexadecimal format and 4 characters successfully
(string strField); long. FALSE: port can´t
be closed
Validate public bool Validates if the product ID is in strField: string to be validated TRUE: port closed
ProductID Validate hexadecimal format and 4 characters successfully
ProductID(string long. FALSE: port can´t
strField); be closed
Validate public bool Validates if the manufacturer string is a strField: string to be validated TRUE: port closed
Manufacturer Validate printable ASCII symbol not longer than successfully
String ManufacturerString 63 characters. FALSE: port can´t
(string strField); be closed
Validate public bool Validates if the product string is a strField: string to be validated TRUE: port closed
Product ValidateProduct printable ASCII symbol not longer than successfully
String String(string 63 characters. FALSE: port can´t
strField); be closed
Validate public bool If the SerialAutoIncrement variable is strField: string to be validated TRUE: port closed
SerialNum ValidateSerial false, this method validates if the successfully
String NumString(string product string is a printable ASCII FALSE: port can´t
strField); symbol not longer than 63 characters.If be closed
the SerialAutoIncrement variable is true
and the HexFormat variable is false,
this method validates that the product
string is in decimal format and no
longer than 8 characters.
If the SerialAutoIncrement variable is
true and the HexFormat variable is true,
this method validates that the product
string is in hexadecimal format and not
longer than 8 characters.
Validate public bool If the BusPowered variable is true, this strField: string to be validated TRUE: port closed
MaxCurrent ValidateMaxCur- method validates that the maximum successfully
Consumption rentConsumtion current consumption is between FALSE: port can´t
(string strField); 20–500 mA. If the BusPowered vari- be closed
able is false, this method validates that
the maximum current consumption is
0 mA.

3 Serial Production GUI User Guide

This section explains how the serial production GUI example works. The serial production GUI allows the
reading and writing of the USB2SER USB descriptors by using the USB2SER_DLL DLL.
The serial production GUI has only one form named MainForm.

Using USB2SER DLL in C# Projects, Rev. 1

8 Freescale Semiconductor
 Serial Production GUI User Guide

3.1 Valid formats and values for USB descriptors’ fields

The methods ValidatePassword, ValidateVendorID, ValidateProductID, ValidateManufacturerString,
ValidateProductString, ValidateSerialNumString, and ValidateMaxCurrentConsumption can be called by
the application at any time. These methods are useful for validating any field on the C# form before
executing any read or write process.
The serial production GUI uses these methods to ensure all fields on the MainForm are within a valid
range. A pop-up error notification is displayed if an error is detected.

3.2 Discover USB devices

To establish communication with the USB2SER device, the USB host must first enumerate the device. The
enumeration process assigns a COM port to the USB2SER device. The port number assigned by the USB
host can be any number. Any application trying to communicate with the USB2SER needs to know the
port number to open it and to be able to send and receive data.
The USB2SER_DLL has a utility, named DiscoverUSBDevice, for the discovery of USB devices. This
method can detect and receive information about any USB device enumerated on the USB host. The scope
of this method was reduced to detect only USB CDC class devices.
Since the USB host can enumerate USB CDC class devices other than the USB2SER device, the
DiscoverUSBDevice method receives a vendor ID and a product ID as parameters to discover only those
devices that its vendor ID and product ID match with the received parameters.

Using USB2SER DLL in C# Projects, Rev. 1

Freescale Semiconductor 9
Conclusion

The serial production GUI is intended to communicate with one USB2SER device at the time. Ensure that
no more than one device with the same vendor ID and product ID is connected.

3.3 Read USB descriptors

To read the USB descriptors, the field’s current password, current vendor ID, and current product ID must
be filled before pressing the READ button. The reading process uses the DiscoverUSBDevice method to
discover the port number of the enumerated USB2SER device. If the READ button is pressed and no
USB2SER device is enumerated, the process stays in a loop until the device is enumerated or the STOP
button is pressed. When the device is connected to the USB host, the reading process starts automatically.

3.4 Customize USB descriptors

To customize the USB descriptors, all fields on the form must be filled before pressing the AUTO button.
Once all fields are completed, the AUTO button can be pressed to start the customization process. This
process uses the DiscoverUSBDevice method to discover the port number of the enumerated USB2SER
device. If the AUTO button is pressed and no USB2SER device is enumerated, the process stays in a loop
until the device is enumerated or the STOP button is pressed. When the device is connected to the USB
host, the customization process starts automatically. This process allows the customization of several
devices in an automated manner much like a serial production line. So when the customization process
ends, the next device can be connected and the application will start to customize the device automatically
using the same parameters.
The serial number string can be modified using the same value if the “Auto incremental serial number”
box is not checked.
The serial number string can be modified using an incremental value if the “Auto incremental serial
number” box is checked. In this mode, the initial string will be increased each time a USB2SER device is
connected on the USB host. The number is increased in hexadecimal format if the “Hexadecimal format”
box is checked. Otherwise the number is increased in decimal format.

4 Conclusion
The DLLs described in this document provide a secure way to use previously-validated methods and
objects. They also allow code reuse and speed up the development of new designs. DLLs also protect
intellectual property since the DLL does not provide source code.

Using USB2SER DLL in C# Projects, Rev. 1

10 Freescale Semiconductor
 Revision History

5 Revision History
Table 2. Revision History

Version Changes

Rev. 0 First public version of this document.

Rev. 1 Changed “USB2SER SDA” to “USB2SER” in first paragraph on page 1.

Using USB2SER DLL in C# Projects, Rev. 1

Freescale Semiconductor 11
How to Reach Us: Information in this document is provided solely to enable system and software
implementers to use Freescale Semiconductor products. There are no express or
Home Page: implied copyright licenses granted hereunder to design or fabricate any integrated
www.freescale.com circuits or integrated circuits based on the information in this document.

Web Support:
http://www.freescale.com/support Freescale Semiconductor reserves the right to make changes without further notice to
any products herein. Freescale Semiconductor makes no warranty, representation or
USA/Europe or Locations Not Listed: guarantee regarding the suitability of its products for any particular purpose, nor does
Freescale Semiconductor, Inc. Freescale Semiconductor assume any liability arising out of the application or use of any
Technical Information Center, EL516 product or circuit, and specifically disclaims any and all liability, including without
2100 East Elliot Road
Tempe, Arizona 85284 limitation consequential or incidental damages. “Typical” parameters that may be
+1-800-521-6274 or +1-480-768-2130 provided in Freescale Semiconductor data sheets and/or specifications can and do vary
www.freescale.com/support in different applications and actual performance may vary over time. All operating
parameters, including “Typicals”, must be validated for each customer application by
Europe, Middle East, and Africa: customer’s technical experts. Freescale Semiconductor does not convey any license
Freescale Halbleiter Deutschland GmbH under its patent rights nor the rights of others. Freescale Semiconductor products are
Technical Information Center not designed, intended, or authorized for use as components in systems intended for
Schatzbogen 7 surgical implant into the body, or other applications intended to support or sustain life,
81829 Muenchen, Germany
+44 1296 380 456 (English) or for any other application in which the failure of the Freescale Semiconductor product
+46 8 52200080 (English) could create a situation where personal injury or death may occur. Should Buyer
+49 89 92103 559 (German) purchase or use Freescale Semiconductor products for any such unintended or
+33 1 69 35 48 48 (French) unauthorized application, Buyer shall indemnify and hold Freescale Semiconductor and
www.freescale.com/support its officers, employees, subsidiaries, affiliates, and distributors harmless against all
claims, costs, damages, and expenses, and reasonable attorney fees arising out of,
Japan: directly or indirectly, any claim of personal injury or death associated with such
Freescale Semiconductor Japan Ltd. unintended or unauthorized use, even if such claim alleges that Freescale
Headquarters
ARCO Tower 15F Semiconductor was negligent regarding the design or manufacture of the part.
1-8-1, Shimo-Meguro, Meguro-ku,
Tokyo 153-0064 For information on Freescale’s Environmental Products program, go to
Japan http://www.freescale.com/epp.
0120 191014 or +81 3 5437 9125
[email protected]
Freescale™ and the Freescale logo are trademarks of Freescale Semiconductor, Inc.
Asia/Pacific: All other product or service names are the property of their respective owners.
Freescale Semiconductor China Ltd. © Freescale Semiconductor, Inc. 2011. All rights reserved.
Exchange Building 23F
No. 118 Jianguo Road
Chaoyang District
Beijing 100022
China
+86 10 5879 8000
[email protected]

For Literature Requests Only:

Freescale Semiconductor Literature Distribution Center
1-800-441-2447 or 303-675-2140
Fax: 303-675-2150
[email protected]

Document Number: AN4314

Rev. 1
07/2011