ABOUT, HISTORY BARON 58 Community (Q&A) TERMS of Use YOUTUBE

Input/Output parameters in X-Plane

X-Plane "standard" and "custom" Datarefs and Commands

In short: Commands are used to initiate action (input controls), DataRefs mostly are used for outpur information (to read their values and display them).

DataRefs

A DataRef can be considered as 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 via API.

But even if some DataRef is writable it doesn't mean that it is suited for input controls, and often you can't simply change it's value via SimVim plugin to get a needed effect.

Generally, "cockpit-related" datarefs should be used for reading and output some information onto the screen - to display numbers, instrument needles and various other animation (or to send data from the simulator out - via such plugin as SimVimCockpit).

Examples:

..../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 or 7-segment indicator or gauge.

..../ice/ice_surfce_heat_on

- this dataref (writable, as 0 or 1) keeps the aircraft current Wings anti-ice system status ( bleed Air valve open/close). It is writable and can be used for toggle switch - but it should be considered for use only as annunciator. For the anti-ice switch a couple of commands are used.

..../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 for direct change as using the up/dn commands is not so convenient for such "axis" controls.


Commands

Simply put, a command is a link 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.

Example:

..../ice/wing_heat_on, ..../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 dataref mentioned above

Commands are useful for virtual cockpit controls, hotkey assignments, and for external controls such as SimVimCockpit 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.



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 specific prefix - "aerobask/.../.../" in opposite to standard "sim/../../" ).

Many of such datarefs used the same way as standard, just having a different name. Some of custom daraefs are included to bring more realizm in 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 it's "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 ---------

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 spend some time and effort to find it.

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 dataref directly, you might lose some functions activated by the commands (see example below).

  • Always prefer the commands for input controls. If you are sure that using a dataref for 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 plane virtual panel has a 4-position rotary switch

You may have these 3 options:
  1. 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)
    • In this case the only option is using these 4 commands for rotary switch positions.

  2. 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)
    • In this case you need to use 2 commands and the dataref which is needed to monitor its current value to set switch position by 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)

  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 you can use 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 will not get what you need, some function will work, some will not, so using the commands is preferable here.


Example 2: Toggle switch

You may have these 3 options:
  1. There are 2 commands for each position - command_On,command_Off (or command_Up,command_Dn)
  2. It's the best option, always use it even if there is a writable dataref.

  3. There is ONE "toggle" command for the switch actions and a read-only dataref:
    • command_toggle
    • dataref_switch_pos, (value = 0,1)
    • 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 by 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)

  4. There is one "toggle" command and one writable dataref:
    • command_toggle
    • dataref_switch_pos, (value = 0,1)
    • 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.






© Copyright 2012-2018 - SimVim