Table of contents
TOC
Collapse the table of content
Expand the table of content

Windows radial controller feature reports

Last Updated: 2/16/2017

This topic details the HID feature reports that are used for radial controller haptic feedback support in Windows 10, version 1607 and later operating systems.

Haptic feedback collection (optional)

If a Windows radial controller device supports haptic feedback, it can allow the system and applications to take advantage of it by including a haptic feedback collection (Page 0x0E, usage 0x01) within the Windows radial controller TLC. For more information on how the HID specification supports haptic feedback, please consult the new haptics page ratification to the HID specification.

The host uses the following usages (through the haptic feedback collection) to communicate the haptic feedback waveform support and allow the host to configure the haptic feedback on the Windows radial controller device. If a device chooses to expose a haptic feedback collection, some usages are mandatory to allow automatic haptic feedback configuration to be supported.

MemberDescriptionPageIDMandatory/Optional
Waveform ListOrdered list of haptic waveforms supported by the device0x0E0x10Mandatory
Duration ListOrdered list of durations for waveforms in the Waveform List0x0E0x11Mandatory
Auto TriggerWaveform to fire automatically at device’s discretion0x0E0x20Mandatory
Auto Trigger Associated ControlHID usage of the control associated with haptic feedback0x0E0x22Mandatory
IntensityOutput – Intensity of Manual Trigger waveform as a percentage0x0E0x23Optional
Repeat CountOutput – Number of times to play Manual Trigger waveform after initial play0x0E0x24Optional
Retrigger PeriodOutput – Duration of time to wait before retriggering Manual Trigger when repeating0x0E0x25Optional
Waveform Cutoff TimeMax time a Manual Trigger waveform can play before being cut off0x0E0x28Optional

Waveform List

Waveform List usage represents a collection of the HID usages of supported waveforms, ordered using ordinals. The pre-defined haptics waveforms are defined in the HID specification. Windows supports implementing the following waveforms for a haptic feedback enabled device:

WaveformDescriptionPageIDMandatory/Optional
WAVEFORM_NONENo-op. Should not impact the play state of ongoing waveforms.0x0E0x1001Mandatory
WAVEFORM_STOPStops the playback of ongoing waveforms.0x0E0x1002Mandatory
WAVEFORM_CLICKCreates a short “click” feedback0x0E0x1003Mandatory
WAVEFORM_BUZZ_CONTINUOUSBuzzes the device for an extended duration of time0x0E0x1004Optional

Both WAVEFORM_NONE and WAVEFORM_STOP are required for all HID-compliant haptics devices. Ordinals 1 and 2 are implicitly set to WAVEFORM_NONE and WAVEFORM_STOP. They do not need to be declared in the Waveform List or Duration List. The Waveform List declares supported waveforms by the physical minimum and maximum of each ordinal in the list.

Duration List

Duration List usage represents a collection of the durations for the supported waveforms in the Waveform list, ordered using ordinals. The unit for waveform duration is milliseconds, and duration must be a positive non-zero value for any non-continuous waveform. If a waveform is continuous (will play until stopped by the host or the Waveform Cutoff Time is exceeded), then its duration is defined as zero.

WAVEFORM_NONE and WAVEFORM_STOP are assumed to have a duration of zero. They do not need to be declared in the Duration List.

Auto Trigger

The Auto Trigger usage represents a supported waveform usage from the Waveform List which will be triggered automatically by the device as needed based on user interactions. This allows lower-latency response to common user interactions like rotation and clicking. This may need to be modified or disabled by the host, and can be set via a feature report. The Auto Trigger waveform can be disabled by being set to zero by the host.

Auto Trigger Associated Control

The Auto Trigger Associated Control specifies the extended HID usage of the physical control associated with automatic haptic feedback on the device. For a radial controller device, this control should be defined as the Dial usage specified within the same top level collection.

Intensity

The Intensity usage represents the percentage of maximum intensity to apply to a waveform. This value should vary between 0 and 100 percent. 100 percent indicates waveforms will be triggered by the device at their maximum strength, and 0 percent indicates the haptic transducer is not enabled.

If defined in a feature report, it sets the default intensity for all Auto Trigger and Manual Trigger waveforms for the device.

Repeat Count

The Repeat Count usage represents the number of times to repeat a waveform. A Repeat Count of zero indicates the Manual Trigger waveform should only be played a single time (no repeat). If the Waveform Cutoff Time has been exceeded, it is expected that any incomplete repeats will be ignored.

If defined in a feature report, it sets the default repeat count for all Auto Trigger and Manual Trigger waveforms for the device.

Retrigger Period

The Retrigger Period usage represents the amount of time for the device to wait before repeating a Manual Trigger waveform in an output report, per the value specified by Repeat Count. The units for this value are milliseconds. If the Retrigger Period is smaller than the duration of the waveform being played, the waveform should be stopped and restarted at the time period indicated by the retrigger period.

If defined in a feature report, it sets the default retrigger period for all Auto Trigger and Manual Trigger waveforms for the device.

Waveform Cutoff Time

The Waveform Cutoff Time usage represents the maximum amount of time the device will allow a Manual Trigger waveform to be repeated before ending playback. This is a constant value for the device and includes both continuous waveforms without set durations, and waveforms with discrete durations which are set to repeat many times. The units for this value are milliseconds.

© 2017 Microsoft