Using Flight Sim Controls

NavFrequency Example

A simulator plugin is used. Currently X-Plane is supported.

Together with Arduino functions and libraries, Flight Sim Controls provides an incredibly flexible platform for implementing almost any type of flight simulation control.

Update: Jorg Neves Bliesener has created an updated plugin which works with DataRef names longer than 58 characters. Look in the "target/TeensyControls" folder for a compiled copy.

Quick Installation Steps

Example Programs

Special Variable Types

In setup(), your code links the variables to data or command names in the simulator. Unlike game controllers, the data mapping is reliable. You can even reprogram or unplug and reconnect your Teensy while the flight simulator is running, and it will always access the data and commands you specify.

Commands: FlightSimCommand (Write Only)

// Create Variables (global scope)
FlightSimCommand NavCoarseUp;
FlightSimCommand NavCoarseDown;

// Configure the X-Plane variables in setup
void setup() {
  NavCoarseUp = XPlaneRef("sim/radios/actv_nav1_coarse_up");
  NavCoarseDown = XPlaneRef("sim/radios/actv_nav1_coarse_down");
}

Writing a 1 to a command variable activates the command. For most commands, this is equivelant to pressing a button. Writing a 0 deactivates the command, or releases the button.

A special once() function can also be used. See the NavFrequency example.

Data: FlightSimInteger & FlightSimFloat (Read or Write)

// Create Variables (global scope)
FlightSimInteger NavFrequencyHz;

// Configure the X-Plane variables in setup
void setup() {
  NavFrequencyHz = XPlaneRef("sim/cockpit2/radios/actuators/nav1_frequency_hz");
}

Writing Data

  NavFrequencyHz = 10050; // Set the radio to 100.50

Reading Data

Reading the variables in equations or function inputs does not cause additional USB communication. FlightSim.update() stores a copy of the simulator's data on Teensy, so you can read the variables without any delays.

Automatic onChange() Updates

void setup() {
  NavFrequencyHz = XPlaneRef("sim/cockpit2/radios/actuators/nav1_frequency_hz");
  NavFrequencyHz.onChange(update_lcd);  // update the LCD when X-Plane changes
}
void loop() {
  FlightSim.update();   // <-- causes actual reception of data
}
void update_lcd(long val) {  // Runs automatically, only when X-Plane changes the data
  lcd.setCursor(6, 0);
  lcd.print(val);
  lcd.print("  ");
}

Array Access

FlightSimFloat throttle;          // access to X-Plane's throttle

void setup() {
  throttle = XPlaneRef("sim/flightmodel/engine/ENGN_thro[0]");  // [0] is first element in array
  throttle.onChange(viewThrottle);
}

Status: FlightSim.isEnabled() (True / False)

  // the LED shows if X-Plane is running and plugin is enabled
  if (FlightSim.isEnabled()) {
    digitalWrite(LED_BUILTIN, HIGH);
  } else {
    digitalWrite(LED_BUILTIN, LOW);
  }

Timing: FlightSimElapsedFrames (Read or Write)

// variables
FlightSimElapsedFrames frameCount; // increases each simulation frame
elapsedMillis milliSeconds;        // increases 1000 per second

Debugging

TeensyControls Show Communication

Arduino Serial Monitor

Finding X-Plane Data

The DataRefEditor plugin lets you easily view and modify data. You can test your idea or verify the data works as expected before writing code on Teensy.

DataRefEditor Plugin

Some helpful tips from Dozer:

The plugins forum is probably the best place to ask about how particular datarefs/commands work, I think. That, and/or the aircraft and panel development forum. Until you wrote this code for the Teensy, users would only be choosing commands and datarefs when they're designing 2d panels and 3d cockpits or building plugins. The beauty of your Teensy/X-Plane integration is that the Teensy has become functionally very similar to a plugin or a 3D cockpit or a 2D panel in terms of how it interacts with X-Plane.

This is the general hierarchy for choosing what to use:

1. Is there a command which does what you want to do? Then use that.
2. Else, is there a sim/flightmodel2/ or sim/cockpit2/ dataref which produces the right result? Then use that. (If you're not concerned about functionality on older X-Plane versions.)
3. Otherwise, use one of the other datarefs.

For example, one of my most recent plugins simply turns off some of the radios when the aircraft is loaded with the engines off. There's no 'turn off NAV1 radio' command, just a 'toggle NAV1 power switch' command, which isn't suitable by itself - the radio might already be off, so blindly issuing that command might just toggle it on. We could read the sim/cockpit2/radios/actuators/nav1_power dataref and then decide whether to issue the sim/radios/nav1_power_toggle (I'm guessing the name) command but it's much simpler just to blindly write '0' to the dataref.

With my SEP2 autopilot Teensy, which must turn functions both on and off, and which must allow other interfaces to access those functions, I have to compare the function's dataref to the hardware switch position and then issue the 'toggle function' command. But there are many X-Plane functions which don't have commands, and a few which are tricky to access by dataref too - autopilot speed hold mode for example. (For activate that function, I have to read the autopilot_state dataref, bitmask it to remove the other pitch modes, set the appropriate flag, then write the resulting value back to the dataref.)

Large System Guidelines

These design guidelines are recommended:

• Memory: 50 data variables per Teensy, 100 per Teensy++.
• Communication: 20 data changes or 40 commands per simulation frame.
• Interrupt pins: 4 rotary encoder per Teensy, 8 per Teensy++.

Teensy can often work beyond these limits, but for best performance multiple boards should be used to keep each one within these recommended maximums.

USB Hubs & Controllers

USB hubs should be "Multi-TT" (Transaction Translator) types. The Multi-TT design allows many 12 Mbit/sec Teensy boards to share a single 480 Mbit/sec USB port. Single-TT hubs do NOT properly share USB bandwidth!

If more than 60 Teensy boards are connected, or high bandwith USB devices are present (eg, webcams, USB speakers, etc) a USB 3.0 port and hub should be used. USB is limited to 127 devices per controller, but multiple USB controllers can be installed. If you build such an incredible system, please send us a photo!

Additional Information

Special thanks to Dozer, whose email conversation led to the inspiration to develop Teensyduino's flight sim control USB type.