Getting started with XPlane - MobiFlight/MobiFlight-Connector GitHub Wiki

Tutorial also available on YouTube

MobiFlight now provides a direct way to interface with X-Plane by using native X-Plane DataRefs and Commands.

X-Plane DataRefs & Commands

X-Plane knows about two different kind of ways to interact with the simulator:

DataRefs

DataRefs are like Sim Variables inside X-Plane that allow you to access state information from the plane, cockpit, and simulator like speed, altitude, altimeter reading, warning lights, etc. You can "read" DataRefs and use them in Output Configs. You can also "write" to some (not all) DataRefs which allows you to use them in Input Configs. For writing to a DataRef you have to provide the new value that you define in your Input Action in MobiFlight.

Commands

Commands are meant for Input Actions only. They are really simple to use because they don't require any parameters. Generally it is recommended to use commands for inputs because you don't have to worry about calculating the correct new value first (e.g., COM1 frequency range goes from 119.000 to 136.990).

Both, DataRefs & Commands are identified by an individual name which has a path structure, for example:

  • DataRef "Autopilot Heading" - sim/cockpit2/autopilot/heading_dial_deg_mag_pilot
  • Command "B737 Autopilot Heading Decrement" - laminar/B738/autopilot/heading_dn

Finding DataRefs & Commands

Using the filter and search

All X-Plane DataRefs and Commands can be found listed and searchable with convenient filter options and a full-text search:

X-Plane comes with many thousands DataRefs and Commands defined which are all provided as Vendor Laminar Research and Aircraft Generic. This is very similar to the way you can find the presets for Microsoft Flight Simulator 2020.

Since the amount of available presets can be quite overwhelming, You can also use the excellent Datareftool plugin by Lee Baker to locate the data you are looking for. It is an interactive way to identify the DataRef that changes or the Command that is triggered by an interaction with your mouse in the cockpit.

Installing DataRefTool

The DataRefTool can be installed like other X-Plane plugins:

  • Download the zip-file from DataRefTool website
  • Unzip the content of the zip-file to your X-Plane installation directory in the \Resources\Plugins-folder Make sure that the DataRefTool-plugin directory contains a "64"-folder now
  • Restart X-Plane
  • Load into a flight
  • In the menu click plugins > DataRefTool > Search

A new window will open:

Finding a DataRef or Command

The list of DataRefs and Commands is typically quite long but it is easy to filter the list so that you only see DataRefs or Commands that are currently changing. Additionally, you can also filter the names with sensible guesses like "radio", "freq", etc.

  • clicking on the last button, top-right window area, until

    • button shows "dat" - filter list is now only showing DataRefs
    • button shows "Cmd" - filter list is now only showing Commands

  • clicking on the second last button, top-right area

    • button shows "ch" or "CH" - filter list is now only showing changing values

Cool, so now that we know how to determine the correct DataRef or Command it is super simple to read, write or execute them through MobiFlight.

Reading data from X-Plane

As an example, we wish to show the autopilot selected heading value, and with DataRefTool we determined, that sim/cockpit2/autopilot/heading_dial_deg_mag_pilot seems to react to the heading knob being turned and is what we are looking for.

Simply click the "Outputs" tab on Mobiflight and add a new configuration line, lets call it for example "Autopilot Heading". Once you have named it, and clicked the "Active" checkbox, open the configuration dialog by clicking the button on the right side, and select "X-Plane DataRef" as the variable type. Click on Show Preset Code so that the code box appears, and paste the dataref path into the field, and click "OK".

With X-plane running, click "Run" on MobiFlight and your autopilot heading should be visible in the "Flight Sim Value" column in the Mobiflight window. You can then configure the "Display" settings on the config item to show the data on a 7-segment display or LCD, like with any flight sim data.

Writing data to X-Plane

This can be done in two ways by:

  • executing Commands and
  • writing a new value directly to a Dataref.

Commands

So we want to adjust the heading bug. We are finding out with Datareftool that the commands that react to the heading bug in the cockpit are laminar/B738/autopilot/heading_dn and laminar/B738/autopilot/heading_up and it changes when I twist the heading knob in the virtual cockpit. So we set those as the Commands for an encoder for onLeft and onRight events:

OnRight looks essentially the same, but uses the "_up" event of course.

The above commands are for the excellent freeware "Zibo" mod of the Boeing 737 NG, so they naturally work only for that plane, but using the Datareftool you can look up pretty much anything from X-Plane, and should be able to make things work for any plane.

Writable DataRefs

Note: You cannot write to all DataRefs, some are read-only. You can check this from the X-plane datarefs.txt list, and also from DataRefTool that shows you if it can be writen to or not, using the Edit button when you select a dataref.

If it is writable, you can define a value for each position using for example a selector switch, or use an encoder with a suitable if() statement on the transform field, to limit the range of positions to the ones the switch can do. ( if($<4, $+1,4) etc..

This example is also from Zibo 737, from the datarefs text file, and it is writable so we ca do this:

This example uses a rotary encoder to control the bank angle selector switch. Not completely realistic, but works. That particular bank angle selector has 5 positions with values 0,1,2,3 and 4, so the OnRight value has "if($<4, $+1, 4)" so it adds one with every encoder click towards right, until it reaches the maximum 4. Same for clicking left, and decrementing the value until it reaches 0 which is the minimum.

For toggle switches you would first look for a pair of ON/OFF commands, but if you find a writable dataref, you can also write 1 for onPress and 0 for onRelease events of the switch.

Migrating XPUIPC configs

Before the native X-Plane integration, MobiFlight supported X-Plane only through XPUIPC which was mimicing the FSUIPC with its Offset oriented way of accessing sim variables and perform input events. The theoretical advantage was, that a MobiFlight config could theoretically be used for a simulator with FSUIPC interface (like FSX or P3D) and also for X-Plane with XPUIPC. However, practice has shown that this benefit was not really relevant because most cockpits would need access to special sim variables and it required a lot of knowledge to extend XPUIPC with own offsets.

If you are a XPUIPC user, there is currently no automated way of migrating your XPUIPC config to the new X-Plane native style. There is two types of configs that you would want to migrate:

  • Configs that use a standard FSUIPC offset - here you have to look up the corresponding DataRef of Command yourself with the DataRefTool, because XPUIPC has them built-in and they are not listed in a config file anywhere.
  • Configs that use an offset that is defined in XpuipcOffsetConfig.cfg - in this case, you can look up the DataRef of Command name by looking through your config.

In any case, it will be some work yes, but still quite straight forward to migrate an "FSUIPC Offset" config to a "X-Plane native" config.

Legacy documentation (XPUIPC)

In case you would like to still continue using the XPUIPC interface, see the old how-to guide with more information. You also might be interested in the XPUIPCOffsets.cfg Notepad++ plugin for editing the config file.