SLAA453A january   2011  – may 2023

 

  1.   1
  2. 1MSP430™ USB HID Windows API Programmer's Guide
  3. 2Introduction
  4. 3Implementation
    1. 3.1 Overview
    2. 3.2 File Organization
    3. 3.3 System Requirements
    4. 3.4 MSP430 USB API Stacks
    5. 3.5 How Windows Maps Physical USB HID Devices to the Host Application
    6. 3.6 Locating a Specific HID Device/Interface on the System and Opening It
    7. 3.7 Sending/Receiving Data
    8. 3.8 Detecting the Dynamic Connection/Disconnection of HID Devices
  5. 4Function Call Reference
    1. 4.1 Device Connection Management and Initialization Calls
      1. 4.1.1 VOID HID_Init(struct strHidDevice* pstrHidDevice)
      2. 4.1.2 DWORD HID_GetSerNums(WORD vid, WORD pid, struct strTrackSerialNumbers *serialNumList)
      3. 4.1.3 DWORD HID_GetNumOfInterfaces(WORD vid, WORD pid, DWORD numSerNums)
      4. 4.1.4 BYTE HID_Open(struct strHidDevice* pstrHidDevice, WORD vid, WORD pid, DWORD deviceIndex, char serialNumber[SERNUM_LEN], DWORD totalDevNum, DWORD totalSerNum)
      5. 4.1.5 BYTE HID_Close(struct strHidDevice* pstrHidDevice)
      6. 4.1.6 BYTE HID_GetVersionNumber(struct strHidDevice* pstrHidDevice, USHORT * VersionNumber)
    2. 4.2 Sending/Receiving Data
      1. 4.2.1 BYTE HID_WriteFile(struct strHidDevice* pstrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesSent)
      2. 4.2.2 BYTE HID_ReadFile(struct strHidDevice* pStrHidDevice, BYTE* buffer, DWORD bufferSize, DWORD* bytesReturned)
    3. 4.3 Plug and Play Management
      1. 4.3.1 BYTE HID_RegisterForDeviceNotification(HWND hWnd, HDEVNOTIFY* diNotifyHandle)
      2. 4.3.2 BYTE HID_UnregisterForDeviceNotification(HDEVNOTIFY* diNotifyHandle)
      3. 4.3.3 BOOL IsDeviceAffected(struct strHidDevice* pstrHidDevice)
  6. 5Demo Application
  7. 6MSP430 USB Tool Suite
  8.   HID Interface Data Structure: strHidDevice
  9.   Format of Reports on HID-Datapipe Devices
  10.   C References
  11.   C Revision History

3.5 How Windows Maps Physical USB HID Devices to the Host Application

Every USB device contains a vendor ID (VID) and a product ID (PID). USB hosts use the VID/PID combination to identify product types. It stands to reason that all products of a given PID from a vendor of a given VID are functionally identical. The host associates all devices with that VID/PID with a particular USB device class – for example, HID or CDC. Whenever it encounters this VID/PID, it loads that particular driver.

Above the Windows HID driver, things look slightly different. The HID driver maintains a list of "HID devices" on the bus, selectable by a generic index, and makes this list available to the host application above it. The "HID devices" in this list are logical entities, not physical USB devices. These logical entities don't necessarily map directly to the physical devices on the bus.

As an example, it is possible that more than one "HID device" with a given VID/PID may be reported to the host application. This could mean there are multiple physical devices of a given product type attached to this host; or it might be that there is a composite device that has multiple HID interfaces (which can be thought of as logical devices). Further, if there are 4+ "HID devices", it is possible that both these factors are involved, as in Figure 3-2.

GUID-81CB5D7E-4D24-4DBA-866B-0A5AD8A59A36-low.gif Figure 3-2 Mapping of "HID Interfaces" to "HID Devices" on a Windows System

In this figure, the Windows application cannot immediately know what these "HID devices" represent in the real world.

If the host application wants to be functional in this kind of multiple-device situation – or further, to be able to take advantage of multiple HID datapipes on a physical device – it needs to probe further. One important piece of information it needs to gather from each HID device is the serial number (marked as "sernum" in Figure 3-2). A USB device can optionally report a serial number that identifies a unique piece of physical equipment among all others containing the same VID/PID. (The MSP430 USB API stacks can automatically report a serial number, if selected to do so with the Descriptor Tool.)

Once the host application has the VID, PID, and serial number of every HID device it sees on the bus, it can begin to understand the situation on the bus. If it finds two HID devices with a given VID/PID, with the serial numbers also the same, then it can know this is a composite HID device that has two HID interfaces. If, instead, these two HID devices have different serial numbers, then the application is looking at two physical single-interface HID devices.

With these techniques, the developer can then design devices with multiple HID interfaces, using each one as a datapipe for a particular kind of information – the equivalent of multiple COM ports. Among other benefits, this helps overcome the bandwidth limitation of a single HID interface (64 kbps). As many as eight HID interfaces can be run in parallel on an MSP430, providing 512-kbps bandwidth.

It should be added that if Windows recognizes in the USB descriptors that this device is a mouse or keyboard during initial enumeration, then Windows itself becomes the "host application" for this HID device. It issues report requests and uses the data to control the mouse on the screen or input data for text entry.