Air Manager Instrument Logic API

From Sim Innovations Wiki
Jump to: navigation, search

Every instrument has a logic file (logic.lua). This file contains the code to tell the instrument how to behave. A well known scripting language is used, called Lua. This page describes which functions may be used in this logic file. For instance to add a background image, to add text or to communicate with X-Plane.

X-plane

These functions are used to communicate with X-plane. X-plane knows two ways of communicating, datarefs and events. Datarefs are used for most kind of data, such as airspeed, altitude etc. etc. The other way of communicating is done by sending commands to X-plane. Commands are event driven, and are mostly used for simulating certain buttons on instruments.

Function Description Version
xpl_dataref_subscribe(dataref,data_type,callback_function) Subscribe to specified dataref(s) AM 1.0/AP 3.0 and up
xpl_dataref_write(dataref,type,value,offset,force) Write to a certain X-plane dataref AM 1.0/AP 3.0 and up
xpl_command(commandref) Send a certain command to X-plane AM 1.2/AP 3.0 and up
variable_subscribe(source,variable_name,type,callback_function) Subscribe to multiple sources (X-plane, FSX, AM) using one subscription AM 3.0/AP 3.0 and up

Flight Simulator X and Prepar3D

These functions are used to communicate with Flight Simulator X and Prepar3D. Air Manager uses the SimConnect interface. There are two ways of communicating, variables and events. Variables are used for most kind of data, such as airspeed, altitude etc. etc. The other way of communicating is done by sending events to FSX or Prepar3D. Events are mostly used for simulating certain buttons on instruments.

Function Description Version
fsx_variable_subscribe(variable,unit,callback_function) Subscribe to specified variable(s) AM 2.0/AP 3.0 and up
fsx_variable_write(variable,unit, value) Write data to a variable AM 2.0/AP 3.0 and up
fsx_event(event_name) Trigger a certain FSX or Prepar3D event AM 2.0/AP 3.0 and up
variable_subscribe(source,variable_name,type,callback_function) Subscribe to multiple sources (X-plane, FSX, AM) using one subscription AM 3.0/AP 3.0 and up

Inter-instrument communication

These functions are used to communicate between instruments. Communication all goes through the Air Manager flight simulator plugin (X-plane or FSX), so make sure that is running. There are two ways to communicate between instruments. Variables and commands. Variables are state full, there is always has a value behind it. Commands are event based, and won't hold any value.

Function Description Version
var_id = am_variable_create(variable,unit,initial_value) Create a new Air Manager variable AM 2.1/AP 3.0 and up
am_variable_subscribe(variable,unit,callback_function) Subscribe to specified Air Manager variable(s) AM 2.1/AP 3.0 and up
am_variable_write(var_id,value,offset) Write to a Air Manager variable AM 2.1/AP 3.0 and up
variable_subscribe(source,variable_name,type,callback_function) Subscribe to multiple sources (X-plane, FSX, AM) using one subscription AM 3.0/AP 3.0 and up
am_command_subscribe(command,callback_function) Subscribe to specified Air Manager command(s) AM 2.1/AP 3.0 and up
am_command(command) Send a Air Manager command AM 2.1/AP 3.0 and up

External data source (Professional version only!)

The Professional version of Air Manager can connect to external data sources. These functions describe how to receive and send data from and to an external source.

Function Description Version
ext_variable_subscribe(source_tag,variable,unit,callback_function) Subscribe to external source variable(s) AM 2.1.2/AP 3.0 Professional and up
ext_variable_write(source_tag,variable,unit, value) Write an external source variable AM 2.1.2/AP 3.0 Professional and up
ext_command(source_tag,event_name) Send a command to the external source AM 2.1.2/AP 3.0 Professional and up

Image

These functions are used to add images to your instrument. The order in which you add the images determines the layering. The images you add first are at the back, and every next image is layed on top of the previous. PNG is used as the image format, since it supports transparency.

Click here for a screencast video about the image functions.

Function Description Version
image_id = img_add(filename,x,y,width,height) Add an image to specified bounds AM 1.0/AP 3.0 and up
image_id = img_add_fullscreen(filename) Add an image fullscreen AM 1.0/AP 3.0 and up
move(image_id,x,y,width,height) Move the image to the specified bounds AM 1.3/AP 3.0 and up
visible(image_id,visible) Makes an image visible or invisible AM 1.3/AP 3.0 and up
viewport_rect(image_id,x,y,width,height) Only shows the image within a specified rectangle AM 1.3/AP 3.0 and up
rotate(image_id,degrees) Rotate an image to the specified degree AM 1.0/AP 3.0 and up
Function Description Version
running_img_id = running_img_add_ver(filename,x,y,nr_visible_items,item_width,item_height) Adds a vertical running image object AM 1.0/AP 3.0 and up
running_img_id = running_img_add_hor(filename,x,y,nr_visible_items,item_width,item_height) Adds a horizontal running image object AM 1.0/AP 3.0 and up
running_img_id = running_img_add_cir(filename,x,y,nr_visible_items,item_width,item_height,radius) Adds a circular running image object AM 1.0/AP 3.0 and up
viewport_rect(running_img_id,x,y,width,height) Only shows the running image within a specified rectangle AM 1.3/AP 3.0 and up
running_img_move_carot(running_img_id, position) Set carrot position for a running image object AM 1.0/AP 3.0 and up

Text

These functions are used to add text to your instrument. TTF (True Type Fonts) are supported by Air Manager.

Click here for a screencast video about the text functions.

Function Description Version
txt_id = txt_add(text,style,x,y,width,height) Add a text box to specified bounds AM 1.0/AP 3.0 and up
txt_set(txt_id,text) Set a new text string AM 1.0/AP 3.0 and up
move(txt_id,x,y,width,height) Move a text to certain new bounds AM 1.3/AP 3.0 and up
visible(txt_id,visible) Makes a text visible or invisible AM 1.3/AP 3.0 and up
viewport_rect(txt_id,x,y,width,height) Only shows the text within a specified rectangle AM 1.3/AP 3.0 and up
rotate(txt_id,degrees) Rotate text to the specified degree AM 3.3/AP 3.3 and up
txt_style(txt_id,style) Change the style of a text box AM 1.0/AP 3.0 and up
txt_load_font(filename) Add a font from resources folder AM 1.0 up to AM 2.1.3
Function Description Version
running_txt_id = running_txt_add_ver(x,y,nr_visible_items,item_width,item_height,value_callback,style) Adds a vertical running text object AM 1.0/AP 3.0 and up
running_txt_id = running_txt_add_hor(x,y,nr_visible_items,item_width,item_height,value_callback,style) Adds a horizontal running text object AM 1.0/AP 3.0 and up
running_txt_id = running_txt_add_cir(x,y,nr_visible_items,item_width,item_height,radius,value_callback,style) Adds a circular running text object AM 1.0/AP 3.0 and up
viewport_rect(running_txt_id,x,y,width,height) Only shows the running text within a specified rectangle AM 1.3/AP 3.0 and up
running_txt_move_carot(running_txt_id, position) Set carrot position for a running text object AM 1.0/AP 3.0 and up

Button

These functions let you add buttons to your instruments. Buttons don't have any state, they always pop back to the original position.

Function Description Version
button_id = button_add(img_normal,img_pressed,x,y,width,height,click_press_callback, click_release_callback) Add a button to specified bounds AM 1.2/AP 3.0 and up
mouse_setting(button_id,property,value) Sets mouse settings for a button (such as custom cursor images) AM 2.1/AP 3.0 and up
move(button_id,x,y,width,height) Move the button to the specified bounds AM 1.2/AP 3.0 and up
visible(button_id,visible) Makes the button visible or invisible AM 1.3/AP 3.0 and up

Switch

These functions let you add switches to your instrument. Switched are statefull, they can have 2 or more positions.

Function Description Version
switch_id = switch_add(img_pos_0, img_pos_1, img_pos_n,x,y,width,height,click_callback) Add a switch to specified bounds AM 1.2/AP 3.0 and up
switch_set_state(switch_id,position) Set the switch to a certain position AM 1.2/AP 3.0 and up
touch_setting(switch_id,property,value) Sets touch settings for a switch AM 2.1/AP 3.0 and up
mouse_setting(switch_id,property,value) Sets mouse settings for a switch (such as custom cursor images) AM 2.1/AP 3.0 and up
move(switch_id,x,y,width,height) Move the switch to the specified bounds AM 1.3/AP 3.0 and up
visible(switch_id,visible) Makes the switch visible or invisible AM 1.3/AP 3.0 and up

Dial

These functions let you add a dial to your instrument. Dials can be rotated endlessly, and don't hold any state.

Function Description Version
dial_id = dial_add(image,x,y,width,height,click_callback) Add a dial to specified bounds AM 1.2/AP 3.0 and up
dial_click_rotate(dial_id,degrees delta) Set number of degrees delta for the dial to rotate on each click AM 1.2/AP 3.0 and up
touch_setting(dial_id,property,value) Sets touch settings for a dial AM 2.1/AP 3.0 and up
mouse_setting(dial_id,property,value) Sets mouse settings for a dial (such as custom cursor images) AM 2.1/AP 3.0 and up
move(dial_id,x,y,width,height) Move the dial to the specified bounds AM 1.3/AP 3.0 and up
visible(dial_id,visible) Makes the dial visible or invisible AM 1.3/AP 3.0 and up

Slider

These functions let you add a slider to your instrument. You can add an horizontal, vertical or circular slider to your instrument.

Function Description Version
slider_id = slider_add_hor(image, x, y, width, height, thumb_image, thumb_width, thumb_height, callback) Add a horizontal slider to specified bounds AM 3.0/AP 3.0 and up
slider_id = slider_add_ver(image, x, y, width, height, thumb_image, thumb_width, thumb_height, callback) Add a vertical slider to specified bounds AM 3.0/AP 3.0 and up
slider_id = slider_add_cir(image, x, y, width, height, radius, start_angle, end_angle, thumb_image, thumb_width, thumb_height, callback) Add a circular slider to specified bounds AM 3.0/AP 3.0 and up
slider_set_position(slider_id, position) Set the slider to a certain position AM 3.0/AP 3.0 and up
move(dial_id,x,y,width,height) Move the slider to the specified bounds AM 3.0/AP 3.0 and up
visible(dial_id,visible) Makes the slider visible or invisible AM 3.0/AP 3.0 and up

Scroll wheel

These functions let you add a scroll wheel to your instrument. You can add a horizontal or vertical scroll wheel to your instrument.

Function Description Version
scrollwheel_id = scrollwheel_add_hor(segment_image, x, y, width, height, segment_width, segment_height, callback) Add a horizontal scroll wheel to specified bounds AM 3.0/AP 3.0 and up
scrollwheel_id = scrollwheel_add_ver(segment_image, x, y, width, height, segment_width, segment_height, callback) Add a vertical scroll wheel to specified bounds AM 3.0/AP 3.0 and up
mouse_setting(scrollwheel_id,property,value) Sets mouse settings for a button (such as custom cursor images) AM 3.1/AP 3.1 and up
touch_setting(scrollwheel_id,property,value) Sets touch settings for a scroll wheel AM 3.1/AP 3.1 and up
move(scrollwheel_id,x,y,width,height) Move the scroll wheel to the specified bounds AM 3.0/AP 3.0 and up
visible(scrollwheel_id,visible) Makes the scroll wheel visible or invisible AM 3.0/AP 3.0 and up

Map

These functions let you open a moving map to your instrument. OpenStreetMap is used as the source for the map. You also have the ability to overlay NAV data (Airports, VOR, NDB) onto the map.

Click here for a screencast video about the map functions.

Function Description Version
map_id = map_add(x,y,width,height,source,zoom) Add a map to the instrument. AM 1.1/AP 3.0 and up
visible(map_id,visible) Make a map visible or invisible AM 1.3/AP 3.0 and up
map_goto(map_id,lon,lat) Go to a certain location on earth, defined by longitude and latitude. AM 1.1/AP 3.0 and up
map_zoom(map_id,zoom) Change the zoom level of a map AM 1.1/AP 3.0 and up
map_baselayer(map_id,source) Change the base layer of a map AM 1.1.2/AP 3.0 and up
layer_id = map_add_nav_img_layer(map_id, nav_type, filename, x, y, width, height) Add an image layer to the map for a certain NAV source. AM 1.1/AP 3.0 and up
layer_id = map_add_nav_txt_layer(map_id, nav_type, nav_param, style, x, y, width, height) Add a txt layer to the map for a certain NAV source. AM 1.1/AP 3.0 and up
visible(layer_id,visible) Make a layer visible or invisible AM 1.3/AP 3.0 and up

Group

Groups give you the ability to group together multiple objects (switch, button, image, text, etc etc). This way you can make the whole group visible of invisible with one function call.

Function Description Version
group_id = group_add(gui_id, ...) Create a new group AM 1.2/AP 3.0 and up
group_obj_add(group_id, gui_id, ...) Add additional objects to the group AM 2.1/AP 3.0 and up
group_obj_remove(group_id, gui_id, ...) Remove objects from the group AM 2.1/AP 3.0 and up
visible(group_id,visible) Change the visibility of the entire group AM 1.3/AP 3.0 and up

Sound

These functions let you add sound clips to your instrument. Only WAV file format is supported.

Function Description Version
sound_id = sound_add(filename) Loads a new sound AM 1.0/AP 3.0 and up
sound_play(sound_id) Play a sound once AM 1.0/AP 3.0 and up
sound_loop(sound_id) Play a sound forever and ever AM 1.0/AP 3.0 and up
sound_stop(sound_id) Stop playing a sound AM 1.0/AP 3.0 and up

Sensor

These functions let you read sensor information, such as GPS, gyroscope and acceleration data.

Function Description Version
sensor_gyroscope_subscribe(callback_function) Subscribe to gyroscope data (roll, pitch, yaw). AM 3.0/AP 3.0 and up
sensor_acceleration_subscribe(callback_function) Subscribe to acceleration data (X, Y and Z). AM 3.0/AP 3.0 and up
sensor_location_subscribe(callback_function) Subscribe to location data (Latitude and longitude). AM 3.0/AP 3.0 and up

Timer

These functions let you add a timer to your instrument. The timer can call a specific function with a configurable interval, and delay.

Function Description Version
timer_id = timer_start(delay,period,callback_function) Start a timer which will call a function at a given interval AM 2.1/AP 3.0 and up
timer_stop(timer_id) Stop a timer AM 2.1/AP 3.0 and up
running = timer_running(timer_id) Check if a timer is still running AM 2.1/AP 3.0 and up

Persistence

Persistence functions let you save data to the hard drive. This makes it possible to let your instrument 'remember' certain settings or values.

Function Description Version
persist_id = persist_add(key, type, initial_value) Open up a new persistence object AM 2.1/AP 3.0 and up
persist_put(persist_id, value) Put a new value in the persistence object AM 2.1/AP 3.0 and up
value = persist_get(persist_id) Get the value from a persistence object AM 2.1/AP 3.0 and up

User properties

User properties can be used to let the user of the instrument change certain aspects of your instrument. User properties are visible to the instrument user and requires no need knowledge of the lua system.

Function Description Version
user_prop_id = user_prop_add_integer(name, min, max, default_value, description) Create a new integer user property AM 3.0/AP 3.0 and up
user_prop_id = user_prop_add_real(name, min, max, default_value, description) Create a new floating point user property AM 3.0/AP 3.0 and up
user_prop_id = user_prop_add_boolean(name, default_value, description) Create a new boolean user property AM 3.0/AP 3.0 and up
user_prop_id = user_prop_add_string(name, default_value, description) Create a new string user property AM 3.0/AP 3.0 and up
user_prop_id = user_prop_add_enum(name, possible_values, default_value, description) Create a new enumeration (list) user property AM 3.0/AP 3.0 and up
user_prop_id = user_prop_add_hardware_id(name, default_value, description) Create a new hardware ID user property AM 3.0/AP 3.0 and up
value = user_prop_get(user_prop_id) Get the value of a user property AM 3.0/AP 3.0 and up

Navigation data

These functions help you get navigation data from Air Manager.

Function Description Version
nav_item = nav_get(nav_type, nav_property, value) Get details of a NAV item AM 2.1.1/AP 3.0 and up
nav_items = nav_get_nearest(nav_type, lat, lon, max_entries) Get the nearest NAV items from a certain latitude and longitude AM 2.1.1/AP 3.0 and up
nav_items = nav_get_radius(nav_type, lat, lon, distance, max_entries) Get the NAV items within a radius around a certain latitude and longitude AM 2.1.1/AP 3.0 and up

Helpers

Helper functions. All sorts of functions aimed to do common instruments tasks.

Function Description Version
value = instrument_prop(property) Get different settings from the current instrument like aircraft, type, version, height, width, development, etc etc... AM 2.1/AP 3.0 and up
meta_data = resource_info(filename) Get information of a resource file. This can also be used to check if a resource exists. AM 2.1.1/AP 3.0 and up
value = var_cap(value,min,max) Limits a value to a minimum and maximum value. AM 1.0/AP 3.0 and up
value = var_round(value,decimals) Rounds the value to the given number of decimals. AM 1.0/AP 3.0 and up
value = var_format(value,decimals) Rounds the value to the given number of decimals and always shows that selected amount of decimals. AM 1.0/AP 3.0 and up
x, y = geo_rotate_coordinates(degrees, radius) Get x and y coordinates from a circle with a certain radius and angle. AM 1.0/AP 3.0 and up

Hardware

Hardware functions. All sorts of functions aimed to do interact with hardware buttons, dials, LED's etc.

Check the list below for compatible hardware (such as Raspberry Pi and Arduino):
Hardware ID list

Function Description Version
hw_button_id = hw_button_add(hw_id, pressed_callback, released_callback) Add a hardware button AM 3.0/AP 3.0 and up
hw_switch_id = hw_switch_add(hw_id_0, hw_id_0, hw_id_n, callback) Add a hardware switch AM 3.0/AP 3.0 and up
hw_dial_id = hw_dial_add(hw_id_a, hw_id_b, callback) Add a rotary encoder AM 3.0/AP 3.0 and up
hw_input_id = hw_input_add(hw_id, callback) Add a hardware input AM 3.0/AP 3.0 and up
state = hw_input_read(hw_input_id) Reads the current state of the input AM 3.0/AP 3.0 and up
hw_adc_input_id = hw_adc_input_add(hw_id, callback) Add a hardware ADC input AM 3.0/AP 3.0 and up
state = hw_adc_input_read(hw_adc_input_id) Read the current ADC input value AM 3.0/AP 3.0 and up
hw_output_id = hw_output_add(hw_id, initial_state) Add a hardware output AM 3.0/AP 3.0 and up
hw_output_set(hw_output_id, state) Set the state of a output AM 3.0/AP 3.0 and up
hw_led_id = hw_led_add(hw_id, initial_brightness) Add a LED output AM 3.0/AP 3.0 and up
hw_led_set(hw_led_id, brightness) Set the brightness of the LED AM 3.0/AP 3.0 and up
hw_output_pwm_id = hw_output_pwm_add(hw_id, frequency_hz, initial_duty_cycle) Add a PWM hardware output AM 3.0/AP 3.0 and up
hw_output_pwm_duty_cycle(hw_output_pwm_id, duty_cycle) Set the duty cycle of a PWM output AM 3.0/AP 3.0 and up
hw_message_port_id = hw_message_port_add(hw_id, message_callback) Add a custom HW device AM 3.1/AP 3.1 and up
hw_message_port_send(hw_message_port_id , message_id, data) Send a message to the HW device AM 3.1/AP 3.1 and up

Flight Illusion gauges (Not yet available, in development)

With these functions, you can connect to a Flight Illusion gauge from your instrument code.

NOTE : This is still in development, and not yet available.

Function Description Version
fi_com_id = fi_bridge_add_com(com_id) Open up Flight Illusion communication on a certain COM port. Not available yet
fi_gauge_id = fi_bridge_add_gauge(fi_com_id, address, type) Connect to a Flight Illusion gauge on a created connection. Not available yet
fi_bridge_set_gauge_prop(fi_gauge_id, prop_name, value) Set a gauge property. E.g. needle position or display text. Not available yet

Canvas (Not yet available, in development)

The canvas allows to draw shapes like lines, rectangles, circles etc. in your instrument.

NOTE : This is still in development, and not yet available.

Function Description Version
canvas_id = canvas_add(x, y, width, height, style, draw_callback) Create a new canvas to draw in. AM 3.3/AP 3.0 and up
canvas_draw(canvas_id, draw_callback) Redraw the canvas AM 3.3/AP 3.0 and up
move(canvas_id,x,y,width,height) Move a canvas to certain new bounds AM 3.3/AP 3.0 and up
visible(canvas_id,visible) Makes a canvas visible or invisible AM 3.3/AP 3.3 and up
rotate(canvas_id,degrees) Rotate canvas to the specified degree AM 3.3/AP 3.3 and up
_move_to(x, y) Move pen to new location, this won't draw anything. AM 3.3/AP 3.0 and up
_line_to(x, y) Queue new pen stroke to new location AM 3.3/AP 3.0 and up
_rect(x, y, width, height) Queue a rectangle for drawing AM 3.3/AP 3.0 and up
_circle(center_x, center_y, start_angle, end_angle, radius) Queue a circle for drawing AM 3.3/AP 3.0 and up
_triangle(x1, y1, x2, y2, x3, y3) Queue a triangle for drawing AM 3.3/AP 3.0 and up
_stroke(color, stroke_width) Stroke enqueued objects AM 3.3/AP 3.0 and up
_fill(color) Fill enqueued objects AM 3.3/AP 3.0 and up