Lua Scripting¶

Starting with version 7.0, XCSoar can be extended using Lua scripts.

Lua is a language that is easy to learn, powerful enough for XCSoar and light: the interpreter library weighs just 200 kB. Lua is a common language choice for integrated scripting languages.

Learning Lua¶

print("Hello World")

This manual will not attempt to teach you basic Lua. There are enough resources on the internet, for example:

Lua 5.4 Reference Manual
Programming in Lua, a book on Lua
Tutorial Directory on the lua-users wiki
Wikipedia

Just to get you started from here, here’s some more example code:

-- comment starts with a double hyphen

--[[
multi
line
comment
]]--

i = 42
if i > 1 then
   print("i=" .. i)
elseif i == 0 then
   print("zero")
else
   error("negative")
end

a = {1, 'a', 3.14}
print(a[2])

function f(a, b)
   return a * b
end
print(f(2, 3))

Running Lua¶

The directory XCSoarData/lua/ may contain Lua scripts (*.lua). The directory XCSoarData/lua/lib/ may contain Lua libraries to be loaded with require.

After startup, XCSoar starts the script init.lua (if it exists).

The InputEvent RunLuaFile can be used to start additional scripts. If no parameter is given, the user is asked to choose a file. Note that the InputEvent subsystem is deprecated and will be removed once Lua support is complete.

As long as a Lua script runs, the XCSoar user interface is blocked. Be careful not to write scripts that loop forever.

Once the Lua script finishes, the Lua interpreter is shut down – unless the script has registered a callback (e.g. a timer). In that case, the Lua script stays resident until it unregisters all callbacks (or until XCSoar quits or the user stops the script explicitly).

Running Lua on the Command Line¶

You can experiment with XCSoar Lua scripts with the RunLua command-line tool, e.g.:

make output/UNIX/bin/RunLua
./output/UNIX/bin/RunLua test/lua/geo.lua

Most libraries are missing here (everything specific to a full XCSoar), but some very basic things can be tested here, for example the HTTP client and the geo library (class GeoPoint). Being a small non-interactive command-line program, it is also easy to debug with gdb and valgrind.

Lua Standard Libraries¶

XCSoar enables the following Lua standard libraries:

package
table
string
math

Lua’s print() function writes to the XCSoar log file (XCSoarData/xcsoar.log).

The error() function aborts the Lua script and reports the specified error message to the user.

XCSoar adds another function to the root namespace: alert(). It shows a dialog with the specified message, and returns as soon as the user has closed the dialog. This function is experimental, and may disappear or be renamed at any time. Most importantly: do not abuse it, as it may annoy the user.

XCSoar’s Lua API¶

The package/namespace xcsoar provides access to XCSoar. It contains the following names:

Name	Description
`VERSION`	The XCSoar version number, for example `7.0`.
`GeoPoint`	A class which describes a geodetic location on earth’s surface.
`blackboard`	Access to sensor data. See The Blackboard.
`map`	The map view. See The Map.
`airspace`	Access to airspace data. See Airspace.
`wind`	Access to wind data and settings. See Wind.
`logger`	Access to logger settings. See Logger.
`replay`	Access to replay system. See Replay.
`tracking`	Access to tracking settings. See Tracking.
`timer`	Class for scheduling periodic callbacks. See Timers.
`http`	HTTP client. See HTTP Client.
`share_text(text)`	Deliver plain text data to somebody; the user will be asked to pick a recipient (Android only).

The Blackboard¶

The blackboard provides access to sensor data, such as GPS location.

The following attributes are provided by xcsoar.blackboard:

Name	Description
`clock`	A monotonic wall clock time [s], with an undefined reference.
`time`	A wall clock time [s], since midnight (UTC) of the day the flight started. Not strictly monotonic (can warp under certain circumstances).
`date_time_utc`	A date table describing the current date and time (UTC), preferably from the GPS. Not strictly monotonic (can warp under certain circumstances).
`location`	The current location (table with keys `longitude` and `latitude` [°]) according to GPS.
`altitude`	The current altitude above MSL [m].
`altitude_agl`	The current altitude above ground [m].
`track`	The current flying direction above ground [°].
`ground_speed`	The aircraft speed relative to the ground [\(m/s\)].
`air_speed`	The true airspeed [\(m/s\)].
`bank_angle`	The bank angle [°].
`pitch_angle`	The pitch angle [°].
`heading`	The current magnetic heading in [°].
`g_load`	The current g-load.
`static_pressure`	The static pressure [Pascal].
`pitot_pressure`	The pitot pressure [Pascal].
`dynamic_pressure`	The dynamic pressure [Pascal].
`temperature`	The current temperature.
`humidity`	The current humidity.
`voltage`	The external battery voltage [V].
`battery_level`	The internal battery-level [percent].
`noncomp_vario`	The non-compensated vertical speed [\(m/s\)].
`total_energy_vario`	The total-energy-compensated vertical speed [\(m/s\)].
`netto_vario`	The netto variometer value [\(m/s\)].

Any of these (except for clock) may be nil if its value is not known, e.g. if there is no GPS fix.

The Map¶

The map provides access to XCSoar’s map view.

The following attributes are provided by xcsoar.map:

Name	Description
`location`	The current reference location (may be aircraft location or pan location).
`is_panning`	Gives back if the panning mode is active at the moment.
`enterpan()`	Activates the panning mode.
`disablepan()`	Disables the panning mode.
`leavepan()`	Leaves the panning mode.
`panto(latitude, longitude)`	Pans to the given location.
`pancursor(dx, dy)`	Pans the cursor by dx and dy.
`zoom(factor)`	Zooms the map, factor -2 to 2.
`next()`	Opens the next page.
`prev()`	Opens the previous page.
`show()`	Show the map; disable thermal assistant or other widgets replacing the map view.

Airspace¶

The Airspace provides access to airspace data, such as name / distance to the next airspace.

The following attributes are provided by xcsoar.airspace:

Name	Description
`nearest_vertical_distance`	The vertical distance to the next airspace [m].
`nearest_vertical_name`	The name of the next vertical airspace.
`nearest_horizontal_distance`	The horizontal distance to the next airspace [m].
`nearest_horizontal_name`	The name of the next horizontal airspace.

Task¶

The Task provides access to task data such as distances / bearing to the next waypoint.

The following attributes are provided by xcsoar.task:

Name	Description
`bearing`	The true bearing to the next waypoint [°]. For AAT tasks, this is the true bearing to the target within the AAT sector.
`bearing_diff`	The difference between the glider’s track bearing, to the bearing of the next waypoint, or for AAT tasks, to the bearing to the target within the AAT sector [°].
`radial`	The true bearing from the next waypoint to your position. [°].
`next_distance`	The distance to the currently selected waypoint [m]. For AAT tasks, this is the distance to the target within the AAT sector.
`next_distance_nominal`	The distance to the currently selected waypoint [m]. For AAT tasks, this is the distance to the origin of the AAT sector.
`next_ete`	Estimated time [s] required to reach next waypoint, assuming performance of ideal MacCready cruise/climb cycle.
`next_eta`	Estimated arrival local time at next waypoint, assuming performance of ideal MacCready cruise/climb cycle.
`next_altitude_diff`	Arrival altitude at the next waypoint relative to the safety arrival height.
`nextmc0_altitude_diff`	Arrival altitude at the next waypoint with MC 0 setting, relative to the safety arrival height.
`next_altitude_require`	Additional altitude required to reach the next turnpoint.
`next_altitude_arrival`	Absolute arrival height at the next waypoint in final glide.
`next_gr`	The required glide ratio over ground to reach the next waypoint, given by the distance to the next waypoint divided by the height required to arrive at the safety arrival height.
`final_distance`	Distance to finish around remaining turn points.
`final_ete`	Estimated time required to complete task, assuming performance of ideal MacCready cruise/climb cycle.
`final_eta`	Estimated arrival local time at task completion, assuming performance of ideal MacCready cruise/climb cycle.
`final_altitude_diff`	Arrival altitude at the final task turn point relative to the safety arrival height.
`finalmc0_altitude_diff`	Arrival altitude at the final task turn point, with MC 0 setting, relative to the safety arrival height.
`final_altitude_require`	Additional altitude required to finish the task.
`task_speed`	Average cross country speed while on the current task, not compensated for altitude.
`task_speed_achieved`	Achieved cross country speed while on the current task, compensated for altitude. Equivalent to Pirker cross country speed remaining.
`task_speed_instant`	Instantaneous cross country speed while on the current task, compensated for altitude. Equivalent to instantaneous Pirker cross country speed.
`task_speed_hour`	Average cross country speed while on the current task over the last hour, not compensated for altitude.
`final_gr`	The required glide ratio over the ground to finish the task, given by the distance to go divided by the height required to arrive at the safety arrival height.
`aat_time`	Assigned Area Task time remaining.
`aat_time_delta`	Difference between estimated task time and AAT miminum time.
`aat_distance`	Assigned Area Task distance around target points for remainder of task.
`aat_distance_max`	Assigned Area Task maximum distance possible for remainder of task.
`aat_distance_min`	Assigned Area Task minimum distance possible for remainder of task
`aat_speed`	Assigned Area Task average speed achievable around target points remaining in minimum AAT time.
`aat_speed_max`	Assigned Area Task average speed achievable if flying maximum possible distance remaining in minimum AAT time.
`aat_speed_min`	Assigned Area Task average spped achievable if flying minimum possible distance remaining in minimum AAT time.
`time_under_max_height`	The contiguous period the plane has been below the task start max. height.
`next_etevmg`	Estimated time required to reach next waypoint, assuming current ground speed is maintained.
`final_etevmg`	Estimated time required to complete task, assuming current ground speed is maintained.
`cruise_efficiency`	Efficiency of cruse, 1 indicates perfect MacCready performance.

Settings¶

The Settings provides access to xcsoar settings, such as MC value.

The following attributes are provided by xcsoar.settings:

Name	Description
`mc`	The current set MacCready Value [\(m/s\)].
`bugs`	The current used bug settings in terms of polar degradation.
`wingload`	The current wingload.
`ballast`	Ballast of the glider. 0 means no ballst, 0.3 means 30% of the maximum ballast the glider can carry.
`qnh`	Area pressure for barometric altimeter calibration [Pascal].
`max_temp`	The forecast ground temperature [Kelvin].
`safetymc`	The MacCready setting used, when safety MC is enabled for reach calculations, in task abort mode and for determining arrival altitude at airfields.
`riskfactor`	The STF risk factor reduces the MacCready setting used to calculate speed to fly as the glider gets low, in order to compensate for risk.
`polardegradation`	A permanent polar degradation, 1 means no degradation, 0.5 indicates the glider’s sink rate is doubled.
`arrivalheight`	The height above terrain that the glider should arrive at for a safe landing.
`terrainheight`	The height above trerrain that the glider must clear during final glide.
`setmc(value)`	Sets the MacCready value.
`setbugs(value)`	Sets the bugs, 1.0 means no bugs, 0.5 means 50% polar degradation.
`setqnh(float value)`	Sets the QNH [Pascal].
`setballast(float value)`	Sets the ballst, 0 means no ballst, 0.5 means 50% of the maximum ballst the glider can carry.
`setmaxtemp(float value)`	Sets the maximum temperature [Kelvin].

Wind¶

The Settings provides access to xcsoar wind data and settings.

The following attributes are provided by xcsoar.wind:

Name	Description
`wind_mode`	Wind mode, 0: Manual, 1: Circling, 2: ZigZag, 3: Both.
`setwindmode(int value)`	Sets wind mode (0..3).
`tail_drift`	Determines whether the snail trail is drifted with the wind when displayed in circling mode, 0: Off, 1: On.
`settaildrift(bool value)`	Turns Taildrift Off / On (0..1).
`wind_source`	The Source of the current wind, 0: None, 1: Manual, 2: Circling, 3: Both, 4: External.
`wind_speed`	The current wind speed [\(m/s\)].
`setwindspeed(float value)`	Sets manual the wind speed [\(m/s\)].
`wind_bearing`	The current wind bearing [°].
`setwindbearing(float value)`	Sets manual the wind bearing [°].
`clear()`	Clears the wind settings and calculations.

Logger¶

The Settings provides access to xcsoar Logger data and settings.

The following attributes are provided by xcsoar.logger:

Name	Description
`pilot_name`	Gives back the set pilot name.
`set_pilot_name(name)`	Sets the pilot name.
`time_step_cruise`	The time interval between logged points when not circling [seconds].
`set_time_step_cruise(time)`	Sets time interval between logged points when not circling [seconds].
`time_step_circling`	The time interval between logged points when circling [seconds].
`set_time_step_circling(int time)`	Sets time interval between logged points when circling [seconds].
`auto_logger`	Status of the auto-logger; 0 = On, 1 = Take off only, 2 = Off.
`set_autologger(mode)`	Sets the Autologger mode; 0 = On, 1 = Take off only, 2 = Off.
`nmea_logger`	Status of the NMEA-Logger; 0 = Off, 1 = On.
`enable_nmea()`	Enables the NMEA-Logger.
`disable_nmea()`	Disables the NMEA-Logger.
`log_book`	Status of the log-book; 0 = Off, 1 = On.
`enable_logbook()`	Enables the logbook.
`disable_logbook()`	Disables the logbook.
`logger_id`	The current set logger-id.
`set_logger_id(char* id)`	Sets the logger-id.

Tracking¶

The Settings provides access to xcsoar Tracking settings.

The following attributes are provided by xcsoar.tracking:

Name	Description
`skylines_enabled`	States if skylines tracking is enabled.
`enable_skylines()`	Enables skylines tracking.
`disable_skylines()`	Disables skylines tracking.
`skylines_roaming`	States if skylines roaming is enabled.
`skylines_interval`	The skylines tracking interval [seconds].
`set_skylines_interval(interval)`	Sets the tracking interval [seconds].
`skylines_traffic_enabled`	If enabled, shows friends on the map, download the position of your friends live from the SkyLines server.
`enable_skylines_traffic()`	Enables the display of friends on the map.
`disable_skylines_traffic()`	Disables the display of friends on the map.
`skylines_near_traffic_enabled`	If enabled shows nearby traffic
`enable_skylines_near_traffic()`	Enables the display of nearby traffic on the map.
`disable_skylines_near_traffic()`	Disables the display of nearby traffic on the map.
`livetrack24_enabled`	States if livetrack24 is enabled.
`enable_livetrack24()`	Enables livetrack24.
`disable_livetrack24()`	Disables livetrack24.
`livetrack24_interval`	Livetrack24 tracking interval [seconds].
`set_livetrack24_interval(interval)`	Sets the tracking interval [seconds].
`livetrack24_vehicle_name`	Get current vehicle name.
`set_livetrack24_vehiclename(name)`	Sets the livetrack24 vehiclename.

Replay¶

The Settings provides access to xcsoar Replay system.

The following attributes are provided by xcsoar.replay:

Name	Description
`start(path)`	Starts replay from file `path`.
`stop()`	Stops replay.
`fast_forward(dt)`	Fast forwards `dt` [seconds].
`set_time_scale(r)`	Sets replay clock rate to `r`.
`time_scale`	Gets replay clock rate.
`virtual_time`	Gets replay virtual time [in seconds].

Timers¶

The class xcsoar.timer implements a timer that calls a given Lua function periodically.

xcsoar.timer.new(60, function(t)
  print("A minute has passed")
  t:cancel()
end)

The following methods are available in xcsoar.timer:

Name	Description
`new(period, function)`	Create a new instance and schedule it. The period is a numeric value in seconds.
`cancel()`	Cancel the timer.
`schedule(period)`	Reschedule the timer.

HTTP Client¶

The class xcsoar.http.Request can be used to send HTTP requests.

request = xcsoar.http.Request:new(
    "https://download.xcsoar.org/repository")
response = request:perform()
print("status", response.status)
for name, value in pairs(response.headers) do
    print("header", name, ":", value)
end
print("body", response.body)

The xcsoar.http.Request interface:

Name	Description
`new(URL)`	Creates a new instance. One instance can only be used once.
`perform()`	Sends the request and waits for the response. Returns a response object.

The response interface:

Name	Description
`status`	The numeric HTTP status code.
`headers`	A table of response headers.
`body`	The response body (as string).

Legacy¶

Before version 7.0, XCSoar was adapted using the InputEvent subsystem (see Appendix [sec:input-events]). During the Lua transition, Lua scripts can invoke InputEvents, for example:

xcsoar.fire_legacy_event("Setup", "basic")
xcsoar.fire_legacy_event("Zoom", "basic")

This function will be removed before the final 7.0 release.