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

In this chapter we'll go over the information needed to retrieve data from Microsoft Flight Simulator 2020 and send it to your controller. The simulator requires us to indicate which data we want to subscribe to. This enables us to only focus on the relevant data without having to filter out unwanted data. It would be a waste of logic having to handle your indicated altitude when you only want to access the latest nav frequency. That is why the first step will be to create a bundle of outputs. //TODO: link to pages i.e. custom events

Bundle creation

A bundle is a group of outputs that tell the connector which data to request from the simulator. To receive data on your controller we first have to create a bundle. It's recommended to create a bundle for each controller that you want to connect. Let's go over the steps required to receive your indicated altitude and the current com frequency 1.

1. Go to the bundle menu (in the top navbar events -> bundle settings)
2. Click the green encircled + button to create your first bundle
3. Give it a descriptive name
4. Your new bundle should now appear in the available bundles
5. Click the pencil on the right side of your new bundle
6. Navigate to the Nav and Coms tab
7. Select com active frequency 1
8. Navigate to the instruments tab
9. Select indicated altitude
10. Hit the save icon next to the title of your bundle

//TODO: Add images

In this example we've created a rather minimalistic set. If your use case requires different events you now know where to look.

Starting the connection

Each controller can subscribe to a single bundle. On the other hand multiple controllers are able to subscribe to the same bundle. But in order for the connector to send the right data to the right controller we have to link them together. This will be done from the home screen. Lets go over the steps required to send your first data.

1. From the home screen select your controller from the com port selector.
2. Select your newly created bundle in the bundle column.
3. Press the green start button

If you've already connected multiple controllers that you'd like to connect you can add a new row by clicking the green add button. Repeat these steps for the amount of controllers required.

//TODO: Add images

Receiving the data

Now we've got everything setup to transmit data we need to setup the receiver. In this example we will connect an I2C LCD screen to our controller in order to display our data.

#include <BitsAndDroidsFlightConnector.h>
#include <LiquidCrystal_I2C.h>

BitsAndDroidsFlightConnector conn = BitsAndDroidsFlightConnector();
LiquidCrystal_I2C lcd(0x27,20,4);

long currentActiveCom = 0;
int currentIndicatedAltitude = 0;

void setup() {
  lcd.init();
  lcd.backlight();
  Serial.begin(115200);
}

void displayCom1(long com){
  lcd.setCursor(0,0);
  lcd.print(com);
}

void displayIndicatedAlt(int alt){
  lcd.setCursor(0,1);
  lcd.print(alt);
}

void loop() {
  //This polls the serial line for incomming messages
  conn.dataHandling();
  long activeCom = conn.getActiveCom1();
  int  indicatedAltitude = conn.getIndicatedAltitude();

  if (activeCom != currentActiveCom){
    currentActiveCom = activeCom;
    displayCom1(activeCom);
  }
  if (currentIndicatedAltitude != indicatedAltitude){
    currentIndicatedAltitude = indicatedAltitude;
    displayIndicatedAlt(indicatedAltitude);
  }
}

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.

Launch when sim starts

This settings will launch the connector when you start Microsoft Flight Simulator 2020. At the moment it just opens the application but doesn't start a connection (this is being worked on). In order to achieve this the connector adds an entry to the exe.xml file used by MFS2020. This file is located 2 levels up from the community folder. The connector uses the community folder path to navigate to this file. If no community folder path has been set the connector will ask for the path.

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.

Library

To make it easier to interface with the connector you're able to utilize the C++ library.

Library generator

You're able to create your own inputs and outputs in the connector. To allow this customization the connector comes with a library generator. The generator will add the outputs you've created to the library. This way the data will be routed to the correct variables in the library.

It's recommended to save the library to your Arduino library folder if using the Arduino IDE

Generated format

The generator will add three components:

• variables
• getters
• switch cases

variables

The added variables are generated in the format output{id} i.e.: int output1000; The type can be altered by changing the output_format in the event editor.

getters

The generator adds get functions to make it easy to retrieve the latest value of the event you defined. This function is designed to retrieve the value in a consistent manner. A getter might look like this: int getOutput1000() { return getOutput1000; }

switch cases

Last but not least the generator adds switch cases. These look like this: case 1000: { output1000 = incommingValue; break; } These cases will route the incoming values to the correct variables.

PLACEHOLDER

Inputs with values

Using SimConnect with Microsoft Flight Simulator 2020 allows sending values directly to the simulator. Some examples would be:

• Set the com frequency to 124.850
• Set the Kohlman altitude indicator to 29.98
• Set the nav frequency to 116.85

The format expected by the simulator might not always be the direct value. For example the Kohlman altitude indicator requires the value to be passed in Millibars multiplied by 16.

Helper functions

The library has helper functions that parse the desired values into the correct format to simplify their use.

connector.sendSetKohlmanAltimeterInHg(float value)

connector.sendSetKohlmanAltimeterMb(float value)

Library Functions

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);
  }
}

Contributing

Events

In this chapter we will go over events and what to keep in mind when contributing events to the connector.

Outputs

Outputs are events that retrieve data from the simulator and get sent to your microcontroller. There are two types of outputs:

1. Simconnect events
2. WASM events

Simconnect events

Simconnect events are provided by Microsoft Flight Simulator. They can be subscribed to, and the simulator will send an update if the value has changed.

  {
    "simvar": "ADF ACTIVE FREQUENCY:1",
    "metric": "Hz",
    "update_every": 0,
    "cb_text": "ADF 1 active",
    "id": 954,
    "output_type": "adf",
    "category": "NAV and COMS"
  },

Simvar

The event itself is declared in the same field. This field dictates which event is subscribed to in the Simconnect SDK. Most events are documented in the Simconnect SDK docs of Microsoft Flight Simulator. In practice, some events aren't appropriately documented. The ingame dev tools can provide more information on the implementation of events.

Metric

The metric value is the value format requested from the simulator. This is usually documented in the Simconnect docs, but it's possible to experiment with different values that aren't documented. For example, events that accept Hz might also accept Khz and Mhz as metric values.

Update rate / Epsilon

The interval at which these events are transmitted can be altered using the epsilon parameter (update_every). The epsilon parameter indicates at which float interval an update has to be sent. For example, when retrieving the height, you can receive an update every 0.00001 feet, 1 foot, or 10 feet. These values can be tweaked to a sensible threshold. Currently, the threshold is set by the connector. At a later point, it will be possible for users of the connector to override these values. Try to set these values at a sensible threshold for most users. For example, most people don't need to receive a heading update every millimeter. Setting the update value to either 0.5 or 1 makes more sense.

Checkbox text

The cb_text field describes the event. This is also the text that will be displayed in the bundle editor. If necessary, this field can be postfixed with a minor description. Try to use descriptors as little as possible. The target is short and to the point.

ID

The ID field is an identifier used to identify events when transmitting them to your controllers. The reserved ID range for Simconnect events is 100-1000.

Output type

Output type dictates the registration and formatting of events. Possible values are:

            "adf" => Ok(OutputType::ADF),
            "boolean" => Ok(OutputType::Boolean),
            "integer" => Ok(OutputType::Integer),
            "float" => Ok(OutputType::Float) // Retrieved as float send as is,
            "float1decplaces" => Ok(OutputType::Float1DecPlaces) // Retrieved as float rounded to 1 dec place,
            "float2decplaces" => Ok(OutputType::Float2DecPlaces) // Retrieved as float rounded to 2 dec places,
            "seconds" => Ok(OutputType::Seconds) // Parsed to time hh:mm:ss,
            "secondsaftermidnight" => Ok(OutputType::Secondsaftermidnight) // Parsed to 15:34:15 (time of day),
            "percentage" => Ok(OutputType::Percentage) // Parsed to 80 for 80%,
            "degrees" => Ok(OutputType::Degrees) // Retrieved as radians parsed to degrees,
            "inhg" => Ok(OutputType::INHG),
            "meterspersecond" => Ok(OutputType::Meterspersecond) // retrieved as mps converted to kmh,
            "meterspersecondtoknots" => Ok(OutputType::MeterspersecondToKnots) // Retrieved as mps converted to knots,
            "string" => Ok(OutputType::String),

The first distinction is whether the output is a string or a number. Both types have separate registration logic in the connector. The second part determined by the output type is the output format. If the value is a number, the output format is determined by the type belonging to the event. In theory, the connector receives all numbers as float values. The parsing logic can be found in the sim_utils/output_converters module.

Category

The bundle edit menu categorizes outputs based on the category provided in the category field. Custom/WASM events get their own separate category. At a later point users will be able to add their own custom categories.

WASM Outputs

Third-party developers might find that the provided Simconnect events only cover some of their needs. They can expose a deeper event layer in a gauge API that the connector hooks into through a WASM module. With Simconnect events, the Simconnect SDK tells us when a new update is available. The WASM logic flow is more complex than Simconnect events. We are in complete control of the entire data flow. We ask for the current value of the event -> store that value -> check if that value is more significant than the indicated threshold/epsilon and send it to the connector. Due to this polling mechanism, there is a slight chance we miss certain intervals of fast-changing values (but the current value will always reflect the latest and up-to-date value).

    {
      "id": 1000,
      "action": "(L:Generic_Master_Caution_Active)",
      "action_text": "Master caution on",
      "action_type": "output",
      "output_format": "time",
      "update_every": 0.0,
      "min": 0.0,
      "max": 100.0,
      "plane_or_category": "generic"
    },

ID ranges

Please note the following text:

Custom WebAssembly (WASM) events can be provided as a base set by the connector or as custom events by users. The base set uses an ID range between 1000 and 7000, while IDs 7000 - 10000 are reserved for custom user events. This differentiation is important to prevent ID conflicts.

Certain default ID ranges have been reserved for event groups of popular aircraft. If you want to contribute to the event list, please open a pull request (PR) to edit the file with a reserved ID block.

• Flybywire: 2000-2500
• PMDG: 3000-3500

If you want to reserve a block, please update this page.

Flight Companion

Drivers

In order to use this device you need to install two pieces of software. Firstly make sure to install the device drivers. This ensures your pc can recognize and communicate with your Flight Companion.

In order to connect your Flight Companion to Microsoft Flight Simulator you need to install the Bits and Droids Flight Connector.

The latest release can be retrieved using the link above. Use the setup.exe to install the connector. Updates are being pushed through the app after installation.

This software interprets the events the controller sends and transmits the game data.

Setup the controller

To make your life easier I've made it really simple to setup your Flight Companion. On the connection page of the connector you're able to load all required settings using the add partner device option. This option can be found in the top navbar, events -> partner devices.

In the window that opens you can add the device using the add to connector button.

First run

We're almost ready to use the Flight Companion. Since you're able to use the Bits and Droids Flight Connector for more devices than your Flight Companion we need to do a minor setup. On the connection page make sure that your device is selected in the left dropdown (it should show up with Silicon Labs CP210x ... in the name). Make sure to select the Flight Companion bundle in the right dropdown.

This ensures the connector knows which data to send to your Flight Companion.

Unlock all features

Microsoft Flight Simulator uses multiple layers of actions. In order to unlock all features we need to install a plugin to utilize features like the pfd controls. This can be done with a single click of a button. From the connection page (the homepage) go to the top navbar -> settings -> install wasm. A popup should appear asking for the location of your community folder.

The default location for this folder is:

Steam

C:\Users\{USERNAME}\AppData\Roaming\Microsoft Flight Simulator\Packages\Community

Microsoft Store

C:\Users\{USERNAME}\AppData\Local\Packages\Microsoft.FlightSimulator_8wekyb3d8bbwe\LocalCache\Packages\Community

MFS 2024

%appdata%\Microsoft Flight Simulator 2024

Click confirm after selecting the community folder.

After this we are able to start our simulator and hit the green start button in the connector.

Automatically start the connector

Having to start the connector everytime you launch Microsoft Flight Simulator can be a hassle. If you want the connector to Automatically launch and start you can enable the auto launch setting. From the connection page (the home page) -> go to the top navbar -> settings -> connection settings. In this window you can enable launch when sim starts.

Controls

There are currently four modes available on your flight companion. The controls change depending on the current active mode. To Change the current mode rotate the lower encoder.

Radio

The radio mode let's you interact with the comms and ATC.

Autopilot

PFD Controls