A Ten-Thousand Foot View of SimConnect - Part 1

The title of this blog series is credited to Mike Powell, of www.mikesflightdeck.com, probably one of the most informative sites about building hardware for your home flight deck project. Mike and I were talking about what is needed for people who want to use SimConnect but are stymied by the IDE, .NET, the data format, etc.

So, A Ten-Thousand Foot View will try to correct that, by starting from scratch and building a fully-usable program with as much explanation as I can manage.

I am not assuming much in the way of programming knowledge, but at the same time, I'm trying to keep my explanations simple.  The goal is be just a way for people to get off the ground, so to speak.

Prologue: How it all works

Presenting the world's worst flowchart. 

As you can see, SimConnect acts as a transport between your programs or DLLs and FSX.  Having this step in the middle means that not only can you transfer data with FSX, but also with other add-ons.  Input can go directly into the sim like normal, or can intercepted by your program.

There are two basic ways to interface with SimConnect, through C++ or managed code, such as C# or Visual Basic.  In these examples, I use C#.  Managed code provides a lot of tools that I feel makes programming, especially for someone starting off, a lot easier.

SimConnect is based on an event system.  I'll try to keep this as concise as possible, because there are some really good tutorials and books on asynchronous programming out there.  Imagine you are at an office, and you want to put together a presentation on financial performance over the last year.  So you call Accounting and request a report on the ledger.  Then you go about your job, doing other things that need to be done, until they send you the report.  Now you can process that information and use it in your presentation.  SimConnect works in a similar fashion.  You send a request to FSX through the SimConnect layer and set up an event to fire off when you receive something back.  That event handles the data you get from the program.  This is different than synchronous programming where you would send your request and then have to wait around before you could do anything else. 

All of that is just background though and should become clearer as we start working with the API.

Part One: Setting Up For SimConnect

There's a few things you'll need before you get started:

• Microsoft Flight Simulator X Deluxe Edition
• Visual C# 2005 Express Edition (available for free here)
• The .NET Framework (this should be installed with FSX)

Once you have these three things, you're ready to start setting up your workspace.  Go ahead and download and install Visual C# Express if you haven't already. 

Then, pop in your FSX DVD (disk 1) and if autorun is turned on, you'll get the installer popping up.  Cancel out of that and browse through my computer to the files on the DVD.

In the /SDK folder on your DVD, you find "Microsoft Flight Simulator X SDK.msi".  Run that to install the SDK.

NOTE: I don't know if there are conflicts or anything to worry about, but I made it a point to not install the SDK into the same folder as FSX.  Mostly I just like to have everything separate. 

Scrolling down to entries in this blog, you'll see a post titled "SimConnect Debug Console" which tells you how to set up the SimConnect.ini file to get the console.  I'll be referring to it from time to time, so you'll want to do this too.

That does it, you're set up for our first SimConnect project.

Part Two: Hello SimConnect!

Open up Visual C# Express, and you should see a window similar to this (click on the image links for larger versions)

Selecting File -> New Project will bring up, not surprisingly, the New Project dialog.  We just want to pick "Windows Application" and give it a name.  I'm calling it "SimConnect Tutorial" but anything will work.  Click ok and the project will load up, showing you what is called the "Designer" or the "Design View".  This feature of Visual C# Express allows you to visually design your Windows application, and will help us out extremely in the long run.

To the right is the Solution Explorer, which has your project and a file hierarchy below it.  There some properties and references that we don't need to worry about, then our two code files, Form1.cs and Program.cs.  All C# code files should have the .cs extension.

Right-click on Form1.cs and select "View Code".  Program.cs just acts as the entry point into our application and runs our form (the term to describe the window we are creating) so we won't even be bothering with it.

Form1.cs looks like this:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;

namespace SimConnect_Tutorial
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }
    }
}

The "using" statements at the top are, in this case, references for namespace inclusion.  When you code in C#, you put your code inside these namespace blocks so that they can be logically organized or accessed without any confusion.  As you can see above, our code is all under the "SimConnect_Tutorial" namespace because it is wrapped in that namespace statement.  The "using" statements at the top include the namespaces of some of the standard .NET components, so that we can use them in our program.  For example:

public partial class Form1 : Form 

is the statement to create our Form1 class, the basic object that is going to control our whole program.  It is extending a basic Form class that is part of the .NET framework.  The full name is "System.Windows.Forms.Form".   Without the line "using System.Windows.Forms;" we wouldn't be able to access that element.

The program, at this time, doesn't know how to talk to SimConnect, though.  We want to add that ability in.  In our Solution Explorer (to the right of the code window) right click on "References" and select "Add Reference".  When the window opens up, go to the "Browse" tab and find your SDK installation.  From the directory you installed in, browse through to the following folder:
"/SDK/Core Utilities Kit/SimConnect SDK/lib/managed/"
and you should find a file called "Microsoft.FlightSimulator.SimConnect.dll".  Select this file and click Ok.  You should see the References folder expand in the Solution Explorer and that file will be in there.  Now that the project knows to use SimConnect, we tell the code that we are working on to use it as well.  Right under the line "using System.Windows.Forms;", add these two lines:

using Microsoft.FlightSimulator.SimConnect;
using System.Runtime.InteropServices;

The first adds our SimConnect functions, the second is to allow our managed code (.NET) to talk to unmanaged code (C++).

From here we are ready to work on our Form1 class.

A class is a description of an object in programming.  The example I see most often is an address book.  In an address book, or a contact list in Outlook, you have a pre-defined set of fields that you can put data into.  No matter how many entries you put in the contact list, each one starts with the same fields to fill in.  A class is like this.  It defines what data, and what functions, each instance of an object will have.   In this case, it is defining what our window does.

Before anything else, we want to define a few member variables, or data that the class can use.  For this intro, we only need two variables.  After the line "public partial class Form1 : Form" and the curly bracket under it, type in these lines:

SimConnect simconnect;
const int WM_USER_SIMCONNECT = 0x0402;

These lines define two variables.  The first is our SimConnect object.  The format is Type   Name  =  Value;  The value is optional.  In the case of the SimConnect variable, we will define the value of it later.  The TYPE is the SimConnect Object, the NAME is simconnect (real original, right?) and the Value, as I said, comes later.   Right now, we are just letting our code know that it is there.  The second one is a constant (const) integer (int) which means that it doesn't change in the program.  Its value is static.  

SimConnect works by sending system messages to our program with the data or information we request inside the message.  To identify which system messages are coming from SimConnect, we create our own indentifier to let the program know.  That's what WM_USER_SIMCONNECT is.  That's straight from the SDK docs, you don't really ever have to change it, just remember to include it.

Now, our Form1 class looks like this:

public partial class Form1 : Form
    {
        SimConnect simconnect;
        const int WM_USER_SIMCONNECT = 0x0402;

        public Form1()
        {

            InitializeComponent();
        }
    }

 The brackets after "public Form1()" contains a function, called the Constructor.  This function executes ("is called") when an object of that class is created.  In this case, when our window opens.  You can identify a constructor because it has the same name as the class (i.e. Form1).

Inside the constructor, above the InitializeComponent() line, we are going to place our function to create a connection to SimConnect.  The line looks like this:

simconnect = new SimConnect("SimConnect Tutorial", this.Handle, WM_USER_SIMCONNECT, null, 0);

 This is creating a new object (of the class SimConnect) by calling its constructor.  The arguments in the parentheses aren't terribly important right now, except to know that the first one in the quotes is where you identify the name of your program to SimConnect, and our buddy WM_USER_SIMCONNECT is in there as well.

Normally, we'd want error checking and a lot of other things in there, but this is just a first step.  Leave Visual C# open and load up FSX.  You don't have to go any farther than the Main Menu.  If you copied over the SimConnect.ini file, you should see a SimConnect Diagnostic Window pop up.  Go back over to your code window and either click the green arrow in the toolbar or press F5 on your keyboard.  If you did everything right, it should think for a second and then pop up a blank grey window.

More importantly, a new line should have appear in the SimConnect console:

> 370.81695 [63, 1]Open: Version=0x00000002 Name="SimConnect Tutorial"

If you see something like this, it means your program has successfully made a connection to SimConnect and is ready to talk to FSX.  To exit out, just click on the x in the corner to close out the program.  Save your work, pat yourself on the back, and I'll move on to the next part in the next few days.

This is my first big tutorial like this.  If you have any questions or comments, please comment below and let me know.