FSUIPC Client DLL for .NET - Version 2.4

Paul Henty · July 22, 2013

.NET DLL for communicating with FSUIPC

Attached is Version 2.4 of my FSUIPC Client DLL for .NET

Benefits:

Object-Oriented class interface better suited to .NET than the other procedural .NET SDKs.
Data from FSUIPC is returned directly to your .NET variables. Supported types are:

Byte, Int16, Int32, Int64, UInt16, UInt32, UInt64, Double, Single

String (Unicode/ASCII conversion and termination handled for you)

BitArray (Allows you to easily manage the bit field type offsets)

Array of Bytes (Allows you to read and write raw blocks of data if you need that level of control.)

Writes are handled just by assigning a new value to the local .NET data variable. The write to FSUIPC will be handled automatically during the next Process().
Errors are handled by .NET exceptions, not by checking return values.
The DLL can be use with any .NET language. Documentation and example projects for C# and Visual Basic.NET.
The library has full internal documentation that will appear on the IntelliSense popup menus in Visual Studio.
Just as fast as the procedural-style .NET SDKs.
Thread safe. Can be used in multi-threaded applications, with each thread communicating with FSUIPC, without corrupting the data. (Only one thread can talk to FSUIPC at a time – other threads will block until the connection is free).

The zip file contains the DLL, documentation and an example project in C# and Visual Basic.NET (Visual Studio 2010 format).

Documentation for the 2.4 features is only in the form of example code which is attached below.

Microsoft have free versions of Visual Studio 2012 compilers for VB, C#, C++ here:

http://www.microsoft.com/visualstudio/eng/products/visual-studio-express-for-windows-desktop#product-express-desktop

Paul

FSUIPCDotNetClient2.4.zip

Paul Henty · July 22, 2013

Full Feature List

PayloadServices

Makes it easy to access the payload stations and fuel tanks on the player's aircraft. The DLL supplies you with a .NET List<> of payload or fuel tank objects. Weights and fuel tank levels are supplied in a number of units (percent full, Lbs, Kg, Slugs, Newtons, Gallons, Litres).

The DLL also supplies calculated data such as Zero Fuel Weight and total aircraft weight.

Individual fuel tank levels can be changed using %, Gallons, Litres, Lbs, Kgs, Newtons or Slugs.

Individual Payload station weights can be changed using Lbs, Kgs, Newtons or Slugs.

UserInputServices

Makes it easy to use the FSUIPC user input facilities to trap key presses and joystick button presses from inside Flight Sim.

Allows you to add your own menu items to the 'Modules' (<=FS9) or 'Add Ons' (FSX) menu. You can respond to the user selecting these menu items in your own application.

Offset Grouping

Make groups of offsets that you can process at different times in your application.

AI Traffic

Make it very easy to access the AI Traffic Information from FSUIPC. AI Planes are returned to you as a strongly-typed List<> of AIPlaneInfo instances. AIPlaneInfo provides all information available from FSUIPC plus lots of extra info (e.g. Distance and Bearing from the player) in a ready-to-use .NET class.

You can also write into the internal FSUIPC AI Traffic Tables. (This does not add AI planes into flight sim, it just adds TCAS targets).

Longitude and Latitude Helper Classes.

These understand the raw FS Units provided by FSUIPC (both the 8-Byte and 4-Byte types) so conversion to and from degrees is done for you. Also has a very flexible ToString() method to enable output in a number of human-readable formats.

Classes exist for dealing with Longitude and Latitude Spans (distances). These classes can be used to convert Lon/Lat spans to and from metres or feet. Lon/Lat spans can be calculated between two Lon/Lats.

Another class deals with a Lon/Lat points. This represents a point on the Earth but can also be used to calculate the distance and/or bearing to another point.

Another class represents a Quadrilateral area on the Earth. Its primary function is to test if a lon/lat point is contained within the Quadrilateral. This is useful for testing if you are on a runway. The Quadrilateral can be generated from a set of four Lat/Lon points, or from basic runway information such as that found in the output of MakeRunways.exe by Pete Dowson.

Connect to Multiple Instances of WideClient

The DLL is fully capable of talking to multiple instances (Classes) of WideClient on the same machine. This is an advanced feature that enables applications to control multiple copies of FS on the same network.

Paul Henty · July 22, 2013

Extra Documentation for the new 2.4 Features - VB.NET (C# Below)

Payload and Fuel data

The payload and fuel data is accessed from a new property on the FSUIPCConnection class called 'PayloadServices'.

It's a good idea to assign this to a local variable to save typing FSUIPCConnection.PayloadServices all the time...

' Get a reference to save so much typing...
Dim ps As PayloadServices = FSUIPCConnection.PayloadServices

Whenever you want to get the latest payload and fuel data you just need to call RefreshData() on the PayloadServices object...

' Get the latest data from FSUIPC
ps.RefreshData()

Once you have done that there are lots of properties on the PayloadServices class that will give you weight and fuel data for the aircraft overall. For example:

ps.PayloadWeightLbs
ps.AircraftWeightLbs

Most are self-explanatory and there is Intellisense on everything.

You also have access to the individual payload stations and fuel tanks. Here is an example of iterating through each payload station.

' Go through each station and get the name and weight
For Each (payloadStation As FsPayloadStation In ps.PayloadStations)
   Dim name As String = payloadStation.Name
   Dim weight As Double = payloadStation.WeightLbs
Next payloadStation

Changing Payload and Fuel

You can also write new values to individual payload stations or fuel tanks.

To change the value of payload station, just change one of the weight properties for that station (Lbs, Kg etc).

When you've made all the changes you want call WriteChanges() on your PayloadServices object. This will send all the changed values to FSUIPC.

Fuel Tanks

Fuel tanks are the same except, in addition to changing the weight, you can also change them by setting a new % full level or a volume in Gallons or Litres.

To access properties on a specific fuel tank you can use the following syntax: (This gets the current level of the Centre_Main tank in US Gallons. Other properties and tanks are available.)

ps.GetFuelTank(FSFuelTanks.Centre_Main).LevelUSGallons

Note that WriteChanges() send both Payload and Fuel changes in one go.

User Input - Menus

1. First, declare a UserInputServices object using the WithEvents modifier

' Declare a UserInputServices object so we can use it in the code
Private WithEvents userInput As UserInputServices

2. After opening the FSUIPC connection you need to set the variable above and add your menu items:

' Set our userInput object to the UserInputServices
userInput = FSUIPCConnection.UserInputServices
' Add our menu items (2 examples)
' First parameter is the ID we use to identify this menu item
' Second parameter is the Text for the menu item (Max 30 chars)
' use & before a letter to make it the shortcut key
' Third parameter specifies whether or not to pause FS when
' the menu item is selected.
userInput.AddMenuItem("Menu1", "Menu Item &One", False)
userInput.AddMenuItem("Menu2", "Menu Item &Two (Pauses FS)", True)

Note that if you use a pausing menu item it will be your application's responsibility to unpause FS by writing to offset 0626 at the appropriate time.

3. You need add a new method to handle the MenuSelected event. This will be called when the user selects one of your menu items:

Private Sub menuItemSelected(ByVal sender As Object, ByVal e As UserInputMenuEventArgs) Handles userInput.MenuSelected
   ' This sub gets called when a menu item is selected
   ' Use the e object to see which one (Check the ID)
   Select Case e.ID
          Case "Menu1"
                MessageBox.Show("Menu item 1 selected")
          Case "Menu2"
                MessageBox.Show("Menu item 2 selected")
    End Select
End Sub

4. You need to call CheckForInput() regularly to check if the user has selected any menu items. If they have the above method above will automatically be called for you. Add this code in one of your timers.

' Check for input. Recommended every 200ms
userInput.CheckForInput()

5. FSUIPC will delete your menu items after about 14 seconds. To prevent this you must tell FSUIPC that your application is still running and stills needs the menu items. You must call KeepMenuItemsAlive() regularly. Pete suggests every 8 seconds. So on an 8 second timer call:

userInput.KeepMenuItemsAlive()

6. Before your application exits, call the RemoveAll() method to clean up your menu items.

' Remove our menu items
userInput.RemoveAll()

User Input - Buttons and Keys

Similar to above except you use AddKeyPress() and AddJoystickButtonPress() to register the buttons/keys.

You then sink the KeyPressed or ButtonPressed events to detect the user pressing the button/key.

You still need to call the CheckForInput() regularly but KeepMenuItemsAlive() is obviously not required for buttons/keys.

Paul Henty · July 22, 2013

Extra Documentation for the new 2.4 Features - C# (VB.NET Above)

Reading Payload and Fuel data

The payload and fuel data is accessed from a new property on the FSUIPCConnection class called 'PayloadServices'.

It's a good idea to assign this to a local variable to save typing FSUIPCConnection.PayloadServices all the time...

// Get a reference to save so much typing...
PayloadServices ps = FSUIPCConnection.PayloadServices;

Whenever you want to get the latest payload and fuel data you just need to call RefreshData() on the PayloadServices object...

// Get the latest data from FSUIPC
ps.RefreshData();

Once you have done that there are lots of properties on the PayloadServices class that will give you weight and fuel data for the aircraft overall. For example:

ps.PayloadWeightLbs
ps.AircraftWeightLbs
ps.FuelWeightLbs
ps.FuelCapacityUSGallons

Most are self-explanatory and there is Intellisense on everything.

You also have access to the individual payload stations and fuel tanks. Here is an example of iterating through each payload station.

// Go through each station and get the name and weight
foreach (FsPayloadStation payloadStation in ps.PayloadStations)
{
   string name = payloadStation.Name;
   double weight = payloadStation.WeightLbs;
}

You can do the same thing with the FuelTanks collection. This holds a FsFuelTank object for each possible tank. Some might not be in use for the current aircraft though.

To access properties on a specific fuel tank you can use the following syntax: (This gets the current level of the Centre_Main tank in US Gallons. Other properties and tanks are available.)

ps.GetFuelTank(FSFuelTanks.Centre_Main).LevelUSGallons

Changing Payload and Fuel

You can also write new values to individual payload stations or fuel tanks.

To change the value of payload station, just change one of the weight properties for that station (Lbs, Kg etc).

When you've made all the changes you want call WriteChanges() on your PayloadServices object. This will send all the changed values to FSUIPC.

Fuel Tanks

Fuel tanks are the same except, in addition to changing the weight, you can also change them by setting a new % full level or a volume in Gallons or Litres.

Note that WriteChanges() send both Payload and Fuel changes in one go.

Here's some code to set all the payload stations to 0

// Get the latest values
ps.RefreshData();
// Go through each station and set weight to 0
foreach (FsPayloadStation payloadStation in ps.PayloadStations)
{
   payloadStation.WeightLbs = 0;
}
// send the changes to FSUIPC
ps.WriteChanges();

User Input - Menus

Below is code for a form that puts two menu items on the FS menu and responds to the user selecting these menu items.

This shows you everything you need to do. If you want to put this behind a real form to see it working, you'll need two timers on the form called 'timerPollForInput' and 'timerKeepAlive'. You'll also have to change the namespace and class name to suit your project and wire up the _load event.

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

namespace TestApp
{
   public partial class MenuDemo : Form
   {
      UserInputServices ui;

      public MenuDemo()
      {
         InitializeComponent();
      }

      private void MenuDemo_Load(object sender, EventArgs e)
      {
            // Open FSUIPC
            FSUIPCConnection.Open();
            // Get a reference to the UserInputServices
            ui = FSUIPCConnection.UserInputServices;
            // Add our Menu Items
            // The first parameter is the key and can be whatever you want.
            // We'll use this later to see which item was chosen.
            // The second parameter is the text to display on the menu item.
            // Putting an & before a letter makes it underlined and becomes the shortcut key.
            // Set the last parameter to true is you want to FS to pause when the user chooses this item.
            ui.AddMenuItem("MenuA", "Our Menu Item &A", false);
            ui.AddMenuItem("MenuB", "Our Menu Item &B", false);
            // Sink the MenuSelected event so we can respond
            ui.MenuSelected += new EventHandler<UserInputMenuEventArgs>(ui_MenuSelected);
            // Start our two timers.
            // This one keeps FSUIPC from deleting our menu items (every 4 seconds)
            this.timerKeepAlive.Interval = 4000;
            this.timerKeepAlive.Tick += new EventHandler(timerKeepAlive_Tick);
            this.timerKeepAlive.Start();
            // This one checks to see if the user has selected a menu item (2 times a second).
            this.timerPollForInput.Interval = 500;
            this.timerPollForInput.Tick +=new EventHandler(timerPollForInput_Tick);
            this.timerPollForInput.Start();
      }

      private void timerPollForInput_Tick(object sender, EventArgs e)
      {
            // Check if the user has selected our menu items
            ui.CheckForInput();
      }

      private void timerKeepAlive_Tick(object sender, EventArgs e)
      {
            // Stop FSUIPC from deleting out menu items
            ui.KeepMenuItemsAlive();
       }

       private void ui_MenuSelected(object sender, UserInputMenuEventArgs e)
       {
              // This method is called when the user selects one of our menu items.
              // Check which one and do stuff
              switch (e.ID)
              {
                  case "MenuA":
                     // Do menu A stuff here
                     MessageBox.Show("Menu Item A selected!");
                     break;
                  case "MenuB":
                     // DO menu B stuf here
                     MessageBox.Show("Menu Item B selected!");
                     break;
               }
        }

        private void Form2_FormClosing(object sender, FormClosingEventArgs e)
        {
              // Remove our menu items from FS
              ui.RemoveAll();
              // Close FSUIPC
              FSUIPCConnection.Close();
        }
    }
}

User Input - Buttons and Keys

Similar to above except you use AddKeyPress() and AddJoystickButtonPress() to register the buttons/keys.

You then sink the KeyPressed or ButtonPressed events to detect the user pressing the button/key.

You still need to call the CheckForInput() regularly but KeepMenuItemsAlive() is obviously not required for buttons/keys.

Sign In

FSUIPC Client DLL for .NET - Version 2.4

Recommended Posts

Paul Henty

Link to comment

Share on other sites

Paul Henty

Link to comment

Share on other sites

Paul Henty

Link to comment

Share on other sites

Paul Henty

Link to comment

Share on other sites

Browse

Activity

Important Information