Wingman Getting Started Guide

Date: February 5th, 2016

Revision: 0.6.0

Audience

Programmers wanting to develop XPlane plugins and aren't familiar with the Wingman development system should read this guide.

Overview

Wingman is a system of tools, libraries, plugins and documentation to help developers create plugins for XPlane 10. 

The current system includes:

• Framework Library
• Operating Subsystem Plugin (OSS)
• Cross Compiling Environment (ClamShell-VCCE)
• Sample Code (WingmanDemo1)
• Documentation
  • Tutorials
  • Class API
  • Programmers Guide
  • User Guides (OSS & Clamshell)

    The Wingman Framework Library consists of class wrappers around most of the XPLM SDK but also provides higher level classes and functionality to create plugins faster and easier.

    The Operating Subsystem, OSS, is a XPlane plugin that inlcudes utilities and a command line interface, CLI, to develop your plugin. The CLI can be used to test and debug you plugin. 

    The cross compile environment is called ClamShell because of the way it interfaces to the host development file system. Yes, ClamShell-VCCE is a Virtual Machine, VM, based on Linux/Ubuntu 14.04 but you don't need to be a Linux expert because its made to be a compiler and not where you write your source code. 

    A build system is also proided to work along side the ClamShell-VCCE. This system provdes a method to build your XPlane plugin for Windows 32bit, 64bit and Linux 64bit systems. The build system also provides a method to package plugins for distribution.

    What good would a library be without sample code to show how things are done. One demo plugin is provided with full source code to help you to begin developing quickly.

    For any project, especially a application programmer library, to be successful then there needs to be documentation to go with it. Careful planning has been made into what kind of documents will be provided: programmer guides; user guides, tutorials and of course a class API generated from the class header files.

 

 

 

Wingman Runtime System 

    The Wingman Runtime System is when your Wingman plugin is loaded by XPlane and the host operating system (MS-Windows/Linux) and includes: Wingman OSS; your plugin and Wingman INI configuration files.

    All Wingman plugins automatically create a wingman.ini configuration file under the plugins root directory. The wingman.ini file configures your plugin's logging and debugging states as well as any other configuration needed by the Wingman framework. Depending on your needs you may want to distribute this file along with your plugin.

    The OSS, Operating Subsystem, is a XPlane plugin that interfaces to your plugin for testing or helping an end user with a problem.

Prerequisites

• XPlane 10.25 or higher.
• Download the latest Wingman ST System
• VirtualBox Installed on your development PC
• Source Code Editor

Development Computer

    If your development PC can run XPlane then you will be able to develop with the Wingman system of development tools. 

Supported Host Operating Systems:

• MS-Windows 7 32/64bit
• MS-Windows 8 32/64bit
• Ubuntu 14.04 64bit 

 

HomeUse Vs Registered Edition

    Plugins developed with the HomeUse edition of Wingman-ST can only be distributed if you are not charging a fee for them. The HomeUse build also has some limitations on what classes can be instantiated or how many can be instantiated.  Keeping your source closed is permitted even if you distribute you plugin to the public.

    The Registered edition of Wingman-ST requires you to purchase a license which allows you to distribute, develop or use your plugin for commercial purposes.  When you purchase a license you will be given access to download the Registered edition of the Wingman Framework Library.

    See the release page for more information and the End User License Agreement, EULA.

References

Installations

The below installations are required for Wingman.

VirtualBox

VirtualBox is a virtualization utility that can be downloaded for free. It is required to compile using the ClamShell-VCCE VM.

Quote form Oracle's VirtualBox website

Download the latest version of VitualBox for you development platfrom from here. Oracle Virtual Box Downloads

• Select all the default installation options.

Wingman Release Files

For each Wingman release there will be a release page with download links simular to the image below. Some binaries have the option to download a ZIP or tar.gz. If you are using MS-Windows then its best to download the ZIP version, Linux systems can use either one.  

Download now the latest packages: Wingman Framework, WingmanOSS, WingmanDemo1 & ClamShell Cross Compiling Environment. Click Here

 

Wingman Framework Library

    The Wingman Framework Library is the core of your XPlane plugin and provides a C++ API. The framework library also provides a template source folder to get you started quickly.

    The Wingman Framework folder needs to be installed in a location that both aircraft and non-aircraft plugins can access so the location under "XPlane/Resources" was chosen.

Steps to install.

Step 1: Go to the folder where you downloaded the packages and open the zip file by double clicking on the WingmanFramework-vx.x.x-HomeUse.zip file.

Step 2: Copy the folder called Wingman.

Step 3: Paste into the XPlane/Resouces folder. Under Windows usually this would be C:\Program Files\XPlane\Resources.

Note: If you already have an older version of Wingman, best to delete the folder before pasting.

Step 4: To verify your paste was successfu, look in the "XPlane\Resouces" folder and you should find a folder called "Wingman".

 

Wingman Operating Subsystem (OSS)

    The WingmanOSS, Operating Subsystem, is a plugin that interfaces to your plugin via a command line interface, CLI,  for development and testing. The WingmanOSS plugin also provides utilities to restart plugins or the scenery.

    The WingmanOSS plugin is a non-aircraft plugin and needs to be installed in "XPlane\Resources\plugins".

Steps to install.

Step 1: Go to the folder where you downloaded the packages and open the zip file by double clicking on the WingmanOSS-vx.x.x.zip file.

Step 2: Copy the folder called WingmanOSS.

Step 3: Paste into the XPlane/Resources/plugins folder. Under Windows this usually would be C:\Program Files\XPlane\Resources\plugins
Note: If you already have an older version of WingmanOSS, best to delete the folder called "WingmanOSS" before pasting.

Step 4: To verify your paste was successful, look in the "XPlane\Resources\plugins" folder and you should see a folder called "WingmanOSS"

 

Wingman Demos

    WingmanDemo1 is a pre-compile plugin, includes full source code, to demonstrate some of the Wingman Framework classes. The WingmanDemo1 has been compiled for Windows 32/64 and Linux 64bit . The plugin is a non-aircraft plugin and needs to be installed in your "XPlane\Resources\plugins" folder.

Steps to install.

Step 1: Go to the folder where you downloaded the packages and open the zip file by double clicking on the WingmanDemo1-x.x.x.zip file.

Step 2: Copy the folder called WingmanDemo1.

Step 3: Paste into your XPlane/Resources/plugins folder. Under Windows this usually would be C:\Program Files\XPlane\Resources\plugins
Note: If you already have an older version of WingmanDemo1, best to delete the folder called "WingmanDemo1" before pasting.

Step 4: To verify your paste was successful look in the "XPlane\Resources\plugins" folder and you should see a folder called "WingmanDemo1"

 

ClamShell Virtual Cross Compile Environment

    The ClamShell Virtual Cross Compile Environment, VCCE, is what builds your plugin for Windows or Linux targets. The VCCE is executed using VirtualBox which interfaces to your host machine's filesystem, this allows you to use your favorite IDE without having to develop under Linux. This section only describes how to unpackage the ClamShell VCCE when downloaded.  

 

Steps to install.

Step 1: Create a folder somewhere that will hold your VMs or just use the default folder created for you by VirtualBox. Under Windows this is normally located under "C:\Users\{your name}\VirtualBox VM's"

Step 2: Go to the folder where you downloaded and saved the ClamShell VCCE package and open the zip file by double clicking on the ClamShell-VCCE-x.x.x.zip file.

Step 3: Copy the folder called ClamShell-VCCE-x.x.x

Step 4: Paste into your VM folder. This is either the folder you made in step1 or use the default one created for you by VirtualBox.

Step 5: Verify your paste was successful  by looking in your VM folder and seeing a folder called "ClamShell-VCCE-x.x.x", then double click to open the folder. You should see files simular to the ones listed in the above screenshot.

To see how to setup and configure VirtualBox with the ClamShell VM see section Setup ClamShell VCCE

Other 3rd Party Tools

    The following installations are optional and limited to some hosts machines.

BareTail

    For MS-Windows only

    BareTail is an excellent tool for monitoring log files that are also being written to and be setup to highlight on certain words.  Since the Wingman Framework supports logging and debugging streams that can go to XPlane's log file and/or to your plugins own logfile, BareTail is excellent for viewing these log files during runtime.

The above screen shot is reading the XPlane/Log.txt file. As you can see INFO and ERROR log messages from plugin developed with Wingman are coloured in Green and Red

Download BareTail by clicking here. Afterwards, you just need to run the provided .exe file, no other installation is necessary.

 

Setup ClamShell Cross Compile Environment

    This section describes setting up VirtualBox to run the ClamShell-VCCE VM for your host development system. The setup described below is the same whether you are running Linux, Machintosh or MS-Windows.

Note: If you start the VM you will need to login as the default user and password:

login id = 'user'

Password = 'password' 

 

Setup VirtualBox

    Setting up VirtualBox has two main objectives:

1. Add the ClamShell Virtual Machine
2. Configuring for Host Development

 

To setup the ClamShell VM. first you must start VirtualBox. Afterwards you should see a screen similar to the one above.

 

Add Virtual Machine

    Adding the ClamShell virtual machine to Virtual Box is the first objective.

Steps needed to add:

Step 1: Add the ClamShell-VCCE VM. 

• From the menubar click on "Machine"
• Click the option "Add"

Step 2: Select the VM Image by going to the folder where you installed ClamShell-VCCE. Open the folder then ClamShell-VCCE-x.x.x VirtualBox Machine Definition file and click the "Open" button.

Step 3: VM is installed. You should see the ClamShell-VCCE-x.x.x listed in VirtualBox's VM list. See image above.

 

Configure for Host Development

This setup is required if you are developing on a Windows host machine and this allows you to develop using tools familiar to you, for example your favorite IDE or source code editor.

If you are using Ubuntu Linux 14.04LTS as your development host you can go to the ClamShell-VCCE Users Guide to find instructions on what packages you need install to compile Wingman plugins for other targets. These instructions will give your Linux box the same functionality as the ClamShell compiler.

Steps needed to configure VirtualBox for your host machine are as follows:

Step 1: Select the ClamShell-VCCE VM and then click "Settings" from the toolbar.

 

Step 2: Add a shared folder by selecting "Shared Folders" in the settings list on the left side of the window. Then on the right side of the window select the folder icon with the plus sign.

Note: If you already see a shared folder with the name "xplane" then you can simply edit it. To do this, select "xplane" from the folders list, which is in the center of the window, and then select the folder with a small circle. 

Step 3: Add your XPlane folder.

• Add a folder by clicking on the "Folder Path" drop down and select "Other...". Navigate the file explorer to where your XPlane is installed. Under MS-Windows, this is usually "C:\Program Files\XPlane". Click the "Ok" button when done.
• Next, in the "Folder Name" enter "xplane". It is important that you use this name for Wingmans build system.
• Last, make sure "Auto-mount" is checked.
• Click the "Ok" button.

Step 4: Verify all is correct and apply the changes. 

    Verify by ensureing:

• The name is set to "xplane"
• The path to where your XPlane is installed is correct.
• Auto-mount is marked as "Yes"
• Access is set to "Full".

    If all of the above matches in what is in the above screenshot, then apply your settings by clicking the "Ok" button.

 

The Walk Around

    This chapter is a quick tour of the Wingman suite of tools and plugins and covers:

• WingmanOSS Plugin
• WingmanDemo1 Plugin
• ClamShell VCCE
• Wingman Framework by compiling WingmanDemo1

If you installed everything as described in sections Installations and Setup ClamShell VCCE this walk around tour will go smoothly.

Please start XPlane 10 now!

Checkout the Plugins

This section is a brief overview of the installed Wingman plugins

• WingmanDemo1
• WingmanOS

 

After XPlane has loaded you will see if the plugins have been installed correctly by clicking on the "Plugins" menu. You will see "WM Demo1" and "WingmanOSS" listed.

 

WingmanDemo1

    This plugin gives a sample of some of the features/functionality you will get using the Wingman Framework Library.

Select the "WM Demo1" under the Plugins menu

 

Select any of the menu options and a dialog window will open. Most of these windows are self explanatory.

This is a sample of one dialog window.

 

WingmanOSS

    WingmanOSS helps you develop your plugin by providing a local console shell and utilities.

 

Utilities:

• Reload Plugins - Reloads all plugins. Useful when you want to compile or update your plugin without having to restart XPlane.
• Reload Scenery - Reloads the scenery.

 

     You will likely to use "Reload Plugins" the most as you cannot re-compile a plugin using ClamShell while XPlane is running unless your plugin is stopped and unloaded. After selecting this option you will be prompted to place in your new plugin. At this time XPlane has unloaded all plugins and it is safe to either copy a new plugin binary or compile your plugin with ClamShell.

 

Local Console: 

    This a command line shell that interacts with plugins made with the Wingman Framework Library.

 

Select the menu option "Local Console" and a semi-transparent window will appear. 

Type: "help {Enter}" and a list of options will be displayed. 

Typing a command with the word "help" afterwords will give you a list of options on how to use the command.

Note: Like any good CLI when typing commands, it is case senstive.

The real magic with the shell is connecting to a Wingman plugin. We can connect to the WingmanDemo1 plugin by typing: "connect local wingman.demo1".

• "connect" is the command.
• "local" is for connecting on this machine.
• "wingman.demo1" is the signature of the plugin, which is set at compile time. 

You will see a message "Connection successful" if the connect command succeeded.

 

Type: "help {Enter}" again and in the listing you will notice there are now more options.

These new options are installed by the WingmanDemo1 plugin. Any plugin using the Wingman Framework can add custom commands to the shell.

Type "pinfo {Enter}" which stands for plugin information. This call will display basic plugin information of the connected plugin.

 

ClamShell VCCE

    This section describes the basics of using the ClamShell Virtual Cross Compile Environment.

 

First you need to start the VM.

Open VirtualBox, select the ClamShell-VCCE VM and then click on the "Start" button located on the toolbar.

Once loaded you will be prompted to login.

Login ID = 'user'

Password  = 'password'

To check if you setup the the shared folder correctly, you need to do two things.

First change directories to the XPlane directory.

Type: "cd /media/sf_xplane/ {Enter}"

Second, list the folder contents.

Type: "ls {Enter}"

The contents should match closely with the screen shot above.

If nothing is listed then check that you setup VirtualBox's shared folder correctly by re-reading the section Setup ClamShell Cross Compiling Environment. 

When you are done with the ClamShell you must stop the VM by shutting down.

This is simular to "Shutting Down' in MS-Windows. If you do not stop the VM properly you can damage it's file system.

To stop the VM type: "sudo shutdown -h now {Enter}"

If prompted with a password enter the same password you logged in with.

After a few seconds the window will disappear and this indicates the VM has stopped and it is now safe to close the VirtualBox application.

 

Compile WingmanDemo1

This section describes how to build plugins using the ClamShell VCCE by compiling WingmanDemo1.

WingmanDemo1 is distributed with all the source code.

 

Step 1: First, if you are running XPlane then you will need to stop all plugins before compiling.

To do this, in XPlane select from the menubar  "Plugins->WingmanOSS->Reload Plugins".

NOTE: At this time DO NOT click "Understood".

 

Step 2: Start the VM, login and go to the XPlane directory.

Note: Of course you can do this before you do step 1 or even before you start XPlane. The VM and XPlane are not dependant on each other.

Step 3: From the XPlane directory go to the WingmanDemo1 plugin directory.

Type: "cd Resources/plugins/WingmanDemo1 {Enter}"

Step 4: Build the source code

The make syntax is: make OS={OStype} [DEBUG=ON]

To  build, you need to specify what operating system target you are compiling for.

Pick one OStype from the options below:

• OS=WIN32 - For Windows 32bit
• OS=WIN64 - for Windows 64bit
• OS=LIN64  - for Linux 64bit

DEBUG=ON is optional and specifies that you will link against the debug build of the Wingman Framework Library. If you do not specify this then no debug verbose messages will be sent to the log file.

Example to build for Windows 64bit.

make OS=WIN64 DEBUG=ON {Enter} 

 

Afterwards, if you want to build for another target you must clean up all object files first.

Type: "make clean {Enter}"

Note: clean does not delete the plugin binaries just the object files.

Now you can build for another target.

Step 4: Compile is complete and you can load your plugin.

If you didn't edit the source code to WingmanDemo1 your compile output should look like the screenshot above.

At this time you can load your plugin by clicking the "Understood" button in XPlane.

 

Conclusion

I hope this guide has helped you get your Wingman development system up and running. For more information please read the other User Guides and Tutorials.