Developer´s Corner

HID USB and SPLAT Messages

Download a printable version of this page here: (HIDUSB.pdf)

An X-keys with MacroWorks software provides tremendous versatility for most applications and users, but a developer may need more control of special devices such as jog wheels, knobs, sliders, and other similar input devices. With direct access to the control data, your application gains a far more accurate level of user input. X-keys SPLAT messages are directly available to the developer at the application level. This allows direct access to the X-keys hardware without MacroWorks.

The ability to access the actual position data from a jog wheel, for example, has many advantages. The speed that the user spins a wheel can be very fast or extremely slow, and often they need different outcomes at these extremes. Keyboard keystroke emulation has limitations for this type of input and if the application developer has access to the raw data, the program can be optimized to provide the best experience for the user. This is especially important when a developer wants to use a standard input device, such as a joystick or trackball, in a non-standard way. A trackball could be used to change a color value for example and not drive the cursor.

Note: SPLAT is not an acronym.  It is the sound a toad makes when landing in wet concrete.  The original description of our data report format was Special HID Input Terminology, and we found that acronym to be inappropriate.

The HID Consumer Page

The USB HID class has defined a complete hierarchy that allows devices to send data based on descriptors to several locations. (keyboard, mouse, joystick, etc.). While standard devices send their data to locations where the OS intercepts and sends it out to the active application, a device can be configured to send data that is not fully recognized by the OS but still managed and stored by the native USB HID drivers.

Most operating systems provide a good location for this type of data in the HID Consumer Page. While keyboard, mouse, and joystick locations have dedicated data types and formats, the HID Consumer Page allows for a flexible, vendor defined data format.  X-keys SPLAT Messages go to the HID driver on the consumer page.

X-keys Modes of Operation

X-keys are normally used in one of 3 ways.

  1. Hardware Mode -- the X-keys simply sends native keyboard and/or mouse commands to the OS.
  2. Software Mode with MacroWorks software -- the X-keys sends SPLAT Messages to the HID driver and MacroWorks translates them into the desired response such as a keystroke or mouse action.
  3. Software Mode with a Custom Application -- the X-keys sends SPLAT Messages to the HID driver and a developer translates them into the desired response within his application.

There are advantages and disadvantages of each one of these uses. Often an advantage for one application or use may be a disadvantage for another.

Hardware Mode

X-keys in Hardware Mode sending native keyboard and mouse messages

In Hardware Mode the X-keys declares itself as a native USB keyboard and/or mouse and sends only USB keyboard or mouse messages to the USB port.  The macros are stored in the X-keys onboard memory and played when the appropriate X-keys button is pressed. After originally programming the X-keys there is no software involved. This mode is very similar to our PS/2 keyboard emulating X-keys.

The data flow is simple and direct. The X-keys sends out a series of USB key codes, and the OS sends these to the active application just as if they were from a standard USB keyboard or mouse.   

    Advantages:
  1. Macros are stored in X-keys so they are always carried with the device.
  2. No special software is required on the user’s machine.
  3. The user can’t change the programming.
  4. The OS and Applications see only normal keyboard and mouse messages with no way to differentiate between messages from the X-keys and messages from the main keyboard or mouse. 
  5. After programming, the X-keys can be used on any OS (Linux, UNIX and other non-windows OS’s).
  6. Very low latency for mouse messages.
    Drawbacks:
  1. Data is limited to normal keystrokes and simple mouse commands.
  2. X-keys must be preprogrammed.*
  3. X-keys are not instantly reprogrammable by end user.*
  4. Memory limit onboard the X-keys limits the maximum size of the macro.
  5. Data is always managed by the OS and sent to the active application as if it were native keyboard or mouse data
  6. No support for non-standard devices such as a jog knob, T-bar or LCD.
  7. No support for feed back to X-keys devices (LCD X-keys for example requires some software to send the display messages.)
    Typical uses:
  1. When it is not allowed or wise to install any special software on an end users computer.
  2. Using a Linux or Unix type OS.
  3. If a user often uses the device on a new or different computer and does not need the flexibility of instant reprogramming.*

*MacroWorks or other PI software is used to program X-keys and put them into Hardware Mode.  If the software is installed on the computer, X-keys can still be programmed and reprogrammed, but the process takes longer as the memory is read or written to.

Software mode with MacroWorks

MacroWorks sends keybaord and mouse data to the OS

In this mode the X-keys transmits simple data (SPLAT messages) to the HID consumer page and MacroWorks translates the data into useful actions. This is the standard “out of the box” configuration for most X-keys because it provides the greatest utility for general use with Windows operating systems.

In this mode there is a programming GUI and macros can be quickly recorded and edited. The macros are stored on the computer and have virtually unlimited length. More complicated macros can be developed including timing delays, combinations of mouse and keyboard commands, and Windows specific functions like launching applications, opening directories, or getting date and time from the OS.

The Data flow is more complicated than other modes. The X-keys sends simple HID consumer page SPLAT Messages to the USB HID driver. These messages are recognized by MacroWorks through PIEHID.dll.  MacroWorks then correlates the message from the X-keys to the desired actions recorded in MacroWorks as scripts. It sends messages to the OS keyboard stream, mouse stream or to some other known windows functions based on these scripts.

Underlying MacroWorks is a complete scripting language, allowing complicated macros to be developed by the user or others in the X-keys community. This scripting language allows correlation of multiple events from more than one X-keys or it can create application specific macros.

    Advantages:
  1. Very versatile, can be used with multiple Windows applications.
  2. Macros are stored on the computer with no size limitation.
  3. Convenient GUI for instant programming and reprogramming.
  4. Powerful scripting language built in to allow extensive user customization if needed.
  5. Can send macros to specific applications and access other OS functions
  6. Supports unique input devices such as the Jog knob.
  7. Can send data back to an X-keys device such as the LCD
    Drawbacks:
  1. MacroWorks software must be installed.
  2. MacroWorks only supports Windows XP and Vista.
  3. End user has access to scripts and could change the programming.
  4. In most cases MacroWorks must still emulate keyboard and mouse messages to communicate with an application.
  5. MacroWorks does not know which input field has focus so key data could be sent to the place.
  6. Some latency in emulating mouse commands.
    Typical uses:
  1. General Windows “helper” macro pad.
  2. Workflow keyboard for consumer applications
  3. Customization of actions on single button when the user does not have access to the application developer.
  4. Controlling simple functions in the OS without losing focus.

Software Mode with a Custom Application

PIEHID.DLL communicates directly with your custom application

In Software Mode an application developer can access the data (SPLAT Messages) from X-keys directly. This gives the developer complete control of the hardware-software interaction. This mode is direct and simple for specific applications where the X-keys will be dedicated to one purpose and the software can be written to directly interact with the X-keys. P.I. Engineering, Inc has developed extensive SDKs with programming examples in several popular programming languages (Visual Studio (VS) C# 2008 Express, VS C++ 2005 and VS Visual Basic 2008 Express) to assist developers. PIEHID.dll (provided with the SDK) is a special dll that makes accessing the SPLAT messages on the HID consumer page very easy.

In this mode the X-keys transmits data (SPLAT messages) to the HID consumer page, PIEHID.dll picks up the messages and holds them for the application. The custom developed application receives the messages from PIEHID.dll and performs the required action.

The application can also send SPLAT Messages to the X-keys through PIEHID.dll to change LED states or send text to an LCD display. P.I. Engineering has also added a "Dongle" feature to many of our X-keys which allows the developer to query the X-keys for an encrypted response code.

    Advantages:
  1. Direct Hardware-Software interaction without OS interference.
  2. No visible software other than the developer's application.
  3. End-user can not alter the behavior of the hardware beyond what was designed by the application developer.
  4. Simple data flow.
  5. Software can be designed to require the presence of X-keys hardware to prevent unlicensed use.
  6. All hardware actions can be processed in appropriate context for the state of the application as determined by the devleoper providing the best end user experience.
  7. Simple installation with application for end-user.
    Drawbacks:
  1. Requires developer to write custom code into their own application.
  2. Generally limits X-keys to single application.
  3. Does not easily allow end user the full benefits of MacroWorks in other applications.
  4. Not often possible if software was developed by other parties.
    Typical uses:
  1. Specialized software that wishes to use complete functionality of the X-keys and provide the end user with the best possible experience.
  2. Software "dongle" protection with out the offense of an actual dongle.
  3. Software that wishes to provide the end user with a simple dedicated hardware interface.

For More Information

Learn more about HID and SPLAT messages in our P.I. Engineering SDKs or contact us by E-mail: tech@xkeys.com

Download a printable copy of this document here: HIDUSB.pdf

 

Join our Private Developer's E-mail List


© Copyright 2010, P.I. Engineering, Inc. All rights reserved.

Visit Our Other Product Sites:

RailDriver.com
Ship Driver