Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Current »

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 use of these constants defined usually in app_cfg.h or app_usbd_cfg.h allows you to use the vendor demo application.

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.

The constants configuration for the Windows application are independent from the device application constants configuration presented in .

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 . Let’s assume a device with two vendor interfaces.

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

Running the Vendor Class Demo Application

illustrates the Echo demo with host and device interactions:

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 .

In the example of , the demo will handle 10 transfers. Each transfer is sent after the header following the simple protocol described in . 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.  presents the execution.

The demo will propose to do a new execution.  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.  shows an example of a 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.

  • No labels