Reference Information: X-Plane Commands and DataRefs
The information on this page is for reference only, all the necessary standard X-Plane commands and datarefs are included in SimVimX input/output parameter database as default.
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), DataRefs are mostly used for output (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 SimVim/X ) can use them to provide data for a hardware panel. Some of them can be used as input.
Examples:
- 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, SimVimX 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 Laminar (since X-Plane 11) prefix, some datarefs under this category can be 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 SimVimX 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 SimVimX |
| sim/weapons/.. | For weapons properties and control - used by SimVimX | Used |
| sim/operation/.. | Some datarefs from this section can be used by SimVimX for the sim control | Few |
| sim/weather/.. | For Weather properties and control - can used with SimVimX 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).
Commands are useful for virtual cockpit controls, hotkey assignments, and for external controls such as SimVimX hardware interface, and they are easy to understand - you call the command's name, something gets done. That's why many developers use them to do something when you interact with cockpit controls - in X-Plane, commands are synonymous with actions.
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 SimVimX plugin 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 learning about custom X-Plane aircraft, they usually only learn about "custom" DataRefs. These DataRefs are created and registered in X-Plane when you start the plane and they have different naming rules (usually they start with a specific prefix - for example, "aerobask/..." instead of the standard "sim/..." ).
Note: Many of such datarefs are replacing the standard ones, just having a different name and used only for image animation (switches, rotaries, etc.). Few 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.
