04. Commands vs. Datarefs (the most frequent issue)

The library supports various types of switches. Choose the one you use with care.

I really can't overemphasize that, as the most common reason for X-Plane switches that seem to move, but actually don't trigger any action is the fact that you directly write to datarefs instead of using the appropriate X-Plane commands that would trigger the action.

There's a series of three blog posts on the X-Plane developer site about the issue. While these posts are directed more towards aircraft developers, they give you a good introduction on how to deal with the situation:

• DataRefs Vs. Commands I: What’s The Difference
• Datarefs Vs. Commands II: Which One Should I Use?
• Datarefs Vs. Commands III: What Is My command Doing?

Basically, it all comes down to the question: "Which approach did they developer of my aircraft use to control X-Plane?" Unfortunately, there's no single answer to that question. You need to discover it for every single plane and, maybe, for every single switch or button.

How do I find the correct datarefs or commands?

There are some tools to help you. You may already know X-Plane's Dataref Editor, but there's an even more advanced plugin: Dataref Tool. It allows you to not only search and filter the commands and datarefs, it also provides a very helpful feature to filter only for datarefs that recently changed or commands that were recently executed. It also highlights these datarefs and commands and therefore allows you to easily spot them. And, of course, you can try writing to the datarefs and trigger the commands that Dataref Tool shows.

If you want to discover whether a specific switch or button from your aircraft is handled through a command or a dataref, you should first try to see if it's a command, because that is much easier to find than a dataref. Here's how it goes:

1. Set Dataref Tool to only show recently issued commands, apply no name filter:

   

2. In the virtual cockpit, click on the switch that you want to find the command for. If it is implemented as a command, it should show up in the window, gradually fade from yellow to green and vanish after a while:

   

3. If you don't see a command, then probably the switch is controlled through a dataref. Please skip the following steps and continue further down at step 6.

4. If you do se a command in the Dataref Tool window, congratulations! You now know that your switch actually is controlled through and what is its name. For pushbuttons, you should have a single command. Two position switches generally have one command for each position ("on" and "off").

5. For multi-position switches, things are a bit more complicated:

   • There is one command to increase and one to decrease the current position. These commands may, for example end in "_up" or "_dn" or in "_lft" or "_rgt". Make sure you capture both commands for the multi-position switch:

     

   • Apart from the two commands, there's a dataref that indicates the current switch position. You need to find this dataref and, in general, its name is somehow related to the name of the command. So, in they above example, switching Dataref Tool to dataref+command mode ("d+c")and filtering for "EFIS" or "mode" would be a good start. Leave filtering for changes turned on, but make sure the lower case "ch" is shown (Dataref Tool won't show changes in integer variables in "CH" [upper case] mode) Flip or turn your multi-position switch again and you should now see the commands as well as the associated dataref:

     

6. If you can't identify a command, then you should start looking for a dataref that represents the switch position. Try filtering for the name, with the change filter set to "ch" (lower case!). Make initial guesses about the name and flip the switch in the virtual cockpit. You should soon be able to find the dataref that changes whenever you change the switch in the virtual cockpit:

   

7. In the previous example, you saw that there's more than one dataref that changes when you turn the EFIS map range selector. That's one of the less fortunate situations and you need to find out which dataref is the primary one. There's no general rule, but here are some clues of how to do this:

   • See if you can write to the dataref. Click on its value in Dataref Tool and try setting a new value. If X-Plane doesn't accept it, you're definitely not looking at the primary dataref:

     

   • Also, if you change the primary dataref, all the others should change as well. If that doesn't happen, you're probably writing to a dataref that is derived from the primary one

   • Sometimes, the same dataref has various names. In that case, it doesn't matter to which one you write.

   • Again, as mentioned in the cited blog posts, the recommended way to perform an action in X-Plane is to execute a command. Please double- check if in your specific aircraft, the action is really triggered by writing to a dataref or if there isn't a command available that does the same thing.

You surely have noticed the many may's and could's in this section. That is because every aircraft in X-Plane handles these issues differently. datarefs can be read/write or read only, so you may be able to write to them or not. Some aircrafts, like the IXEG 737-300 can actually be controlled by Writing to datarefs, others, like the stock 737-800 or the Zibo version require commands. It really depends on the implementation of your specific aircraft and you'll have to check the documentation or go through the procedure described above.

Technical background

So why is this all so complicated? Can't we find a single consistent and easy way to extract the datarefs and commands from X-Plane?

Well, yes and no. The data is there, but it's hidden in a very technical way in the aircraft definition files and it can't be easily extracted (yet?)

Here's the technical background: In X-Plane, the visual cockpit is composed of tons of 3D objects that are defined in .acf and .obj files. Switches are some of these visual 3D objects and their position in the 3D cockpit generally is defined by a dataref. That means, that for any switch in the 3D cockpit, there is a dataref that defines its position. This dataref is queried by the 3D drawing engine when the cockpit is drawn on the screen.

This is a section from the X-Plane stock Cessna 172 3D object file (Cessna_172SP_G1000_cockpit.obj):

[...]
ANIM_trans -0.475653 -0.032821 0.394501 -0.475653 -0.032821 0.394501 0.000000 0.000000 none
ANIM_rotate_begin 0.000000 0.000000 1.000000 sim/cockpit2/engine/actuators/ignition_key[0]
ANIM_rotate_key 0.000000 0.000000
ANIM_rotate_key 1.000000 -40.000000
ANIM_rotate_key 2.000000 -73.000000
ANIM_rotate_key 3.000000 -100.000000
ANIM_rotate_key 4.000000 -160.000000
ANIM_rotate_end
ANIM_trans 0.475653 0.032821 -0.394501 0.475653 0.032821 -0.394501 0.000000 0.000000 none
ATTR_manip_command_knob rotate_large laminar/c172/ignition_up laminar/c172/ignition_down MAGNETOS KEY / STARTER
[...]

What do these lines tell us? There's a rotary switch for the magnetos/ignition selection in the Cessna. It has five positions that correspond to 0 degrees, -40 degrees, -73 degrees, -100 degrees and -160 degrees. The visual position of the switch is stored in a dataref called sim/cockpit2/engine/actuators/ignition_key[0]. However, in order to change the dataref, you need to use the commands laminar/c172/ignition_up and laminar/c172/ignition_down.

So, if you decide to directly write to the dataref sim/cockpit2/engine/actuators/ignition_key[0], you may even be able to change the position of the switch in the virtual 3D-cockpit, but, remember, that's just the visual representation.

It doesn't mean that the action associated with the switch (in the case above: starting or stopping the engine) is actually executed. Being more specific: When you write a value 4 to the dataref that controls the switch position for the magnetos, the switch may turn to position "START", but that doesn't mean that the engine actually starts.

In order to start the engines, you (may) have to send a specific command to X-Plane. That command, in turn, triggers a command handler that (for example) checks if you have electric power on your aircraft and then turns on the starter. In turn, the command handler also sets the dataref sim/cockpit2/engine/actuators/ignition_key[0] to the new value.

The magnetos/ignition switch in the C172 is a good example of how the command handler (and not the dataref) actually controls the behavior of the aircraft. In addition to handling the actions associated with the various switch position, the command handler also determines that the switch does not lock in the START position. That means, in order to turn on the engine, you have to HOLD the switch in the START position. Holding the button there requires a different approach in X-Plane (using command.begin() and command.end() instead of command.once()), but the library provides a way to do this. Check the Demo_Cessna172 or the FlightSimUpDownCommandSwitch description to see how it works.

So, the switch dataref actually is a consequence of the command handler, but it does not execute any specific action that would change a system state in your aircraft.