Introduction

These are the docs for the Flightconnector.

Supported simulators

• Microsoft Flight Simulator 2020
• (will work on compatibility ASAP) Microsoft Flight Simulator 2024

How does the connector work

The connector uses Serial communication to communicate with your peripherals. It listens for data transmitted by your devices (we call them inputs) and at the same time it can send data to your devices (we call these outputs). ID's are used to match inputs and outputs to the correct simulation variables.

Input flow

You'll find a list of all available inputs in the inputs chapter.

Output flow

You'll find a list of all available outputs in the outputs chapter.

Installation

Connector

The connector can be installed using the latest installer. During startup the connector will automatically check for updates on Github. A pop-up will appear if a new version is available.

WASM

The WASM module unlocks more simulation variables with which to interact. The WASM chapter provides a full explanation. You're able to install the module by copying the entire wasm_module into the MFS2020 community package folder.

If you want to ensure the module is properly installed, you're able to follow these steps:

• Start MFS2020
• Open the option menu
• Enable developer mode
• Open the debug menu
• Open the console
• Search for BitsAndDroids

If the search results show messages that the module was initialized, the module will be loaded properly.

Install from the connector

You’re able to install the WASM module using the installer in the connector.

• Click on settings from the menubar
• Select install WASM
• Click on the “select directory” button
• Search for the MFS2020 community folder

• Click “Select folder”
• Click the confirm button

To check if the installation succeeded, you can open the community folder. If the installation succeeded, there should be a folder called BitsAndDroidsModule.

Your first flight with the Connector

Let's setup the connector and take it for a spin. The simplest action to perform is to connect a button to the connector and see if it works. We will use the simulator to see if the button press is registered. So, let's get started.

Make sure you have the connector installed. If not, follow the instructions in the Installation section.

Open the connector and you will see the following screen: //TODO add image

On this screen you're able to start/stop the connector and add/remove devices. For every peripheral you want to connect to the connector, you need to add a device. In this example we will add a single device to the connector.

To keep things simple, we will use a button to connect to the connector. The button will be used to trigger the parking brake in the simulator. The connector will send the signal to the simulator when the button is pressed. For this example we will be using an Arduino Uno but any other microcontroller will work as well. The code for the Arduino Uno can be found here. // THIS ARTICLE IS INCOMPLETE AND WILL BE EXPANDED

Bundles

A bundle is a group of outputs. For example, you can have a bundle for all outputs that are used for a specific controller. This makes it possible to send the correct data to the controller. You can also use these bundles to save multiple presets.

Inputs

Outputs

Presets

Presets are a way to save multiple device configurations for flight simmers that want to match their setup to their needs. This makes it simple to swap your devices when you switch your airliner for a general aviation plane. In short, each preset contains one or multiple bundles (A bundle is a device matched with the outputs it needs to receive) that can be saved as a set.

Your presets can be managed from the home screen. From here, you can create, save, and edit them. Your first preset will be called (what a coincidence) default by default. You’re able to alter this preset to your heart’s desire.

Create a preset

If you want to create a new preset, press the Create new preset button. This prompts you to enter a fitting name. The connector will save the new empty preset to your settings. It will also be selected as the current active preset. To ensure you’re using the correct set, you should see the name of your new set in the dropdown menu. If you hit start for the first time using your new preset, the connector will save the set as the last active preset. If you start the connector, your last preset will be reinstated. The connector defaults to the first available device if the device isn't connected. If this happens, the alternate device won’t be saved to memory unless you manually press the save preset button.

Edit a preset

You can edit your presets by changing the run configuration by adding and removing rows, changing devices, and altering the bundles. Remember to save your changes before changing the preset you’ve equipped.

These changes will automatically be saved when you make changes

Delete a preset

You're able to remove a preset from the manage preset page.

• Click on settings in the main menu
• Navigate to the Manage presets page
• Click on the trashcan to delete the preset

You're not able to delete the default preset

Edit preset name

This is a placeholder. This functionality isn't finished yet.

Settings

In this chapter, we'll go over the connector's available settings. The settings menu can be accessed from the main menu in the settings tab.

Connection settings

These settings affect the way the connector interacts with your devices.

Enable TRS

The terminal-ready signal is a signal that can be sent to your devices when the connector connects to your controller. Specific microcontrollers like the Arduino use this signal to prepare the controller for incoming data. The behavior of this signal depends on the microcontroller manufacturer's implementation. For example, an Arduino Due uses the signal to reset the controller before establishing a serial connection.

If your microcontrollers reset, pay attention to the order of your devices. For example, the Arduino Due has 2 USB ports (programmer and default). When these ports are reset, the order in which the connectors are reset can affect whether the connection is established or dropped. For the Due, it’s recommended that the programming port be placed at the top of the connection rows.

Logs

When tinkering with your projects, seeing what the connector does can provide valuable information.

Log window

You can use the log window to see a live stream of the logs being output. The log window can be accessed from the main menu. It shows the last 1000 log entries. The logs can fill up quite rapidly if you send a lot of data to or from your controller. If you need some breathing room to analyze the logs, you’re able to pause and resume the log stream using the pause button.

Log file

Looking for information about events that happened when the log window was closed? Don’t worry. All logs get saved to an external file as well. This provides a more accessible format to share during a bug report as well. On Windows, you can type %localappdata% in the file explorer address bar to navigate to your appdata/local folder. The log files can be found in the bitsanddroids/logs folder.

WASM

Usually, the connector communicates with MFS2020 using SimConnect. SimConnect is an interface that exposes the simulation data to other software. This interface provides an easy way to start consuming the sim data but has some downsides.

One of these downsides is that third-party developers can’t easily add functionality to this interface when they want to implement new features. The result for you as a user is that some interactions are locked in the simulator.

Luckily, there is an answer to this problem! MFS2020 provides functionality that lets an add-on interact with the in-game data. Even the data that isn’t created by the add-on itself. These add-ons are called WASM (web-assembly) modules. These WASM modules live inside the simulator but can talk to the outside world using SimConnect. There are other ways these modules can communicate to the outside world, but since we’re already utilizing SimConnect, this route will be our pick.

The great benefit of this system is that we can add more functionality to this module when necessary. That way we’re able to interact with new aircraft the moment they’re released.

Custom events

As explained in the previous chapter not all events can be accessed through SimConnect. Using the WASM module we're able to utilize a whole new set of functionalities. You're able to send data to MFS or receive data and send it to your microcontroller. Since there are more third party planes available than my wallet allows me to obtain it's not possible to add events for everyone of them to the connector. By adding custom events you're able to control event the most obscure aircraft. These events are formatted using Reverse Polish Notation. The connector calls these actions custom commands. You're able to see and edit the custom commands from the custom events menu under the events menu.

Events broken down

An event can be broken down in smaller parts.

• ID
• Actions
• Description
• Type
• Category
• Output format
• Update every

ID

The ID is used to identify the event. When the event is defined as an input, you can trigger it by sending the ID to the connector. The connector will then trigger the corresponding action. When the event is defined as an output the connector will prefix the value with the ID. This makes it possible to identify the received value on your controller.

Action

The action is the event that will be triggered if the connector receives the corresponding ID or the data that MFS requests.

HubHop is a website that contains a library of events created by other simmers.

You can add logical/conditional steps into these events to create complex events. An example of a more complex event is: (A:AUTOPILOT ALTITUDE LOCK VAR, feet) - 1000 + (>K:AP_ALT_VAR_SET_ENGLISH) (>H:AP_KNOB_Down) This basically involves taking the current AP alt lock variable and subtracting 1000, assigning this value to the AP alt variable, and animating the button press. A simpler event would be 1 (>H:TRANSPONDER:1, Enum), which sets the transponder state to mode 1.

Description

Actions can become quite complex and challenging to follow. The description provides a readable description of the event. When the event is defined as an output, the description is also used as a label for the checkbox in the bundle editor.

Type

There are two types of events: inputs and outputs. Inputs are events that are triggered by an incoming message from your controller. To trigger these events, you need to send the ID to the connector. Output events define events that the connector continuously requests from the simulator. If the data changes more than the threshold (update every field), the connector sends the value to your controller, which is prefixed by the ID.

Category

You can add a category to organize your events. This will eventually be used to filter the events table (WIP). In the future, you can add more categories.

Output format

If the event is an output, the output format field will appear. This determines in which format the connector needs to return the data. Available types are:

• Float (1.5)
• Integer (1)
• Time (20:10:10)
• Boolean (true/false or 1/0)
• String (still untested)

Update every

Update every is only applicable to outputs. This value dictates at which interval the connector needs to send data. Let’s say you want to receive the altitude of your aircraft. The simulator will send every altitude change even if it's just a few inches/millimeters. In reality, you're probably more interested in the changes per foot. To achieve this, you could set the update for every value to 1.0.

Update default events

The custom event menu has a button that says update default events. This button resets the default events or adds them if they were added to the connector after your install date. To prevent overwriting of your changes, this isn’t done automatically. In the future you’ll be able to pick and choose which events to import/reset.

Resetting the default events only reinstates the original events the connector ships with (or those added later). It won’t affect events you’ve added yourself.

Autpilot button example

The easiest setup to get you started is getting a pushbutton to interact with MFS2020. In this example, we'll explain everything you need to create your first project.

What you’ll need

• A microcontroller (Arduino, ESP, Teensy, etc.).
• A pushbutton.
• 2 Wires (preferably 1 black and 1 colored).
• A breadboard

Other components will work as well so feel free to experiment to your hearts desire

Wiring the components

There are multiple ways to connect the pushbutton to a microcontroller. We’ll teach you the easiest way, which utilizes the microcontroller's built-in pullup resistors.

First place the pushbutton in the middle of the breadboard so it bridges the gap in the middle. Now connect one of the wires to the ground connection on your controller and the other end to the top leg of the button (see the image below). The next step will be to connect the other leg of the button to pin 8 on your controller (you can change the pin as long as you alter the code as well).

Writing the firmware

We need to write a small bit of code to make the controller interact with the button. Remember to make any changes if you’ve decided to connect the button to another pin.

// This is needed when using another IDE than the Arduino IDE
#include <Arduino.h>
#include <BitsAndDroidsFlightConnector.h>
// Connect the button to pin 8
#define APBTNPIN 8

// Create a connector instance
auto connector = BitsAndDroidsFlightConnector();
// To check against if the state changed
int old_btn_state = HIGH;

void setup() {
  // Start serial coms at a rate of 115200 (this can be changed later)
  Serial.begin(115200);
  // Enable the internal pullup resistors
  pinMode(APBTNPIN, INPUT_PULLUP);
}

void loop() {
  const int btn_state = digitalRead(APBTNPIN);
  // To avoid unnescesary triggers
  if (old_btn_state != btn_state){
    if(btn_state == LOW){
      // A  full list of commands can be found in the inputs chapter 
      connector.send(sendApMasterOn);
    }
    old_btn_state = btn_state;
    // Add a delay to debounce noise
    delay(200);
  }
}

Outputs

Outputs are simvars that will be matched to an unique ID. The structure of an output:

#![allow(unused)]
fn main() {
#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct Output {
    pub simvar: String,
    pub metric: String,
    pub update_every: f32,
    pub cb_text: String,
    pub id: u32,
    pub output_type: i8,
    pub category: String,
}
}

Depending on the output_type the simvar is registered as a string or float. The metric determines the return value returned from the game. These can sometimes be altered from the official simconnect docs.