ABOUT, PROJECTS BLOG, NEWS COMMUNITY TERMS of Use BARON 58

<<<      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:

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

sim/cockpit2/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.

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 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:

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 dataref mentioned above

Commands are useful for virtual cockpit controls, hotkey assignments, and even 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. 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 netes 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.

Custom planes for SimVim

We started to add all laminar and some other planes in the SimVim database as defaults, so you can simply use any parameter names from the configurator as usual.

Here you can see examples of different panels mapped to default SimVim names, that can be assigned in the configurator once and used with different models of the same plane.

Some insight on what datarefs and commands really are

Some programming knowledge may be required to understand datarefs. In reality, datarefs are class objects that contain several constants.

The main of them are links to several functions that get called when X-Plane or another program wants to Read or Write this dataref.

Most commonly, there are only 2 functions linked to a dataref - one for reading, and one for writing. There can be more than one pair of functions for several data types, but this is rarely used. X-Plane doesn't actually store "values" for custom datarefs.

Strictly speaking, when a program wants to read a dataref's value, it calls the "Read" function linked to that particular dataref, which returns a value (which can be a result of some calculations, not just a stored value from memory). Similarly, when writing a dataref value, a program passes the value as an argument to the dataref's "Write" function. That function may do anything with that value - most commonly, it just writes it into a variable, but can also be used in some conditions and calculations.

So, here is the interesting thing about datarefs - their "Write" functions are not much different from commands, in that, from a programming perspective, they can do more than just write a value into a variable. A programmer writing a custom dataref could make it so that when you change the dataref's value in DataRefEditor (or via one of our interfaces), the function would do everything needed when the actuator is used in the cockpit. So, it could do the same thing that a command does. However, as the commands are used by the virtual cockpit controls and keyword assignments, they are the ones that are mostly used for the programming of "actions".

That is why using commands instead of datarefs can be important when making cockpit input controls - they are just more likely to contain all the needed actions to simulate the correct behavior of the controls.




© Copyright 2012-2018 - SimVim