Switch connection tutorial

Description

Switches have multiple (at least two) positions. The callback returns the position of the switch as a number from 0 to whatever positions the switch has.

An example of a switch is the master battery switch, which turns the battery power on and off. Another example is the magnetos/starter switch, which usually has 5 positions. In the examples below we will show you how these can be made. The API function we'll be using is hw_switch_add.

Examples

Master battery switch

The first example will be the battery switch. This is a single switch with two positions: Off (0) and On (1). In this case you can either have a switch with three pins (two-way switch), from which two go to the I/O and one to ground. Or a switch with two pins (one-way switch), from which one goes to the I/O pin and one to ground. Both situations are drawn below.

Now let's start with the script. We're going to turn the battery in the sim on and off with events (Prepar3D) and commands (X-Plane).

-- This function is called every time the battery switch has a new position
function switch_battery_callback(position)
  print("The battery switch got changed to position " .. position)

  if position == 0 then
    fsx_event("BATTERY_BUS_CONTACT_SET", 0)
    xpl_command("sim/electrical/battery_1_off")
  elseif position == 1 then
    fsx_event("BATTERY_BUS_CONTACT_SET", 1)
    xpl_command("sim/electrical/battery_1_on")
  end
end

-- Here we create the switch. In case of a two-way switch use 2, in case of a one-way switch use 1. In this example we use 2 (two-way).
hw_switch_add("Battery", 2, switch_battery_callback)

Now you have to assign either one (one-way) or two pins (two-way) in Air Manager.

Ignition switch

The ignition (magnetos) switch has five positions: 0: OFF 1: RIGHT 2: LEFT 3: BOTH 4: START

For this we use a five-way switch as shown below. Note that real (aircraft) ignition switches have a more complex connection structure. There are five position key switches available from various sources.

The script for this setup looks like this.

-- This function is called every time the ignition switch has a new position
function switch_ignition_callback(position)
  print("The ignition switch got changed to position " .. position)

  if position == 0 then
    fsx_event("MAGNETO1_OFF")
    xpl_command("sim/magnetos/magnetos_off_1")
  elseif position == 1 then
    fsx_event("MAGNETO1_RIGHT")
    xpl_command("sim/magnetos/magnetos_right_1")
  elseif position == 2 then
    fsx_event("MAGNETO1_LEFT")
    xpl_command("sim/magnetos/magnetos_left_1")
  elseif position == 3 then
    fsx_event("MAGNETO1_BOTH")
    xpl_command("sim/magnetos/magnetos_both_1")
    -- X-Plane requires you to send a begin command (1) to keep the starter engine activated, after that we need to turn it off (0) when going back to BOTH
    xpl_command("sim/starters/engage_starter_1", 0)
  elseif position == 4 then
    fsx_event("MAGNETO1_START")
    -- The starter engine will run as long as you keep it in the last position.
    xpl_command("sim/starters/engage_starter_1", 1)
  end
end

-- Create a 5 position switch
hw_switch_add("Ignition", 5, switch_ignition_callback)

The last step is to assign all the five positions to individual I/O pins.