Reference Information: X-Plane Commands and DataRefs
The information on this page is for reference only, you do not need to worry about how X-Plane data is organized, all the necessary standard X-Plane commands and datarefs are included in SimVim input/output parameters.
If you have been working with X-Plane data manipulation, Plane Maker or external interfacing, then, for sure, you know about X-Plane data structure. If you were only flying various virtual planes, at least you've heard about "DataRefs" and "Commands" in relation to simulator control (e.g., when assigning the Joystick buttons).
All standard X-Plane commands and datarefs are named strings started with sim/.. prefix. What is the difference between them?
In short, the Commands are used to initiate action (input control functions), DataRefs are mostly used for output information (to read simulator variables and display them).
DataRefs
To put it simply, from a user's point of view, a DataRef can be considered an internal named variable that stores information. This variable can be writable or not. Writable DataRef can be changed either by an internal flightmodel function or by a plugin. But even if the DataRef is writable it doesn't mean that it is suited for input controls, and simply changing its value in the plugin may be not enough to change an aircraft system state.
Generally, "cockpit-related" datarefs are used in X-Plane to display information onto the screen instrument panel and "animate" on-screen switches. Or, the plugin (such as SimVimCockpit) can use them to provide data for a hardware panel. Some of them can be used as input:
- sim/cockpit2/gauges/indicators/airspeed_kts_pilot - this dataref (read-only) keeps the aircraft current Airspeed and it's value can be used to display speed on the virtual panel, a 7-segment indicator or gauge.
- sim/cockpit2/ice/ice_surfce_heat_on - this dataref (writable, accepts values 0 and 1) keeps the aircraft current Wings anti-ice system status (bleed Air valve open/closed). It is writable and can be used for a toggle switch - but it should be considered for use only as annunciator. For the switch a couple of commands are used.
- sim/cockpit2/controls/flap_ratio - this dataref (writable, variable from 0.00 to 1.00) keeps the aircraft current Flap Handle position. It is writable, and it can be used to directly change the handle position (also, the up/dn commands can be used for this input control, but only to increment it by specific steps instead of continuous movement).
X-Plane Dataref categories
You can see the large list of X-Plane datarefs sorted by category on the X-Plane Developer website. Also, you can use such plugins as DataRefTool or DataRefEditor to see the dataref list in X-Plane window.
NOTE: A "hardware" cockpit requires only a small number of datarefs from the huge X-Plane data list, namely only those used for control panels and instruments. Thus, SimVimCockpit functions use only the appropriate standard datarefs from the table below:
| Dataref prefix /../ | The DataRef's purpose in X-Plane, relation to aircraft control | Used for cockpit Input/Output? |
|---|---|---|
| sim/... | This is the base X-Plane prefix for all standard datarefs and commands | |
| sim/cockpit2/.../.. | This is the only category where ALL datarefs can be used for cockpit input controls and outputs. | USED |
| laminar/.../... | New X-Plane-11 prefix, all datarefs under this category are used in specific Laminar plane models. | USED for specific laminar planes cockpit controls |
| sim/aircraft/.. sim/aircraft2/.../.. | These categories are not needed for cockpit controls, and used by developers to define an aircraft systems properties in Plane Maker. Some datarefs are used in SimVimCockpit custom functions | Some datarefs are used as predefined variables |
| sim/flightmodel/.. sim/flightmodel2/... | (../weight/, ../position/, ../engine/, .) is NOT USED for any cockpit input controls and outputs, these datarefs are used to define aircraft flight model properties by plane developers for external model, animations, etc. | A few datarefs are used in SimVimCockpit |
| sim/weapons/.. | For weapons properties and control - used by SimVim | Used |
| sim/operation/.. | Some datarefs from this section can be used by SimVIm for the sim control | Few |
| sim/weather/.. | For Weather properties and control - can used with SimVim for weather control Console. | OPT |
| sim/cockpit/.../.. | Most datarefs in this category are deprecated and not needed to use! - "cockpit2/.." is used now instead! | NONE or few |
| sim/graphics/.. | Everything related to sim graphics and animation, NOT USED for any cockpit input controls and outputs | NONE |
| sim/joystick/... | This category is used only for joystick settings, NOT related to other external cockpit control. | NONE |
| sim/multiplayer/.. | For multiplayer mode, current properties of 20 planes, NOT used for interfacing | NONE |
| sim/network/.. | For Network UDP properties, NOT used for control | NONE |
| sim/physics/.. | World physics, NOT used for interfacing | NONE |
Commands
A command can be thought of as a reference to a single program function. When a command is called via X-Plane, it runs a particular function in the program that created this command (that could be X-Plane itself, a plugin, or a custom aircraft's script). This function can do whatever the programmer wants. It also accepts a single argument - the command's state (begins, continues, ends). Some commands can use all of these states, particularly the commands for "Press-and-hold" buttons - that means the function can do different things when the button is pressed, held, or released and change different dtarefs and system parameters.
- sim/ice/wing_heat_on - sim/ice/wing_heat_off - these two commands are used to switch Wings anti-ice system ( bleed Air valve open/close) and besides all, sets the related dataref mentioned above (and can affect some other data depending on plane model).
X-Plane Command Categories
You can see the list of X-Plane commands in the X-Plane's Plugins folder (the commands.txt file) . Also, you can use DataRefTool to see the command list in X-Plane window. The SimVimCockpit input functions use all standard commands from these categories:
| sim/magnetos/..... | sim/engines/..... | sim/starters/.../... | sim/ignition/.../.. |
| sim/igniters/..... | sim/fadec/..... | sim/flight_controls/..... | sim/systems/..... |
| sim/altair/..... | sim/fuel/..... | sim/electrical/..... | sim/lights/..... |
| sim/bleed_air/..... | sim/pressurization/..... | sim/weapons/..... | sim/audio_panel/..... |
| sim/ice/..... | sim/oxy/..... | sim/radios/..... | sim/transponder/..... |
| sim/autopilot/..... | sim/instruments/..... | sim/annunciator/..... | sim/FMS/.. ... |
| sim/GPS/..... | sim/operation/..... | sim/view/..... | sim/general/..... |
Custom Datarefs/Commands
When people start studying X-Plane custom aircrafts, they usually find out about "custom" DataRefs only. These DataRefs are created and registered in X-Plane when you start your custom plane and they have their naming rules (usually they start with a specific prefix - for example, "aerobask/.../.../" instead of the standard "sim/.../.../" ).
Many of such datarefs are used the same way as standard, just having a different name. Some of the custom daraefs are included to bring more realism to the virtual cockpit and plane systems - see some notes about this here.
You may wrongly think that all you need to control your specific custom aircraft is to find its "custom" datarefs and simply change their value when needed. But often it's not.
What is sometimes overlooked is the existence of custom commands, and that utilizing these commands for interaction with the aircraft model is often better then using custom datarefs.
The reason for that is that, commands are often programmed to do more then just change a single dataref value. While a dataref's value is important as it is used by other parts of the program to check what needs to be done, just changing the dataref value may not result in all the necessary actions being done, that are supposed to happen when a switch in the cockpit is flipped, for example.
----- NOTES: Custom data assignment --------- for SimVim replacemet tables editors!
The main thing you will need for custom aircraft data conversion for SimVim is the list of all custom commands and datarefs needed for cockpit control. Sometimes it's easily accessible (included in the aircraft), sometimes you need to find it or see the list in the DataRefTool plugin.
Search only for those commands (and datarefs) that correspond to the parameter that doesn't work. The list of all custom datarefs for your aircraft can be very large, but you probably would really need only a small part of it for your cockpit controls.
While working with custom data for your aircraft model, you should remember the following rules:
- Commands are used for actions (input controls), datarefs - for displaying data, annunciators, gauges.
- For any input action, always try to find the appropriate command first, not the dataref!
- If you think you can't find the command, try harder - it should be somewhere there (ask the plane developer).
- Dataref also can be used for inputs (by directly changing its value), if this dataref is writable.
- When using a dataref directly, you might lose some functions activated by the commands (see example below).
- Always prefer commands for input controls. If you are sure that using a dataref for a particular input control works correctly without the need for commands, and this is more convenient, you can use a dataref. For axis (analog) input only datarefs (writable) can be used.
Example 1: Your aircraft virtual panel has a 4-position rotary switch
You may have these 3 options:- There are 4 commands for each position and a read-only dataref (contains the switch position number - 0,1,2,3):
- command_pos1, command_pos2, command_pos3, command_pos4
- dataref_switch_pos, (value = 0,1,2,3)
- There are 2 commands for up/down rotary switch actions and a read-only dataref:
- command_pos_UP, command_pos_DN
- dataref_switch_pos, (value = 0,1,2,3)
- There are 4 commands for each position and one writable dataref:
- command_pos1, command_pos2, command_pos3, command_pos4
- dataref_switch_pos, (value = 0,1,2,3)
In this case the only option is using these 4 commands for rotary switch positions.
In this case you need to use the 2 commands and the dataref which is needed to monitor its current value to set switch position using the up/dn commands correctly.
(SimVim plugin will process this switch correctly, when you assign both commands and the reference dataref in the data conversion tool).
In this case you can use the dataref with 4 different values instead of commands.
But some of these commands (#1 here) can not only set the dataref value, but also initiate other functions, for example turn some annunciators, launch another system, etc. So, you may not get what you need, some function will work, some will not, so using the commands is preferable here.
Note that this is not always the case, as datarefs can also be programmed to initiate some additional functions when the value is changed, but it's up to the developer to do it.
Example 2: Toggle switch
You may have these 3 options:- There are 2 commands for each position - command_On,command_Off (or command_Up,command_Dn)
- There is ONE "toggle" command for the switch actions and a read-only dataref:
- command_toggle
- dataref_switch_pos, (value = 0,1)
- There is one "toggle" command and one writable dataref:
- command_toggle
- dataref_switch_pos, (value = 0,1)
It's the best option, always use it even if there is a writable dataref.
In this case you need to use both the command and the dataref which is needed to monitor its current value to set switch position using the toggle command correctly.
(SimVim plugin will process this switch correctly, when you assign both the command and the dataref in the data conversion tool).
In this case you can use it as in the previous case, or use the dataref only, but only if the toggle command does not initiate some other function.