Using the Vendor Class Demo Application

Micrium provides a demo application that lets you test and evaluate the class implementation. Source template files are provided for the device. Executable and source files are provided for Windows host PC.

Note that the demo application provided by Micriµm is only an example and is intended to be used as a starting point to develop your own application.

Configuring PC and Device Applications for Vendor Class

The demo used between the host and the device is the Echo demo. This demo implements a simple protocol allowing the device to echo the data sent by the host.

On the device side, the demo application file, app_usbd_vendor.c, provided for µC/OS-II and µC/OS-III is located in this folder:

\Micrium\Software\uC-USB-Device-V4\App\Device\

app_usbd_vendor.c contains the Echo demo available in two versions:

The Echo Sync demo exercises the synchronous communication API described in the Synchronous Communication section.
The Echo Async demo exercises the asynchronous communication API described in the Asynchronous Communication section.

The use of these constants defined usually in app_cfg.h or app_usbd_cfg.h allows you to use the vendor demo application.

Table - Device Application Constants Configuration

Constant	Description	File
`APP_CFG_USBD_VENDOR_EN`	General constant to enable the Vendor class demo application. Must be set to `DEF_ENABLED`.	`app_usbd_cfg.h`
`APP_CFG_USBD_VENDOR_ECHO_SYNC_EN`	Enables or disables the Echo Sync demo. The possible values are `DEF_ENABLED` or `DEF_DISABLED`.	`app_usbd_cfg.h`
`APP_CFG_USBD_VENDOR_ECHO_ASYNC_EN`	Enables or disables the Echo Async demo. The possible values are `DEF_ENABLED` or `DEF_DISABLED`.	`app_usbd_cfg.h`
`APP_CFG_USBD_VENDOR_ECHO_SYNC_TASK_PRIO`	Priority of the task used by the Echo Sync demo.	`app_cfg.h`
`APP_CFG_USBD_VENDOR_ECHO_ASYNC_TASK_PRIO`	Priority of the task used by the Echo Async demo.	`app_cfg.h`
`APP_CFG_USBD_VENDOR_TASK_STK_SIZE`	Stack size of the tasks used by Echo Sync and Async demos. A default value can be 256.	`app_cfg.h`

APP_CFG_USBD_VENDOR_ECHO_SYNC_EN and APP_CFG_USBD_VENDOR_ECHO_ASYNC_EN can be set to DEF_ENABLED at the same time. The vendor device created will be a composite device formed with two vendor interfaces. One will represent the Echo Sync demo and the other the Echo Async demo.

On the Windows side, the demo application file, app_vendor_echo.c, is part of a Visual Studio solution located in this folder:

\Micrium\Software\uC-USB-Device-V4\App\Host\OS\Windows\Vendor\Visual Studio 2010

app_vendor_echo.c allows you to test:

One single device. That is Echo Sync or Async demo is enabled on the device side.
One composite device. That is Echo Sync and Async demos are both enabled on the device side.
Multiple devices (single or composite devices).

app_vendor_echo.c contains some constants to customize the demo.

Table - Windows Application Constants Configuration

Constant	Description
`APP_CFG_RX_ASYNC_EN`	Enables or disables the use of the asynchronous API for IN pipe. The possible values are `TRUE` or `FALSE`.
`APP_MAX_NBR_VENDOR_DEV`	Defines the maximum number of connected vendor devices supported by the demo.

The constants configuration for the Windows application are independent from the device application constants configuration presented in Table - Windows Application Constants Configuration.

Editing an INF File

An INF file contains directives telling to Windows how to install one or several drivers for one or more devices. Refer to the About INF Files section for more details about INF file use and format. The Vendor class includes two INF files located in \Micrium\Software\uC-USB-Device-V4\App\Host\OS\Windows\Vendor\INF:

WinUSB_single.inf, used if the device presents only one Vendor class interface.
WinUSB_composite.inf, used if the device presents at least one Vendor class interface along with another interface.

The two INF files allows you to load the WinUSB.sys driver provided by Windows. WinUSB_single.inf defines this default hardware ID string:

USB\VID_FFFE&PID_1003

While WinUSB_composite.inf defines this one:

USB\VID_FFFE&PID_1001&MI_00

The hardware ID string contains the Vendor ID (VID) and Product ID (PID). In the default strings, the VID is FFFE and the PID is either 1003 or 1001. The VID/PID values should match the ones from the USB device configuration structure defined in usb_dev_cfg.c. Refer to the Modify Device Configuration section for more details about the USB device configuration structure.

If you want to define your own VID/PID, you must modify the previous default hardware ID strings with your VID/PID.

In the case of a composite device formed of several vendor interfaces, in order to load WinUSB.sys for each vendor interface, the manufacturer section in WinUSB_composite.inf can be modified as shown in Listing - INF File Example for Composite Device Formed of Several Vendor Interfaces. Let’s assume a device with two vendor interfaces.

Listing - INF File Example for Composite Device Formed of Several Vendor Interfaces

[MyDevice_WinUSB.NTx86]
%USB\MyDevice.DeviceDesc% =USB_Install, USB\VID_FFFE&PID_1001&MI_00
%USB\MyDevice.DeviceDesc% =USB_Install, USB\VID_FFFE&PID_1001&MI_01
 
[MyDevice_WinUSB.NTamd64]
%USB\MyDevice.DeviceDesc% =USB_Install, USB\VID_FFFE&PID_1001&MI_00
%USB\MyDevice.DeviceDesc% =USB_Install, USB\VID_FFFE&PID_1001&MI_01
 
[MyDevice_WinUSB.NTia64]
%USB\MyDevice.DeviceDesc% =USB_Install, USB\VID_FFFE&PID_1001&MI_00
%USB\MyDevice.DeviceDesc% =USB_Install, USB\VID_FFFE&PID_1001&MI_01

You can also modify the [Strings] section of the INF file in order to add the strings that best describe your device. Listing - Editable Strings in the INF File to Describe the Vendor Device shows the editable [Strings] section common to WinUSB_single.inf and WinUSB_composite.inf.

Listing - Editable Strings in the INF File to Describe the Vendor Device

[Strings]
ProviderName            ="Micrium"                                            (1)
USB\MyDevice.DeviceDesc ="Micrium Vendor Specific Device"                     (2)
ClassName               ="USB Sample Class"                                   (3)

(1) Specify the name of your company as the driver provider.

(2) Write the name of your device.

(3) You can modify this string to give a new name to the device group in which your device will appear under Device Manager. In this example, “Micrium Vendor Specific Device” will appear under the “USB Sample Class” group. Refer to Figure - Windows Device Manager Example for a CDC Device for an illustration of the strings used by Windows.

Running the Vendor Class Demo Application

Figure - Echo Demo illustrates the Echo demo with host and device interactions:

Figure - Echo Demo

Echo Demo

(1) The Windows application executes a simple protocol consisting of sending a header indicating the total payload size, sending the data payload to the device and receiving the same data payload from the device. The entire transfer for data payload is split into small chunks of write and read operations of 512 bytes. The write operation is done using a bulk OUT endpoint and the read uses a bulk IN endpoint.

(2) On the device side, the Echo Sync uses a task that complements the Windows application execution. Each step is done synchronously. The read and write operation is the opposite of the host side in terms of USB transfer direction. Read operation implies a bulk OUT endpoint while a write implies a bulk IN endpoint.

(3) If the Echo Async is enabled, the same steps done by the Sync task are replicated but using the asynchronous API. A task is responsible to start the first asynchronous OUT transfer to receive the header. The task is also used in case of error during the protocol communication. The callback associated to the header reception is called by the device stack. It prepares the next asynchronous OUT transfer to receive the payload. The read payload callback sends back the payload to the host via an asynchronous IN transfer. The write payload callback is called and either prepares the next header reception if the entire payload has been sent to the host, or prepares a next OUT transfer to receive a new chunk of data payload.

Upon the first connection of the vendor device, Windows enumerates the device by retrieving the standard descriptors. Since Microsoft does not provide any specific driver for the Vendor class, you have to indicate to Windows which driver to load using an INF file (refer to the About INF Files section for more details about INF). The INF file tells Windows to load the WinUSB generic driver (provided by Microsoft). Indicating the INF file to Windows has to be done only once. Windows will then automatically recognize the vendor device and load the proper driver for any new connection. The process of indicating the INF file may vary according to the Windows operating system version:

Windows XP directly opens the “Found New Hardware Wizard”. Follow the different steps of the wizard until the page where you can indicate the path of the INF file.
Windows Vista and later won’t open a “Found New Hardware Wizard”. It will just indicate that no driver was found for the vendor device. You have to manually open the wizard. Open the Device Manager, the vendor device connected appears under the category ‘Other Devices’ with a yellow icon. Right-click on your device and choose ‘Update Driver Software...’ to open the wizard. Follow the different steps of the wizard until the page where you can indicate the path of the INF file.

The INF file is located in:

\Micrium\Software\uC-USB-Device-V4\App\Host\OS\Windows\Vendor\INF

Refer to the About INF Files section for more details about how to edit the INF file to match your Vendor and Product IDs.

Once the driver is successfully loaded, the Windows host application is ready to be launched. The executable is located in the following folder:

\Micrium\Software\uC-USB-Device-V4\App\Host\OS\Windows\Vendor\Visual Studio 2010\exe\

There are two executables:

EchoSync.exe for the Windows application with the synchronous communication API of USBDev_API.
EchoAsync.exe for the Windows application with the asynchronous IN API of USBDev_API.

The Windows application interacts with WinUSB driver via USBDev_API which is a wrapper of WinUSB driver. USBDev_API is provided by Micrium. Refer to the USBDev_API page for more details about USBDev_API and WinUSB driver.

The Echo Sync or Async demo will first determine the number of vendor devices connected to the PC. For each detected device, the demo will open a bulk IN and a bulk OUT pipe. Then the demo is ready to send/receive data to/from the device. You will have to enter the maximum number of transfers you want as shown by Figure - Demo Application at Startup.

Figure - Demo Application at Startup

Demo Application at Startup

In the example of Figure - Demo Application at Startup, the demo will handle 10 transfers. Each transfer is sent after the header following the simple protocol described in Figure - Echo Demo. The first transfer will have a data payload of 1 byte. Then, subsequent transfers will have their size incremented by 1 byte until the last transfer. In our example, the last transfer will have 10 bytes. Figure - Demo Application Execution (Single Device) presents the execution.

Figure - Demo Application Execution (Single Device)

Demo Application Execution (Single Device)

The demo will propose to do a new execution. Figure - Demo Application Execution (Single Device) shows the example of a single device with 1 vendor interface. The demo is able to communicate with each vendor interface in the case of a composite device. In that case, the demo will open bulk IN and OUT pipes for each interface. You will be asked the maximum number of transfers for each interface composing the device. Figure - Demo Application Execution (Composite Device) shows an example of a composite device.

Figure - Demo Application Execution (Composite Device)

Demo Application Execution (Composite Device)

GUID

A Globally Unique IDentifier (GUID) is a 128-bit value that uniquely identifies a class or other entity. Windows uses GUIDs for identifying two types of devices classes:

Device setup class
Device interface class

A device setup GUID encompasses devices that Windows installs in the same way and using the same class installer and co-installers. Class installers and co-installers are DLLs that provide functions related to the device installation. A device interface class GUID provides a mechanism for applications to communicate with a driver assigned to devices in a class. Refer to the Using GUIDs section for more details about the GUID.

Device setup class GUID is used in WinUSB_single.inf and WinUSB_composite.inf located in \Micrium\Software\uC-USB-Device-V4\App\Host\OS\Windows\Vendor\INF. These INF files define a new device setup class that will be added in the Windows registry under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Class upon first connection of a vendor device. The following entries in the INF file define the new device setup class.

Class     = MyDeviceClass                          ; Name of the device setup class.

ClassGuid = {11111111-2222-3333-4444-555555555555} ; Device setup class GUID

The INF file allows Windows to register in the registry base all the information necessary to associate the driver Winusb.sys with the connected vendor device.

The Windows Echo application is able to retrieve the attached vendor device thanks to the device interface class GUID. WinUSB_single.inf and WinUSB_composite.inf define the following device interface class GUID: {143f20bd-7bd2-4ca6-9465-8882f2156bd6}. The Echo application includes a header file called usbdev_guid.h. This header file defines the following variable:

GUID USBDev_GUID = {0x143f20bd,0x7bd2,0x4ca6,

                   {0x94,0x65,0x88,0x82,0xf2,0x15,0x6b,0xd6}};

USBDev_GUID is a structure whose fields represent the device interface class GUID defined in WinUSB_single.inf and WinUSB_composite.inf. The USBDev_GUID variable will be passed as a parameter to the function USBDev_Open(). A handle will be returned by USBDev_Open(). And the application uses this handle to access the device.