NVAN X-Plane Connector for C#

A simple C# library that wraps the X-Plane REST API and WebSockets API.

This is an evolution of the old XPlaneConnector library that worked via UDP.

The new native protocol implements several changes, like only getting the updates on a suscription when a dataref actually changes, or being able to push and hold a command which was not possible with the UDP API.

Usage

Download

Import the package from NuGet by looking for nvan.XPlaneConnector.

Also can be added via CLI to your project:

nuget install nvan.XPlaneConnector

Connection

Make an instance of XPlaneConnector and then call Start() on it.

nvan.XPlaneConnector.XPlaneConnector xPlaneConnector = new nvan.XplaneConnector.XPlaneConnector(
    IPAddress.Parse("127.0.0.1"), // Optional, default: 127.0.0.1
    8086                          // Optional, default: 8086
);

// Then start so it connects via WebSocket
xPlaneConnector.Start();

Dataref subscription

You can subscribe to Dataref changes with a string:

xPlaneConnector.SubscribeToDatarefAsync("sim/time/total_running_time_sec");

Or with an object:

Dataref dataref = await xPlaneConenctor.FindDatarefAsync("sim/time/total_running_time_sec");
xPlaneConnector.SubscribeToDatarefAsync(dataref);

Or even from the object itself:

Dataref dataref = await xPlaneConenctor.FindDatarefAsync("sim/time/total_running_time_sec");
dataref.SubscribeAsync();

You can set an action to be executed on a particular Dataref change:

xPlaneConnector.SubscribeToDatarefAsync("sim/time/total_running_time_sec", (dataref) =>
{
    dataref.SubscribeAsync();
    timeLabel.Invoke(new Action(() => { timeLabel.Text = "Time running: " + dataref.Value; }));
});

Or via the object:

Dataref dataref = await xPlaneConenctor.FindDatarefAsync("sim/time/total_running_time_sec");
dataref.SubscribeAsync();
dataref.OnUpdate += (dataref) =>
{
    dataref.SubscribeAsync();
    timeLabel.Invoke(new Action(() => { timeLabel.Text = "Time running: " + dataref.Value; }));
};

Or you can have subscribe to a global event:

xPlaneConnector.OnDatarefUpdate += (dataref) =>
{
    Console.WriteLine(dataref.Name + " new value is: " + dataref.Value);
};

Dataref setting

You can set the value via the method with a string:

xPlaneConnector.SetDatarefValueAsync("AirbusFBW/DMCSwitching", -1);

Or via the method with the object:

xPlaneConnector.SetDatarefValueAsync(await xPlaneConnector.FindDatarefAsync("AirbusFBW/DMCSwitching"), 0);

Or via the object:

var dr = await xPlaneConnector.FindDatarefAsync("AirbusFBW/DMCSwitching");
dr.Value = 1;

Dataref getting

You can get the value (once, no subscription) via the method with a string:

Console.WriteLine(
    await xPlaneConnector.GetDatarefValueAsync("AirbusFBW/DMCSwitching")
);

Or via the method with the object (once, no subscription):

Dataref dataref = await xPlaneConnector.FindDatarefAsync("AirbusFBW/DMCSwitching");
var value = await xPlaneConnector.GetDatarefValueAsync(dataref);

Or if you are subscribed, the Value of the object will be updated:

Dataref dataref = await xPlaneConnector.FindDatarefAsync("AirbusFBW/DMCSwitching");
var value = dataref.Value; // Last value received by subscription

Note that all Dataref objects are unique per dataref name and index, so even if you use the FindDatarefAsync() method, it's gonna look up in the cache before creating a new object.

This way we ensure each dataref object is up to date and there are no duplicate actions.

Arrays and Strings

This library supports both array and string Datarefs.

String ones will just return a string as the Value, and will accept a String too.

To interact with an array, just call it like with the old libraries, by using [x] to indicate the index:

xPlaneConnector.SubscribeToDatarefAsync("Airbus/EnginePower[0]");
xPlaneConnector.SubscribeToDatarefAsync("Airbus/EnginePower[1]");

Commands

You can activate a command once, or begin/end a push & hold command.

No timers have been implemented so if you need a timer, you'll gotta implement it on your side.

Send once

You can via a string:

xPlaneConnector.SendCommandOnceAsync("sim/operation/pause_toggle");

Or via an object:

var command = await xPlaneConnector.FindCommandAsync("sim/operation/pause_toggle");
xPlaneConnector.SendCommandOnceAsync(command);

Or via the object:

var command = await xPlaneConnector.FindCommandAsync("sim/operation/pause_toggle");
command.OnceAsync();

Begin push & hold

You can via a string:

xPlaneConnector.BeginCommandAsync("AirbusFBW/ECAMAll");

Or via an object:

var command = await xPlaneConnector.FindCommandAsync("AirbusFBW/ECAMAll");
xPlaneConnector.BeginCommandAsync(command);

Or via the object:

var command = await xPlaneConnector.FindCommandAsync("AirbusFBW/ECAMAll");
command.BeginAsync();

End push & hold

You can via a string:

xPlaneConnector.EndCommandAsync("AirbusFBW/ECAMAll");

Or via an object:

var command = await xPlaneConnector.FindCommandAsync("AirbusFBW/ECAMAll");
xPlaneConnector.EndCommandAsync(command);

Or via the object:

var command = await xPlaneConnector.FindCommandAsync("AirbusFBW/ECAMAll");
command.EndAsync();

Donations

If you use and like this program, consider buying me a 🍺 beer. You can donate via PayPal:

Issues and contributions

Please, feel free to ask for questions or features, or report bugs in the Issues section.

Also, feel free to Contribute by making a Pull Request.

Tested in our own A320 Simulator

We are building an A320 Flight Simulator in Mallorca, check it on Instagram!

License

MIT

This program is free, but credit is appreciated if you use it at your setup!