Xplane interface

[admin]

Installation
LuaMacros can control Xplane as my main motivation is flight simulation. You need to install Xplane plugin to get interface to work. Xplane plugin is currently provided only for Windows platform 64bit version. LuaMacros is windows specific program so there's no sense to provide plugin for other platforms. I believe most of windows users fly with 64bit version so I haven't compiled 32bit version. Installation is easy, in Xplane home go to Resources/plugins directory, create luamacros\64 directories and copy win.xpl to 64 directory. Standard thing, no big deal.

Then you can use Xplane related commands in LuaMacros.

Commands

Code: Select all

lmc_xpl_command('sim/view/still_spot')

With lmc_xpl_command you just execute command in xplane. List of available commands can be found in Xplane's Resources\plugin directory in file Commands.txt.
Some commands can be "started" and "finished" - typically when you need to hold some button like starter. Then you use separate command for start and end

Code: Select all

lmc_xpl_command_begin('sim/engines/engage_starters')
lmc_xpl_command_end('sim/engines/engage_starters')

Text
You can display text in Xplane e.g. to indicate that some actions were executed, mode has changed etc. Then you can call command

Code: Select all

lmc_xpl_text('From LUA macros')
lmc_xpl_text('From LUA macros', 0.5)
lmc_xpl_text('From LUA macros', 0.7, 10)

It has 1 mandatory parameter and 2 optional

• (mandatory) text to be shown
• (optional) y-position as float, 0 is top left corner, 1 is bottom left corner. Default is 0.3
• (optional) timeout in seconds, after this timeout text disappears. With 0 timeout text will stay on the screen

Variables
Variables are called datarefs in Xplane (SDK). Available datarefs are listed in Xplane's Resources\plugin directory in file DataRefs.txt. Datarefs can be read and some of them (see txt) can be written to. To read dataref use command

Code: Select all

lmc_get_xpl_variable('sim/cockpit2/radios/actuators/adf1_frequency_hz')

The only argument is dataref's name and value is returned as a result of function call. So you would actually use at least something like

Code: Select all

print(lmc_get_xpl_variable('sim/cockpit2/radios/actuators/adf1_frequency_hz'))

When you need to write to a dataref add one more parameter (with value) and call

Code: Select all

lmc_set_xpl_variable('sim/cockpit2/radios/actuators/adf1_frequency_hz', 425)

Some datarefs are arrays (e.g. engine related) so then you use one more argument to indicate array index (0 is the first element)

Code: Select all

print(lmc_get_xpl_variable('sim/flightmodel/engine/ENGN_thro', 0)) -- throttle of first engine
lmc_set_xpl_variable('sim/flightmodel/engine/ENGN_thro', 0.3, 1) -- set throttle of second engine

Your script can be informed when value of some variable in Xplane has changed. In this case you use function lmc_on_xpl_var_change providing variable name and callback function. For example you can be informed when another plane is loaded by

Code: Select all

lmc_on_xpl_var_change('sim/aircraft/view/acf_tailnum', function(value)
  print('Have new plane ' .. value)
end)

However some values (like current latitude or longitude) change so often that your script would be overloaded with calls that you don't ever need (new variable value is checked with each simulation frame). So you can add one more parameter with number of milliseconds between each callback - even if variable has changed more times.

Code: Select all

varName='sim/cockpit2/radios/actuators/adf1_frequency_hz'
lmc_on_xpl_var_change(varName,
  function(value, count)
    print(varName .. ' changed to ' .. value .. ' with ' .. count .. ' changes')
  end, 1000)

Also the callback function can take one more argument with number of changes of the variable from last callback. It means if you don't use this "ignore interval in ms" the second argument of callback function will be always 1.
The on-change callback can be also unregistered with function

Code: Select all

lmc_remove_xpl_var_change('sim/cockpit2/radios/actuators/adf1_frequency_hz')

Callback for array datarefs is not (yet?) implemented.

Please note the Xplane interface hasn't been tested much. Report any bugs in this forum. Thanks.

[admin]

Reading variable value is quite slow because it must be synchronous. Lua script calls XPL plugin with request, it must wait for next “simulator” frame to get XPL plugin activated and then answer is sent back to Lua script. Considering your fps it can take tens of milliseconds to get variable value. And this is just one value. If your macro reads multiple values it can easily take significant time to get processed.

But sometimes you have a macro that needs to increment some variable. Imagine you have rotary encoder. Turning left it “pushes” button 0, turning right it sends push of button 1. You could do something like:

Code: Select all

lmc_set_xpl_variable('sim/cockpit2/radios/actuators/adf1_frequency_hz', lmc_get_xpl_variable('sim/cockpit2/radios/actuators/adf1_frequency_hz') + 10)

But that would be performance heavy solution – you would need at least 2 frames in XPL to have it processed.

So from version 0.1.0.313 we have a new function

Code: Select all

lmc_inc_xpl_variable('sim/cockpit2/radios/actuators/adf1_frequency_hz', 1)

It takes variable (1st argument) and change its actual value by 2nd argument. Second argument can be positive or negative (to decrease). Some variables can have ranges – you may need to not decrease heading bug value less than 0. Then you can use 3rd argument giving limit that result should not exceed.

Code: Select all

lmc_inc_xpl_variable('sim/cockpit/autopilot/heading_mag', -10, 0)

When current value is e.g. 5 then value after this call would be 0 (not -5). However if you really set heading bug by 2 buttons from rotary encoder you would probably expect smooth change between 0 and 360. It means when increasing the value anything above 360 would be added to 0. And on decrease anything below 0 will be subtracted from 360. And that’s why there is 4th argument. See example:

Code: Select all

-- following command means: increase value by 10, when overflow 360, start from 0
lmc_inc_xpl_variable('sim/cockpit/autopilot/heading_mag', 10, 360, 0)
-- following command means: decrease value by 10, when "underflow" below 0, start from 360
lmc_inc_xpl_variable('sim/cockpit/autopilot/heading_mag', -10, 0, 360)

There’s also alternative function which additional index parameter for array datarefs. The index comes right after variable name.

Code: Select all

lmc_inc_xpl_array_variable('sim/flightmodel/engine/ENGN_thro', 0, 10)
--PS: never tried to called this one. Testers, I need you :-)