USBHID in the MIA Softclient – Guide for hardware manufacturers (EN)

USBHID in the MIA Softclient – Guide for hardware manufacturers

Introduction

The MIA SIP softclient has the capability to natively support HID USB devices such that calls can be made or hung up at a touch of a button on an HID USB device [1], [2].

All the MIA application has to know is a unique ID of a headset device and how to translate messages from a headset device into actions taken by the MIA SIP softphone.

The USB HID interface

MIA, as well as other SIP softphones based on the SDK from Global IP Telecommunications provide a portable and comfortable way to enumerate devices that are connected to the Universal Serial Bus (USB) and that feature HID (Human Input Device) functionality. The goal is to enable the user to select a specific USB HID device and to receive button events from that device.

Supported operating systems are currently the Windows and the Linux platform which differ substantially from each other. While device paths are comparably long under the Windows OS, the Linux OS has the disadvantage that USB devices are protected. A telephone application must either run with superuser privileges or access rights must be changed so that applications running with user mode rights can as well access a specific device.

The shell command

su chmod 666 /dev/hidraw1

MUST be invoked in order to allow the USBHID functionality built into this library access to the USB HID device /dev/hidraw1, which in this specific case may be a USB headset.

Internals: The inbound message “USBHIDDeviceList”

Internally, a specific XML tag is used to inform the softclient about the available USB HID devices.

Whenever the device list changes, the SIP engine sends this message and the list of devices in the GUI changes.

In order to keep the XML as simple as possible, <USBHIDDeviceList> … </USBHIDDeviceList> encapsulates a single string that can potentially be very long as all HID-compliant USB devices are contained, sometimes even with multiple HID interfaces per device. It is encapsulated in a <SystemEvent> XML node.

Example:

<?xml version="1.0" encoding="UTF-8" ?>

<Allow>INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY, REFER, MESSAGE, INFO</Allow>

<InputAudioDeviceName>Jabra LINK 360</InputAudioDeviceName>

<OutputAudioDeviceName>Jabra LINK 360</OutputAudioDeviceName>

<USBHIDDeviceList>VID:PID="0e0f:0003";UsagePage="0";Usage="0";

InterfaceNumber="0";FilePath="/dev/hidraw0";ManufacturerString="Vmware";

ProductString="VMware Virtual USB Mouse";SerialNumber="";

VID:PID="0b0e:a346";UsagePage="0";Usage="0";

InterfaceNumber="3";FilePath="/dev/hidraw1";ManufacturerString="";

ProductString="Jabra LINK 360";SerialNumber="1C48F9F40301011800";

</USBHIDDeviceList>

</SystemEvent>

...

</System>

</sip>

The USBHIDDeviceList message for has the following parameters (each parameter within exclamation marks):

VID:PID= Vendor ID:Product ID.

UsagePage= Organization of usages into pages of related controls. “11” e.g stands for “telephony”. Under Linux, “0” is always provided.

Usage= HID usage comunicates the intended function or meaning of a particular control. ”01” e.g. stands for “Phone” and “05” e.g. stands for “Headset”. Under Linux, “0” is always provided.

InterfaceNumber= An HID device may feature more than one interface. In the example above the device with VID:PID 0b0e:a346 exposes a single interface. This interface is numbered with “3”.

FilePath= This parameter specifies the file path that is used to communicate with the device.

ManufacturerString= Contains the manufacturer of the respective USB device. The string may be empty.

ProductString= This parameter contains the name of the product.

SerialNumber= A value might be provided in this string which might be helpful to distinguish two or more identical USB HID devices that are connected to a computer. The string may although be empty as the manufacturer might assume that it is highly unlikely that e.g. two identical headsets are connected to one PC.

Internals: The command “USBHIDCommand”

In order to connect to a specific USB HID device and subsequently to receive button events, the command “USBHIDCommand” can be issued once the device is known.

<?xml version="1.0" encoding="UTF-8"?>

<sip>

<USBHIDCommand>Command="ListenToUSBHIDDevice";

VID:PID="0b0e:a346";SerialNumber="1C48F9F40301011800";

FilePath="/dev/hidraw1";

</USBHIDCommand>

</System>

</sip>

The command has the following parameters:

Command= Is either “ListenToUSBHIDDevice” or “StopListeningToUSBHIDDevice”.

VID:PID= Vendor ID:Product ID.

FilePath= This parameter specifies the file path that is used to communicate with the device. If no file path is known, the Vendor ID and the Product ID are used to access the USB device.

SerialNumber= A value might be provided in this string which might be helpful to distinguish two or more identical USB HID devices that are connected to a computer. If no serial number is known, this parameter can be omitted.

Success is communicated by the SIP engine by the USBHIDMessageList message.

In order to change the device to listen to, it is not necessary to dispatch the “StopListeningToUSBHIDDevice” command as the connection to the previously selected device is automatically closed prior to opening the new connection.

Internals: Inbound message “USBHIDMessageList”

This message is used to inform the softclient about successful connection to a specific USB HID device and about button events.

In order to keep the XML as simple as possible, <USBHIDMessageList> … </USBHIDMessageList> encapsulates a single string containing messages that are separated by semicolon characters. It is encapsulated in a <SystemEvent> XML node.

Example:

<?xml version="1.0" encoding="UTF-8" ?>

<Allow>INVITE, ACK, CANCEL, OPTIONS, BYE, SUBSCRIBE, NOTIFY, REFER, MESSAGE, INFO</Allow>

<InputAudioDeviceName>Jabra LINK 360</InputAudioDeviceName>

<OutputAudioDeviceName>Jabra LINK 360</OutputAudioDeviceName>

<USBHIDMessageList>Connected to /dev/hidraw1;</USBHIDMessageList>

</SystemEvent>

</System>

</sip>

In the example the successful connection to a device with the file path /dev/hidraw1 is reported. If the attempt to connect to a device has failed, the following XML is issued:

<USBHIDMessageList>Not connected to /dev/hidraw1;</USBHIDMessageList>

If a button has been pressed on the USB HID device that is currently listened to, a sequence of numbers ranging between 0 .. 255 and separated by commas is issued. In the following example, two messages are dispatched:

Each message can contain up to 64 numbers. Messages are separated by semicolons.

Tool for creating or updating definitions files in MIA

The link between a USB HID headset device and the MIA SIP softphone is an XML file that is created or updated using the control “Feature Mapping for Headsets” in the MIA settings dialog:

	Number		Description
	1		HID Device. Select the most appropriate HID USB usage page and the device for which you want to create or update an XML definition file.

	2		Received device events Once a specific USB HID device and usage page has been selected, MIA receives events from the device it is connected with. This includes the open event, as well as device events that comprise up to 64 numbers that are displayed as comma-separated strings.

	3		Meaning of last Event If the last event e.g. means “Toggle between on hook/off hook”, simply click at the “Off Hook Toggle” button in order to give MIA the chance to logically link this event to the corresponding function.

	4		Save Definition Once you have finished assigning HIDUSB events to functions, a click at this button saves the XML file in the roaming directory of the application. The assignment is now active and can be tested. If the same headset device is used again, the XML definition file is automatically read and clicking at the button(s) on the headset should result in MIA executing the associated command(s).

Currently only “Off Hook Toggle” is fully implemented. We’re always happy to receive XML definition files for USB HID headset devices that are currently not supported.

The goal is to encourage manufacturers to make their devices emit HID USB events that allow for remote-control of MIA and similar applications through a simple mapping between USB HID events and their intended function.

Example of a definition file for IPN’s W980 wireless headset, the first wireless headset that does NOT require a vendor-specific software developers kit:

File name:

DECT Headset_DevIfGUID={4D1E55B2-F16F-11CF-88CB-001111000030

}_VIDPID=3006-1977_UsgPg=11_Usg=5.xml

<?xml version="1.0" encoding="UTF-8"?>

<OnOff_Hook_toggle>3,0,0,0,0</OnOff_Hook_toggle>

<OnOff_Hook_toggle>3,1,0,0,0</OnOff_Hook_toggle>

</Definition>

</Definitions>

The Cisco 561 wireless headset is another example for USB HID headset devices that are compatible with MIA nd similar applications without the need for a vendor-specific SDK:

File name: Cisco 561 SB_DevIfGUID={4D1E55B2-F16F-11CF-88CB-001111000030}_VIDPID=05a6-0018_UsgPg=11_Usg=5.xml

<?xml version="1.0" encoding="UTF-8"?>

<OnOff_Hook_toggle>8,2</OnOff_Hook_toggle>

</Definition>

</Definitions

Literature

[1] USB Implementers' forum, Device Class Definition for Human Interface Devices (HID), 2001, http://www.usb.org/developers/hidpage/HID1_11.pdf

[2] USB Implementers' forum, HID Usage Tables, 2004, http://www.usb.org/developers/hidpage/Hut1_12v2.pdf