In the original A Simple Keypad post, we wrote some code to send keyboard events using the Teensy's built in Keyboard emulator libraries. While this works, the code as written pretty much acts as a momentary button works, by checking for a key press in the loop() function and send a key press event, wait a bit, and send a key release event. But what if we want to use the keypad as an actual keyboard, where you can press and hold a key and it will initially type it once, and while hold it down, it will repeatedly keep sending the same key until you release it. Luckily, the Keypad.h library provides a mechanism for that via an event listener.

Here are the code changes:

#include <Keypad.h>

const byte ROWS = 4;
const byte COLS = 4;

char keys[ROWS][COLS] = {
  { '1', '2', '3', 'A' },
  { '4', '5', '6', 'B' },
  { '7', '8', '9', 'C' },
  { '*', '0', '#', 'D' }
};

// pads keypad
// byte rowPins[ROWS] = { 12, 11, 10, 9 };  //connect to the row pinouts of the keypad
// byte colPins[COLS] = { 8, 7, 6, 5 };     //connect to the column pinouts of the keypad
// mechanical keypads
byte rowPins[ROWS] = { 8, 7, 6, 5 };     //connect to the row pinouts of the keypad
byte colPins[COLS] = { 12, 11, 10, 9 };  //connect to the column pinouts of the keypad

//Create an object of keypad
Keypad keypad = Keypad(makeKeymap(keys), rowPins, colPins, ROWS, COLS);

void setup() {
  keypad.addEventListener(keypadEvent);
}


void loop() {
  keypad.getKey();
}

void keypadEvent(KeypadEvent key) {
  switch (keypad.getState()) {
    case PRESSED:
    case HOLD:
      Keyboard.press(key);
      break;
    case RELEASED:
      Keyboard.release(key);
      break;
    case IDLE:
      break;
  }
}

Breakdown

The first noticeable change is that during the setup() function, we are adding an event listener called keypadEvent, which we later define in the code. Next, our loop() function now just calls getKey() but doesn't do anything with it. This allows the library to scan for key presses.

If we take a look at the void keypadEvent(KeypadEvent key) function, we see that now we can get the state of the keypad using the keypad.getState(). There are 4 predefined states, IDLE, PRESSED, HOLD and RELEASED. With these now we can send the corresponding keyboard events using the built-in Keyboard object, which contains a press(key) and release(key) functions that we can use.

Sending Multiple Keys

So now that we have this basic functionality in place, we can make some more fun stuff. Lets map the * and # keys to be CTRL+C and CTRL+V to do something different. We can change the event listener function to do something like this instead:

void keypadEvent(KeypadEvent key) {
  switch (keypad.getState()) {
    case PRESSED:
    case HOLD:
      pressKey(key);
      break;
    case RELEASED:
      releaseKey(key);
      break;
    case IDLE:
      break;
  }
}

void pressKey(KeypadEvent key) {
  switch (key) {
    case '*':
      Keyboard.press(KEY_LEFT_CTRL);
      delay(25);
      Keyboard.press(KEY_C);
      delay(25);
      break;
    case '#':
      Keyboard.press(KEY_LEFT_CTRL);
      delay(25);
      Keyboard.press(KEY_V);
      delay(25);
      break;
    default:
      Keyboard.press(key);
      break;
  }
}

void releaseKey(KeypadEvent key) {
  switch (key) {
    case '*':
      Keyboard.release(KEY_LEFT_CTRL);
      delay(25);
      Keyboard.release(KEY_C);
      delay(25);
      break;
    case '#':
      Keyboard.release(KEY_LEFT_CTRL);
      delay(25);
      Keyboard.release(KEY_V);
      delay(25);
      break;
    default:
      Keyboard.release(key);
      break;
  }
}

Now depending on what key was pressed, we can either send the default Keyboard press and release events, or send a combination of them. And you are not just limited to send Keyboard events. The Teensy's also have built-in Mouse and Joystick emulation so you can technically send Mouse clicks, drags, etc. the same way you send the Keyboard events.

Here is an example on how I bound the # key to click on the screen, press the right ALT key down and send a mouse click. If you play Microsoft Flight Simulator you know this is what you need to click to pop-out the digital panels, and then use the keypad's D to maximize it.

 case '#':
      Mouse.click();
      delay(25);
      Keyboard.press(KEY_RIGHT_ALT);
      delay(25);
      Mouse.set_buttons(1, 0, 0);
      break;

case 'D':
      Mouse.click();
      delay(25);
      Keyboard.press(KEY_RIGHT_ALT);
      delay(25);
      Keyboard.press(KEY_ENTER);
      break;

Conclusion

While the initial way of sending keyboard events discussed earlier works, it's limited if you for example wanted to do key combinations. I ended up changing my code to this way because I wanted to bind a key to ALT and hold it down while I clicked on my mouse, but eventually figured out that I could just bind a key and send all those events and don't need to even use my keyboard or mouse to do so.

Hope you found this updated code useful and see you on the next one!

This is a quick tutorial on how to debug UDP broadcast traffic sent from our code to ForeFlight. This method applies for any type of UDP traffic you want to monitor, but the fact that it is sent in plain text makes it even easier.

Linux

If you happen to have a Linux box connected to the same network, you can use the built-in nc command to listen to a specific TCP or UDP port. For our ForeFlight data, we would do something like this:

nc -u -l 49002 -k

Where -u is for specifying UDP, -l to specify the port and the -k is to keep monitoring indefinitely (the default behavior stops printing the data after a few bytes are received).

You'll see all the traffic coming through like this:

XGPSHelloForeFlight,-69.4282,44.3234,3657.42,45.00,56.59
XGPSHelloForeFlight,-69.4232,44.3284,3657.42,45.00,56.59
XGPSHelloForeFlight,-69.4182,44.3334,3657.42,45.00,56.59
XGPSHelloForeFlight,-69.4132,44.3384,3657.42,45.00,56.59
XGPSHelloForeFlight,-69.4082,44.3434,3657.42,45.00,56.59
XGPSHelloForeFlight,-69.4032,44.3484,3657.42,45.00,56.59
XGPSHelloForeFlight,-69.3982,44.3534,3657.42,45.00,56.59
XGPSHelloForeFlight,-69.3932,44.3584,3657.42,45.00,56.59

Microsoft Windows

For Windows, you can use a tool called Wireshark and create a udp filter. Note that you might need to install the WinPcap if you don't already have it installed. The filter should look like this:

udp.port == 49002

You'll see output like this, which you can right click on any packet and click on Follow->UDP Stream to see it in a nicer way:

Mobile

There are many apps that can do something similar, both on iOS and Android, both free and paid so try out a few to see which one you like 😄

So let's do something different today. Now that we know how to read data from the sim and send it to our Arduino devices, let's use that same idea to send data to Electronic Flight Bags (EFB) apps like ForeFlight, Garmin Pilot and Avare.

But what is an EFB and what can I we use it for? An EFB is a digital device or mobile device application that pilots use to manage flight information, replacing the need of paper based materials they usually carry in their flight bags, like VFR Sectional and IFR charts, with the addition that they can be connected to the aircraft's GPS to read navigation and positional data and display it on the screen for flight planning and tracking in real time, with the additional benefit that you can record your flights and play them back later.

We want to be able to use an EFB together with our simulator the same way you would use it while flying on a real aircraft and connecting it to the aircraft's GPS, via Wi-Fi or Bluetooth, depending on the equipment your aircraft has. Although there are already a few Windows apps that do this, let's look at how it's done so you can add it to the app we built earlier since we already have some of the data we need and we can figure out the rest.

I will show an example code for sending the data to ForeFlight, since it's pretty straight forward. The code for supporting Avare (on Android) is similar, with the difference that it uses NMEA sentences instead of ForeFlight's proprietary ones. I haven't looked into how this would be implemented for other EFB's like Garmin Pilot, but I'm guessing it might be a similar idea.

ForeFlight's Protocol

We will be using the UDP protocol to send data to devices running ForeFlight that are connected to the same network our PC. Unlike TCP, UDP is connectionless so the packets are just broadcasted over the network so any device on the network can receive the traffic. We can have multiple devices connected on the network and as long as they are listening to the same port, all of them will be able to read it.

If we look at the ForeFlight GPS Integration documentation, it listens on UDP port 49002 and supports 3 types of sentences, two for your own aircraft's information and the other for other traffic. They are all text based and the fields are comma separated.

XGPS

This is used for your own aircraft's position, altitude, track and ground speed. It expects one sentence per second. The format is:

XGPSname,longitude,latitude,altitude,track,groundspeed

XATT

This is used by ForeFlight's built-in Attitude Indicator. The sentences need to be sent between 4 to 10 times per second. The format is:

XATTname,heading,pitch,roll

XTRAFFIC

This is used for traffic aircraft's properties surrounding your own aircraft. It expects one sentence per second. The format is:

XTRAFFICname,id,lat,long,alt,vspeed,airborne,heading,speed,callsign

Note: The id will be given to us in the OnRecvSimobjectDataBytype(SimConnect sender, SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE data) as data.dwObjectId. Normally your own aircraft's ID = 1, and the rest start around 300.

The Coding Part

Let's write a simple Console Application to explain some concepts:

using System.Net;
using System.Net.Sockets;
using System.Text;

namespace HelloForeFlight
{
    internal class Program
    {
        private const string APP_NAME = "HelloForeFlight";

        private const float FEET_TO_METERS = 3.281f;
        private const float KNOTS_TO_METERS_PER_SECOND = 0.51444f;

        private const string BROADCAST_ADDRESS = "255.255.255.255";
        private const int BROADCAST_PORT = 49002;

        private static void Main(string[] args)
        {
            float altitude = 12000;         // in feet
            float groundspeed = 110;        // in knots
            float groundtrack = 45;
            float latitude = 42.4630f;
            float longitude = -71.2872f;

            // Define the broadcast endpoint (IP address and port)
            var endPoint = new IPEndPoint(IPAddress.Parse(BROADCAST_ADDRESS), BROADCAST_PORT);

            using (UdpClient udpClient = new UdpClient() { EnableBroadcast = true })
            {
                while (true)
                {
                    try
                    {
                        // Write the XGPS sentence.
                        // Since we are using altitude in feet and ground speed in knots, we need to convert them to meters and to meters per second respectively.
                        // If you pull them from the Sim as Meters or Meters per second (check MSFS SDK documentation), you don't have to convert them
                        var xgps = $"XGPS{APP_NAME},{longitude:F4},{latitude:F4},{altitude / FEET_TO_METERS:F2},{groundtrack:F2},{groundspeed * KNOTS_TO_METERS_PER_SECOND:F2}\n";

                        // Convert the message to bytes
                        byte[] data = Encoding.UTF8.GetBytes(xgps);

                        // Send the UDP message to the broadcast address
                        udpClient.Send(data, data.Length, endPoint);
                        Console.WriteLine($"Sent: {xgps}");

                        // Finally, let's modify the latitude and longited a little to see the plane move in ForeFlight
                        longitude += 0.005f;
                        latitude += 0.005f;
                    }
                    catch (Exception ex)
                    {
                        Console.WriteLine($"Error: {ex.Message}");
                    }

                    Thread.Sleep(1000);
                }
            }
        }
    }
}

Code Breakdown

First, we'll create an IPEndpoint to specify the target broadcast address and port, and an UdpClient to send the data over UDP. Make sure you set EnableBroadcast to true after you create the client. We'll be using 255.255.255.255 as the broadcast address for simplicity.

var endPoint = new IPEndPoint(IPAddress.Parse(BROADCAST_ADDRESS), BROADCAST_PORT);

using (UdpClient udpClient = new UdpClient() { EnableBroadcast = true })

If you want to only broadcast to a specific network, you could do so by either specifying the broadcast IP address of the that network, i.e. 192.168.0.255, and provide some sort of mechanism like a config file, a text box, etc. to specify, or even programmatically query the network devices on your PC and let the user select. A query could look something like this, which is what I use in my plugin:

var nics = NetworkInterface.GetAllNetworkInterfaces().Where(n => n.NetworkInterfaceType == NetworkInterfaceType.Ethernet && n.OperationalStatus == OperationalStatus.Up).ToList();
var addrinfos = nics.SelectMany(x => x.GetIPProperties().UnicastAddresses.Where(y => y.Address.AddressFamily == AddressFamily.InterNetwork)).ToList();

Then, we will loop once per second and build our XGPS sentence based on the data we get from the Sim (or some hardcoded values for demo purposes). We have to remember that ForeFlight expects the altitude in meters and the ground speed in meters per second, so if you subscribed to receive the SimVar in feet as we did in previous posts, you'll have to convert the value to meters or subscribe to it in meters, but convert it to feet when we send it to the Arduino.

 simconnect.AddToDataDefinition(RequestType.PerFrameData, "INDICATED ALTITUDE", "feet", SIMCONNECT_DATATYPE.FLOAT32, 0, SimConnect.SIMCONNECT_UNUSED);

We set the precision based on ForeFlight's documentation. I chose 4 decimals for latitude/longitude and 2 for the rest.

var xgps = $"XGPS{APP_NAME},{longitude:F4},{latitude:F4},{altitude / FEET_TO_METERS:F2},{groundtrack:F2},{groundspeed * KNOTS_TO_METERS_PER_SECOND:F2}\n";

We then convert our sentence to a byte array and send it using the UdpClient and IPEndpoint we previously created.

byte[] data = Encoding.UTF8.GetBytes(xgps);

udpClient.Send(data, data.Length, endPoint);

And finally just to see some stuff happen in ForeFlight, we increase the latitude and longitude to see the plane moving in the northeast direction.

The XATT sentence is pretty much built the same as the XGPS one is, so not going to cover it here.

Traffic

Traffic is a bit different. You have to register an additional SimObject event handler and request traffic in a different way.

First, you want to create a struct for the Traffic data and an enum to register it:

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi, Pack = 1)]
public struct TrafficSimVarData
{
    public bool IsGrounded;                         // SIM ON GROUND (bool)

    [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
    public string CallSign;                         // ATC ID (string)

    public float AirSpeed;                          // AIRSPEED TRUE (knots)
    public float Altitude;                          // PLANE ALTITUDE (feet)
    public float Heading;                           // PLANE HEADING DEGREES TRUE (degrees)
    public float Latitude;                          // PLANE LATITUDE (degree)
    public float Longitude;                         // PLANE LONGITUDE (degree)
    public float VerticalSpeed;                     // VERTICAL SPEED (feet/minute)
}

internal enum RequestType
{
    PerFrameData,
    TrafficData,
}

Then, you want to register a new event handler by type:

  // add this below where you registered your other handlers
  simConnect.OnRecvSimobjectDataBytype += new SimConnect.RecvSimobjectDataBytypeEventHandler(SimConnect_OnRecvSimobjectDataBytype);

...

// define your handler
public void RecvSimobjectDataBytypeEventHandler(SimConnect sender, SIMCONNECT_RECV_SIMOBJECT_DATA_BYTYPE data)
{
    try
    {
        var objectId = data.dwObjectID;
        var requestType = (RequestType)data.dwRequestID;
        // your aircraft's objectId is 1, and it seems that the rest start above 300 
        if (requestType == RequestType.TrafficData && objectId > 300)
        {
            var traffic = (TrafficSimVarData)data.dwData[0];
            // call your method to build and send the XTRAFFIC package here
            // SendTraffic(objectId, traffic);
        }
    }
}

Last but not least, you might want to have a background worker thread to run once per second, to request the traffic data from the sim and sent it to ForeFlight like the documentation suggests.

simConnect?.RequestDataOnSimObjectType(RequestType.TrafficData, RequestType.TrafficData, radius, SIMCONNECT_SIMOBJECT_TYPE.AIRCRAFT);

Note that when you register this, you'll specify the radius in meters around your aircraft and the RecvSimobjectDataBytypeEventHandler() method will be called once for any object within that radius, and it's unique object Id will be included in the response data as data.dwObjectId, which you will send as the id in the XTRAFFIC sentence that ForeFlight uses to keep track of each unique traffic aircraft.

Running and testing

That's it, build and run the Console Application and open ForeFlight. First thing you want to verify is that ForeFlight is receiving data from your "plugin". In ForeFlight, go to Devices and you should see your "HelloForeFlight" app connected. Now open the Maps tab and watch your plane move around.

Wrapping up

That's it. With everything here you should be able to add register some new SimVars on your C# app and add the UdpClient broadcast logic along the other minor modifications to request traffic data and implement the other two sentences.

If you are on Android and cannot use ForeFlight, the code is very similar for Avare and the only difference is the sentences used are NMEA ones. Since Avare is open source, you can find the sentences they expect in their github repo here: https://github.com/apps4av/avare/tree/master/app/src/main/java/com/ds/avare/nmea

One thing I discovered is that you can actually send the sentences to ForeFlight faster than one per second, but be aware that if you broadcast too often, you can literally kill your network with all the traffic being generated... speaking from experience 😅

In the next post I'll show you how to use 3rd party tools for Windows, and Linux so you can see the broadcast traffic live in case you need to do some debugging, or even connect your mobile device to the aircraft's device and see the actual traffic being sent. See you on the next one!

In this final part of this Sending Events series, we'll put everything we learned so we can now send events from the device to the C# app, and then to Microsoft Flight Simulator.

Arduino Sketch Changes

Lets insert the rotary encoder code from part 2 with a small modification so we can send a more specific string when the state changes:

#include "SPI.h"
#include "ILI9341_t3.h"

#define TFT_DC 9
#define TFT_CS 10
#define CHAR_WIDTH 6

#define CLK_PIN 14
#define DATA_PIN 15
#define BUTTON_PIN 16

ILI9341_t3 tft = ILI9341_t3(TFT_CS, TFT_DC);

float currentAltitude = 0;
float previousAltitude = -1;

float currentBarometer = 0;
float previousBarometer = -1;

int lastEncoderState;
int lastEncoderButtonState;

void setup() {
    pinMode(CLK_PIN, INPUT_PULLUP);
    pinMode(DATA_PIN, INPUT_PULLUP);
    pinMode(BUTTON_PIN, INPUT_PULLUP);

    lastEncoderState = digitalRead(CLK_PIN);

    // initialize the port and set the baud rate to 115200, change to 9600 if you are having communication issues, but make sure it's the same rate as in the C# code
    Serial.begin(115200);

    tft.begin();
    tft.setRotation(1);
    tft.fillScreen(ILI9341_BLACK);

    // labels
    drawTextCentered("Altitude (feet)", 0, 2, ILI9341_WHITE);
    drawTextCentered("Barometer (inHg)", 120, 2, ILI9341_WHITE);

    // refresh values
    update();

    // wait for a serial connection before beginning
    while (!Serial) {}
}

void loop() {
    // check if we have at least 8 bytes. our full message should be 9 bytes,
    if (Serial.available() > 8) {
        currentAltitude = readFloat();
        currentBarometer = readFloat();

        Serial.readStringUntil('\n');

        update();
    }

    // process encoder
    switch (readEncoder(CLK_PIN, DATA_PIN, lastEncoderState)) {
    case -1:
        Serial.println("ENCODER_DECREASED");
        break;
    case 1:
        Serial.println("ENCODER_INCREASED");
        break;
    }

    // check if the button was pressed
    if (readButton(BUTTON_PIN, lastEncoderButtonState)) {
        Serial.println("ENCODER_BUTTON_PRESSED");
    }

    // small delay to give it time for debouncing
    delay(1);
}

// util method to read 4 bytes from the serial port and return them as a float
float readFloat() {
    char buffer[4];
    Serial.readBytes(buffer, 4);

    float value;
    memcpy(&value, buffer, sizeof(float));

    return value;
}

// util method to redraw the values
void update() {
    if (previousAltitude != currentAltitude) {
        tft.fillRoundRect(30, 40, 260, 50, 10, ILI9341_GREEN);
        tft.drawRoundRect(30, 40, 260, 50, 10, ILI9341_WHITE);
        drawTextCentered(String(currentAltitude), 50, 4, ILI9341_BLACK);

        previousAltitude = currentAltitude;
    }

    if (previousBarometer != currentBarometer) {
        tft.fillRoundRect(30, 160, 260, 50, 10, ILI9341_GREEN);
        tft.drawRoundRect(30, 160, 260, 50, 10, ILI9341_WHITE);
        drawTextCentered(String(currentBarometer), 170, 4, ILI9341_BLACK);

        previousBarometer = currentBarometer;
    }
}

// util method to draw centered
void drawTextCentered(String text, int y, int size, uint16_t color) {
    int offset = 160 - (text.length() * CHAR_WIDTH * size / 2);

    tft.setTextSize(size);
    tft.setCursor(offset, y);
    tft.setTextColor(color);
    tft.print(text);
}

// simple funciton that reads the state of a button connected to 'pin', with current and last states for determining if the button is being pressed or not.
bool readButton(uint8_t pin, int& lastState) {
    int state = !digitalRead(pin);

    if (state != lastState) {
        lastState = state;
        if (state == 0) {
            return true;
        }
    }

    return false;
}

// In my encoder, and depends on how you wired it, this is the sequence.
// If yours is inverted, you can invert the CLK and DATA connections
// cw   00,01,11,10,00
// ccw  00,10,11,01,00
int readEncoder(int clkPin, int dataPin, int& lastState) {
    int state = digitalRead(clkPin);

    if (state != lastState) {
        lastState = state;

        int dataState = digitalRead(dataPin);
        if (dataState != state) {
            return -1;
        }
        else {
            return 1;
        }
    }

    return 0;
}

Notice that we are now sending ENCODER_DECREASED, ENCODER_INCREASED and ENCODER_BUTTON_PRESSED, but we really can send anything we like, 0,1,2, 'D','I','P', or even the original string messages as long as our C# code matches with what we sent. I opted for these human readable strings for demo and debugging purposes.

WPF Application Changes

Now let's look at the SerialPort_DataReceived(...) method, which it's really the only thing we have to modify:

private void SerialPort_DataReceived(object sender, SerialDataReceivedEventArgs e)
{
    try
    {
        // Read data from the serial port until NewLine is found and trim the newline character(s)
        var dataReceived = serialPort.ReadLine().Trim();

        switch (dataReceived)
        {
            case "ENCODER_DECREASED":
                simconnect.TransmitClientEvent(
                    SimConnect.SIMCONNECT_OBJECT_ID_USER,
                    SimEventType.KOHLSMAN_DEC,
                    0,
                    GroupId.FLAG,
                    SIMCONNECT_EVENT_FLAG.GROUPID_IS_PRIORITY
                );
                break;

            case "ENCODER_INCREASED":
                simconnect.TransmitClientEvent(
                    SimConnect.SIMCONNECT_OBJECT_ID_USER,
                    SimEventType.KOHLSMAN_INC,
                    0,
                    GroupId.FLAG,
                    SIMCONNECT_EVENT_FLAG.GROUPID_IS_PRIORITY
                );
                break;

            case "ENCODER_BUTTON_PRESSED":
                simconnect.TransmitClientEvent_EX1(
                    SimConnect.SIMCONNECT_OBJECT_ID_USER,
                    SimEventType.KOHLSMAN_SET,
                    GroupId.FLAG,
                    SIMCONNECT_EVENT_FLAG.GROUPID_IS_PRIORITY,
                    (uint)(STANDARD_PRESSURE * INHG_TO_MILLIBAR * 16), 0, 0, 0, 0
                );
                break;

            default:
                Debug.WriteLine($"Unsupported message received: {dataReceived}");
                break;
        }
    }
    catch (Exception ex)
    {
        Debug.WriteLine("Error while receiving data: " + ex.Message);
    }
}

Since we are sending a string, we can still use serialPort.ReadLine() to read a string from the port and put that in a switch statement for each one of the 3 message types that we are sending. We moved the code from the event handlers into each one of the corresponding case blocks and added a default for debugging purposes.

At this point you can remove the additional 3 buttons we added in Part 1 for sending the events and remove the handlers, but that's optional. They both should still work independently.

Build and upload the Sketch, build and run the WPF app and launch the Sim and click on connect. Rotate the encoder clockwise and counterclockwise and you'll see the barometer setting increasing and decreasing, in addition to the altimeter getting updated because of the barometer setting change.

Demo

Here is a short video with a demo on how it should work. I'm using a dual rotary encoder hence the extra wires, but like I mentioned in the previous post, it works the same. And once again, ignore the red lines, it's my broken screen that I use for development purposes 😅

Wrapping up

In this 3 Part series about Sending Events, we learned how to use SimConnect SDK to send events to Microsoft Flight Simulator. We learned about the two methods available TransmitClientEvent() and TransmitClientEvent_EX1() and their differences. We learned about electromechanical rotational input devices like potentiometers and rotary encoders and we looked into rotary encoders deeper. Finally we combined the code we wrote in part 1 with what we learned about rotary encoders in part 2 so we could convert an action performed on a rotary encoder into an event in the sim.

If you want to have a look at the instruments I've designed drawn in the same way explained in this series, have a look at My Flight Instruments where I put screenshots and a description of each one of the ones I've designed.

Hope you found this series useful, and see you on the next one!

In Part 1, we learned how to send events from C# to Microsoft Flight Simulator using the SimConnect SDK's EventIds. We added two buttons in our WPF app to increase and decrease the barometer setting and resetting it to standard 29.92 with the press of another button. Now let's achieve the same but with a knob connected to the Teensy.

Types of Knobs

In electronics, two of the most common types of electromechanical rotational input devices are Potentiometers and Rotary Encoders. To the naked eye, they both kinda look the same, but there is a big difference in terms of how they internally work and how to use them. In addition, both them come with an integrated push button which have two additional pins, signal and ground, to determine if the button is open or closed.

Potentiometers

Potentiometers are a three-terminal resistor, that forms as an adjustable voltage divider. You can turn it clockwise and counterclockwise, and they have a minimum and a maximum limit of movement. Two of the pins are connected to ground and a voltage signal, and the 3rd pin is used for the output signal which is proportional to the potentiometer position. Since they have limits, they are typically used for things like volume control, brightness, etc. anything that has a predefined minimum and maximum.

Rotary Encoders

Rotary Encoders are electromechanical devices that convert the angular position or motion of a shaft into digital or analog signals. They don't have a minimum or maximum limit so you can rotate them on either direction infinitely. They also have three pins, one is used for your reference signal (ground or VCC), and the other two are for CLK and DATA signals. These two signals are phased, so depending on the rotation direction, you can determine if its rotating clockwise or counterclockwise based on the values of these two signals combined. That means, the output pattern could look something like (0,0) -> (0,1) -> (1,1) -> (1,0) -> (0,0) when rotating clockwise, and (0,0) -> (1,0) -> (1,1) -> (0,1) -> (0,0) when rotation counterclockwise. They are typically used for adjusting parameters that you just need to infinitely increase and decrease without a limit.

There are even dual rotary encoder versions that have 3 extra pins for an outer ring encoder besides the shaft encoder, which packs much more functionality into a single device, and pretty much acts as if you are working with two independent rotary encoders.

Wiring

Wiring a rotary encoder can vary depending on what you got. Some come in little development boards with pins that come out so you can connect them on a breadboard, but those boards wire them to Vcc and the logic is inverted. I will be using a standalone encoder like the one in the picture above.

The signal pins are arbitrary, so use the ones that are convenient to you.

Implementation

For my instruments, I decided to go with a Rotary Encoder so I can use it to adjust different parameters depending on what instrument I'm building, and if I require min/max limits, it is something I can handle in code. I'm actually using a Dual Rotary Encoder, but the principle is the same.

Let's look at some code:

// set this to the pins you are using on your device. if you notice that the increase/decrease is inverted, swap the CLOCK/DATA PINs
#define CLK_PIN 14
#define DATA_PIN 15
#define BUTTON_PIN 16

int lastEncoderState;

int lastEncoderButtonState;

void setup() {
  // I'm wiring my encoder and buttons to ground, so my signals need to be pullup to use the internal resistance. If you were to wire to Vcc, you probably want to use INPUT instead.
  // this is also a good practice to have your circuit being HIGH at start so you know if you supply enough power to it, vs being low and then doing something that will drain more power than provided.
  pinMode(CLK_PIN, INPUT_PULLUP);
  pinMode(DATA_PIN, INPUT_PULLUP);
  pinMode(BUTTON_PIN, INPUT_PULLUP);

  // store the current state the encoder is when we turn on the arduino
  lastEncoderState = digitalRead(CLK_PIN);

  // open serial connection and wait
  Serial.begin(115200);
  while (!Serial) {}
}

void loop() {
  // read the encoder connected to CLK_PIN, DATA_PIN with last state, and depending on the return value, we determine if we moved clockwise or counterclockwise
  switch (readEncoder(CLK_PIN, DATA_PIN, lastEncoderState)) {
    case -1:
      Serial.println("Encoder Decreased");
      break;
    case 1:
      Serial.println("Encoder Increased");
      break;
  }

  // check if the button was pressed
  if (readButton(BUTTON_PIN, lastEncoderButtonState)) {
    Serial.println("Button Pressed");
  }

  // small delay to give it time for debouncing
  delay(1);
}

// simple funciton that reads the state of a button connected to 'pin', with current and last states for determining if the button is being pressed or not.
bool readButton(uint8_t pin, int& lastState) {
  int state = !digitalRead(pin);

  if (state != lastState) {
    lastState = state;
    if (state == 0) {
      return true;
    }
  }

  return false;
}

// In my encoder, and depends on how you wired it, this is the sequence.
// If yours is inverted, you can invert the CLK and DATA connections
// cw   00,01,11,10,00
// ccw  00,10,11,01,00
int readEncoder(int clkPin, int dataPin, int& lastState) {
  int state = digitalRead(clkPin);

  if (state != lastState) {
    lastState = state;

    int dataState = digitalRead(dataPin);
    if (dataState != state) {
      return -1;
    } else {
      return 1;
    }
  }

  return 0;
}

If we build and run the sketch and open the Serial Monitor window, we can rotate the encoder clockwise, counterclockwise and press the button and see a similar output:

Breakdown

First, we define our pins for CLK/DATA and BUTTON signals. Then we create some variables to store the current and previous states for the encoder and button.

In the setup() function, we set the 3 pins as INPUT_PULLUP since we are connecting the signal to ground. Then we store the last button state so we don't get a false button pressed message.

In our loop() function, we first call readEncoder() to check the state of the encoder. This function returns -1,1 for when the encoder is being decreased or increased, and 0 when it's static. The logic in this function is a bit tricky, but it is based on how our sequence works. Remember that the two signals are out of phase, that means for example, that when CLK is 0, DATA can be 0 or 1 before CLK can change to 1 and so on. This is true only if your reading speed is fast enough, because if you are turning the encoder way too fast, it can jump into the wrong state and you would 'read' movement in the opposite direction, which is something I've even seen on equipment out there... no, I'm not talking about my flight school's $100k RedBird FAA certified simulator that has this issue... nope 🙃

Similar, we call the readButton() function to determine if the button was pressed or released depending on the previous state we stored in lastState.

Note that I made these two functions generic enough so they can be used to verify multiple encoders and buttons, hence I'm passing the lastState argument by reference.

Conclusion

That wraps up Part 2 of this series. Now that we know how to use a Rotary Encoder with some pretty straight forward code, in Part 3 we'll apply these changes to the HelloMSFS.ino sketch from Part 1 to send an increase, decrease, and button events to the C# app, so we can then call corresponding SimConnect SDK methods to send that event to the sim.

So up to this point we were only pulling data from Microsoft Flight Simulator 2020 and sending it down to the devices. But what about interacting back with the sim? There are two things that you can do with the SimConnect SDK: setting some SimVars, and sending EventIds. I clarify that we can only set someSimVars since a lot of them are read only, but you can check the Simulation Variables section in the SDK's documentation to see which ones are read/write. Here's an example:

We'll skip setting SimVars for now. Right now we just want to focus on sending EventIds.

The SimConnect SDK offers a way of communicating back with the sim via EventIds. A list of all the existing ones and their documentation can be found here: https://docs.flightsimulator.com/html/Programming_Tools/Event_IDs/Event_IDs.htm

Continuing to build our Altimeter instrument, let's create some events to change the barometer setting, the same way we would by turning a knob in an airplane's Altimeter. If we look at the documentation, we can see there are 3 events that we can use to increase, decrease and reset the barometer setting:

Note: we really only need the INC and DEC to mimic the behavior of the Altimeter's knob in an airplane, but I'll use SET to reset to standard barometric pressure of 29.92 to explain the two different ways of sending the events based on the EventId properties.

Code Changes

Setting the events is very similar to how we setup the Simvars. We first need to create an enum with our events:

public enum SimEventType
{
  KOHLSMAN_INC,   // increments the altimeter setting
  KOHLSMAN_DEC,   // decrements the altimeter setting
  KOHLSMAN_SET,   // sets the altimeter setting to a specified value
}

Next, we need to register our EventIds in a similar way to when we registered our SimVars. Let's do this in the same Simconnect_OnRecvOpen() method we used before:

private void Simconnect_OnRecvOpen(SimConnect sender, SIMCONNECT_RECV_OPEN data)
{
  // original simconnect.AddToDataDefinition(...)'s here
  ...
  // register events
  simconnect.MapClientEventToSimEvent(SimEventType.KOHLSMAN_SET, "KOHLSMAN_SET");
  simconnect.MapClientEventToSimEvent(SimEventType.KOHLSMAN_INC, "KOHLSMAN_INC");
  simconnect.MapClientEventToSimEvent(SimEventType.KOHLSMAN_DEC, "KOHLSMAN_DEC");
}

Next let's modify the XAML UI a bit so we can add some buttons to send the events. Also, I added a text field for specifying the COM port so I can test with different devices without having to rebuild the code.

<Window x:Class="HelloMSFS.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:HelloMSFS"
        mc:Ignorable="d"
        Title="Hello MSFS" SizeToContent="WidthAndHeight" Topmost="True">
    <Grid Margin="20">
        <Grid.ColumnDefinitions>
            <ColumnDefinition MinWidth="100"/>
            <ColumnDefinition MinWidth="100"/>
        </Grid.ColumnDefinitions>

        <Grid.RowDefinitions>
            <RowDefinition MinHeight="25"/>
            <RowDefinition MinHeight="25"/>
            <RowDefinition MinHeight="25"/>
            <RowDefinition MinHeight="25"/>
            <RowDefinition MinHeight="25"/>
            <RowDefinition MinHeight="25"/>
        </Grid.RowDefinitions>

        <Label x:Name="label0" Content="Serial Port:" Grid.Row="0" VerticalContentAlignment="Center" Margin="5"/>
        <Label x:Name="label1" Content="Altimeter:" Grid.Row="1" VerticalContentAlignment="Center" Margin="5" />
        <Label x:Name="label2" Content="Barometer:" Grid.Row="2" VerticalContentAlignment="Center" Margin="5"/>

        <TextBox x:Name="serialPortTextBox" TextWrapping="Wrap" Text="COM5" Grid.Row="0" Grid.Column="1" VerticalContentAlignment="Center" Margin="5" IsReadOnly="True"/>
        <TextBox x:Name="altimeterTextBox" TextWrapping="Wrap" Text="1000" Grid.Row="1" Grid.Column="1" VerticalContentAlignment="Center" Margin="5" IsReadOnly="True"/>
        <TextBox x:Name="barometerTextBox" TextWrapping="Wrap" Text="29.92" Grid.Row="2" Grid.Column="1" VerticalContentAlignment="Center" Margin="5" IsReadOnly="True"/>

        <Grid Grid.Row="3" Grid.Column="1">
            <Grid.ColumnDefinitions>
                <ColumnDefinition />
                <ColumnDefinition />
            </Grid.ColumnDefinitions>
            <Button x:Name="decreaseBaroButton" Content="-" Grid.Column="0" Click="decreaseBaroButton_Click" IsEnabled="False"/>
            <Button x:Name="increaseBaroButton" Content="+" Grid.Column="1" Click="increaseBaroButton_Click" IsEnabled="False"/>
        </Grid>
        <Button x:Name="resetBaroButton" Content="STD Baro" Grid.Row="3" Grid.Column="0" Click="resetBaroButton_Click" IsEnabled="False"/>

        <Button x:Name="connectButton" Content="Connect" Grid.Row="5" Click="connectButton_Click" />
        <Button x:Name="disconnectButton" Content="Disconnect" Grid.Row="5" Grid.Column="1" Click="disconnectButton_Click" IsEnabled="False"/>
    </Grid>
</Window>

To use the new serialPortTextBox, change the private void InitializeSerialPort() to this:

private void InitializeSerialPort()
{
    serialPort = new SerialPort(serialPortTextBox.Text, 115200)
    {
        ReadTimeout = 1000,
        WriteTimeout = 1000,
        DtrEnable = true,
        RtsEnable = true,
        NewLine = Environment.NewLine,
    };

    // attach an event handler
    serialPort.DataReceived += SerialPort_DataReceived;

    serialPort.Open();
}

For the button event handlers, this is the code behind:

private void decreaseBaroButton_Click(object sender, RoutedEventArgs e)
{
    simconnect.TransmitClientEvent(SimConnect.SIMCONNECT_OBJECT_ID_USER, SimEventType.KOHLSMAN_DEC, 0, GroupId.FLAG, SIMCONNECT_EVENT_FLAG.GROUPID_IS_PRIORITY);
}

private void increaseBaroButton_Click(object sender, RoutedEventArgs e)
{
    simconnect.TransmitClientEvent(SimConnect.SIMCONNECT_OBJECT_ID_USER, SimEventType.KOHLSMAN_INC, 0, GroupId.FLAG, SIMCONNECT_EVENT_FLAG.GROUPID_IS_PRIORITY);
}
        
private void resetBaroButton_Click(object sender, RoutedEventArgs e)
{
    simconnect.TransmitClientEvent_EX1(SimConnect.SIMCONNECT_OBJECT_ID_USER, SimEventType.KOHLSMAN_SET, GroupId.FLAG, SIMCONNECT_EVENT_FLAG.GROUPID_IS_PRIORITY, (uint)(29.92 * 33.864 * 16), 0, 0, 0, 0);
}

Code Break down

Notice we have two different methods that send an EventId:

TransmitClientEvent(uint ObjectID, Enum EventID, uint dwData, Enum GroupID, SIMCONNECT_EVENT_FLAG Flags)

TransmitClientEvent_EX1(uint ObjectID, Enum EventID, Enum GroupID, SIMCONNECT_EVENT_FLAG Flags, uint dwData0, uint dwData1, uint dwData2, uint dwData3, uint dwData4)

The difference between the two is that TransmitClientEvent has a single dwData argument, while TransmitClientEvent_EX1 is used for when the data is expected in an array, and dwData0 through dwData4 are the elements of that array.

If we look back at the documentation for KOHLSMAN_SET, it expects the first parameter [0]: Value to set and the second [1]: Altimeter index, which in this case would be 0 for the first altimeter. This would be used in cockpits that have multiple altimeters, like for pilot and copilot, or backup instruments, where you would send 0,1,2, etc. as dwData1 in this case.

Note: If we tried to use TransmitClientEvent for KOHLSMAN_SET, we would see that nothing happens, since we are not sending the data in the format it expects.

In the resetBaroButton_Click we are using the standard aviation barometric pressure of 29.92 inHg, then we multiply by 33.864 to convert to Millibars and then we multiply by 16 as the sim expects it.

Of course if we want to be efficient in our coding, we could some constants for this or write a method to convert from a given pressure in inHg to Millibars, but got lazy, no judging! 😄

The rest of the parameters are:

1. The SimConnect "User ID" const used to represent the user's own aircraft in the sim. We also used this to subscribe to the SimVars earlier.
2. The enum for the event you want to send, that you previously registered with MapClientEventToSimEvent(...).
3. The group id, set to 1 which maps to SIMCONNECT_GROUP_PRIORITY_HIGHEST
4. A flag that provides additional options. Common ones are SIMCONNECT_EVENT_FLAG.DEFAULT, and SIMCONNECT_EVENT_FLAG.GROUPID_IS_PRIORITY

Running and testing

If we build and run our code, we get the updated UI:

We connect and again verify that the numbers match what the sim is showing. Pressing on the +/- buttons should increase and decrease the barometer setting both in game and in the C# app, along an altitude value corresponding to the new barometer setting. This is because we send the event to the game, and then the game sends the new SimVars values back to us so we update the text field with the newest values.

Now press on the STD Baro button, and you should see that it changed to 29.92 and the altitude was updated accordingly as well.

Conclusion

Sending events to the sim is pretty straight forward. One of the biggest mistakes I've done is calling TransmitClientEvent instead of TransmitClientEvent_EX1 by missing that it was expecting an array in the documentation. Another challenge I've encountered is that sometimes it expects the data in a very specific data format I have never worked with before, so I had to spend some time transforming something like a float value into some weird byte array of some obscure standard I have never heard of before. 🤣

In Part 2 and Part 3 of this series I will introduce a rotary encoder so we can send decrease, increase and button push events from the Teensy to the C# app, and repurpose the DataReceived handler method to interpret what I'm sending it and use that to trigger these same events.

Now that we wired our Teensy to a TFT LCD ILI9341 display, lets go ahead and revisit our previous sketch that received data from Microsoft Flight Simulator 2020 via our C# app. We'll add the SPI.h and ILI9341_t3.h libraries and #defines for the TFT and create an ILI9341_t3 instance tft to draw. We also added variables to store the current and previous values for both the altitude and barometer for refresh purposes.

The Code

#include "SPI.h"
#include "ILI9341_t3.h"

#define TFT_DC 9
#define TFT_CS 10
#define CHAR_WIDTH 6

ILI9341_t3 tft = ILI9341_t3(TFT_CS, TFT_DC);

float currentAltitude = 0;
float previousAltitude = -1;

float currentBarometer = 0;
float previousBarometer = -1;

void setup() {
  // initialize the port and set the baud rate to 115200, change to 9600 if you are having communication issues, but make sure it's the same rate as in the C# code
  Serial.begin(115200);

  tft.begin();
  tft.setRotation(1);
  tft.fillScreen(ILI9341_BLACK);

  // labels
  drawTextCentered("Altitude (feet)", 0, 2, ILI9341_WHITE);
  drawTextCentered("Barometer (inHg)", 120, 2, ILI9341_WHITE);

  // refresh values
  update();

  // wait for a serial connection before beginning
  while(!Serial);
}

void loop() {
  // check if we have at least 8 bytes. our full message should be 9 bytes,
  if (Serial.available() > 8) {
    currentAltitude = readFloat();
    currentBarometer = readFloat();

    Serial.readStringUntil('\n');

    update();
  }
}

// util method to read 4 bytes from the serial port and return them as a float
float readFloat() {
  char buffer[4];
  Serial.readBytes(buffer, 4);

  float value;
  memcpy(&value, buffer, sizeof(float));

  return value;
}

// util method to redraw the values
void update() {
  if (previousAltitude != currentAltitude) {
    tft.fillRoundRect(30, 40, 260, 50, 10, ILI9341_GREEN);
    tft.drawRoundRect(30, 40, 260, 50, 10, ILI9341_WHITE);
    drawTextCentered(String(currentAltitude), 50, 4, ILI9341_BLACK);

    previousAltitude = currentAltitude;
  }

  if (previousBarometer != currentBarometer) {
    tft.fillRoundRect(30, 160, 260, 50, 10, ILI9341_GREEN);
    tft.drawRoundRect(30, 160, 260, 50, 10, ILI9341_WHITE);
    drawTextCentered(String(currentBarometer), 170, 4, ILI9341_BLACK);

    previousBarometer = currentBarometer;
  }
}

// util method to draw centered
void drawTextCentered(String text, int y, int size, uint16_t color) {
  int offset = 160 - (text.length() * CHAR_WIDTH * size / 2);

  tft.setTextSize(size);
  tft.setCursor(offset, y);
  tft.setTextColor(color);
  tft.print(text);
}

Initialization

We initialize our tft in the setup() method like before and add some labels for the "Altitude (feet)" and "Barometer (inHg)". Since these we will only update a portion of the screen to draw the actual values, we only need to draw these labels once during setup(). Finally, we call the update() function to draw the values on the screen and wait for the Serial port to be opened, so that we wait until our C# app connects and starts sending data.

Loop

In our loop() function, we replaced the the code that sent the altitude and barometer values back to the C# app, in favor of the update() function. If we look at the update() function's body, we have two similar sections, for altitude and barometer. Let's examine the altitude section.

To reduce updates, we only redraw when the new currentAltitude value is different from previousAltitude, We draw 2 rectangles, a solid GREEN one for the background, and a WHITE one for the border. We call the same drawTextCentered() function we used to draw the labels and we finally store the new currentAltitude value as previousAltitude for the next loop() pass.

Centering Text

The void drawTextCentered(String text, int y, int size, uint16_t color) function is a handy utility function I use on a lot of my projects. Since displaying text is based on the top-left corner of the first letter in the String, based on the String's length() we can calculate how much we need to offset the x coordinate so that the entire text is centered.

Since I called tft.rotate(1) in the setup() function, the resolution is 320 x 240. If we want to make the text centered, we start from x=160. We calculate half of the String's length(), times the text size, times the character's width. We then subtract that from 160 and we have a rough position to make it centered.

Let's say we have "Hello World!". String length is 12. Font size is set to 4. Default font width is 6.

offset_x = 160 - (12 * 4 * 6 / 2) = 160 - (144) = 16

Build and Run

If we build and upload the Sketch into our Teensy, run Microsoft Flight Simulator 20202 and load a flight, run the Hello MSFS app and click on Connect, we should see something like this:

Please ignore the red lines, this screen is damaged and it has those 3 rows of pixels permanently red, so it is the one I use for development ;-)

Now fly around or change the barometer setting in your plane's Altimeter and see how these change. Immediately you will notice that the altitude value flickers a lot compared to the barometer value. This is because it is constantly changing and it needs to redraw this section a lot.

Wrapping up

At this point I have provided all the building blocks needed to pull data from Microsoft Flight Simulator 2020 using the SimConnect SDK, sending the data down to a device via a USB Serial connection, and draw an instrument based on the data on a TFT LCD display. Now you can start designing your own instruments that mimic the typical steam gauge instruments or even digital ones like the Aspens or Garmin digital display instruments.

The only thing we are missing that I'll be covering in the next post is how to send events from the device back to the sim. Later on, we'll talk about how we can use the GFXCanvas16 to minimize the flickering by drawing to a in-memory canvas and updating only the necessary areas of the screen.

In our previous post Choosing the right display we looked at a few options to use as our main display. We ended up choosing a 240x320 ILI9341 TFT Screen that is available to buy at a lot of places, like Amazon, AliExpress, PJRC, Ebay, etc. It is driven by a ILI9341 chip that can handle 240x320 resolution, 18-bit color, and uses the SPI (Serial Peripheral Interface) for communications and uses only 4 signal pins, CS, SCLK, MOSI and MISO, which is perfect for interfacing with boards like the Arduino, ESP32 and Teensy, since they all support SPI communications natively.

Most of these displays also come with Touch capabilities from a XPT2046 touch controller, which require an additional library to control and 5 additional pins.

Wiring

One important fact about these displays. The signal lines can only handle 3.3V, so be careful what you connect them to that could damage your display. 5V should only be used as VCC, and if wiring the LED pin to 5V, put a 100 ohm resistor in place (or just wire to 3.3V)

I recommend using a breadboard for development before soldering all the cables without testing. This is how my development setup looks like:

Arduino IDE Setup

The Arduino IDE supports multiple boards besides Arduino. To get Teensy support in the Arduino IDE, open File->Preferences and in the Additional boards manager URLs add the following:

https://www.pjrc.com/teensy/package_teensy_index.json

Should look like something like this:

Note that this is Arduino IDE 2.x. If you want to, you can do the same in Arduino 1.x, but I recommend using 2.x.

Once that you added the Teensy board manager URL, let's open the Boards Manager and search for teensy. Teensy (for Arduino IDE 2.0.4 or later) should show up. Install the latest version.

Now that our IDE is setup and our Teensy is connected to the computer, lets try out one of the examples. Go to File -> Examples, under Examples for Teensy 4.0 look for ILI9341_t3 and open the graphicstest example:

Select your Teensy in the boards drop down menu and Build and Upload the Sketch. Once finished, and if everything is wired properly, you'll see a message on the screen saying "Waiting for Arduino Serial Monitor...". Open the Serial Monitor in the IDE and watch the magic happen!

While the graphics eye candy show is going, the Teensy will output some stats for nerds to the Serial Monitor window that look like this:

One thing to try out. If you have an Arduino UNO, hook it up to the LCD screen and run the Adafruit ILI9341 graphicstest example sketch so you can compare the numbers. The Teensy is so much faster, which is why I decided to go with this platform.

So how does this work?

At the beginning of the Sketch, we can see the following:

#include "SPI.h"
#include "ILI9341_t3.h"
#include "font_Arial.h"

// For the Adafruit shield, these are the default.
#define TFT_DC  9
#define TFT_CS 10

// Use hardware SPI (on Uno, #13, #12, #11) and the above for CS/DC
ILI9341_t3 tft = ILI9341_t3(TFT_CS, TFT_DC);

These TFT devices have an ILI9341 driver that uses SPI for communications. The ILI9341_t3.h is a Teensy optimized version of the ILI9341.h library made by Adafruit, which works in combination of the Adafruit_GFX.h library for drawing graphics on a screen.

We also define where our Data/Communications and Chip Select pins are connected to and we create an ILI9341_t3 object called tft for drawing.

In the setup() function we see the following:

void setup() {
  tft.begin();
// Note: you can now set the SPI speed to any value
// the default value is 30Mhz, but most ILI9341 displays
// can handle at least 60Mhz and as much as 100Mhz
//  tft.setClock(60000000);
  tft.fillScreen(ILI9341_BLACK);
  tft.setTextColor(ILI9341_YELLOW);
  tft.setTextSize(2);
  tft.println("Waiting for Arduino Serial Monitor...");

We are initializing our tft screen with the begin() function, which takes care of the SPI initialization. Then we use fillscreen() to set the screen to black, we setTextColor() to yellow and setTextSize() to 2, which renders the default font at 10 x 16 pixels per character, instead of the default size of 1 which renders it at 6 x 8 pixels. We can also specify the screen orientation by calling setRotation() with values of 0,1,2,3 for 0, 90, 180 and 270 degrees. Note that the coordinate system is always (0,0) at the top left corner of the screen and depending on the orientation, can be either 240x320 or 320x240 at the bottom left corner of the screen.

To draw text, we first call the setCursor(x,y) to specify where we will begin writing text, and use println() to output text with the last color specified (yellow) and font size (2). All subsequent calls to print() or println() will also use the same color and size unless you change it to something else.

tft.setSize(2);
tft.setColor(ILI9341_RED);
tft.println("This text is RED and size 2");

tft.setSize(3);
tft.setColor(ILI9341_WHITE);
tft.println("This text is WHITE and size 3");

Drawing lines can be done in two ways: you can use drawLine(x1,y1,x2,y2,color) to draw a line from point (x1,y1) to point (x2,y2) with the specified color, or you can use the drawFastHLine(x,y,width,color) and drawFastVLine(x,y,height,color) to draw a horizontal or vertical line starting from point (x,y) and with the specified width or height and color. These two take advantage of ILI9341 commands and are more efficient than using the regular drawLine() to draw horizontal and vertical lines.

The library also functions to either draw an empty shape or fill a solid shape. For example drawCircle(x,y,radius,color) will draw an empty circle with a center at point (x,y) of the specified radius and color, but fillCircle(x,y,radius,color) will draw a solid circle at point (x,y) of the specified radius and filled in its entirety of the specified color. Similar functions are available for triangles and rectangles, with the addition of rectangles have an additional round corner counterparts, for when you might want to draw something like a button.

Performance considerations

A very important thing to know, there is no native logic for "remembering" what the drawn shapes are. These functions are the most basic forms of drawing, and they just draw on top of whatever is already on the screen. If for example you wanted to draw something like the blue sky and the sun, and later want to draw the black night sky and the moon, you first have to fill the entire screen with a blue color using fillScreen() which erases everything, then you would have to use fillCircle() to draw a "sun". Then when you want to draw the night scene, you'll need to call fillScreen() again, this time with black, erasing the entire display, and then would have to call fillCircle() again to draw the "moon". This tends to be slow, especially whenever you call fillScreen(), so keep in mind this and only update the sections of the screen you need to update depending on what you are drawing. Like I mentioned before, there are other ways around this, like using a frame buffer, which I'll talk more about later.

Useful Links

Both Adafruit libraries can be found here:

GitHub - adafruit/Adafruit-GFX-Library: Adafruit GFX graphics core Arduino library, this is the ‘core’ class that all our other graphics libraries derive from

Adafruit GFX graphics core Arduino library, this is the ‘core’ class that all our other graphics libraries derive from - adafruit/Adafruit-GFX-Library

GitHubadafruit

GitHub - adafruit/Adafruit_ILI9341: Library for Adafruit ILI9341 displays

Library for Adafruit ILI9341 displays. Contribute to adafruit/Adafruit_ILI9341 development by creating an account on GitHub.

GitHubadafruit

They also have a really good tutorial on how to draw on these ILI9341 driven devices here, which I suggest you go through for more details on how to draw graphics on the screen using the library.

Adafruit GFX Graphics Library

The Adafruit_GFX library for Arduino provides a common syntax and set of graphics functions for all of our LCD and OLED displays.

Adafruit Learning SystemPhillip Burgess

The problem

Up until this point, I've been sharing code examples for the Arduino Leonardo/Micro. Arduinos are an "ok" starter microcontroller board, but eventually you will realize that it doesn't have the specs needed for building something other than a keypad, game controller or a switch/buttons box. Their processor speed is only 16 MHz and they only have 2 kB of SRAM and, 32 kB of Flash memory. Even worse, the Leonardo/Micro that I've been using for these input devices really only has 28 kB of Flash memory.

When drawing complex graphics on a screen, we typically make use of a frame buffer to do graphics operations in memory before writing to the screen so we can have a high refresh rate. This is because writing to the screen is slow and we only want to update pixels as needed. Without a frame buffer, you pretty much have to rely on very simple graphics and remembering what you draw in the last frame so you can erase it and draw the new one (remember 70s and 80s flickering polygon graphics?)

Screen Resolution

Small TFT LCD displays that are used in these types of projects usually come in a resolution of 320x240 pixels. That is 76,800 pixels each consisting of 3 bytes for the RGB color, for a total of 230,400 bytes or 225 kB of required RAM. Even the Minima is near max capacity just for a frame buffer, which won't leave us much room for other variables we would need to create, especially used in complex mathematical operations to draw simple polygons on a screen.

The Alternatives

After doing some research across other microcontroller boards similar to Arduino, I looked some other popular boards that also work with the Arduino IDE and most of the existing community developed libraries. Here are some of them:

1. Arduino R4 Minima

The newest series in the Arduino line is the Arduino UNO R4 Minima. It has a 48 MHz processor and 256 kB of Flash and 32 kB of RAM which could work for our code but with 225 kB already dedicated to the frame buffer, we can easily run out of memory (which I did during my testing) while trying to calculate and draw complex shapes on the screen.

2. ESP32

The ESP32's are very popular and cheap. There are so many variants that honestly it was a bit overwhelming deciding what to buy for experimenting. I finally ended up buying a set of 3 ESP-WROOM-32 boards for around $15 on Amazon, which even have WiFi and Bluetooth on board. While a very interesting development board, and so many ideas come to mind with these capabilities, they only have around 520 kB RAM and 448 kB Flash. That's more than the newest Arduino R4, but after trying to compile some code, I realized I didn't have access to all the memory and after doing some digging, it's due to some partitioning that the ESP32 supports and the Default partitioning only gives you like 1/3 of the memory and I didn't bother looking into how to reclaim all that memory or the consequences of doing so.

3. Teensy

Another board I came across was the Teensy. Similar in size to the Arduino Micro, this board was created by Paul Stoffregen (PJRC.COM), who is a big contributor to a lot of the Arduino libraries used by the Arduino community. Teensy originally used an ATMEGA AVR 8-bit processor similar to the Arduinos but eventually he moved to using Cortex M 32-bit and 64-bit processors. Their newest boards the Teensy 4.0 and 4.1 rock a Cortex-M7 processor running at 600 MHz that can be overclocked to 912 MHz, both have 1024 kB of RAM and the 4.0 has ~2 MB of Flash Memory, while 4.1 has ~8 MB, which for complex graphic processing is perfect. Teensy 4.0 has 40 pins, and 4.1 has 55 and even comes with an Ethernet Chip.

Conclusion

After messing around with the latest Arduinos, the ESP32's and a few versions of the Teensy, I decided to use Teensy4.0 and 4.1 for the Flight Instruments I'm building, because of the small form factor, number of pins, processor speed and RAM/Flash memory size.

Let's think about what data types. Remember the SimVar structure we created in Part 1 of the series, we created a struct with two floats that represent the Altitude and Barometric Setting of an altimeter.

private struct SimVars
{
  public float Altitude;            // INDICATED ALTITUDE (feet)
  public float KohlsmanSettingHg;   // KOHLSMAN SETTING HG (inHG)
}

In memory, Arduino's float and double are both 4-bytes objects, but our PC is 64-bit and C#'s double is a 8-bytes object. Fortunately, float is 32-bits so we can register our SimVars as SIMCONNECT_DATATYPE.FLOAT32 type to get the values as floats and send them directly to Arduino.

Changing the C# Code to send the data in bytes

Let's change the private void Simconnect_OnRecvSimobjectData(SimConnect sender, SIMCONNECT_RECV_SIMOBJECT_DATA data) method. Instead of calling serialPort.WriteLine(...) we will be converting the values to byte arrays and sending them using serialPort.Write(byte[] buffer, int offset, int count).

// comment out so we don't send it as a string anymore
//serialPort.WriteLine($"{simvars.Altitude},{simvars.KohlsmanSettingHg}");

// first, create a buffer to put the data
List<byte> buffer = new();

// then lets add the two simvars. We will use BitConverter to get the floats as a byte array
buffer.AddRange(BitConverter.GetBytes(simvars.Altitude));
buffer.AddRange(BitConverter.GetBytes(simvars.KohlsmanSettingHg));

// now, lets add our newline to specify the end of our message
buffer.Add((byte)'\n');

// finally, lets write the message to the serial port
serialPort.Write(buffer.ToArray(), 0, buffer.Count);

That's it. We created a byte buffer, we converted both SimVars to byte arrays using the utility class BitConverter, while adding them to our buffer. We added our newline to specify the end of our message and we wrote the bytes to the serial port. Our message size should always be 9 bytes, that is:

• 4 bytes - for the Altitude
• 4 bytes - for the Barometer Setting
• 1 byte - for the Newline Character ('\n')

Changing the Arduino Sketch to read and convert Serial bytes

To read bytes from the serial port, we will be using the Serial.readBytes(char* buffer, int length). We will then use memcpy(float* value, char* buffer, int size) to literally copy the 4 bytes we have in the buffer into the object's memory. This will reconstruct the float value we sent from the C# app. Finally we will send a message back to see if all of this worked:

void setup() {
  // initialize the port and set the baud rate to 115200, change to 9600 if you are having communication issues, but make sure it's the same rate as in the C# code
  Serial.begin(115200);
}

float altimeter;
float barometer;

void loop() {
  // check if we have at least 8 bytes. our full message should be 9 bytes,
  if (Serial.available() > 8) {
    altimeter = readFloat();
    barometer = readFloat();

    Serial.readStringUntil('\n');

    // send the data back through the serial connection
    Serial.print("Altitude: ");
    Serial.print(altimeter);
    Serial.print(", Barometer: ");
    Serial.println(barometer);
  }
}

// util method to read 4 bytes from the serial port and return them as a float
float readFloat() {
  char buffer[4];
  Serial.readBytes(buffer, 4);

  float value;
  memcpy(&value, buffer, sizeof(float));

  return value;
}

Lets upload the Sketch to the Arduino, and press on the Connect button in the Hello MSFS app. We can see that the data is being sent correctly and the new message format is being displayed with the correct Altimeter and Barometer Setting values:

Wrapping things up

In Part 1 we learned about the Serial Port, how to send and receive data from and to the PC using C# code and an Arduino Sketch in C++. We learned how to identify our Arduino devices using PID/VID, which can be used to maintain a list of connected devices and send the SimVar data to them, but for sake of simplicity, just hardcoded my COM port in the examples to give the reader the option of adding that logic with the WMI query snippet provided.

In Part 2 we extended the code we wrote that uses SimConnect SDK to subscribe to SimVars and send them to an Arduino device using the Serial Port object as a string, and we verified that the data was received correctly by sending the same string back and printing it in the Debug output window.

In Part 3 we modified the code again to send the data in their own native type by using BitConverter to convert the floats to byte arrays, build a byte buffer with both Altitude and Barometer Setting SimVars byte arrays and our newline terminator, and modified the Arduino Sketch to read the data from the Serial connection as bytes and convert them back to float types and rebuilt our message and send it back to the Hello MSFS app to visually verify that the data was received and converted correctly.

Now you have the building blocks on how to build your own instruments based on the SimVar data from Microsoft Flight Simulator 2020, and hopefully you can start building some kickass instruments and build up your sim cockpit!

Expanding the code we used to send data from C# to Arduino in Part 1 of this series, let's define a SerialPort object and initialize it.

public partial class MainWindow : Window
{
  ...
  
  private SerialPort serialPort;

  ...

  private void InitializeSerialPort()
  {
    serialPort = new SerialPort("COM8", 115200);
  }
}

Note: My Arduino is on COM8, so update the port to match yours.

Next, let's try to open and close the serial port connection when we press on the Connect/Disconnect buttons:

 // Connect button event handler
 private void connectButton_Click(object sender, RoutedEventArgs e)
 {
     if (Process.GetProcessesByName(MSFS_PROCESS_NAME).Any())
     {
         try
         {
           ...
           
            // open the COM port
            InitializeSerialPort();

            // start out DispatcherTimer to start polling from the game
            simConnectDispatcherTimer.Start();

            ...
          }
          catch (Exception ex)
          {
            ...
          }
      }
  }

  // Disconnect button event handler
  private void disconnectButton_Click(object sender, RoutedEventArgs e)
  {
    ...

    // if port is open, close it
    if (serialPort.IsOpen)
    {
        serialPort.Close();
    }
}

Finally, let's expand the Simconnect_OnRecvSimobjectData handler to send data:

 // called whenever we receive a new set of SimVar data
private void Simconnect_OnRecvSimobjectData(SimConnect sender, SIMCONNECT_RECV_SIMOBJECT_DATA data)
{
    switch ((RequestType)data.dwRequestID)
    {
        case RequestType.PerFrameData:
          simvars = (SimVars)data.dwData[0];

          // send data to serial port if it's open
          if (serialPort.IsOpen)
          {
              try
              {
                  serialPort.WriteLine($"{simvars.Altitude},{simvars.KohlsmanSettingHg}");
              }
              catch (Exception ex)
              {
                  Debug.WriteLine($"Exception sending data to Arduino: {ex.Message}");
              }
          }
      
          altimeterTextBox.Text = $"{simvars.Altitude:0.00}";
          barometerTextBox.Text = $"{simvars.KohlsmanSettingHg:0.00}";
      
          break;

        default:
            Debug.WriteLine($"Unsupported Request Type: {data.dwRequestID}");
            break;
    }
}

We can use the same Arduino Sketch we used before:

void setup() {
  // initialize the port and set the baud rate to 115200, change to 9600 if you are having communication issues, but make sure it's the same rate as in the C# code
  Serial.begin(115200);
}

void loop() {
  if (Serial.available() > 0) {
    // read all data until end of line
    String data = Serial.readStringUntil('\n');

    // send the data back through the serial connection
    Serial.println(data);
  }
}

Arduino Serial Monitor

If we compile and upload this Sketch to our Arduino before running the Hello MSFS app, we can open the Tools–>Serial Monitor window in the Arduino IDE, set the BAUD to 115200, and type anything and hit enter. The sketch should echo what we just we wrote back to us. Now, make sure MSFS is running and run the Hello MSFS app and click on connect. As soon as it connects to the sim and tries to send data to the Arduino, we'll see the following exception:

22:36:04:570	Exception thrown: 'System.UnauthorizedAccessException' in System.IO.Ports.dll
22:36:04:570	Access to the path 'COM8' is denied.

So what happened? Since we still have the Arduino IDE Serial Monitor open, it already has COM8 opened and Windows won't let us open it a second time, so let's close the Serial Monitor window and try one more time. Click Disconnect and then Connect and now we don't get the exception but we don't have a way of knowing what was actually received on the Arduino. We are sending data back from the Arduino to the PC, but our app is not listening to data coming in from the COM8 port.

Note: If we would try to open the Serial Monitor again while our app is running and connected, we will get into a similar error in the Arduino IDE since, it won't be able to open the port because our app already has it opened.

DataReceived Event Handler

So how do we verify that the data received by the Arduino is correct? We also did this in the previous post. Let's add some code to subscribe to the DataReceived event via a custom handler. By modifying the InitializeSerialPort method we created earlier, we can define our custom event handler:

private void InitializeSerialPort()
{
    serialPort = new SerialPort("COM8", 115200)
    {
        ReadTimeout = 1000,
        WriteTimeout = 1000,
        DtrEnable = true,
        RtsEnable = true,
        NewLine = Environment.NewLine,
    };

    // attach an event handler
    serialPort.DataReceived += SerialPort_DataReceived;
}

private void SerialPort_DataReceived(object sender, SerialDataReceivedEventArgs e)
{
    try
    {
        // Read data from the serial port until NewLine is found and trim the newline character(s)
        var dataReceived = serialPort.ReadLine().Trim();

        Debug.WriteLine($"Received: {dataReceived}");
    }
    catch (Exception ex)
    {
        Debug.WriteLine("Error while receiving data: " + ex.Message);
    }
}

Notice a few new extra parameters while creating the SerialPort object:

1. ReadTimeout/WriteTimeout – setting these to one second. The default is -1 which blocks forever and we don't want that
2. DtrEnable/RtsEnable – Enabling Data Terminal Ready and Request To Send flags. For some reason the DataReceived Handler doesn't work without these on, and haven't found where it's documented that they are needed.
3. NewLine – We are setting this to '\r\n' on Windows to match Arduino's Serial.print() behavior. See the documentation for more details.

With all this in place, we can now run our app again. First make sure Arduino's Serial Monitor is not open, and Debug the app and click on Connect. This time we'll be both displaying the SimVar values we are getting from the sim in the UI and sending them to the Arduino device as a string. The string with our SimVars does the round robin trip back and the DataReceived handler will read the string and print it on the Debug window:

A note on message format

One thing worth mentioning, for the sake of simplicity, our communications rely on sending the data as a string using the newline character to determine when a "message" ends. We send from the C# app using serialPort.WriteLine(), we read in the Arduino Sketch using Serial.readStringUntil('\n'), then we send it back using Serial.println() and read it in the C# app using serialPort.ReadLine(). You really want to be able to send other data types besides string, since you don't want to have to do a lot of string parsing in Arduino when you can send floats and ints in byte format and convert them directly to their corresponding types on the Sketch. There are many existing standards and protocols used in Serial Communications that can do this, but they are out of scope for what I wanted to achieve here.

Conclusion

In part 2 of this 3 part series, we modified the code we created on part 1 that received data from Microsoft Flight Simulator and send it down to an Arduino device connected to the same PC where the Hello MSFS app is running. We simplified the process by sending a newline delimited string message and we verified that the data was received by implementing the DataReceived handler to print out the same data we sent to the Arduino.

In the last part of this series, we'll modify the code to send the two SimVars as floats and then storing them on some variables in the Arduino Sketch.

Let's continue thinking about building our Altimeter device. Now that we have the altimeter and barometer data from the sim, lets see what we need to be able to write a sketch to send the two SimVars to an Arduino and display them somehow.

The obvious questions

So... how do we send data from Windows to an Arduino via USB? But more important, how do we know out of all the USB devices connected to the PC, which one's our Arduino? It's pretty simple and I already talked about in my post about Arduino Joystick Emulation. We can use the device's PID/VID to identify them.

What is a PID/VID?

The Product ID (or PID) and the Vendor ID (or VID) are unique identifiers used in USB devices to identify the manufacturer and their specific product. For Arduino devices, the VID is 2341, and the PID depends on the Arduino board. For example:

Note: these are the PID/VID values defined in C:\Program Files (x86)\Arduino\hardware\arduino\avr\boards.txt

How do we query USB devices in .NET?

Unfortunately, there is no "native" .NET way of querying that data for USB devices so you have to use some other API like a Windows Management Instrumentation (or WMI) query and parse the results. Here is an example code snippet with the general idea of how to do it:

using System.Management;

var searcher = new ManagementObjectSearcher("select DeviceID, PNPDeviceID, MaxBaudRate from win32_serialport");

var devices = searcher.Get().Cast<ManagementBaseObject>().ToList();

// print all devices
foreach (var d in devices)
{
  // this contains the COM port
  var deviceId = (string)d["DeviceID"];

  // this contains the PID?VID
  var pnpDeviceId = (string)d["PNPDeviceID"];

  // this contains the Max Baud Rate you can use to talk to the device
  var maxBaudRate = (uint)d["MaxBaudRate"];

  Debug.WriteLine($"DeviceID: {deviceId}, PNPDeviceId: {pnpDeviceId}, MaxBaudRate: {maxBaudRate}");
}

// you can write a lambda to filter by your supported devices based on the PNPDeviceID

Once we have built a list of connected devices that we can talk to, we can now write some C# code to open a Serial connection to a device and send our data.

About Serial Ports

A serial port is a communication interface where information is transmitted sequentially one bit at a time. This is the interface used historically for communications between computers and peripherals like modems, keyboards, mice, terminals, back in the day before high speed USB, Ethernet, etc. Devices that support serial port communications are typically associated with port name and their speed, plus other data integrity validation parameters like data/stop bits and parity.

Although all these parameters must match on both sides to be able to communicate properly, we are going to focus on two things, the port name and the speed. When connecting to an Arduino, these typically look like "COM3", "COM5" for the port name, and values like 115200, 9600, 38400 for the speed.

Sending data from C# using SerialPort

We can use the SerialPort class to send and receive data to/from an Arduino. We'll need two things, it's COM port and the speed. To find the COM port name manually, we can go to Device Manager and find our Arduino device and see what port it is using; alternatively we can open the Arduino IDE and find it there.

Let's look at some code:

// initialize the SerialObject, assuming our Arduino is on COM3 and we can send data at 115200. If not, try a lower setting like 9600 which is commonly seen in older Arduino example Sketches
var serialPort = new SerialPort("COM3", 115200);

// try to open the port
try
{
  serialPort.Open();

  // send some data
  serialPort.WriteLine("Hello Serial World!");
}
catch (Exception e)
{
  Debug.WriteLine(e.Message);
}
finally
{
  // close the serial port
  if (serialPort.IsOpen)
  {
    serialPort.Close();
  }
}

Receiving data in C# using SerialPort

For receiving data, we need to define a DataReceived event handler which is triggered whenever data comes to the serial port. Example:

// initialize the SerialObject, assuming our Arduino is on COM3 and we can send data at 115200. If not, try a lower setting like 9600 which is commonly seen in older Arduino example Sketches
var serialPort = new SerialPort("COM3", 115200);

// attach an event handler
serialPort.DataReceived += SerialPort_DataReceived;

// try to open the port
try
{
  serialPort.Open();

  while(true)
  {
    Thread.Sleep(1000);
  }
}
catch (Exception e)
{
  Debug.WriteLine(e.Message);
}
finally
{
  // close the serial port
  if (serialPort.IsOpen)
  {
    serialPort.Close();
  }
}

private static void SerialPort_DataReceived(object sender, SerialDataReceivedEventArgs e)
{
  try
  {
    // Read data from the serial port
    var dataReceived = serialPort.ReadLine(); // Reads until a newline character is found
    // Alternatively, use serialPort.ReadExisting() to read all available data as a string
            
    Debug.WriteLine(dataReceived);
  }
  catch (Exception ex)
  {
    Debug.WriteLine("Error while receiving data: " + ex.Message);
  }
}

Sending and Receiving data from Arduino

Arduino has a Serial class used serial port communications which is pretty straightforward to use. All Arduinos have at least one Serial port, but some can have Serial2 and Serial3 for additional I/O. Example:

void setup() {
  // initialize the port and set the baud rate to 115200, change to 9600 if you are having communication issues, but make sure it's the same rate as in the C# code
  Serial.begin(115200);
}

void loop() {
  if (Serial.available() > 0) {
    // read all data until end of line
    String data = Serial.readStringUntil('\n');

    Serial.print("Received: ");
    Serial.println(data);
  }
}

Conclusion

.NET and Arduino both provide simple classes to communicate via serial port. In the examples above, we are sending and receiving simple string messages as a proof of concept, but we can easily expand these to send other data types. The catch is that we have to send and receive them in bytes and convert them to the corresponding types after receiving them.

Alternatively, there are existing standardized protocols that are supported in Arduino that we could use to implement more robust communications instead of simple raw byte communications, but with the added overhead that could impact performance, but it's worth looking into in the future.

Something I have to start thinking about at this point is how will I interact with these screens. All the ones I purchased for experimenting have touch capabilities. Some are capacitive, some are resistive. Both have their differences, so should I go in that direction? On one hand they all already come with it, but then there's about 4-5 more connections I need to solder on each screen for touch, and from the tests I've done... it's a bit finicky.

But what exactly do I want to interact with and how? For starters if I'm going to build a device that supports multiple instruments, I need a way to selecting which one I want to display. Is touch really a good choice for something like this? And, if we look at the instruments in a typical cockpit, most of them have knobs and buttons.

Alternatives

1. Touch:
   1. I'll be drawing a lot of stuff on tiny 3.2" screens, so I don't have a lot of room to add buttons. I played around with the idea of having the screen divided into 4 sections so I could use those as buttons, but for things like increasing/decreasing a heading bug on a Heading Indicator, a barometric pressure on an Altimeter, or an OBS on a VOR, it's unpractical.
   2. Pros:
      1. Already comes with the device
   3. Cons:
      1. Extra wiring
      2. Finicky and unpractical code
2. Push Buttons
   1. I tried adding two buttons to each screen for going back and forth along the screens, but that was about it. I even 3D printed an oval shape cap for the 2 buttons that pretty much looked like the buttons on a DVD player for fwd/back that looked really good but I felt was only solving half of the problem.
   2. Pros:
      1. They are pretty straightforward to add and implement
      2. They are more reliable than touch on these type of devices
   3. Cons:
      1. Only solved half of the problem
3. Rotary Encoders
   1. I messed around with the idea of a rotary encoder or two. Usually they come with an integrated push button so between two knobs and two buttons I would have more than enough inputs for the instruments I want to design
   2. Pros:
      1. With the rotary encoder, I could control different values that I could increment and decrement
      2. I also had available 2 buttons to assign to anything I needed
   3. Cons:
      1. There was really not a lot of room to put two rotary encoders on these small scale screens I'm designing, especially when everything is built and soldered by hand and with off shelf components.
4. Dual Rotary Encoder
   1. Pretty much the same as having two rotary encoders but in the space occupied by just one, but with the trade-off of only having one button instead of two.
   2. Pros:
      1. Same as two rotary encoders plus one is easier to mount and solder than two.
   3. Cons:
      1. They are a bit more expensive than regular rotary encoders

The Choice

After a lot of experimentation and testing, I decided to go with the dual rotary encoders. The extra cost is worth the simplicity and reduced space. I went with this one from Digikey and did not disappoint.

Design restriction

Remember back when I talked about measuring the 3U bracket that comes with the Logitech Multi Panel display, and designing a 2U bracket for my Switch Box that would be compatible with Logitech's and the yokes out there? I also ended up designing a 1U version of it so whatever I choose to use for a display has to fit in that space.

The screen I choose has to fit inside of the 94mm x 87.25mm 1U bracket. I started looking around to see what screens were typically used with Arduinos, and ended up finding that 2.8" and 3.2" TFT screens that are driven by the ILI9341 controller are widely used, and there is a wide variety of graphics libraries that support them. Some even have touch capabilities, if we wanted to go in that direction. These are a few I screens experimented with:

Adafruit 2.8" TFT Touch Shield for Arduino

1. Pros:
   1. Comes in a Shield factor, so you just have to mount it on top of an Arduino
   2. Already has libraries made by Adafruit for drawing and with tutorials on how to use them
   3. Has capacitive touch
   4. Has an SD Card slot
   5. Works with 3.3V and 5V signals
2. Cons:
   1. The Shield form factor limits you on what devices you can use it with.
   2. Only supports Arduino Uno/Leonardo/Mega, unless you want to get creative and modify the library for your device
   3. Costs about $25 each (I believe it was around $45 when I bought mine)
   4. It's a bit too small and there's definitely room for a bigger screen.

Adafruit 3.2" TFT LCD with Touchscreen

1. Pros:
   1. Comes in a breakout board so you can solder cables directly to it
   2. Already has libraries made by Adafruit for drawing and with tutorials on how to use them
   3. Can be wired to use SPI or 8-bit mode, for even faster data speeds.
   4. Has capacitive touch
   5. Has an SD Card slot
2. Cons:
   1. 8-bit mode has very limited support
   2. 8-bit mode requires 8 lines
   3. Costs around $35 each

PJRC Color 320x240 TFT Display, ILI9341 Controller Chip

1. Pros:
   1. Comes in 2.8" and 3.2" sizes
   2. Has a Teensy Optimized ILI9341 Library to control it
   3. Costs about $16 for the 2.8" and $18 for the 3.2", although you can find similar ones in Ali Express for half than, if you can wait the 3 weeks shipping
2. Cons:
   1. Resistive Touch
   2. Comes with an SD Card slot but it's not supported natively
   3. Limited to 3.3V signals and 5V will fry it.
   4. Comes with the pins pre-soldered so you have to de-solder them if you want to solder wires to it
   5. You need a 100 ohm resistor for the LED connection from VIN

AliExpress 3.2" 320x240 TFT

1. Pros:
   1. Pretty similar to PJRC's version
   2. Works with the same PRJC Optimized ILI9341 library
   3. Comes with touch or no touch
   4. Has an SD Card slot
   5. Doesn't require the 100 ohm resistor
2. Cons:
   1. You wire the LED pin to 3.3V, although wiring to 5V with a 100 ohm like PJRC does work too but the screen too bright so you need a bigger one.
   2. Comes with the pins pre-soldered so you have to de-solder them if you want to solder wires to it

And the winner is?

After getting a few of these, I initially ended up going with the PJRC 320x240 TFT screen for my first batch of instruments, and eventually moved to the cheap ones from AliExpress. These do have a small difference in how you wire them, and the screen is brighter but besides that hardware difference, there is no difference when it comes to writing code for it.

Before we start developing with the MSFS SDK, there are a few things you’ll need to have installed:

1. Microsoft Flight Simulator 2020: Ensure you have a copy of MSFS 2020 installed on your machine.
2. Enable Developer Mode: While not strictly necessary for using the SDK, enabling Developer Mode within the simulator is recommended. This mode allows you to download the SDK directly from within the sim and provides access to additional tools that will be useful throughout the development process, which I’ll cover below.

Note: when you install the SDK it goes under your C:\MSFS SDK folder, so keep that in mind if you install it elsewhere.

3. Microsoft Visual Studio 2022. You can download the free Community version here. During installation, make sure to select the .NET desktop development workload, as this will include everything you need to develop WPF applications. Once installed, you’re ready to move on to the next step.

Setting up your project

Lets proceed by creating a new project. A .NET WPF Application is ideal for what I want to achieve. However, if you prefer, you can write a Console Application and most of the steps this tutorial still applies.

After completing the "Create New Project" wizard in Visual Studio, the first thing you should do is configure your project file. To do this:

1. In the Solution Explorer, right-click on your project’s name.
2. Select Edit Project File.

This allows you to manually adjust the project settings, add dependencies, and make other configurations necessary for integrating the MSFS SDK.

3. To properly integrate the MSFS SDK, you need to reference the SimConnect library in your project. Add the following two <ItemGroup> entries in lines 12 through 24 to your project file to include SimConnect.dll for both build and runtime:

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <TargetFramework>net6.0-windows7.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
        <UseWPF>true</UseWPF>
    </PropertyGroup>
    
    <!-- Add this reference for build and intellisense -->
    <ItemGroup>
        <Reference Include="Microsoft.FlightSimulator.SimConnect">
            <HintPath>C:\MSFS SDK\SimConnect SDK\lib\managed\Microsoft.FlightSimulator.SimConnect.dll</HintPath>
        </Reference>
    </ItemGroup>
    
    <!-- Add this so the dll gets copied to the project output directory for runtime -->
    <ItemGroup>
        <Content Include="C:\MSFS SDK\SimConnect SDK\lib\SimConnect.dll">
            <Link>SimConnect.dll</Link>
            <CopyToOutputDirectory>Always</CopyToOutputDirectory>
        </Content>
    </ItemGroup>
</Project>

Note: If you installed the SDK in a different location, update these paths accordingly.

Build an Altimeter... kinda...

Let’s start by building a simple instrument: the Altimeter. For this, we need to read two values from the simulator: the indicated altitude and the barometric pressure setting. By consulting the Simulation Variables documentation, we can identify the specific SimVars that will provide these values:

Now, let’s build a simple UI for our Altimeter. Open MainWindow.xaml and add the following XAML code to create a basic layout for displaying the altitude and barometric pressure:

<Window x:Class="HelloMSFS.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:HelloMSFS"
        mc:Ignorable="d"
        Title="Hello MSFS" SizeToContent="WidthAndHeight" Topmost="True">
    <Grid Margin="20">
        <Grid.ColumnDefinitions>
            <ColumnDefinition MinWidth="100"/>
            <ColumnDefinition MinWidth="100"/>
        </Grid.ColumnDefinitions>

        <Grid.RowDefinitions>
            <RowDefinition MinHeight="25"/>
            <RowDefinition MinHeight="25"/>
            <RowDefinition MinHeight="25"/>
        </Grid.RowDefinitions>

        <Label x:Name="label" Content="Altimeter:" VerticalContentAlignment="Center" Margin="5" />
        <Label x:Name="label1" Content="Barometer:" Grid.Row="1" VerticalContentAlignment="Center" Margin="5"/>
        
        <TextBox x:Name="altimeterTextBox" TextWrapping="Wrap" Text="1000" Grid.Column="1" VerticalContentAlignment="Center" Margin="5" IsReadOnly="True"/>
        <TextBox x:Name="barometerTextBox" TextWrapping="Wrap" Text="29.92" Grid.Row="1" Grid.Column="1" VerticalContentAlignment="Center" Margin="5" IsReadOnly="True"/>
        
        <Button x:Name="connectButton" Content="Connect" Grid.Row="2" Click="connectButton_Click" />
        <Button x:Name="disconnectButton" Content="Disconnect" Grid.Row="2" Grid.Column="1" Click="disconnectButton_Click" IsEnabled="False"/>
    </Grid>
</Window>

This should create a simple text based altimeter like this:

Implementing the SimConnect Code

With the UI in place, it’s time to add the functionality. Open MainWindow.xaml.cs and include the following C# code to connect to the simulator and update the UI with the Altimeter data:

using Microsoft.FlightSimulator.SimConnect;
using System.Diagnostics;
using System.Runtime.InteropServices;
using System.Windows;
using System.Windows.Threading;

namespace HelloMSFS
{
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
    {
        private const uint WM_USER_SIMCONNECT = 0x0402;                 //
        private const string MSFS_PROCESS_NAME = "FlightSimulator";     // this is MSFS's process name
        private const string PLUGIN_NAME = "Hello MSFS";                // your plugin's name

        private const int SIMCONNECT_TIMER_INTERVAL_MS = 50;            // how often to poll data from the game
        private DispatcherTimer simConnectDispatcherTimer;              // the DispatcherTimer object used to poll data from the game

        private SimConnect simconnect;                                  // the SimConnect SDK object used to subscribe and interact with the game
        private SimVars simvars;                                        // the object we'll store our new data from the game

        public MainWindow()
        {
            InitializeComponent();

            InitializeTimers();
        }

        // this is the structure that will store the data received from the game. note that the number of properties here have to be exactly the same number
        // of AddToDataDefinition(...) calls we are registering, and the type has to match the SIMCONNECT_DATATYPE type.
        [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi, Pack = 1)]
        private struct SimVars
        {
            public float Altitude;                         // INDICATED ALTITUDE (feet)
            public float KohlsmanSettingHg;                // KOHLSMAN SETTING HG (inHG)
        }

        // we need an enum to register the data structure above. note that if you want to store them in separate structures, you'll need to register with a separate enum value here.
        private enum RequestType
        {
            PerFrameData,
        }

        // initializing our DispatcherTimers
        private void InitializeTimers()
        {
            simConnectDispatcherTimer = new DispatcherTimer() { Interval = new TimeSpan(0, 0, 0, 0, SIMCONNECT_TIMER_INTERVAL_MS) };
            simConnectDispatcherTimer.Tick += SimConnectTimer_Tick;
        }

        // function that will be called by the DispatcherTimer to receive new data from the game
        private void SimConnectTimer_Tick(object? sender, EventArgs e)
        {
            try
            {
                simconnect?.ReceiveMessage();
            }
            catch (Exception ex)
            {
                Debug.WriteLine($"Exception in {nameof(SimConnectTimer_Tick)}: {ex.Message}");
            }
        }

        // called whenever we receive a new set of SimVar data
        private void Simconnect_OnRecvSimobjectData(SimConnect sender, SIMCONNECT_RECV_SIMOBJECT_DATA data)
        {
            switch ((RequestType)data.dwRequestID)
            {
                case RequestType.PerFrameData:
                    simvars = (SimVars)data.dwData[0];

                    Debug.WriteLine($"Received: Altitude: {simvars.Altitude}, Barometer: {simvars.KohlsmanSettingHg}");

                    altimeterTextBox.Text = $"{simvars.Altitude:0.00}";
                    barometerTextBox.Text = $"{simvars.KohlsmanSettingHg:0.00}";

                    break;

                default:
                    Debug.WriteLine($"Unsupported Request Type: {data.dwRequestID}");
                    break;
            }
        }

        // called when the connection throws an exception so we can log it
        private void Simconnect_OnRecvException(SimConnect sender, SIMCONNECT_RECV_EXCEPTION data)
        {
            Debug.WriteLine($"Exception received: {data}");
        }

        // called when the game exits
        private void Simconnect_OnRecvQuit(SimConnect sender, SIMCONNECT_RECV data)
        {
            simConnectDispatcherTimer.Stop();
        }

        // called when we connect to the game for the first time
        private void Simconnect_OnRecvOpen(SimConnect sender, SIMCONNECT_RECV_OPEN data)
        {
            // the framework is flexible enough to let you specify the units. check the documentation, for example for altitude you could set this to "feet", "meters", etc.
            simconnect.AddToDataDefinition(RequestType.PerFrameData, "INDICATED ALTITUDE", "feet", SIMCONNECT_DATATYPE.FLOAT32, 0, SimConnect.SIMCONNECT_UNUSED);
            simconnect.AddToDataDefinition(RequestType.PerFrameData, "KOHLSMAN SETTING HG", "inHG", SIMCONNECT_DATATYPE.FLOAT32, 0, SimConnect.SIMCONNECT_UNUSED);

            // register our SimVar structure with the PerFrameData enum
            simconnect.RegisterDataDefineStruct<SimVars>(RequestType.PerFrameData);

            // request data from sim
            simconnect.RequestDataOnSimObject(RequestType.PerFrameData, RequestType.PerFrameData, SimConnect.SIMCONNECT_OBJECT_ID_USER, SIMCONNECT_PERIOD.SIM_FRAME, SIMCONNECT_DATA_REQUEST_FLAG.DEFAULT, 0, 0, 0);
        }

        // Connect button event handler
        private void connectButton_Click(object sender, RoutedEventArgs e)
        {
            if (Process.GetProcessesByName(MSFS_PROCESS_NAME).Any())
            {
                try
                {
                    var handle = Process.GetCurrentProcess().MainWindowHandle;

                    simconnect = new SimConnect(PLUGIN_NAME, handle, WM_USER_SIMCONNECT, null, 0);

                    // register a callback for each handler:
                    // called when you connect to the sim for the first time
                    simconnect.OnRecvOpen += new SimConnect.RecvOpenEventHandler(Simconnect_OnRecvOpen);
                    // called when the sim exits
                    simconnect.OnRecvQuit += new SimConnect.RecvQuitEventHandler(Simconnect_OnRecvQuit);
                    // called when there's an exception when sending us the data
                    simconnect.OnRecvException += new SimConnect.RecvExceptionEventHandler(Simconnect_OnRecvException);
                    // called every time we are sent new simvar data
                    simconnect.OnRecvSimobjectData += new SimConnect.RecvSimobjectDataEventHandler(Simconnect_OnRecvSimobjectData);

                    // start out DispatcherTimer to start polling from the game
                    simConnectDispatcherTimer.Start();

                    // toggle the connect/disconnect buttons
                    connectButton.IsEnabled = false;
                    disconnectButton.IsEnabled = true;
                }
                catch (Exception ex)
                {
                    Debug.WriteLine($"{ex.Message}");
                }
            }
        }

        // Disconnect button event handler
        private void disconnectButton_Click(object sender, RoutedEventArgs e)
        {
            // stop our DispatcherTimer
            simConnectDispatcherTimer.Stop();

            // toggle the connect/disconnect buttons
            connectButton.IsEnabled = true;
            disconnectButton.IsEnabled = false;
        }
    }
}

Ok that looks like a lot, I swear I tried to keep it as simple as possible, but here is what the code is doing:

1. Creating a SimConnect object that will be used to read data from the sim
2. Register the event handlers for when the SimConnect object sends the events we are interested on:
   1. OnRecvOpen - handler for when we connect successfully to the sim
   2. OnRecvQuit - handler for when the sim is exiting
   3. OnRecvSimobjectData - handler for when the sim sends us a new data object with SimVars
   4. OnRecvException - handler for when there is an exception
3. Create one or more structures that will hold our SimVars, which the sim will return with the current values
4. Create an enum with values representing our different structures
5. Register our two SimVars so they can be returned as our structure object.
6. Use a DispatcherTimer to run a background task to check for new data
7. Connect/Disconnect to/from a local MSFS 2020 instance
8. On new data received, update the UI with the latest altimeter values

About Data Types

An important thing we need to keep in mind when designing your struct is what data types to use. Let's look at our struct:

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Ansi, Pack = 1)]
private struct SimVars
{
  public float Altitude;
  public float KohlsmanSettingHg;
}

Notice that in the Simconnect_OnRecvSimobjectData handler, we are doing an explicit casting of an object to our SimVars structure,

simvars = (SimVars)data.dwData[0]

and by doing so, the data gets copied from the object heap into our structure sequentially. This works because of the StructLayout(LayoutKind.Sequential) attribute we added to our struct, since the structure is stored in memory sequentially as well.

We told SimConnect the order and how big that data is when we registered the SimVars via the simconnect.AddToDataDefinition(...) calls, and specifying the SIMCONENCT_DATATYPE.

simconnect.AddToDataDefinition(RequestType.PerFrameData, "INDICATED ALTITUDE", "feet", SIMCONNECT_DATATYPE.FLOAT32, 0, SimConnect.SIMCONNECT_UNUSED);

simconnect.AddToDataDefinition(RequestType.PerFrameData, "KOHLSMAN SETTING HG", "inHG", SIMCONNECT_DATATYPE.FLOAT32, 0, SimConnect.SIMCONNECT_UNUSED);

That is, we are expecting to receive 4 bytes for the altitude and 4 bytes for the barometer in that order. This exactly matches our SimVars structure.

This sounds tedious and prone for errors, especially if you add/remove or move the properties in your structure and forget to do the corresponding update where you are registering your SimVars, so be mindful when updating your struct.

Here are some of the mappings I've used in my projects:

Note: when you are working with strings, you must add an extra annotation specifying the size of the string matching the SIMCONNECT_DATATYPE you registered with

public struct GPS {
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)]
  public string GpsWpNextId;                      // GPS WP NEXT ID
}


public void RegisterMySimVars()
{
  simconnect.AddToDataDefinition(RequestType.PerFrameData, "GPS WP NEXT ID", "", SIMCONNECT_DATATYPE.STRING256, 0, SimConnect.SIMCONNECT_UNUSED);
  ...
}

Running and Connecting to the Sim

• Start MSFS 2020:Open Microsoft Flight Simulator 2020.Navigate to the World Map.Select your favorite airport and click Fly.Wait for the simulator to finish loading.
• Debugging the App:In Visual Studio, start debugging your application.Once the app is running, click Connect.
• Verify Functionality:If everything is set up correctly, the app should connect to the simulator.You’ll see the Altimeter and Barometer values updating in real-time on your UI.You can interact with the simulator: fly around, adjust the barometer knob, and observe the changes reflected in your application.Since we added some Debug.WriteLine(...) statements, we can open the Output View in Visual Studio to see some output. Should look something like this:

Developer Mode

If you haven't already done so, go to General Options-> Developers and turn on DEVELOPER MODE. Save and go back to the sim.

If we go to the top of the screen, you'll see the Developer menu shown. If it's not shown, move your mouse to the top of the screen and it should be visible. It has an autohide option, which you can turn off if you want. Click on the Tools tab and, on the SimConnect Inspector menu item.

Once the SimConnect Inspector window opens, click on the drop down menu and you'll see our new Hello MSFS application connected to the game.

Fun fact: if you are using other plugins or peripherals that use a plugin like Logitech's Instrument Panel, you'll see them here too.

If we click on the Frames tab, we can see the frame where we registered our two SimVars and requested data sent to us.

We can also click on the Data Definitions tab and see our two SimVars:

Fun fact: if you select the other plugins, you can see what SimVars they have registered, which helps you figure out what to use for yours.

Wrapping things up

This tutorial has covered how to read data from Microsoft Flight Simulator 2020 using the SimConnect SDK. To summarize:

1. Reading Data:
   • Consult the documentation to find the SimVars you need.
   • Add the SimVars to your struct and register them using AddToDataDefinition(...).
2. Data Order and Type Matching:
   • The order in which you register SimVars with AddToDataDefinition(...) must match the order of the properties in your data structure. This is crucial for accurate data retrieval.
   • Ensure that the data types of your structure properties align with the types specified in the SimConnect documentation to avoid mismatches.