03.04. FlightSimUpDownCommandSwitch

This is the most complex of all switches and the recommended solution for all multi-position switches that are actuated by up and down commands.

The FlightSimUpDownCommandSwitch switch object tracks the position of a multi-position switch and compares it with a dataref that represents the switch position in X-Plane's virtual cockpit. It then sends up and down commands until the value of the dataref matches the position of the physical switch.

Each physical switch position matches one of the values of the dataref. These values can be integer or floating point. At each moment, at maximum one of the input pins may be closed. If none of the pins is connected, the switch uses a "default value" and sends up and down commands until this value is reached by the dataref.

After sending an up or down command, the switch object waits for a change in the dataref before sending the next command.

The switch object has various configuration options that can be set on declaration or during setup():

• The "default value". If not specified, the value 0.0 is used as default value.
• A "tolerance" that is used to determine if up or down commands need to be sent. This happens only if the difference between the dataref value and the value that corresponds to the current switch position is larger than this tolerance. If not specified, the value DEFAULT_TOLERANCE (0.0001) is used.
• Please note that, in contrast to the FlightSimOnOffCommandSwitch, FlightSimOnCommandSwitch, FlightSimOffCommandSwitch, FlightSimPushbutton and FlightSimOnOffDatarefSwitch objects, the pin numbers of FlightSimUpDownCommandSwitch must be set on declaration.

Therefore, on declaration, the FlightSimUpDownCommandSwitch needs at least the following information:

• Number of connected pins
• List of pin numbers
• List of values (one for each pin number)

The dataref and commands must be set in setup() with setDatarefAndCommands().

Note that the following example will not run with the dummy datarefs and commands used in the sketch, as the dummy commands do not change a dataref and the dummy datarefs do not exist. For a working example, please see Demo_Cessna172.

#include <FlightSimSwitches.h>

// always declare FlightSimSwitches first
FlightSimSwitches switches;

// Up/down command switch connected to
// pins 3, 4 and 5. When pin 3 is connected to GND,
// "up" or "down" commands are sent until the dataref
// contains the value 2. Connecting pin 4 to GND sends
// "up" or "down" commands until the dataref holds 1.
// Same for pin 5 and value 3. When no pin is connected
// to GND, the object creates "up" or "down" command
// until the dataref is zero (default value).
// The "up" and "down" commands, as well as the dataref
// will be defined in setup().
FlightSimUpDownCommandSwitch sw1(
  3,                        // 3 pins connected
  SWITCH_POSITIONS(3,4,5),  // pin numbers of connected pins
  SWITCH_VALUES   (2,1,3)); // one value for each pin number

// Another Up/down command switch, but this time
// the default value that the dataref should take
// when none of the pins is connected is 5.
FlightSimUpDownCommandSwitch sw2(
  3,                        // 3 pins connected
  SWITCH_POSITIONS(6,7,8),  // pin numbers of connected pins
  SWITCH_VALUES   (2,1,3),  // one value for each pin number
  5);                       // default value

// Another up/down command switch, but this time
// the default value and tolerance are defined
// in setup()
FlightSimUpDownCommandSwitch sw3(
  4,                        // 4 pins connected
  SWITCH_POSITIONS(9,10,11,12),  // pin numbers of connected pins
  SWITCH_VALUES   (2, 1, 3, 4)); // one value for each pin number


void setup() {
  delay(1000);

  Serial.begin(115200);
  Serial.print  ("CAUTION! This program will not work without defining real and ");
  Serial.println("existing dataref and commands, as sending a command must result");
  Serial.print  ("in a change to the dataref value, which will not happen with the ");
  Serial.println("dummy datarefs used in this example.");

  // set switch 1 dataref and commands
  sw1.setDatarefAndCommands(
    XPlaneRef("dataref/for/switch1"), // dataref
    XPlaneRef("up/cmd/switch/1"),     // up command
    XPlaneRef("down/cmd/switch/1")    // down command
    );

  // set switch 2 dataref and commands
  sw2.setDatarefAndCommands(
    XPlaneRef("dataref/for/switch2"), // dataref
    XPlaneRef("up/cmd/switch/2"),     // up command
    XPlaneRef("down/cmd/switch/2")    // down command
    );

  // set switch 3 dataref, commands and options
  sw3.setDatarefAndCommands(
    XPlaneRef("dataref/for/switch3"), // dataref
    XPlaneRef("up/cmd/switch/3"),     // up command
    XPlaneRef("down/cmd/switch/3")    // down command
    );
  sw3.setDefaultValue(5);  // Default value: 5 if no pin is active
  sw3.setTolerance(0.1);   

  switches.setDebug(DEBUG_SWITCHES);
  switches.begin();
}

void loop() {
  FlightSim.update();
  switches.loop();
}

As an additional option, the FlightSimUpDownCommandSwitch permits to define some of the positions as "pushbutton" positions. These, in general, are the extreme positions of the switch and in these positions the switch in the virtual cockpit won't latch, but would need to be manually held. As an example, take the rotary ignition switch in the Cessna. While the first four positions ("off", "Mag R", "Mag L" and "Both") latch the key in position, the last position "Start" needs to be held by the pilot while the starter drives the engine.

The setPushbuttonPosition() method allows to specify one or more position indexes in the list of pin numbers that should be handled with "begin" and "end" calls to the "up" and "down" commands, just like with FlightSimPushbutton. See the Demo_Cessna172 for how this works.