Download - X KeyPad - Stick and Rudder Studios

[Type text] [Type text] [Type text]

X-KeyPad

User’s Guide

10/29/2018 Stick and Rudder Studios

Stick and Rudder Studios Copyright © 2018 Stick and Rudder Studios, LLC. | All Rights Reserved

Page | 1

Table of Contents Change Log .................................................................................................................................................... 3

Release Notes ............................................................................................................................................... 3

1.1 ............................................................................................................................................................. 3

License Keys .......................................................................................................................................... 3

Key State Dataref Arrays ....................................................................................................................... 3

Master / Slave Numeric Datarefs .......................................................................................................... 3

1.0 ............................................................................................................................................................. 4

Introduction .................................................................................................................................................. 4

Licensing ........................................................................................................................................................ 4

Copyright ................................................................................................................................................... 4

Registration ............................................................................................................................................... 4

Purchasing from the Stick and Rudder Studios Website ...................................................................... 5

Purchasing from the X-Plane.org Store ................................................................................................. 5

Installation .................................................................................................................................................... 5

Platform Support .......................................................................................................................................... 5

Configuring X-KeyPad .................................................................................................................................... 5

General Information ................................................................................................................................. 5

Commands ................................................................................................................................................ 7

X-KeyPad.csv File Format .......................................................................................................................... 8

Loading the Numeric Buffer .................................................................................................................. 9

Command Execution ........................................................................................................................... 10

Piggyback Commands ......................................................................................................................... 10

Advanced Dataref Manipulation ......................................................................................................... 11

Making Changes to the File ................................................................................................................. 11

X-Keys.csv Configuration and File Format .............................................................................................. 11

Overview ............................................................................................................................................. 11

File Format .......................................................................................................................................... 16

Led Evaluation ..................................................................................................................................... 17

Example 4 ............................................................................................................................................ 19

Executing Commands .......................................................................................................................... 19

Shifting ................................................................................................................................................ 23


Page | 2

Controlling the Leds and reading key state with Lua Scripts .............................................................. 24

Other Samples ............................................................................................................................................. 25

Settings........................................................................................................................................................ 25

Tips and Other References .......................................................................................................................... 27

Commands vs Datarefs ........................................................................................................................... 27

Dataref Tool ............................................................................................................................................ 27

Bitwise AND Operations .......................................................................................................................... 27

FlyWithLua .............................................................................................................................................. 27

XSaitekPanels .......................................................................................................................................... 28

Editing CSV Files ...................................................................................................................................... 28

Tips for X-Key devices ................................................................................................................................. 28

Hardware vs. Software Mode ................................................................................................................. 28

Limitations .................................................................................................................................................. 29

Support ....................................................................................................................................................... 29

Appendix ..................................................................................................................................................... 30

Defined Commands ................................................................................................................................. 30

Defined Datarefs ..................................................................................................................................... 31


Page | 3

Change Log

Version Changes

1.1 Added support for X-Plane.org store keys in preparation for selling on the store

Added the ability to enter and validate your key from the menu

Added dataref arrays for current key state and key pressed flag

Added the ability to specify up to 15 slave numeric datarefs that will be set simultaneously with the master

1.0 Initial Release Table 1

Release Notes

1.1

License Keys

Stick and Rudder Studios products are now offered on the X-Plane.org store. In preparation for that event we needed to enhance X-KeyPad to support license keys that will be provided as part of the X-Plane.org store checkout process. As part of this enhancement we now provide the ability to enter your key using the clipboard paste function from the “Validate Registration” menu item.

Key State Dataref Arrays

X-KeyPad now exposes two additional array datarefs: SRS/X-KeyPad/current_key_states[128] READ ONLY SRS/X-KeyPad/key_pressed_flags[128] The current_key_states holds 128 integers, index 0-127 representing up to 128 keys on an X-Key device. A 1 indicates that key is currently down and a 0 indicates that it is up. The array is read only. The key_pressed_flags also hold 128 integers. A 1 indicates that the key was pressed. You must write a 0 after processing and logic in order to capture the next key press. This dataref is more likely to be used with Lua scripts using the do_often callback which runs once per second.

Master / Slave Numeric Datarefs

You can now specify up to 15 slave numeric datarefs in both the X-Keys.csv file and the X-KeyPad.csv file. The master / slave datarefs are separated by a ; similar to the ability to specify multiple commands. The first dataref is considered the master and it will be set based upon any numeric data that was entered or using the master’s current value and incrementing or decrementing according to those rules. Once the master is set all the slaves will be set to the same value.


Page | 4

This should cut down on the logic necessary in a Lua script to keep multiple similar datarefs in sync. Look at the XK-80 sample for the default 737 panel lights key for an example of how this can be used.

1.0 Initial product release

Introduction X-KeyPad is a plugin for X-Plane 10 and 11 that supports setting any numeric simulator variable by collecting numeric input from either a keyboard or game controller and then, in response to a command, setting a specified simulator variable (dataref) to the numeric input value. X-KeyPad can also be used with PI Engineering X-Key devices to control the red and blue backlighting of individual keys based on dataref values or by lua scripts. X-KeyPad can work with any keyboard or game controller to set numeric simulator variables. A PI Engineering X-Key device is just one example. Cherry POS keyboards or Genovation ControlPads are just two examples of devices that may prove to be useful with X-KeyPad due to the fact that many of these units have keyboard keys that can have their legends customized. Programmable backlighting support is only available with PI Engineering X-Key devices.

Licensing

Copyright X-KeyPad is copyrighted software.

You have the right to use this software for personal, non-commercial use in a flight simulator on a single PC.

You may not redistribute the software in any way including o Posting it on the internet o Embedding it in another product o Transmitting or sharing the files with a third party in any way

You may not share or publish your license key if you are running the registered version.

You may make a backup copy of the software for archival purposes

Registration X-KeyPad operates in an unregistered and registered mode. The unregistered mode is free to use and does not require a license key. With the unregistered version you can define up to 10 numeric datarefs that can be set with numeric buffer data. You can also program the backlighting of keys 0 – 31 of a PI Engineering X-Keys device.

http://xkeys.com/xkeys/xkeypad.php



Page | 5

The registered mode requires the purchase of a license key. Registered mode allows you to define up to 50 numeric datarefs as well as allowing you program keys 0 – 127 on an X-Key device.

Purchasing from the Stick and Rudder Studios Website

When you purchase your key directly from Stick and Rudder Studios we create a text file containing your key and email address. This file, license.txt, will be delivered upon purchase to your email account as an email with a text file attachment. The attachment needs to be saved to the X-KeyPad folder and must be named license.txt

X-Plane 11\Resources\plugins\X-KeyPad\license.txt Once the key file is installed and X-Plane is either restarted or you refresh your configuration data from the X-KeyPad menu, X-KeyPad will indicate that it is registered by a log entry in log.txt as well as indicating the registration mode in the X-KeyPad plugin menu item “About”.

Purchasing from the X-Plane.org Store

If you purchase X-KeyPad from the X-Plane.org store a key will be provided during the checkout process. You can enter this key using the “Validate Registration” menu item. Once this is entered it will be stored in the aforementioned license.txt file so the key can be validated when X-Plane is started in the future.

Installation X-KeyPad is distributed as a ZIP archive. Unzip X-KeyPad.zip to a temporary directory and then copy the resulting X-KeyPad folder to your X-Plane plugins folder: X-Plane 11\Resources\plugins

Platform Support X-KeyPad will run on X-Plane 10 (32 and 64 bit) as well as X-Plane 11 64 bit. Only the Windows platform is supported at this time.

Configuring X-KeyPad

General Information There are two comma delimited files that are used to configure X-KeyPad.

1. X-KeyPad.csv 2. X-Keys.csv


Page | 6

X-KeyPad.csv is primarily used when you are not planning to use a P.I. Engineering X-Keys device. It is used to specify which X-Plane datarefs should be set with collected numeric data in response to an X-KeyPad command or a shadow X-Plane command. Shadow commands will be explained a little later in this guide. X-Keys.csv is used with a PI Engineering X-Key device to specify behavior for each key on the device:

Red and Blue back light behavior based on the state of an X-Plane dataref

X-Plane command execution on a key press o Command execution can be conditional based on the state of a simulator dataref o Multiple commands can be executed with a single key press

Numeric dataref to be set to an entered value when a key is pressed

Automatic incrementing and decrementing of a numeric dataref on key press

Optional text to speech that will be spoken by the simulator on a key press When a new aircraft is loaded in X-Plane, X-KeyPad will look for an X-KeyPad and / or an X-Keys csv file in the aircraft directory. The files must be named like this:

X-KeyPad_acfname.csv

X-Keys_acfname.csv As an example assume we wanted to have aircraft specific configuration files for the Laminar Cessna 172 G1000. In that case we would want the following files:

X-Plane 11\Aircraft\Laminar Research\Cessna 172SP\ X-KeyPad_Cessna_172SP_G1000.csv

X-Plane 11\Aircraft\Laminar Research\Cessna 172SP\ X-Keys_Cessna_172SP_G1000.csv

If X-KeyPad can find the above files it will use them. If they cannot be found then X-KeyPad will look for generic ones in the X-KeyPad folder:

X-Plane 11\Resources\plugins\X-KeyPad\X-KeyPad.csv

X-Plane 11\Resources\plugins\X-KeyPad\X-Keys.csv

The Samples folder contains sample X-KeyPad CSV files, X-Keys CSV files, and example Lua scripts. The remainder of this document primarily references the files in the Samples\ XK-80 folder. You will need to copy the CSV files from that folder to the appropriate aircraft folder if you wish to use those as a starting sample. Note: most examples also have a corresponding Lua script that should be placed in the FlyWithLua script directory. You can get FlyWithLua from here: https://forums.x-plane.org/index.php?/files/file/38445-flywithlua-ng-next-generation-edition-for-x-plane-11-win-lin-mac/



https://forums.x-plane.org/index.php?/files/file/38445-flywithlua-ng-next-generation-edition-for-x-plane-11-win-lin-mac/



Page | 7

Commands X-KeyPad defines a number of plugin commands that you can map to keyboard keys or joystick buttons using X-Plane’s command mapping feature. The following commands are used to fill the numeric buffer.

Command Purpose

SRS/X-KeyPad/Keypad_0 Adds a 0 character to the numeric buffer










SRS/X-KeyPad/Keypad_Decimal Adds a . character to the numeric buffer

SRS/X-KeyPad/Keypad_Minus Adds a - character to the numeric buffer

SRS/X-KeyPad/Keypad_Clear Clears the numeric buffer

SRS/X-KeyPad/Keypad_BackSpace Clears the last character entered in the numeric buffer

SRS/X-KeyPad/Toggle_Shift Toggles X-Keys shift mode on and off

SRS/X-KeyPad/Momentary_Shift Momentarily toggles X-Keys shift mode. It will toggle again as soon as the key or joystick button is released

Table 2

As soon as X-KeyPad detects any of the numeric commands it will begin to add them to the numeric buffer. The numeric data entry will be displayed as soon as numeric data is in it allowing you to see the contents. The window will be hidden as soon as a command is executed to load a dataref with the numeric buffer contents or if you execute the Clear numeric buffer command above. The data entry window can be moved around on the screen.


Page | 8

Figure 1

Commands SRS/X-KeyPad/Set_Sim_Variable_1 through SRS/X-KeyPad/Set_Sim_Variable_50 are used to set the corresponding datarefs in X-KeyPad_Datarefs.csv file to the value collected in the numeric buffer. If the numeric buffer is empty the command will be ignored. The use of these commands are primarily needed when working with devices other than the an X-Keys device.

X-KeyPad.csv File Format If you are using and X-Keys device we recommend skipping this section and looking at the X-Key.csv file format. It is only on rare occasions that you will need to use an X-KeyPad.csv file in conjunction with an X-Keys.csv file. X-KeyPad.csv is used to define the set of numeric datarefs that you wish to manipulate in response to directly executing one of the:

SRS/X-KeyPad/Set_Sim_Variable_1 through SRS/X-KeyPad/Set_Sim_Variable_50 or when a specified X-Plane command is detected. It can be used in conjunction with any game controller, keyboard, or keyboard emulator. The X-KeyPad.csv file is a simple comma delimited file that can be edited with any text file editor. If possible we would recommend using an editing tool that specifically handles comma delimited files. Microsoft Excel, Google Sheets, and Open Office Sheets are such tools. There are also a number of free tools available that are specifically oriented to editing CSV files.

The first line of the file is the column headers. The remainder of the file can contain up to 50 rows

defining 50 sim datarefs that can be set. X-KeyPad ships with a number of sample files. We are using the

Samples\Keyboard Only\ X-KeyPad.csv for this discussion. We suggest you open that file now and follow

along as we outline the file format.


Page | 9

The following table outlines the columns in each row.

Column Data Type Description

Name Text A descriptive name for the dataref. Note that you can place – in the front of the name to indicate that this line is commented out and won’t be read.

Comment Text Some comments about the dataref. Note: don’t use commas in here

Dataref Number Integer A number between 1 and 50 that maps to the X-KeyPad commands SRS/X-KeyPad/Set_Sim_Variable_1 through SRS/X-KeyPad/Set_Sim_Variable_50

Dataref Text The X-Plane writable dataref that will be set to the value collected in the numeric buffer when the X-KeyPad command Set_Sim_Variable_n is executed Specific elements of an array dataref are represented with a [n] at the end of the dataref name where n is the zero based index of element you want. See the Zibo 737 sample for examples.

Piggyback Command Text An optional X-Plane command that will be monitored for activity by X-KeyPad. See the section on piggyback commands for further detail

Multiply By Number A numeric factor that will be applied to the numeric buffer before setting the dataref. This is useful for datarefs like COM frequencies where it is more user friendly to enter frequencies in mega HZ but the dataref needs the data in 10K HZ units.

Min Number The minimum allowed value for the dataref

Max Number The maximum allowed value for the dataref

Increment Text If set to the word “WRAP” means the current value of the dataref will be incremented by 1 until greater than the max value and then it will be set to the min value. This is useful for enumerations such as the HSI selector. If set to the word “UP-DOWN” means the current value of the dataref will be incremented up to MAX and then it will be decremented down to MIN and then back up to MAX in a cycle. This tends to model a rotary switch or multi-position toggle switch with a fixed set of positions. If set to the word “DOWN-UP” incrementing will behave the same as UP-DOWN except that the first increment will be down.

Numeric Speech Text One or more strings separated by ; that can be selected based on comparison logic. The selected string will be spoken by the simulator if the Numeric Speech setting is enabled.

Table 3

Loading the Numeric Buffer


Page | 10

The numeric buffer is filled when X-KeyPad detects the commands specified in Table 2. As soon as one character is entered a floating window will appear showing you the numbers being entered. The window will remain visible until you close it, clear the buffer with the clear command, or a command is executed to set a dataref. If you are running X-Plane 11 this numeric window has a number of characteristics which can be adjusted using the Settings menu item. See the Settings section of this manual for more details.

Command Execution

When X-Keypad detects the execution the commands, Set_Sim_Variable_1 through Set_Sim_Variable_50, it will use the command number to find the corresponding entry in X-KeyPad_Datarefs.csv. Using the included sample file you will notice that at line 10 we have defined dataref # 9 as referencing the barometer dataref. Assuming you mapped a button or key to SRS/X-KeyPad/Set_Sim_Variable_9 X-KeyPad will detect that command and will look at the data referenced on line 10. If no data is present in the numeric buffer the command will be ignored. When data exists in the numeric buffer it will be converted to a floating point value and will be set in the X-Plane dataref “sim/cockpit2/gauges/actuators/barometer_setting_in_hg_pilot”. As soon as this is done the numeric buffer will be cleared in preparation for the next entry.

Piggyback Commands

Piggyback commands allow you to use a keyboard key or joystick button for two purposes. Let’s take the XPlane command “sim/transponder/transponder_ident” as an example. This command would be mapped to a key or button that when activated would toggle transponder ident. Refer to line 8 of the sample file. When X-KeyPad has a piggyback command specified it will constantly monitor and intercept any activation of that command. When it sees activation it will look to see if any numbers have been collected in the numeric buffer. If the buffer is empty X-KeyPad will allow the processing of the command to continue and the X-Plane transponder will start its IDENT cycle. If numbers exist in the numeric buffer when the piggyback command is intercepted then the specified dataref will be set to that value and the piggyback command will stop execution and not be passed on to X-Plane. Note:

Whenever you use a piggyback command your key or joystick button should be mapped to the piggyback command NOT the SRS/X-KeyPad/Set_Sim_Variable_x command.

If you are not using a piggyback command then your key or joystick button should be mapped to the SRS/X-KeyPad/Set_Sim_Variable_x where x is the Dataref Number in column three of the dataref CSV file.


Page | 11

Advanced Dataref Manipulation

There are more advanced capabilities that can be used to control numeric datarefs:

Multiply by a factor before storing

Incrementing

Min and Max testing

Using a set of shared datarefs to interact with Lua scripts

Selecting strings that can be spoken using the simulator’s built-in text to speech capabilities These advanced features are discussed in greater detail in the X-Keys.csv file format section. Many of the concepts can be applied to using X-KeyPad with other devices beside the P.I. Engineering X-Keys devices.

Making Changes to the File

X-KeyPad will read either the aircraft specific version or default version of X-KeyPad.csv whenever a plane is loaded or if you request a refresh from the menu item plugins/X-KeyPad/ Reload Configuration Files.

X-Keys.csv Configuration and File Format

Overview

X-KeyPad is integrated with the PI Engineering X-Keys SDK. This integration allows you to control the backlighting on many X-Key devices and it allows you to specify X-Plane commands you want executed on a key press.

Commands

An X-Keys device can be operated in a number of configurations.

Direct Interface

When using X-KeyPad we suggest that set your X-Keys device to its default factory settings and operate it in hardware mode. You can reset your device my using the MacroWorks menu item tools\advanced\reset to factory defaults. Resetting your device to factory defaults will erase all key definitions so the keys will not act as keyboard input or as a game controller button. This allows X-KeyPad to read the key presses directly from your X-Key device and execute the X-Plane commands you specify for each key. Here are some of the advantages to this approach:

X-KeyPad will detect input even when the simulator does not have window focus.



Page | 12

All command mapping is in the X-Keys.csv file. There is no need to have to go into X-Plane and map keys or joystick buttons to those commands.

Using this approach will likely reduce the number of X-Plane profiles you would need to handle the variations between planes.

You have the ability to execute commands conditionally based on the state of a simulator variable. This is particularly valuable when there is no toggle command available for a function.

You can execute a chain of up to 15 commands with a single key press

As Keyboard and/or Game Controller

You can optionally configure your X-Keys device to act as a keyboards and / or game controller. In this mode you will need to use MacroWorks or the Basic X-Keys setup utility to configure each key to be either a keyboard key or game controller button. Here are some advantages and disadvantages to this approach:

Advantages o Using MacroWorks you can create complex key sequences that will do multiple things

on a single key press including interacting with other programs beside X-Plane o You would use the familiar X-Plane keyboard or joystick mapping functionality to map

your keys to the X-Plane commands you want executed.

Disadvantages o X-Keys can only support 40 joystick buttons so if you buy and X-Keys device with more

than 40 keys some of those keys would need to be configured as keyboard keys. Those keys will be susceptible to problems of not getting input to the simulator if the simulator window does not have focus.

o You will need to map your keys to the associated commands in X-Plane and if you fly different planes you will need to make extensive use of X-Plane 11’s profiles to support the different mappings for each plane.

o It is more difficult to keep track of what keys are mapped to which functions.

Leds

Most X-Key devices have two banks of leds. Bank one are blue leds and bank two are red leds. Both of these banks can be controlled on a key by key basis. A blue or red led can be either off, on, or flashing. Leds can be controlled either by lua scripts or more commonly with the X-Keys.csv file. This csv file can either be aircraft specific or generic. See the sections above on naming conventions for aircraft specific led files. The led file specifies the key, 0 – 127 depending on the X-Key device, and the state of bank one and two. Each led state can be optionally controlled by values in a referenced logic dataref. When a logic dataref is involved you are able to specify a logical test expression for each Led condition as well as for command execution and Speech string selection.


Page | 13

Expression Meaning

=n True if the dataref equals n

>n True if the dataref is greater than n

<n True if the dataref is less than n

&n True if the bitwise AND of the dataref and n results in a non-zero value

!=n True if the dataref does not equal n

!>n True if the dataref is not greater than n

!<n True if the dataref is not less than n

!&n True if the bitwise AND of the dataref and n results in zero value

n Same as a bitwise AND above

!n Same as a NOT bitwise AND above Table 4

In most cases a simple equal to or less than / greater than expression will meet your needs. However, some simulator variables employ an approach of setting individual bits in a number to indicate the state of some system. The auto pilot system is a good example of this. In this case a bitwise AND (&) operation is employed to determine if the specified led or command state should be active if the AND operation evaluates to true. You can read more about bitwise operations here:

https://en.wikipedia.org/wiki/Bitwise_operation You may also find this logical AND calculator useful:

https://www.rapidtables.com/calc/math/binary-calculator.html For the following discussion on how to control leds we suggest you follow along with led file that can be found in Samples\XK-80\BE58\ X-Keys_Baron_58.csv. Note, if you have an X-Key device and you want to try this file with X-Plane you will need to make a copy and place it in the Baron 58 aircraft folder. This example file was designed to work with an XK-80 device that was configured with the following legends:

https://en.wikipedia.org/wiki/Bitwise_operation

https://www.rapidtables.com/calc/math/binary-calculator.html


Page | 14

Figure 2


Page | 15

The following image shows the key numbering on the XK-80:

Figure 3


Page | 16

File Format

The file contains multiple rows of information with each row representing the logical state of the two led banks under the key as well as the commands you want executed on a key press. The following table describes the columns:

Column Data Type Description

Name Text A descriptive name for this key. Note that you can place a – in front of the name to indicate that this is a comment line. The remainder of the line will not be processed.

Comment Text Comment for the key. Note: Don’t put any commas in here

X-Key Unit Number Integer A value for 0 – 7 to indicate which of up to eight connected X-Key devices this Key is on. A blank entry assumes unit 0

Shift Flag Integer 0 or empty indicates that this key definition is for the non-shifted state. A 1 indicates that it is for the shifted state.

Key Integer A number between 0 and 127 that represents the key backlighting being referenced

Logic Dataref Text An optional simulator dataref that can be used to determine the led state, command execution, and / or speech. Elements of an array dataref are specified using [n] at the end of the dataref name where n is the zero based index into the array

Float Scale Factor Integer If specified the Logic Dataref float will be multiplied by this number before any logic tests. This is only applied if the logic dataref is a float. If left blank a scale factor of 1 is assumed.

Bank 1 On Text A test expression that when true will light the blue led under the key. See Table 4

Bank 1 Blink Text A test expression that when true will flash the blue led under the key. See Table 4

Bank 2 On Text A test expression that when true will light the red led under the key. See Table 4

Bank 2 Blink Text A test expression that when true will flash the red led under the key. See Table 4

Command Logic Test Text A test expression that when true will select the true command / speech columns and when false will select the false / default command / speech columns. See Table 4. Note: a blank entry here evaluates to false.

False Command Text The X-Plane command to execute when the logic test above is false

True Command Text The X-Plane command to execute when the logic test above is true

False Speech Text The text to speak when the command logic test above is false. This column can also contain multiple strings separated by a ; that have been tagged with a selection expression using the data from the Logic dataref to select a specific string.

True Speech Text The text to speak when the command logic test above is true. This column can also contain multiple strings separated by a ; that have been tagged with a selection expression using the data from the


Page | 17

Logic dataref to select a specific string.

Numeric Dataref TEXT The optional numeric dataref to set when there are numbers in the data buffer or to increment if incrementing is specified

Multiply By Number A numeric factor that will be applied to the numeric buffer before setting the dataref. This is useful for datarefs like COM frequencies where it is more user friendly to enter frequencies in mega HZ but the dataref needs the data in 10K HZ units.

Min Number The minimum allowed value for the dataref

Max Number The maximum allowed value for the dataref

Increment Text If set to the word “WRAP” means the current value of the dataref will be incremented by 1 until greater than the max value and then it will be set to the min value. This is useful for enumerations such as the HSI selector. If set to the word “UP-DOWN” means the current value of the dataref will be incremented up to MAX and then it will be decremented down to MIN and then back up to MAX in a cycle. This tends to model a rotary switch or multi-position toggle switch with a fixed set of positions. If set to the word “DOWN-UP” incrementing will behave the same as UP-DOWN except that the first increment will be down.

Numeric Speech Text Up to 20 strings separated by ; that can be selected for speech using an expression format described in Table 4 and the data in the Numeric after it has been set or incremented.

Led Evaluation

Led State Precedence

If no dataref is specified then the default comparison number is a -1 which in binary is all bits set. If a logic dataref is specified the current value of the dataref is used for the logic test. This approach allows you to use a simple 1 in the led column to turn a led on or make it flash when no dataref is driving the logic. Blue and red Led states can either be Off, On, or Flashing. Blue and Red Leds can be controlled separately. Off is the assumed state. The On state expression is evaluated first and if true will light the led. If the On state is not true then we will evaluate the Blink expression and if true will flash the led.


Page | 18

Examples

The following examples are from the XK-80 sample X-Keys_Baron_58.csv file

Example 1

A simple blue led on example can be seen my looking at the COM1 XFR definition on line 13 of the sample file. This line refers to the logic needed to light the blue led under key number 10. This definition does not refer to any dataref and has a 1 on the bank 1 (blue led) column which will evaluate to true as a non-zero value and will cause the blue led to light under key 10 (COM1 XFR).

Example 2

Another example is the audio panel keys for COM1 – ADF2. In these examples we want the blue led lit when the audio monitoring is disabled for that radio and we want the blue led extinguished and the red illuminated when the radio is being monitored on the audio panel. Refer to the logic on line 4 of the sample file. This references key 2 which is labeled as COM1 audio. The dataref sim/cockpit2/radios/actuators/audio_selection_com1 will be 0 when COM1 is NOT being monitored and will be 1 when COM1 is being monitored. Bank 1 on has a !1 in it. The 1 will be logically anded with the dataref value. Since there is a ! symbol in front of the 1 the blue led will be lit when the dataref value is NOT 1. In comparison, the bank 2 (red led) on state has a 1. This will evaluate to true when anded with the dataref when it contains a 1. Since this does not have an ! symbol in front the red led will light when COM1 is being monitored. Another way to express this would be the example for COM2. In this case we light the blue led when the dataref is <1 and light the red led when it is >0. As you can see, there are multiple ways to use logic expressions to control the leds.

Example 3

A considerably more complex example can be seen with the NAV key #25 on line 38 of the sample file. The backlighting of this key is intended to show the three states of the autopilot NAV mode, off, arm, and capture. Off we want represented by a blue led, arm is a flashing red led, and capture is a steady red led. The sim/cockpit/autopilot/autopilot_state dataref is used to evaluate the NAV mode state. Each bit in this dataref indicates the state of a particular autopilot mode. Refer to the following link for a description of this dataref: http://www.xsquawkbox.net/xpsdk/mediawiki/Sim/cockpit/autopilot/autopilot_state The bank 1 state is specified by !768. The two decimal number values representing the HNAV armed and HNAV engaged state, 512 and 256 are added together to get 768. This value is then inverted with ! to indicate that the blue led should be on when BOTH HNAV bits are 0. The red led will be steady on when 512 is anded with the dataref indicating that the HNAV engaged bit is set. The red led will flash when 256 is anded indicating that the HNAV arm bit is set.

http://www.xsquawkbox.net/xpsdk/mediawiki/Sim/cockpit/autopilot/autopilot_state


Page | 19

Example 4

In some cases the underlying dataref is a float that has values in the range of 0 to 1. Since all logic expressions must be done with an integer to support the AND operation the float values to the right of the decimal point are truncated. So you would only be able to evaluate 0 and 1. The Float Scale Factor can be used to magnify the float value to it can be more accurately evaluated as an integer. Look at the flaps up and down definitions on line 27 and 36 for keys 23 and 31. Note that we scale the dataref up by a factor of 100 before it is evaluated. This turns the flaps deploy ratio into a flaps percent deploy value that ranges from 0 to 100. This allows us to have the leds blue when the flaps are fully retracted, red when fully deployed, and flashing when partially deployed. This same technique is also used for the gear leds.

Executing Commands

You can specify the commands you want executed on key press in columns M and N. Commands can be conditional if you specify a logic test in column L (Command Logic Test). If you do not specify a logic test the default command in column M will be executed. Up to 15 commands can be executed with a single key press by separating the command definitions with a ;. Look at the DE-ICE example for the Baron 58 on line 33, key #28. If you have specified an X-Plane command in any of the Command columns X-KeyPad will execute that command once when the key is pressed. Commands can have a continuous modifier as a prefix. Look at line 57 of the Baron 58 sample. Notice the * in front of the command reference “sim/radios/obs_HSI_down”. The asterisk tells X-KeyPad to execute the command in continuous mode while you continue to hold the key down. Both the CRS Down and CRS Up keys use this to make the HIS OBS dial move either down or up continuously while the key is held down. Without the asterisk the command will only execute once and you will need to release the key and press it again to execute the command multiple times. Note: If you plan to use your X-Keys device as a keyboard and / or game controller you will want to do all your mappings in X-Plane and not specify any commands here. If you do both you are likely to get duplicate command executions in the simulator.

Speech

For each key press you can specify optional text that will be spoken by the simulator. The text spoken can be conditionally selected using the Command Logic Test expression. Columns O and P are where you specify the speech you want spoken.


Page | 20

The logic test is exactly the same as it is for commands. You can also globally turn this feature on or off from the X-KeyPad settings UI. You also have the ability to specify multiple strings separated by a ; that also must have a trailing expression tag that will be used with the data in the Logic dataref to select a specific string. Note, the data used for this expression will be based on the contents of the Logic dataref AFTER any commands have been executed.

Example

Take a look at the Baron 58 example in the XK-80 Samples folders. Refer to line 36, key # 31 which is the flaps up key. Note that we are using the Logic dataref

sim/cockpit2/controls/flap_handle_deploy_ratio which we scaled by a factor of 100 to represent the percent flaps deployment. Our Speech string contains:

Flaps Fully Retracted[=0];Flaps 50 Percent[=100];Flaps 0 Percent[>40] Note that each string is separated by a ; and has an ending logic expression tag enclosed in []. After the flaps command is executed X-KeyPad will use the logic expression with the data in the Logic Dataref to evaluate each tagged string from left to right. The first string whose logic tag evaluates to TRUE will be spoken by the simulator.

Numeric Dataref

Columns Q through U specify the optional operation of a numeric dataref associated with this key.

Example 1

A typical example is setting the COM frequency. Look at line 4, key 2 of the Baron 58 sample. When this key is pressed to toggles COM1 monitoring on or off using the command:

sim/audio_panel/monitor_audio_com1 However, we want to be able to use the same key to set COM1 to a frequency if we have entered that frequency in the numeric data window. Column O identifies the numeric dataref:

sim/cockpit/radios/com1_freq_hz Which represents the frequency of COM1 in 10KHz increments. When X-KeyPad sees that you pressed this key and it also sees that you have a number entered into the number buffer it will set that value in the dataref rather than executing the command. Note that we have also specified the multiplier 100 in column R. This allows us to enter the frequency in MegaHetz but then convert it to 10KHz units before the value is set.


Page | 21

Example 2

Look at line 20, key number 16. This is the autopilot HDG mode key. We want to be able to also use this key to set the heading bug when there is a value in the number buffer and the key is pressed. The dataref:

sim/cockpit2/autopilot/heading_dial_deg_mag_pilot is the value we want to set in degrees. Note that we specified a min and max value of 0 and 360 respectively so we won’t allow any invalid values to be set.

Example 3

In some cases it is easier to control a simulator function by incrementing and decrementing a dataref. Let’s take a look at the Transponder Mode key on line 12, key #9. The transponder on the Baron 58 has four states:

Value State

0 Off

1 Standby

2 On

3 Alt Transmit Table 5

We can use the min, max, and increment mode to cause the transponder mode to be adjusted in an up down fashion with each press of the key.

Example 5

On occasion you may not be able to implement all the functionality you need just in the X-Keys.csv file. A common way to extend the capability is to add functionality to a Lua script. This is what we did for finer control of the cowl flaps. In this example we are using a Shared dataref to communicate to the Lua script what cowl position we want. Refer to line 24, key #20 of the Baron 58 sample file. SRS/X-KeyPad/SharedInt[0] is incremented up and down through five states 0,1,2,3,4. Closed, open 25%, open 50%, open 75%, Open 100%. Look at the EvaulateCowlFlaps() function in the Baron 58 sample Lua script. Based on the value of the Shared dataref the Lua script will calculate and set the left and right cowl flap ratios.

Master Slave Datarefs

It is possible to specify an additional 15 slave datarefs after the first (master) has been specified. The dataref strings are separated by the ; character. Look at the XK-80 sample for the default 737 and specifically the numeric dataref specification for the panel lights.


Page | 22

When slave datarefs have been specified they will be set to the same value as the master. Note that the first specified dataref is the master and its value is what will be used for determining any increment functions.

Numeric Speech

Numeric Speech is nearly identical to command speech. You can also specify multiple tagged strings using the same format as the command speech. There are two differences.

1. The logic test is done on the Numeric Dataref AFTER it has been incremented or decremented. This is in contrast to the command speech strings which are compared to the Logic Dataref.

2. There is an optional [n] specifier that can be places anywhere in the string. This is used to indicate where you want any numeric buffer data, entered via the keypad, to be placed in the string.

Example 1

Refer to line 12, key # 9 of the Baron 58 XK-80 sample. This is the transponder mode key that cycles through the transponder modes with each key press. The cycling is controlled using the Numeric Dataref:

sim/cockpit2/radios/actuators/transponder_mode Which is cycled in an up-down fashion beteen the value of 0 and 4. The Numeric Speech string:

Transponder Off[=0];Transponder Standby[=1];Transponder On Mode A[=2];Transponder On Mode C[=3]

Is evaluated after the Numeric Dataref is incremented or decremented. The string whose logic expression tag matches the new transponder mode will be spoken.

Example 2

Refer to line 4, key # 2 of the Baron 58 XK-80 sample. This is the COM1 monitor key. It is also bound to the Numeric Dataref:

sim/cockpit/radios/com1_freq_hz This dataref will be set to any number entered into the numeric buffer (number window) when the COM1 key is pressed. When that happens the speech string:

COM 1 Set to [n] Mega Hertz will be evaluated. The lowercase [n] will be replaced with the numeric string you entered on the keypad and then will be spoken by the simulator.


Page | 23

Lower and Uppercase [n] / [N]

You can also use an uppercase [N] to indicate that you want the number to be spoken as individual digits. Look at the samples for setting the transponder code, altimeter, heading, and course. In those cases the numeric text 4523 will be spoken as four five two three rather than four thousand five hundred twenty three.

Multiple X-Key Units

The Unit Number column allows you to specify one of up to eight connected X-Key devices, 0 – 7. The unit number of a device is assigned sequentially from 0 on up when X-Plane starts and are generally based on the order that X-Key devices are plugged into USB hubs and ports. Unit numbers can change if you swap USB connectors so it is a good idea to choose the USB connectors you want to use before finalizing any configuration files or Lua scripts that reference more than one X-Key device.

Shifting

Shifting allows you to have two key definitions for each key. Your X-Key devices can be placed in shift mode by using either of the following two commands:

SRS/X-KeyPad/Toggle_Shift SRS/X-KeyPad/Momentary_Shift

These commands can be mapped to a keyboard key, joystick button, or an X-Key key. The momentary command will toggle the shift state on press and will toggle it back on key release. The shift state is indicated by the Red and Green leds in the upper left corner of most X-Key devices. The Green led indicates the device is in a non-shifted state and the Red led indicates that it is in the shifted state. Note: When shifting all X-Keys devices will be shifted together. There is no support for shifting individual X-Key units if you have more than one connected. The use of the shift functionality will give you twice the functionality on every key. Practically speaking it may be difficult to label the keys with this much functionality. The Baron 58 sample demonstrates the use of the CRS UP and DOWN keys to act as heading bug UP and DOWN keys when in the shifted state. See the definitions of keys 49 and 57 in any of the XK-80 samples. Here are some suggestions of where using key shifting can give you extra keys without complicating key labeling too much:

HDG / CRS Up and Down

COM1 / COM2 monitoring and setting

COM1 / COM2 Standby Swap

Same as above for NAV1/NAV2 and ADF1/ADF2

XPDR Mode/Ident


Page | 24

Flaps / Speed Brakes Up and Down

Brake Toggle / Tug Push

Controlling the Leds and reading key state with Lua Scripts

X-KeyPad exposes two dataref integer arrays for the led banks:

SRS/X-KeyPad/red_leds

SRS/X-KeyPad/blue_leds Each array contains 128 integers representing the blue and red led state for keys 0 – 127. The following integer values are used to control the led:

0 Off

1 On

2 blink X-KeyPad also exposes a unit selector integer dataref: SRS/X-KeyPad/UnitSelector. This unit selector must be set to the X-Key unit number 0 – 7 of the X-Key device that you are trying to set back lighting on before writing to the red or blue array datarefs. If you only have one X-Key device connected the unit selector should always be set to 0. Using lua scripts or another plugin you can control each led by writing values to these int arrays. Take a look at the Challenger 300 Lua script in the Samples\XK-80\CL300 folder. The file can be viewed with any text editor such as Notepad. The script is a good example of controlling led states with much more complicated logic. This script will control the led lighting for keys 7 and 15 which are the two Gear Toggle keys. When the gear is fully deployed we want the blue led illuminated. If any of the gear are in transition we want the red led to flash. When all gear are fully retracted we want the red light to be on steady. Notice how the EvaluateGear() function looks at the three gear states in the gear deployment array and then based on their values will set the proper led states for key 7 and 15. Compare this to the technique we used in the Baron 58 example for the gear. In that example we could only monitor one possibly two datarefs as we have the gear key spanning two keys. In that example we are looking the nose gear and just one of the main gear. Compare this to the Lua example that can monitor all three gear positions. X-KeyPad also exposes two additional array datarefs for reading the key state: SRS/X-KeyPad/current_key_states[128] READ ONLY SRS/X-KeyPad/key_pressed_flags[128] The current_key_states holds 128 integers, index 0-127 representing up to 128 keys on an X-Key device. A 1 indicates that key is currently down and a 0 indicates that it is up. The array is read only.


Page | 25

The key_pressed_flags also hold 128 integers. A 1 indicates that the key was pressed. You must write a 0 after processing and logic in order to capture the next key press. This dataref is more likely to be used with Lua scripts using the do_often callback which runs once per second. Similar to the led datarefs you must set the UnitSelector dataref if you are trying to read key states from an X-Key unit other than unit 0.

Other Samples Under the X-KeyPad folder is a Samples folder which contains a Keyboard only sample configuration. This is a minimalistic configuration just using the keyboard to set COM frequencies, Transponder functions, and a few autopilot variables. Refer to the readme.pdf in the Keyboard Only samples folder. The XK-80 folder contains Samples for the C172, Baron 58, SF50, C90, 737, Aerobask DA62, and Dden Challanger 300. The Zibo 737 folder shows examples of using aircraft specific custom datarefs and more complex examples of Lua scripts using the shared datarefs.

Settings There are a number of settings which can be adjusted using the Settings menu item.

Data Entry Window background and text color

Ability to have a translucent or transparent background on the Data Entry Window

X-Keys device Led flash frequency

X-Keys device Led brightness

Numeric Speech

Command Speech


Page | 26

Figure 4

The figure above shows the settings dialog. If you are running X-Plane 10 you will not see the upper portion of the dialog that deals with the options for the Numeric Data Entry window as these are only available in X-Plane 11 or above.

Adjust Backgound Color – Allows you to switch the sliders from adjusting the text color or the background color.

Red Green Blue Sliders – adjust the RGB values for the text or background colors.

Always Show Background – When set the numeric data entry window will always have a translucent or solid background. When not set the background is transparent and only the numeric data will show when there is data in the number buffer.

Sample Area – This shows what the color impact will be on the data entry window

Blink Speed – Adjusts the blink speed of the X-Keys Leds

Brightness – Adjusts the intensity of the X-Keys backlighting The Save button will save your settings for the next time you start X-Plane. The Save button will also save the current location of your data entry window. The Led Blink Speed and Led Brightness can also be adjusted using to integer data refs:

SRS/X-KeyPad/LedBrightness SRS/X-KeyPad/LedBlinkSpeed


Page | 27

The valid values for these datarefs are 0 – 255.

Enable Numeric Speech will use the simulator’s text to speech function to announce the numeric value being set in the dataref as specified by the Numeric Speech column in the X-Keys.csv or X-KeyPad.csv files

Enable Command Speech will use the simulator’s text to speech function to announce any command speech that was specified in the currently loaded X-Keys.csv file.

Tips and Other References

Commands vs Datarefs It is easy to get confused by the difference between X-Plane’s commands vs datarefs. Here is a good description from the X-Plane developer’s blog. https://developer.x-plane.com/2009/04/datarefs-vs-commands-i-whats-the-difference/

Dataref Tool You may be familiar with a popular tool called the Dataref Tool. This amazing plugin really helps to find which datarefs and commands impact the simulator. It is also invaluable if you are trying to get X-KeyPad to work with any custom planes that may very well use a set of custom datarefs and commands.

https://github.com/leecbaker/datareftool/releases

Bitwise AND Operations If you have to work with bit masks you may find this online binary converter valuable.

https://www.mathsisfun.com/binary-decimal-hexadecimal-converter.html

FlyWithLua FlyWithLua is a powerful scripting language that can be used to dramatically extend X-KeyPad’s ability. Programing knowledge is required but there are a lot of examples. https://forums.x-plane.org/index.php?/files/file/38445-flywithlua-ng-next-generation-edition-for-x-plane-11-win-lin-mac/

https://developer.x-plane.com/2009/04/datarefs-vs-commands-i-whats-the-difference/

https://github.com/leecbaker/datareftool/releases

https://www.mathsisfun.com/binary-decimal-hexadecimal-converter.html




Page | 28

XSaitekPanels X-KeyPad and XSaitekPanels have a lot in common. If you are trying to get a custom complex plane configured for X-KeyPad you may often be able to look at the Lua scripts and XSaitekPanel configurations for ideas. https://forums.x-plane.org/index.php?/files/category/182-xsaitekpanel-configurations/

Editing CSV Files There are a number is ways to edit a CSV file, Microsoft Excel, Google Sheets, Open Office Spreadsheets. There are also a number of free / low cost text editors that are specifically designed to editing CSV files: https://www.ronsplace.eu/Information/RonsEditor/Articles/The_Best_CSV_Editor Keep in mind that if you do use Microsoft Excel or other tools that have similar formula capabilities it is important to make sure that all the logic test columns of an X-Keys.cvs file are set to text format. If they are not you may have difficulty entering an = sign for the expression as Excel will interpret that as a formula. All the samples have a corresponding .xslx file that preserves the text formatting on those columns. A dedicated CSV file editor that does not have the formula capability is not likely to have that problem.

Tips for X-Key devices

Hardware vs. Software Mode Running your X-Key device in hardware mode without using MacroWorks is preferred. We also recommend setting your X-Keys device to the factory default with all key definitions blank and then specifying your command execution in the X-Keys.csv file. Once your X-Key device is configured you can bring it to any PC and it will work without the need to install any other software. We recommend not keeping Macroworks on your system and just use the X-Keys Basic setup utility to configure your device. You can download it from here:

http://xkeys.com/PISupport/SoftwareMacroWorksHW.php Note: MacroWorks may be necessary to reset your device to factory defaults but it won’t be needed after that unless you want to define complex macros.

https://forums.x-plane.org/index.php?/files/category/182-xsaitekpanel-configurations/

https://www.ronsplace.eu/Information/RonsEditor/Articles/The_Best_CSV_Editor

http://xkeys.com/PISupport/SoftwareMacroWorksHW.php


Page | 29

Limitations

X-KeyPad only works with Windows. OSX and Linux may follow sometime in the future possibly

with some limitations

Support You can obtain support for X-KeyPad by visiting our Q&A page:

https://www.stickandrudderstudios.com/answers/?question_type=all&search=

You can also contact us using the contact form:

https://www.stickandrudderstudios.com/contact-us/

https://www.stickandrudderstudios.com/answers/?question_type=all&search=

https://www.stickandrudderstudios.com/contact-us/


Page | 30

Appendix

Defined Commands X-KeyPad defines a number of commands that are used to control the plugin. The commands and their purpose have been discussed in previous sections of this user guide. The following table is an aggregated list of all those commands.

Command Purpose











SRS/X-KeyPad/Keypad_Decimal Adds a . character to the numeric buffer

SRS/X-KeyPad/Keypad_Minus Adds a - character to the numeric buffer

SRS/X-KeyPad/Keypad_Clear Clears the numeric buffer

SRS/X-KeyPad/Keypad_BackSpace Clears the last character entered in the numeric buffer

SRS/X-KeyPad/Toggle_Shift Toggles X-Keys shift mode on and off

SRS/X-KeyPad/Momentary_Shift Momentarily toggles X-Keys shift mode. It will toggle again as soon as the key or joystick button is released


Page | 31

Defined Datarefs X-KeyPad defines a number of datarefs that are used to control the plugin and to interface to FlyWithLua scrips. The datarefs and their purpose have been discussed in previous sections of this user guide. The following table is an aggregated list of all those datarefs.

Name Type Comments

SRS/X-KeyPad/LedBrightness Integer A value between 0 and 255 which indicates the Led brightness level on all X-Keys units

SRS/X-KeyPad/LedBlinkSpeed Integer A value between 0 and 255 which indicates the Led flash speed on all X-Keys units

SRS/X-KeyPad/CommandSpeechEnabled Integer A 1 indicates that command speech is enabled on the settings dialog, 0 indicates that it is disabled

SRS/X-KeyPad/SharedInt Integer Array[0-49] Array of 50 integers that are shared between X-KeyPad and FlyWithLua

SRS/X-KeyPad/SharedFloat Float Array[0-49] Array of 50 floating point numbers that are shared between X-KeyPad and FlyWithLua

SRS/X-KeyPad/UnitSelector Integer A value between 0 and 7 indicating which X-Keys unit you are addressing for all the following datarefs in this table

SRS/X-KeyPad/current_key_states Read Only Integer Array [0-127]

A one indicates that the key is currently pressed

SRS/X-KeyPad/key_pressed_flags Integer Array[0-127] A one indicates that the key pas pressed. You must clear it in your script after process the key press

SRS/X-KeyPad/blue_leds Integer Array[0-127] 0 = Blue led off 1 = Blue led on 2 = Blue led flashing

SRS/X-KeyPad/red_leds Integer Array[0-127] 0 = Red led off 1 = Red led on 2 = Red led flashing