X-keys Integration

Integration Hardware

X-keys are normally used in one of 3 ways

  • Hardware Mode -- the X-keys simply sends native USB commands to the OS
  • 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, mouse, or other action
  • 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 the application

Integration Overview

Hardware Mode

Integration Hardware

In Hardware Mode the X-keys declares itself as a native USB keyboard (and/or mouse, game controller, or media controller) and sends messages to the operating system. 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, no special software is required or involved.

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


  • Macros are stored in X-keys so they are always carried with the device
  • No special software is required on the user's machine
  • The end user can't easily change the programming
  • The OS and Applications see only normal USB messages with no way to differentiate between messages from the X-keys and messages from any other USB hardware (keyboard, mouse, or controller)
  • After programming, the X-keys can be used on any OS (Linux, UNIX, and other non-windows OS's)
  • Very low latency for mouse messages


  • X-keys must be preprogrammed
  • X-keys are not instantly reprogrammable by end user
  • Memory limit onboard the X-keys limits the maximum size of the macro.
  • Data is always managed by the OS and sent to the active application as if it were native keyboard or mouse data
  • No support for feed back to X-keys devices

Typical Uses:

  • When it is not allowed or wise to install any special software on an end users computer
  • Using a Linux or Unix type OS If a user often uses the device on a new or different computer and does not need the flexibility of instant reprogramming

Software Mode with MacroWorks

Integration Software

MacroWorks is P. I. Engineering's Windows based software for X-keys.

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 MacroWorks provides a programming GUI and macros can be quickly recorded and edited. The macros may be stored on the computer and have virtually unlimited length. More complicated macros can be developed including timing delays, combinations of mouse, keyboard, and other 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 (Visual Basic), 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.


  • Very versatile, can be used with multiple Windows applications
  • Macros are stored on the computer with no size limitation
  • Convenient GUI for instant programming and reprogramming
  • Powerful scripting language built in to allow extensive user customization if needed
  • Can send macros to specific applications and access other OS functions
  • Supports unique input devices such as the Jog knob
  • Can send data back to an X-keys device (controlling backlighting for example)


  • MacroWorks software must be installed
  • End user has access to scripts and could change the programming
  • In most cases MacroWorks must still emulate keyboard and mouse messages to communicate with an application
  • Some latency in emulating mouse commands.

Typical Uses:

  • General Windows “helper” macro pad.
  • Workflow keyboard for consumer applications
  • Customization of actions on single button when the user does not have access to the application developer
  • Controlling simple functions in the OS without losing focus

Software Mode with Custom Application

Integration Software Custom

In Software Mode an application developer can access the data (SPLAT Messages) from the 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 for example).


  • Direct Hardware-Software interaction without OS interference
  • No visible software other than the developer's application
  • End-user can not alter the behavior of the hardware beyond what was designed by the application developer
  • Simple data flow
  • All hardware actions can be processed in appropriate context for the state of the application as determined by the developer providing the best end user experience
  • Simple installation with application for end-user


  • Requires developer to write custom code into their own application
  • Generally limits X-keys to single application
  • Does not easily allow end user the full benefits of MacroWorks in other applications
  • Not often possible if software was developed by other parties

Typical Uses:

  • Specialized software that wishes to use complete functionality of the X-keys and provide the end user with the best possible experience
  • Software that wishes to provide the end user with a simple dedicated hardware interface.