In SimVimCockpit users no longer need to concern themselves with the specifics of using "commands" and "datarefs", or various options as it was in previous interface.
SimVim is using its own Parameter names that are meant to represent a real fuctionality in an actual aircraft cockpit, not a specific model. The idea is that a cockpit builder plans their cockpit and assigns these parameters to inputs/outputs based on what they should do (in a real aircraft cockpit), not how they would interact with a particular aircraft in X-Plane.
Each parameter name is associated with a default X-Plane datarefs, commands and a set of default input/output options specific to this parameter. Every parameter name in SimVim is "predefined" in the plugin, that means that one "Data_Name" actually may include:
All available parameter names can be found in the configurator database . Of course, not all possible functions are still listed there, and if you can't find some in the table you can help us to create a list of controls that you think need to be added to the databse ( note: it's not datarefs or commands).
If a custom aircraft supported by the plugin is loaded, some parameters get replaced with custom datarefs, commands and options specific to this aircraft. So, the same configuration file will work with both the default and supported custom aircrafts.
For this an additional "mapping table" is used for specific custom planes, that associate corresponding SimVim names (parameter names) with custom commands, datarefs, and even macros/functions.
As we plan to make SimVim compatible with MSFS/P3D this feature (universal parameter names) it guarantees uniform configuration format, one configurator and possibility to fly on any simulator using the same data file.
For now, "mappings" for several "custom" planes including all "laminar/" will be added to the plugin database, to work out the mechanism of custom mapping for any complex situation. And, after that, we could provide on the website some sort of editor for everyone who wants ( and can) to analyze custom functions and create custom mappings for their planes.
In short: Commands are used to initiate action (input controls), DataRefs mostly are used for outpur information (to read their values and display them).
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).
- 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.
- 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.
- 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.
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.
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.
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.